TEMPLATE CONSTRUCTION

INTRODUCTION

	Template construction is perhaps the most complex aspect of shotcuts use.

	Tools could be developed to automate this task, but for now, no such tool
	exists - instead we use a shell script and the MLT 'inigo' command line 
	tool to construct an empty project which dictates which tracks a project has 
	and how they can be used.

	You could, potentially, author the westley xml manually or generate the 
	templates in C, C++, perl, ruby, tcl, java, or any other language that can
	access the MLT API. Only the shell/inigo approach is covered in this 
	document but the principles should map to any method of westley authoring.


WHAT YOU NEED TO KNOW BEFORE YOU START

	Shell scripting and Some basic knowledge of the multi track aspects of MLT 
	and inigo are pre-requisites.

	It is vitally important to note that templates are stored in a users
	home directory. These entries are created via the 'shotcut-templates' 
	script and this script is executed every time a user access 'New Project' 
	from the NLE or when there is no autosaved project to reload.

	The shotcut-templates provided is meant to provide examples - typically,
	you would create your own shotcut-templates and ensure that it is found 
	on the users PATH before the default one.


CREATING A CUSTOM SHOTCUT-TEMPLATES SCRIPT

	Your custom script takes a single argument - this is the directory in
	which you should place the templates - it may not exist at the point
	of invocation, so you may need to create it. Typically, your first few
	lines should look like:

		#!/bin/sh

		[ "$1" == "" ] && exit

		export TEMPLATES=$1

		mkdir -p "$TEMPLATES" 
		[ "$?" != "0" ] && exit

	If you're regularly modifying and removing the templates available from the
	script, then you might find it convenient to remove all the existing templates
	using:

		rm -f "$TEMPLATES"/*.westley

	This is optional, but be aware that the default shotcut-templates does do 
	this.

	Now we're ready to start creating templates.


THE FIRST TEMPLATE - SINGLE TRACK

	The most basic template defines a single track which accepts video:

		inigo nle_template="Single Track" nle_prefix="STR_" \
		-track nle_label=Visual nle_type=1 \
		-blank 0 \
		-consumer westley:$TEMPLATES/SingleTrack.westley store="nle_"

	Notes:

	* the nle_template property defines the label that will be shown when you access
	  New Project in the nle 
	* nle_prefix is used to define a prefix for this project type when saving a file -
	  the default location and file name for all projects saved is 
	  ~/shotcut/'prefix''title'.westley. If no prefix is provided, the default is to 
	  use a the nle_template to define a directory to save projects of that type.
	* the -track introduces an audio/video track (track 0) and assigns it a label
	  and a type - the type here says that this track will accept video only (more
	  details on types below)
	* The -blank 0 is required to ensure that the first track isn't empty - this is a 
	  prerequisite for it to be serialised in inigo - it is not needed in other 
	  environments of mlt use (ie: perl, ruby, c++, the c api itself, etc)
	* The last line simply serialises the template and ensures that all properties
	  with nle_ are stored

	The behaviour of this template will be to:

	1. provide a single track 
	2. reject drops of any item that is not a video clip

	Further, it provides no 'Attributes' or 'Super' track and these panels will 
	remain inactive. It also provides no information for defining the auto transitions
	associated to the Preview mode. Essentially, it provides the most basic playlist
	oriented usage.

	The only feature that the NLE will provide on top of this is the obscure masking
	functionality.


GENERAL STRUCTURE

	The basic pattern for all templates is:

		inigo [ template property assignment] \
		-track [ track property assignment ] \
		-blank 0 \ 
		[ -track [ track property assignment ] ]*
		[ track level filters and transitions ]
		[ project level filters ]
		-consumer westley:$TEMPLATES/[Template name].westley store="nle_"


THE SECOND TEMPLATE - AUDIO MIXING

	Now let's assume we want to add an audio track. The audio track will mix with
	the audio from the video track. For this to work, we need to add a second
	track of the correct type and a 'transition' which defines how the mix should be
	applied.

	For this example, we'll assume an equal mix of audio from both tracks and we'll
	have the audio on the lower track fade in and out for a second on the start and
	end of each audio cut.

		inigo nle_template="Audio Mixing" \
		-track nle_label=Visual nle_type=1 \
		-blank 0 \
		-audio-track nle_label=Voice nle_type=16 \
		-transition mix:0.5 always_active=1 length=25 a_track=0 b_track=1 \
		-consumer westley:$TEMPLATES/AudioMixing.westley store="nle_"

	This should provide us with the template described above.

	Typically, all template level transitions are 'always_active' and have 
	a_track=0 b_track=n properties - note that not all mlt transitions are
	candidates for use in this manner (at the time of writing, only mix and
	composite are supported - however, these two are sufficient for many 
	types of operations).


THE THIRD TEMPLATE - AUTO TRANSITIONS

	One of the features that the NLE provides are auto transitions between 
	neighbouring video cuts on the first track (note that this only applies to 
	the first track).

	You can activate this by providing some properties on the first track which 
	define the transition to use, the duration and other properties associated to
	the effect.

	The most basic example is a fade between the cuts and is defined as follows:

		inigo nle_template="Auto Transitions" \
		-track nle_label=Visual nle_type=1 \
		nle_transition=luma nle_transition_length=12 \
		-blank 0 \
		-audio-track nle_label=Voice nle_type=16 \
		-transition mix:0.5 always_active=1 length=25 a_track=0 b_track=1 \
		-consumer westley:$TEMPLATES/AutoTransitions.westley store="nle_"

	Just to reiterate - this kind of processing is only applied if both 
	nle_transition and nle_transition_length are specified. Further, the 
	transition is created by holding the last frame of the outgoing frame 
	and applying the transition between that and the corresponding opening
	frames of the incoming cut. This transition technique is used to avoid
	relative positions of cuts on other tracks getting lost.

	Note that all user saved and published projects enforce the 'preview' 
	mode regardless of the NLE's GUI state.


THE FOURTH TEMPLATE - SUPERS

	Supers are a special case track - they don't contain audio or video - each
	'clip' holds 1 or 2 lines of text which is sent to a (customisable) filter 
	which renders the text on the output frame in some way.

	Note that supers are tightly coupled to track 0 - in shotcut this is
	normally gapless and the supers are situated so they don't step outside 
	the cut on track 0 to which they belong.

	Because of the coupling, it makes sense to place the supers on track 1 as
	follows:

		inigo nle_template="Supers" \
		-track nle_label=Visual nle_type=1 \
		nle_transition=luma nle_transition_length=12 \
		-blank 0 \
		-null-track nle_label=Super nle_type=8 \
		-audio-track nle_label=Voice nle_type=16 \
		-transition mix:0.5 always_active=1 length=25 a_track=0 b_track=2 \
		-filter data_show:%etv.properties track=-1 \
		-consumer westley:$TEMPLATES/AutoTransitions.westley store="nle_"

	Supers are very sensitive to the template layout. They impose a number of 
	restrictions on templates and shotcut use in general:

	* they must be applied to the final frame, hence the super data show must
	  use the 'wild card' track association (track=-1 above) - if you have single
	  video track, then track=0 is sufficient

	* They (and any filters which should be rendered on the resultant frame) 
	  must be rendered in the last filter(s) in the template - you can have 
	  multiple data_show filters that provide the rules for rendering supers
	  and attributes, but they must be the last filters (unless you want a
	  'burnt in' filter [such as a watermark] to be applied after).

	The super filter used here is defined in the etv.properties feed data file 
	(at runtime this is located in $prefix/share/mlt/modules/feeds/PAL).

	More details on customising supers are found below.


THE FIFTH TEMPLATE - ATTRIBUTES

	As with supers, our main concern with attributes is ensuring they get 
	handled in the correct place.

	Unlike supers, attributes can be more flexibly placed, but with the 
	flexibility comes more decision making and care must be taken to ensure 
	the results are as required.

	Typically, attributes, like supers, are rendered on the output frame
	and the same rules apply as above. Note that for convenience, all the
	ETV demo supers and attributes are defined in the same file, so all we
	have to do is define which attributes are applied to track 0:

		inigo nle_template="Attributes" \
		-track nle_label=Visual nle_type=1 \
		nle_transition=luma nle_transition_length=12 \
		nle_attributes="location,courtesy,*exclusive,*file_shot,*special" \
		-blank 0 \
		-null-track nle_label=Super nle_type=8 \
		-audio-track nle_label=Voice nle_type=16 \
		-transition mix:0.5 always_active=1 length=25 a_track=0 b_track=2 \
		-filter data_show:%etv.properties track=-1 \
		-consumer westley:$TEMPLATES/Attributes.westley store="nle_"

	The syntax of 'nle_attributes' is simply 'name' to dictate that it takes 
	a 'markup' argument that is passed to the rendering, or '*name' to stipulate 
	that the filter doesn't take an argument. 

	Note that these attributes belong to the output frame and by default, all 
	attributes on track 0 (along with the super) are a special case. These 
	attributes are accessible to the consumer - the consumer can 'hijack' these 
	items and render them outside of the mlt environment (for example, on dedicated 
	hardware).

	Attributes belonging to other tracks are locked into mlt rendering.


THE SIXTH TEMPLATE - DOUBLE AUDIO	

	The templates above are building up to the ETV 'Package' template. This
	example will complete this and add a little more information regarding 
	the 'nle_type' track property.

	As has been shown above, tracks can be tailored to accept specific types.
	So far, we've introduced types for audio/video clips (internally known as
	'stories'), audio only and supers. The full list is as follows:

	STORIES = 1		All video clips are categorised as stories
	AUDIO = 2		All inputs that have audio are categorised as audio 
					(ie: a video clip is both story and audio)
	STILLS = 4		Inputs that have no audio are categorised as stills
	TEXT = 8		Used to indicate the track holds supers
	VOICE = 16		Special categorisation that indicates audio only 
					(an audio only clip is both audio and voice)
	PROJECTS = 32	Categorisation of an injected nle project

	Most of these are fairly self explainatory.

	If we want to extend our first track to accept stories, stills and 
	projects, we add the values together - 1 + 4 + 32 = 37.

	Similarly, if we want our audio tracks to accept stories with ambient
	audio, we can can use - 16 + 2 = 18 or just 2 because of the special
	case cited above.

	Note that only the first track can accept a project as a project - 
	when you drop a project on to the first track, the NLE will attempt 
	to convert the entire contents of the project in to the current
	projects template. If track 0 doesn't accept projects specifically,
	the project will be treated as a story.

	Just for completeness, we'll accept ambient video on the Voice track
	and add a Music track (as per the ETV Package) and further we'll allow
	project conversion via the first track:

		inigo nle_template="Double Audio" \
		-track nle_label=Visual nle_type=37 \
		nle_transition=luma nle_transition_length=12 \
		nle_attributes="location,courtesy,*exclusive,*file_shot,*special" \
		-blank 0 \
		-null-track nle_label=Super nle_type=8 \
		-audio-track nle_label=Voice nle_type=2 \
		-audio-track nle_label=Music nle_type=16 \
		-transition mix:0.2 always_active=1 length=25 a_track=0 b_track=2 \
		-transition mix:0.5 always_active=1 length=25 a_track=0 b_track=3 \
		-attach data_show:%etv.properties track=-1 \
		-consumer westley:$TEMPLATES/DoubleAudio.westley store="nle_"

	Clear as mud?


THE SEVENTH TEMPLATE - LOCALISATION

	The thorny issue of localisation will raise its ugly head from time to 
	time. 

	Linux has 3 mechanisms for font rendering - shotcut/fltk and mlt/pango use 
	two different approaches.

	This is an added complexity as it means we need to ensure that fonts are
	listed in both the fc-list and xlsfonts output. 

	Taking ETV's Bengali font as an example, we need to add 4 additional 
	properties to our template:

		inigo nle_template="Double Audio" \
		nle_font_display=BN-TTDurga \
		nle_font_capture=-misc-asbwlttdurga-medium-r-normal--0-0-0-0-p-0-iso8859-1 \
		nle_font_attr_size=32 \
		nle_font_super_size=48\
		-track nle_label=Visual nle_type=37 \
		nle_transition=luma nle_transition_length=12 \
		nle_attributes="location,courtesy,*exclusive,*file_shot,*special" \
		-blank 0 \
		-null-track nle_label=Super nle_type=8 \
		-audio-track nle_label=Voice nle_type=2 \
		-audio-track nle_label=Music nle_type=16 \
		-transition mix:0.2 always_active=1 length=25 a_track=0 b_track=2 \
		-transition mix:0.5 always_active=1 length=25 a_track=0 b_track=3 \
		-attach data_show:%etv.properties track=-1 \
		-consumer westley:$TEMPLATES/DoubleAudio.westley store="nle_"

	The nle_font properties dictate which fonts to use in the MLT display and
	in the shotcut data capture and their respective sizes.


FX CUSTOMISATION

	As mentioned above, it is possible to customise attributes and supers.

	These fx are handled by the MLT 'feed' and 'show' mechanism.

	Essentially, a feed is a property or collection of properties which are placed
	on a frame (normally automatically by assigning them to the producer or the cut)
	and a 'show' is a filter which matches the feeds up to a set of rules and 
	applies the effect.

	The feed definitions are defined in the mlt/src/modules/feeds directory.

	The PAL/examples.properties provides the simplest definitions, for example:

		greyscale=greyscale
		.description=Greyscale

	To use this with inigo, you could use the following:

		inigo colour:blue colour:red meta.attr.greyscale=1 \
		-filter data_show:%example.properties

	This will cause the second colour to be treated by the greyscale effect.

	Obviously, most of the examples in etv.properties are much more complex.
	For example, the 'location' attribute is defined as follows:

		location=region
		.description=Titles
		.properties.markup=filter[1].producer.text
		.properties.font=filter[1].producer.font
		.properties.size=filter[1].producer.size
		.period=2
		.properties.length[0]=composite.out
		.composite.geometry=0,80:230x30:0;12=,:x:100
		.composite.luma=%luma01.pgm
		.composite.softness=.3
		.filter[0]=watermark
		.filter[0].resource=colour:0x6c0101ff
		.filter[1]=watermark
		.filter[1].resource=pango:
		.filter[1].producer.text=
		.filter[1].producer.font=Sans
		.filter[1].producer.size=24
		.filter[1].composite.geometry=0,0:95%x100%
		.filter[1].composite.titles=1
		.filter[1].composite.halign=right
		.filter[1].composite.valign=center

	The lines beginning with .properties dictate the names of additional 
	properties that can be accepted from the feed and how they're handled. 

	.properties.length[0] is a special case - it is handled internally.

	In this case, the following inigo command would activate the effect:

		inigo colour:red meta.attr.location=1 \
		meta.attr.location.markup=Hello \
		meta.attr.location.font=Embargo \
		meta.attr.location.size=32 \
		-filter data_show:%etv.properties
	
	All shotcut attributes assume these 3 properties are available and they
	are assigned to the cut - in the current implementation of shotcut, it is not
	possible to collect different properties via the GUI and pass them though
	on the feed.

	The remaining properties are standard to the 'region' filter which is 
	defined in the MLT 'services.txt' document.

	Supers are defined in a similar way, except their properties are as follows:

		super=region
		.description=Transcription
		.properties.0=filter[1].producer.text
		.properties.1=filter[2].producer.text
		.properties.align=filter[1].composite.valign
		.properties.weight=filter[1].producer.weight
		.properties.f0=filter[1].producer.font
		.properties.s0=filter[1].producer.size
		.properties.f1=filter[2].producer.font
		.properties.s1=filter[2].producer.size

	(the remainder of definition can be found in mlt/src/modules/feeds/PAL/etv.properties).

	These property names are very terse so a quick explaination is required:

		0 = the text on the top
		f0 = font of the top
		s0 = size of the top font
		1 = text on the bottom
		f1 = font of the bottom
		s1 = size of the bottom font
		align = vertical alignment of the top (special case - allows Single Line supers).
		weight = specificies the weight of the top super

	As an example:

		inigo colour:red meta.attr.super=1 \
		meta.attr.super.0=Hello \
		meta.attr.super.1=There \
		-filter data_show:%etv.properties
	
	Note that we don't need to supply all properties values to use the supers, but 
	again, the current implementation assumes the properties and their meanings.

