a clarification

[mlt] / docs / inigo.txt

Inigo Documentation

Copyright (C) 2004 Ushodaya Enterprised Limited
Author: Charles Yates <charles.yates@pandora.be>
Last Revision: 2004-03-20


INIGO
-----

Preamble:

        inigo was developed as a test tool for the MLT framework. It can be thought
        of as a powerful, if somewhat obscure, multitrack command line oriented 
        video editor.

        The following details the usage of the tool and as a result, provides a lot 
        of insight into the workings of the MLT framework.


Usage:

        inigo [ -group [ name=value ]* ]
              [ -consumer id[:arg] [ name=value ]* ]
              [ -filter id[:arg] [ name=value ] * ]
              [ -transition id[:arg] [ name=value ] * ]
              [ -blank frames ]
              [ -track | -hide-track | -hide-video | -hide-audio ]
              [ producer [ name=value ] * ]+
              [ -serialise file.inigo ]


General rules:

        1. Order is incredibly important;

        2. Error checking on command line parsing is weak;

        3. Please refer to services.txt for details on services available;

        4. The MLT framework, from which inigo has inherited its naming convention,
        is very mlt-centric. Producers produce MLT frame objects and consumers 
        consume MLT frame objects.  The distinction is important - a DV producer 
        does not produce DV, it produces MLT frames from a DV source, and similarly
        a DV consumer does not consume DV, it consumes MLT frames and produces DV
        frames.


Terminology:

        'Producers' typically refer to files but may also indicate devices (such as
        dv1394 input or video4linux). Hence, the more generic term is used [the more 
        generic usage is out of scope for now...].

        'Filters' are frame modifiers - they always guarantee that for every frame 
        they receive, they output *precisely* one frame.  Never more, never less, 
        ever. Nothing says that a filter cannot generate frames though
        
        'Transitions' collect frames from two tracks (a and b) and output 1 
        modified frame on their 'a track', and 1 unmodified frame on their 'b track'.
        Never more, never less, ever.
        
        'Consumers' collect frames from a producer, do something with them and
        destroy them.
        
        Collectively, these are known as 'services'. 
        
        All services have 'properties' associated to them. These are typically
        defaulted or evaluated and may be overriden on a case by case basis.
        
        All services except consumers obey in and out properties.
        
        Consumers have no say in the flow of frames [though they may give the
        illusion that they do]. They get frames from a connected producer, use them, 
        destroy them and get more.


Basics:

        To play a file with the default SDL PAL consumer, usage is:
        
        $ inigo file

        Note that 'file' can be anything that inigo has a known 'producer' mapping 
        for (so this can be anything from .dv to .txt).

        You can also specify the producer directly, for example:

        $ inigo avformat:file.mpeg

        Would force the direct use of avformat for loading the file.


Properties:

        Properties can be assigned to the producer by adding additional name=value
        pairs after the producer:
        
        $ inigo file in=50 out=100 something="something else"
        
        Note that while some properties have meaning to all producers (for example:
        in, out and length are guaranteed to be valid for all, though typically, 
        length is determined automatically), the validity of others are dependent on 
        the producer - however, properties will always be assigned and silently 
        ignored if they won't be used.


Multiple Files:

        Multiple files of different types can be used:
        
        $ inigo a.dv b.mpg c.png
        
        Properties can be assigned to each file:
        
        $ inigo a.dv in=50 out=100 b.mpg out=500 c.png out=500

        MLT will take care of 'normalising' the output of a producer to ensure
        that the consumer gets what it needs. So, in the case above, the mlt
        framework will ensure that images are rescaled and audio resampled to meet
        the requirements of your configuration (which, by default, will be PAL).
        See 'Appendix A: Normalisation Rules' below.


Filters:

        Filters are frame modifiers - they can change the contents of the audio or
        the images associated to a frame.

        $ inigo a.dv -filter greyscale

        As with producers, properties may be specified on filters too.
        
        Again, in and out properties are common to all, so to apply a filter to a
        range of frames, you would use something like:
        
        $ inigo a.dv -filter greyscale in=0 out=50
        
        Again, filters have their own set of rules about properties and will
        silently ignore properties that do not apply.


Groups:

        The -group switch is provided to force default properties on the following
        'services'. For example:
        
        $ inigo -group in=0 out=49 clip*
        
        would play the first 50 frames of all clips that match the wild card
        pattern.
        
        Note that the last -group settings also apply to the following filters, 
        transitions and consumers, so:
        
        $ inigo -group in=0 out=49 clip* -filter greyscale
        
        is *probably not* what you want (ie: the greyscale filter would only be 
        applied to the first 50 frames).
        
        To shed the group properties, you can use any empty group:
        
        $ inigo -group in=0 out=49 clip* -group -filter greyscale


Introducing Tracks and Blanks:

        So far, all of the examples have shown the definition of a single
        playlist, or more accurately, track.

        When multiple tracks exist, the consumer will receive a frame
        from the 'highest numbered' track that is generating a non-blank
        frame.
        
        It is best to visualise a track arrangement, so we'll start with
        an example:
        
        $ inigo a.dv -track b.dv in=0 out=49
        
        This can be visualised as follows:
        
        +------------------+
        |a                 |
        +-------+----------+
        |b      |
        +-------+

        Playout will show the first 50 frames of b and the 51st frame shown will be
        the 51st frame of a.

        This rule also applies to audio only producers on the second track, for
        example, the following would show the video from the a track, but the audio
        would come from the second track:

        $ inigo a.dv -track b.mp3 in=0 out=49

        To have the 51st frame be the first frame of b, we can use the -blank switch:
        
        $ inigo a.dv out=49 -track -blank 49 b.dv
        
        Which we can visualise as:
        
        +-------+
        |a      |
        +-------+-------------------+
                |b                  |
                +-------------------+
        
        Now playout will continue as though a and b clips are on the
        same track (which on its own, is about as useful as reversing the 
        process of slicing bread).


Transitions:

        Where tracks become useful is in the placing of transitions.
        
        Here we need tracks to overlap, so a useful multitrack
        definition could be given as:
        
        $ inigo a.dv out=49 \
                -track \
                -blank 24 b.dv \
                -transition luma in=25 out=49 a_track=0 b_track=1
        
        Now we're cooking - our visualisation would be something like:
        
        +-------+
        |a      |
        +---+---+--------------+
            |b                 |
            +------------------+
        
        Playout will now show the first 25 frames of a and then a fade
        transition for 25 frames between a and b, and will finally
        playout the remainder of b.


Reversing a Transition:

        When we visualise a track definition, we also see situtations
        like:
        
        +-------+              +----------+
        |a1     |              |a2        |
        +---+---+--------------+----+-----+
            |b                      |
            +-----------------------+
        
        In this case, we have two transitions, a1 to b and b to a2. 
        
        In this scenario, we define a command line as follows:
        
        $ inigo a.dv out=49 -blank 49 a2.dv \
                -track \
                -blank 24 b.dv out=99 \
                -transition luma in=25 out=49 a_track=0 b_track=1 \
                -transition luma in=100 out=124 reverse=1 a_track=0 b_track=1


Serialisation:

        Inigo has a built in serialisation mechanism - you can build up
        your command, test it via any consumer and then add a -serialise
        file.inigo switch to save it.
        
        The saved file can be subsequently used as a clip by either
        miracle or inigo. Take care though - paths to files are saved as
        provided on the command line....

        A more expressive serialisation can be obtained with the westley consumer
        - this will provide an xml document which can be used freely in inigo and
        miracle.

        See westley.txt for more information.


Missing Features:

        Some filters/transitions should be applied on the output frame regardless
        of which track it comes from - for example, you might have a 3rd text 
        track or a watermark which you want composited on every frame, and of 
        course, there's the obscure filter.... 
        
        inigo only supports this in two invocations - as a simple example:

        $ inigo a.dv -track -blank 100 b.dv -consumer westley:basic.westley
        $ inigo basic.westley -filter watermark:watermark.png