X-Git-Url: http://research.m1stereo.tv/gitweb?a=blobdiff_plain;f=docs%2Fwestley.txt;h=2d5e29196ee016d3571c52af6cde6e498ca6d040;hb=3b9de6081136b2a28bf7a6f85354ec04d92065bb;hp=89e59288d82cc7768e8a3bf5cf84105d08ee03b0;hpb=2a800ec4c840132c7a629b764b673dce09771637;p=melted diff --git a/docs/westley.txt b/docs/westley.txt index 89e5928..2d5e291 100644 --- a/docs/westley.txt +++ b/docs/westley.txt @@ -279,3 +279,182 @@ Tractors: placed between all producers and the consumer). TODO: transition example + + +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: + + + + + + + + + clip1.dv + + + + + + + + + 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 , , and 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: + + + + + + clip1.dv + + + + + + Yes, filters and transitions can be added to the above example after the + closing multitrack tag () 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 or , then the edit points apply to the playlist + entry and not to the producer itself. This facilitates re-use of media: + + + + clip1.dv + + + + + 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: + + + + + + clip2.mpeg + + + + + + + + clip3.mpeg + + + + + + + + + + + + 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: + + ... ]]> + + 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: + + + + + + + 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. + + TODO: xml entities + + +Technique: + + If one finds the above hierarchical, abbreviated format intuitive, + start with a simple template and fill and extend as needed: + + + + + ...add a playlist for each track... + + ...add filters and transitions... + + + 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 or later add when necessary. + + A more advanced template that allows sequencing multitracks is: + + + + + + ...add a playlist for each track... + + ...add filters and transitions... + + + + + + + ...add a playlist for each track... + + ...add filters and transitions... + + + + If you want to have a silent, black background for audio and video fades, + then make the last track simply . Then, + use composite and volume key-framable properties. + TODO: to be continued + + TODO: considerations with mixing multiple audio layers