test not only if header frei0r.h exists, also use an item

[mlt-frei0r-support.git] / shotcut / docs / templates.txt

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.