+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 ego-centric. Producers produce
- MLT frame objects and consumers consume MLT frame objects.
- The distinction is important - a DV producer does not produce
- DV and a DV consumer does not consume DV.
+ 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.
-Terminoligy:
+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, but it doesn't mean they
- will 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:
$ 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:
-
- 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.
+Filters:
+ Filters are frame modifiers - they can change the contents of the audio or
+ the images associated to a frame.
-Filter Properties:
+ $ 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:
+ 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.
+ 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:
+ 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.
+ 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 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
+-------------------+
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).
+ same track (which on its own, is about as useful as reversing the
+ process of slicing bread).
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 \
+ $ inigo a.dv out=49 \
-track \
- -blank 24 b.dv
+ -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:
Reversing a Transition:
- When we visualise a track definition, we also see situtations
+ When we visualise a track definition, we also see situations
like:
+-------+ +----------+
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).
+ -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:
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 feature....
+ 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....
- A -post switch will be added to provided this feature at some
- point soon.
+ 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
projects / mlt / blobdiff