+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.
+ 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.
+ 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 ] * ]
+ [ -filter filter[:arg] [ name=value ] * ]
+ [ -attach filter[:arg] [ name=value ] * ]
+ [ -mix length [ -mixer transition ]* ]
[ -transition id[:arg] [ name=value ] * ]
[ -blank frames ]
[ -track ]
+ [ -split relative-frame ]
+ [ -join clips ]
+ [ -repeat times ]
[ producer [ name=value ] * ]+
- [ -serialise file.inigo ]
General rules:
2. Error checking on command line parsing is weak;
- 3. Please refer to services.txt for details on services
- available;
+ 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.
+ 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...].
+ '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.
+ '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.
+ '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.
+ '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 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.
+ 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).
+
+ 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:
+ 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.
+ 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:
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
+ 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
Groups:
- The -group switch is provided to force default properties on the
- following 'services'. For example:
+ 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.
+ 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:
+ 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).
+ 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
+Attached Filters:
+
+ As described above, the -filter switch applies filters to an entire track. To
+ localise filters to a specific clip on a track, you have to know information
+ about the lengths of the clip and all clips leading up to it. In practise,
+ this is horrifically impractical, especially at a command line level (and not
+ even that practical from a programing point of view...).
+
+ The -attach family of switches simplify things enormously. By default, -attach
+ will attach a filter to the last service created, so:
+
+ $ inigo clip1.dv clip2.dv -attach greyscale clip3.dv
+
+ would only apply the filter to clip2.dv. You can further narrow down the area of
+ the effect by specifying in/out points on the attached filter.
+
+ This might seem simple so far, but there is a catch... consider the following:
+
+ $ ingo clip1.dv -attach watermark:+hello.txt -attach invert
+
+ The second attached filter is actually attached to the watermark. You might
+ think, yay, nice (and it is :-)), but, it might not be what you want. For example
+ you might want to attach both to clip1.dv. To do that, you can use:
+
+ $ ingo clip1.dv -attach-cut watermark:+hello.txt -attach-cut invert
+
+ As you shall see below, there are still another couple of gotchas associated to
+ -attach, and even another variant :-).
+
+
+Mixes:
+
+ The -mix switch provides the simplest means to introduce transitions between
+ adjacent clips.
+
+ For example:
+
+ $ inigo clip1.dv clip2.dv -mix 25 -mixer luma -mixer mix:-1
+
+ would provide both an audio and video transition between clip1 and clip2.
+
+ This functionality supercedes the enforced use of the -track and -transition
+ switches from earlier versions of inigo and makes life a lot easier :-).
+
+ These can be used in combination, so you can for example do a fade from black
+ and to black using the following:
+
+ $ inigo colour:black out=24 clip1.dv -mix 25 -mixer luma \
+ colour:black out=24 -mix 25 -mixer luma
+
+ while this may not be immediately obvious, consider what's happening as the
+ command line is being parsed from left to right:
+
+ Input: Track
+ ----------------------- -----------------------------------------------------
+ colour:black out=24 [black]
+ clip1.dv [black][clip1.dv]
+ -mix 25 [black+clip1.dv][clip1.dv]
+ -mixer luma [luma:black+clip1.dv][clip1.dv]
+ colour:black out=24 [luma:black+clip1.dv][clip1.dv][black]
+ -mix 25 [luma:black+clip1.dv][clip1.dv][clip1.dv+black]
+ -mixer luma [luma:black+clip1.dv][clip1.dv][luma:clip1.dv+black]
+
+ Obviously, the clip1.dv instances refer to different parts of the clip, but
+ hopefully that will demonstrate what happens as we construct the track.
+
+ You will find more details on the mix in the framework.txt.
+
+
+Mix and Attach:
+
+ As noted, -attach normally applies to the last created service - so, you can
+ attach a filter to the transition region using:
+
+ $ inigo clip1.dv clip2.dv -mix 25 -mixer luma -attach watermark:+Transition.txt
+
+ Again, nice, but take care - if you want the attached filter to be associated
+ to the region following the transition, use -attach-cut instead.
+
+
+Splits, Joins, Removes and Swaps:
+
+ COMPLEX - needs simplification....
+
+
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
+ 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 in=0 out=49 -track b.dv
+ $ 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 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:
+ |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
Reversing a Transition:
- When we visualise a track definition, we also see situtations
+ When we visualise a track definition, we also see situations
like:
+-------+ +----------+
projects / mlt / blobdiff