X-Git-Url: http://research.m1stereo.tv/gitweb?a=blobdiff_plain;f=docs%2Finigo.txt;fp=docs%2Finigo.txt;h=0000000000000000000000000000000000000000;hb=17b5a97b9bbe00b442a58a5065498e67b497af09;hp=854c1c12d086422134297247b1b15f4543565ff8;hpb=f4963a6aa07644399b273b5d2b1f9299c9047414;p=melted diff --git a/docs/inigo.txt b/docs/inigo.txt deleted file mode 100644 index 854c1c1..0000000 --- a/docs/inigo.txt +++ /dev/null @@ -1,401 +0,0 @@ -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. - - 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 [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: - - 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 [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. 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. - - '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). - - 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: - - $ 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. - - -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 - - 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: - - Filters are frame modifiers - they can change the contents of the audio or - the images associated to a frame. - - $ 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: - - $ 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 - - -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 '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 -track b.dv in=0 out=49 - - This can be visualised as follows: - - +------------------+ - |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 - - Which we can visualise as: - - +-------+ - |a | - +-------+-------------------+ - |b | - +-------------------+ - - Now playout will continue as though a and b clips are on the - same track (which on its own, 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 \ - -track \ - -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: - - +-------+ - |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 situations - 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 \ - -track \ - -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: - - 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.... - - 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 filter.... - - 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 -