diff options
Diffstat (limited to 'DOCS')
-rw-r--r-- | DOCS/edl-mpv.rst | 94 |
1 files changed, 94 insertions, 0 deletions
diff --git a/DOCS/edl-mpv.rst b/DOCS/edl-mpv.rst new file mode 100644 index 0000000000..611182b003 --- /dev/null +++ b/DOCS/edl-mpv.rst @@ -0,0 +1,94 @@ +EDL files +========= + +EDL files basically concatenate ranges of video/audio from multiple source +files into a single continuous virtual file. Each such range is called a +segment, and consists of source file, source offset, and segment length. + +For example:: + + mpv EDL v0 + f1.mkv,10,20 + f2.mkv + f1.mkv,40,10 + +This would skip the first 10 seconds of the file f1.mkv, then play the next +20 seconds, then switch to the file f2.mkv and play all of it, then switch +back to f1.mkv, skip to the 40 second mark, and play 10 seconds, and then +stop playback. The difference to specifying the files directly on command +line (and using ``--{ --start=10 --length=20 f1.mkv --}`` etc.) is that the +virtual EDL file appears as a single file, instead as a playlist. + +The general simplified syntax is: + + <filename> + <filename>,<start in seconds>,<length in seconds> + +If the start time is omitted, 0 is used. If the length is omitted, the +estimated duration of the source file is used. + +Note:: + + mpv can't use ordered chapter files or libquvi-resolved URLs in EDL + entries. Usage of relative or absolute paths as well as any protocol + prefixes is prevented for security reasons. + + +Syntax of mpv EDL files +======================= + +Generally, the format is relatively strict. No superfluous whitespace (except +empty lines and commented lines) are allowed. You must use UNIX line breaks. + +The first line in the file must be ``mpv EDL v0``. This designates that the +file uses format version 0, which is not frozen yet and may change any time. +(If you need a stable EDL file format, make a feature request. Likewise, if +you have suggestions for improvements, it's not too late yet.) + +The rest of the lines belong to one of these classes: + +1) An empty or commented line. A comment starts with ``#``, which must be the + first character in the line. The rest of the line (up until the next line + break) is ignored. An empty line has 0 bytes between two line feed bytes. +2) A segment entry in all other cases. + +Each segment entry consists of a list of named or unnamed parameters. +Parameters are separated with ``,``. Named parameters consist of a name, +followed by ``=``, followed by the value. Unnamed parameters have only a +value, and the name is implicit from the parameter position. + +Syntax:: + + segment_entry ::= <param> ( <param> ',' )* + param ::= [ <name> '=' ] ( <value> | '%' <number> '%' <valuebytes> ) + +The ``name`` string can consist of any characters, except ``=%,;\n``. The +``value`` string can consist of any characters except to ``,;\n``. + +The construct starting with ``%`` allows defining any value with arbitrary +contents inline, where ``number`` is an integer giving the number of bytes in +``valuebytes``. If a parameter value contains disallowed characters, it has to +be guarded by a length specifier using this syntax. + +The parameter name defines the meaning of the parameter: + +1) ``file``, the source file to use for this segment. +2) ``start``, a time value that specifies the start offset into the source file. +3) ``length``, a time value that specifies the length of the segment. + +(Currently, time values are floating point values in seconds.) + +Unnamed parameters carry implicit names. The parameter position determines +which of the parameters listed above is set. For example, the second parameter +implicitly uses the name ``start``. + +Example:: + + mpv EDL v0 + %18%filename,with,.mkv,10,length=20,param3=%13%value,escaped,param4=value2 + +this sets ``file`` to ``filename,with,.mkv``, ``start`` to ``10``, ``length`` +to ``20``, ``param3`` to ``value,escaped``, ``param4`` to ``value2``. + +Instead of line breaks, the character ``;`` can be used. Line feed bytes and +``;`` are treated equally. |