westley/libxml2 mods, mcdv/mpeg release integration

[melted] / docs / inigo.txt

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 ]
              [ 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 [yes, 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.
        
        '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).


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, but it doesn't mean they
        will 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


Filters:

        The Multiple Files examples above will logically playout one
        after the other. 
        
        However, inigo doesn't care too much about changes in frame
        dimensions or audio specification, so you may need to add
        additional normalising filters to that, ie:
        
        $ inigo a.dv b.mpg c.png -filter resize -filter resample
        
        These filters are designed to guarantee that the consumer gets
        what it asks for.

        It should also be stressed that filters are applied in the order
        in which they're specified.


Filter Properties:

        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 'lowest 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 in=0 out=49 -track b.dv
        
        This can be visualised as follows:
        
        +-------+
        |a      |
        +-------+----------+
        |b                 |
        +------------------+
        
        Playout will show the first 50 frames of a and the 51st frame
        shown will be the 51st frame of b.
        
        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 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 -transition luma in=25 out=49 \
                -track \
                -blank 24 b.dv
        
        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 \
                        -transition luma in=25 out=49 \
                -transition luma in=100 out=124 reverse=1 \
                -track \
                -blank 24 b.dv out=99


Filters and Tracks:

        A filter applies to a [specified region of a] single track, so
        normalisation filters need to be applied to each track when
        applicable.
        
        This user specification is a necessary evil (you do not want to
        resize a text or png overlay to be the size of the frame that
        the consumer is requesting, and you may not want to unecessarily
        resize a video track if you will be later rescaling it for
        composition).


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....


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 feature.... 
        
        A -post switch will be added to provided this feature at some
        point soon.