+Westley Documentation
+
+Copyright (C) 2004 Ushodaya Enterprised Limited
+Authors: Charles Yates <charles.yates@pandora.be>
+Last Revision: 2004-03-20
+
+
WESTLEY
-------
Preamble:
Westley is the MLT projects XML serialisation/deserialisation format -
- as such, it closely mirrors the internal structure of the MLT API.
+ as such, it closely mirrors the internal structure of the MLT API.
+
+ If you just want to go straight to the DTD, then see
+ mlt/src/modules/westley/westley.dtd, which gets installed at
+ $(prefix)/share/mlt/modules/westley.dtd. Currently, the westley parser is
+ non-validating.
Introduction:
appear to be an exception - it isn't - it simply has a route back to the
application to allow the application to interpret key presses).
- Whether this is better or worse than a traditional graph approach is a moot
- point. The author of this document likes it anyway :-).
-
Tractors:
Note that it's only applied to the visible parts of the top track.
- The requirement to apply a filter to the output, as opposed to a specific track
- leads us to the final item in the Rules section above. As an example, let's
- assume we wish to watermark all output, then we could use the following:
+ The requirement to apply a filter to the output, as opposed to a specific
+ track leads us to the final item in the Rules section above. As an example,
+ let's assume we wish to watermark all output, then we could use the
+ following:
<westley>
<producer id="producer0">
be better handled at the playout stage itself (ie: as a filter automatically
placed between all producers and the consumer).
- TODO: transition example
+ Tracks act like "layers" in an image processing program like the GIMP. The
+ bottom-most track takes highest priority and higher layers are overlays
+ and do not appear unless there are gaps in the lower layers or unless
+ a transition is applied that merges the tracks on the specifed region.
+ Practically speaking, for A/B video editing it does not mean too much,
+ and it will work as expected; however, as a general rule apply any CGI
+ (graphic overlays with pixbuf or titles with pango) on tracks higher than
+ your video tracks. Also, this means that any audio-only tracks that are
+ lower than your video tracks will play rather than the audio from the video
+ clip. Remember, nothing is affected like mixing or compositing until one
+ applies a transition or appropriate filter.
+
+ <westley>
+ <producer id="producer0">
+ <property name="resource">clip1.dv</property>
+ </producer>
+ <playlist id="playlist0">
+ <entry producer="producer0"/>
+ </playlist>
+ <producer id="producer1">
+ <property name="resource">clip2.mpeg</property>
+ </producer>
+ <playlist id="playlist1">
+ <blank length="50"/>
+ <entry producer="producer1"/>
+ </playlist>
+ <tractor id="tractor0" in="0" out="315">
+ <multitrack id="multitrack0">
+ <track producer="playlist0"/>
+ <track producer="playlist1"/>
+ </multitrack>
+ <transition id="transition0" in="50" out="74">
+ <property name="a_track">0</property>
+ <property name="b_track">1</property>
+ <property name="mlt_service">luma</property>
+ </transition>
+ <transition id="transition1" in="50" out="74">
+ <property name="a_track">0</property>
+ <property name="b_track">1</property>
+ <property name="mlt_service">mix</property>
+ <property name="start">0.0</property>
+ <property name="end">1.0</property>
+ </transition>
+ </tractor>
+ </westley>
+
+ A "luma" transition is a video wipe processor that takes a greyscale bitmap
+ for the wipe definition. When one does not specify a bitmap, luma performs
+ a dissolve. The "mix" transition does an audio mix, but it interpolates
+ between the gain scaling factors between the start and end properties -
+ in this example, from 0.0 (none of track B) to 1.0 (all of track B).
+ Because the bottom track starts out with a gap specified using the <blank>
+ element, the upper track appears during the blank segment. See the demos and
+ services.txt to get an idea of the capabilities of the included transitions.
+
+Flexibility:
+
+ The information presented above is considered the MLT Westley "normal"
+ form. This is the output generated by the westley consumer, for example,
+ when used with inigo. It is the output generated when you use the
+ "Westley to File" consumer in the demo script, which beginners will find
+ most useful for learning to use westley XML. This section describes
+ alternative forms the westley producer accepts.
+
+ First of all, the normal form is more of a linear format with producers
+ and playlists defined prior to their usage in a multitrack. Westley
+ also accepts a hierarchical format with producers as children of tracks
+ or playlist entries and with playlists as children of tracks:
+
+ <westley>
+ <tractor>
+ <multitrack>
+ <track>
+ <playlist>
+ <entry>
+ <producer>
+ <property name="resource">clip1.dv</property>
+ </producer>
+ </entry>
+ </playlist>
+ </track>
+ </multitrack>
+ </tractor>
+ </westley>
+
+ Obviously, this example is meant to demonstrate hierarchy and not effective
+ use of playlist or multitrack!
+
+ Secondly, as part of error handling, westley is forgiving if you fail to
+ supply <tractor>, <track>, and <entry> where one can be understood. This
+ affords an abbreviated syntax that is less verbose and perhaps less
+ intimidating for a human to read and understand. One can simplify the
+ above example as:
+
+ <westley>
+ <multitrack>
+ <playlist>
+ <producer>
+ <property name="resource">clip1.dv</property>
+ </producer>
+ </playlist>
+ </multitrack>
+ </westley>
+
+ Yes, filters and transitions can be added to the above example after the
+ closing multitrack tag (</multitrack>) because it is still enclosed within
+ the westley body tags.
+
+ If you specify in and out on a producer and it has been enclosed within
+ an <entry> or <playlist>, then the edit points apply to the playlist
+ entry and not to the producer itself. This facilitates re-use of media:
+
+ <playlist>
+ <producer id="clip1" in="25" out="78">
+ <property name="resource">clip1.dv</property>
+ </producer>
+ <entry producer="clip1" in="119" out="347"/>
+ </playlist>
+
+ In the above example, the producer attribute of the entry element is
+ a reference to the preceding producer. All references must follow the
+ definition. The edit points supplied on the producer above will not affect
+ the entry that references it below because westley knows the clip is a
+ playlist entry and optimises this situation. The advantage is that one
+ does not need to determine every clip to be included ahead of time
+ and specify them outside the context of the mutlitrack timeline.
+
+ This form of authoring will be easier for many to visualise as a non-linear
+ editor's timeline. Here is a more complex example:
+
+ <westley>
+ <multitrack>
+ <playlist>
+ <producer id="foo" in="100" out="149">
+ <property name="resource">clip2.mpeg</property>
+ </producer>
+ <blank length="25"/>
+ <entry producer="foo" in="10" out="59"/>
+ </playlist>
+ <playlist>
+ <blank length="25"/>
+ <producer id="bar" in="100" out="199">
+ <property name="resource">clip3.mpeg</property>
+ </producer>
+ <entry out="99" producer="bar"/>
+ </playlist>
+ </multitrack>
+ <filter mlt_service="greyscale" track="0"/>
+ <transition mlt_service="luma" in="25" out="49" a_track="0" b_track="1"/>
+ <transition mlt_service="luma" in="75" out="99" a_track="0" b_track="1">
+ <property name="reverse" value="1"/>
+ </transition>
+ </westley>
+
+ Did you notice something different in the last example? Properties can be
+ expressed using XML attributes on the element as well. However, only
+ non-service-specific properties are supported in this way. For example,
+ "mlt_service" is available to any producer, filter, or transition. However,
+ "resource" is actually service-specific. Notice the syntax of the last
+ property, on the last transition. Westley accepts property values using
+ the "value" attribute as well as using element text.
+
+ We have seen a few different ways of expressing property values. There are
+ a couple more for properties that can accept XML data. For example, the
+ GDK pixbuf producer with librsvg can handle embedded SVG, and the Pango
+ producer can handle embedded Pango markup. You can enclose the embedded XML
+ using a CDATA section:
+
+ <property name="resource"><![CDATA[ <svg>...</svg> ]]></property>
+
+ Please ensure the opening CDATA tag immediately follows the opening
+ property tag and that the section closing tag immediately precedes the
+ closing property tag.
+
+ However, westley can also accept inline embedded XML:
+
+ <property name="resource">
+ <svg>
+ </svg>
+ </property>
+
+ Currently, there is no namespace handling so a conflict will occur only on
+ any embedded XML that contains an element named "property" because
+ westley collects embedded XML until it reaches a closing property tag.
+
+
+Entities and Parameterisation:
+
+ The westley producer parser supports XML entities. An example:
+
+ <?xml version="1.0"?>
+ <!DOCTYPE westley [
+ <!ENTITY msg "Hello world!">
+ ]>
+ <westley>
+ <producer id="producer0">
+ <property name="mlt_service">pango</property>
+ <property name="text">&msg;</property>
+ </producer>
+ </westley>
+
+ If you are embedding another XML document into a property value not using
+ a CNODE section, then any DOCTYPE section must be relocated before any of
+ the xml elements to be well-formed. See demo/svg.westley for an example.
+
+ Entities can be used to parameterise westley! Using the above example, the
+ entity declared serves as the default value for &msg;. The entity content
+ can be overridden from the resource property supplied to the westley
+ producer. The syntax is the familiar, url-encoded query string used with
+ HTTP, e.g.: file?name=value&name=value...
+
+ There are a couple of rules of usage. The Miracle LOAD command and inigo
+ command line tool require you to preface the URL with "westley:" because
+ the query string destroys the filename extension matching peformed by
+ Fezzik. Also, inigo looks for '=' to tokenise property settings. Therefore,
+ one uses ':' between name and value instead of '='. Finally, since inigo
+ is run from the shell, one must enclose the URL within single quotes to
+ prevent shell filename expansion, or similar.
+
+ Needless to say, the ability to parameterise westley XML compositions is
+ an extremely powerful tool. An example for you to play with is available in
+ demo/entity.westley. Try overriding the name from inigo:
+ inigo 'westley:entity.westley?name:Charlie'
+
+ Technically, the entity declaration is not needed in the head of the XML
+ document if you always supply the parameter. However, you run the risk
+ of unpredictable behviour without one. Therefore, it is safest and a best
+ practice to always supply an entity declaration. It is improves the
+ readability as one does not need to search for the entity references to
+ see what parameters are available.
+
+
+Tips and Technique:
+
+ If one finds the above hierarchical, abbreviated format intuitive,
+ start with a simple template and fill and extend as needed:
+ <westley>
+ <multitrack>
+ <playlist>
+ </playlist>
+ ...add a playlist for each track...
+ </multitrack>
+ ...add filters and transitions...
+ </westley>
+
+ By using a playlist for each track, it is easier to iteratively add new
+ clips and blank regions as you develop the project. You will not have to
+ use <track> or later add <playlist> when necessary.
+
+ A more advanced template that allows sequencing multitracks is:
+ <playlist>
+ <entry>
+ <multitrack>
+ <playlist>
+ </playlist>
+ ...add a playlist for each track...
+ </multitrack>
+ ...add filters and transitions...
+ </entry>
+
+ <entry>
+ <multitrack>
+ <playlist>
+ </playlist>
+ ...add a playlist for each track...
+ </multitrack>
+ ...add filters and transitions...
+ </entry>
+ </playlist>
+
+ If you end up making a collection of templates for various situations, then
+ consider using XML Entities to make the template more effective by moving
+ anything that should parameterised into an entity.
+
+ If you want to have a silent, black background for audio and video fades,
+ then make the top track simply <producer mlt_service="colour"/>. Then,
+ use composite and volume effects. See the "Fade from/to black/silence"
+ demo for an example (demo/mlt_fade_black).
+
+ If you apply the reverse=1 property to a transition like "luma," then
+ be careful because it also inherently swaps the roles of A and B tracks.
+ Therefore, you need to might need to swap the a_track and b_track values
+ if it did not turn out the way you expected. See the "Clock in and out"
+ for an example (demo/mlt_clock_in_and_out).
projects / mlt / blobdiff