--- /dev/null
+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. This document does not duplicate the information in services.txt.
+
+Terminoligy:
+
+ '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 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 show 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.
+
projects / melted / blobdiff