X-Git-Url: http://research.m1stereo.tv/gitweb?a=blobdiff_plain;f=docs%2Finigo.txt;h=854c1c12d086422134297247b1b15f4543565ff8;hb=bcbe5ecf7001335895da8be92518f4645977a839;hp=0ea0b93e1d56985507466c63e46a34d8dd2496a9;hpb=16c5c516008b9debec7765e34f4756f8063dee7e;p=melted diff --git a/docs/inigo.txt b/docs/inigo.txt index 0ea0b93..854c1c1 100644 --- a/docs/inigo.txt +++ b/docs/inigo.txt @@ -1,26 +1,60 @@ +Inigo Documentation + +Copyright (C) 2004-2009 Ushodaya Enterprised Limited +Author: Charles Yates +Last Revision: 2009-01-21 + + 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 ] * ] - [ -transition id[:arg] [ name=value ] * ] - [ -blank frames ] - [ -track ] - [ producer [ name=value ] * ]+ - [ -serialise file.inigo ] + inigo [options] [producer [name=value]* ]+ + Options: + -attach filter[:arg] [name=value]* Attach a filter to the output + -attach-cut filter[:arg] [name=value]* Attach a filter to a cut + -attach-track filter[:arg] [name=value]* Attach a filter to a track + -attach-clip filter[:arg] [name=value]* Attach a filter to a producer + -audio-track | -hide-video Add an audio-only track + -blank frames Add blank silence to a track + -consumer id[:arg] [name=value]* Set the consumer (sink) + -debug Set the logging level to debug + -filter filter[:arg] [name=value]* Add a filter to the current track + -group [name=value]* Apply properties repeatedly + -help Show this message + -join clips Join multiple clips into one cut + -mix length Add a mix between the last two cuts + -mixer transition Add a transition to the mix + -null-track | -hide-track Add a hidden track + -profile name Set the processing settings + -progress Display progress along with the position + -remove Remove the most recent cut + -repeat times Repeat the last cut + -query List all of the registered services + -query "consumers" | "consumer"=id List consumers or show info about one + -query "filters" | "filter"=id List filters or show info about one + -query "producers" | "producer"=id List producers or show info about one + -query "transitions" | "transition"=id List transitions or show info about one + -serialise [filename] Write the commands to a text file + -silent Do not display position/transport help + -split relative-frame Split the last cut into two cuts + -swap Rearrange the last two cuts + -track Add a track + -transition id[:arg] [name=value]* Add a transition + -verbose Set the logging level to verbose + -version Show the version and copyright message + -video-track | -hide-audio Add a video-only track General rules: @@ -29,47 +63,43 @@ 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. -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: @@ -77,25 +107,29 @@ 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: @@ -108,88 +142,171 @@ 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 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 @@ -202,8 +319,8 @@ Introducing Tracks and Blanks: +-------------------+ 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: @@ -213,9 +330,10 @@ 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: @@ -232,7 +350,7 @@ Transitions: Reversing a Transition: - When we visualise a track definition, we also see situtations + When we visualise a track definition, we also see situations like: +-------+ +----------+ @@ -246,23 +364,10 @@ Reversing a Transition: 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: @@ -275,14 +380,22 @@ 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