X-Git-Url: http://research.m1stereo.tv/gitweb?a=blobdiff_plain;f=docs%2Fwestley.txt;h=1f42538d091be2e2d0558128eef7fa07b1573a63;hb=f4963a6aa07644399b273b5d2b1f9299c9047414;hp=2d5e29196ee016d3571c52af6cde6e498ca6d040;hpb=72245f174372601b158fda2dc4a2e3f936ea0381;p=melted diff --git a/docs/westley.txt b/docs/westley.txt index 2d5e291..1f42538 100644 --- a/docs/westley.txt +++ b/docs/westley.txt @@ -1,10 +1,22 @@ +Westley Documentation + +Copyright (C) 2004 Ushodaya Enterprised Limited +Authors: Charles Yates +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: @@ -173,9 +185,6 @@ Interlude - Introducing Multitracks: 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: @@ -231,9 +240,10 @@ 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: @@ -278,8 +288,60 @@ Tractors: 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. + + + + clip1.dv + + + + + + clip2.mpeg + + + + + + + + + + + + 0 + 1 + luma + + + 0 + 1 + mix + 0.0 + 1.0 + + + + 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 + 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: @@ -411,50 +473,102 @@ Flexibility: any embedded XML that contains an element named "property" because westley collects embedded XML until it reaches a closing property tag. - TODO: xml entities - + +Entities and Parameterisation: + + The westley producer parser supports XML entities. An example: + + + + ]> + + + pango + &msg; + + + + 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. + -Technique: +Tips and 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... - - + + + + + ...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 + 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... - - + + + + + + ...add a playlist for each track... + + ...add filters and transitions... + + + + + + + ...add a playlist for each track... + + ...add filters and transitions... + + + + 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 last track simply . Then, - use composite and volume key-framable properties. - TODO: to be continued + then make the top track simply . Then, + use composite and volume effects. See the "Fade from/to black/silence" + demo for an example (demo/mlt_fade_black). - TODO: considerations with mixing multiple audio layers + 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).