diff options
Diffstat (limited to 'DOCS/edl-mpv.rst')
| -rw-r--r-- | DOCS/edl-mpv.rst | 144 |
1 files changed, 142 insertions, 2 deletions
diff --git a/DOCS/edl-mpv.rst b/DOCS/edl-mpv.rst index 46a25293aa..0e4d2b410e 100644 --- a/DOCS/edl-mpv.rst +++ b/DOCS/edl-mpv.rst @@ -146,7 +146,8 @@ The current implementation will Another header part of this mechanism is ``no_clip``. This header is similar to ``mp4_dash``, but does not include on-demand opening/closing of segments, and does not support init segments. It also exists solely to support internal -ytdl requirements. +ytdl requirements. Using ``no_clip`` with segments is not recommended and +probably breaks. ``mp4_dash`` already implicitly does a variant of ``no_clip``. The ``mp4_dash`` and ``no_clip`` headers are not part of the core EDL format. They may be changed or removed at any time, depending on mpv's internal @@ -182,6 +183,144 @@ this will use a unified cache for all streams. The ``new_stream`` header is not part of the core EDL format. It may be changed or removed at any time, depending on mpv's internal requirements. +If the first ``!new_stream`` is redundant, it is ignored. This is the same +example as above:: + + # mpv EDL v0 + !new_stream + video.mkv + !new_stream + audio.mkv + +Note that ``!new_stream`` must be the first header. Whether the parser accepts +(i.e. ignores) or rejects other headers before that is implementation specific. + +Track metadata +============== + +The special ``track_meta`` header can set some specific metadata fields of the +current ``!new_stream`` partition. The tags are applied to all tracks within +the partition. It is not possible to set the metadata for individual tracks (the +feature was needed only for single-track media). + +It provides following parameters change track metadata: + +``lang`` + Set the language tag. + +``title`` + Set the title tag. + +``byterate`` + Number of bytes per second this stream uses. (Purely informational.) + +``index`` + The numeric index of the track this should map to (default: -1). This is + the 0-based index of the virtual stream as seen by the player, enumerating + all audio/video/subtitle streams. If nothing matches, this is silently + discarded. The special index -1 (the default) has two meanings: if there + was a previous meta data entry (either ``!track_meta`` or ``!delay_open`` + element since the last ``!new_stream``), then this element manipulates + the previous meta data entry. If there was no previous entry, a new meta + data entry that matches all streams is created. + +Example:: + + # mpv EDL v0 + !track_meta,lang=bla,title=blabla + file.mkv + !new_stream + !track_meta,title=ducks + sub.srt + +If ``file.mkv`` has an audio and a video stream, both will use ``blabla`` as +title. The subtitle stream will use ``ducks`` as title. + +The ``track_meta`` header is not part of the core EDL format. It may be changed +or removed at any time, depending on mpv's internal requirements. + +Global metadata +=============== + +The special ``global_tags`` header can set metadata fields (aka tags) of the EDL +file. This metadata is supposed to be informational, much like for example ID3 +tags in audio files. Due to lack of separation of different kinds of metadata it +is unspecified what names are allowed, how they are interpreted, and whether +some of them affect playback functionally. (Much of this is unfortunately +inherited from FFmpeg. Another consequence of this is that FFmpeg "normalized" +tags are recognized, or stuff like replaygain tags.) + +Example:: + + !global_tags,title=bla,something_arbitrary=even_more_arbitrary + +Any parameter names are allowed. Repeated use of this adds to the tag list. If +``!new_stream`` is used, the location doesn't matter. + +May possibly be ignored in some cases, such as delayed media opening. + +Delayed media opening +===================== + +The special ``delay_open`` header can be used to open the media URL of the +stream only when the track is selected for the first time. This is supposed to +be an optimization to speed up opening of a remote stream if there are many +tracks for whatever reasons. + +This has various tricky restrictions, and also will defer failure to open a +stream to "later". By design, it's supposed to be used for single-track streams. + +Using multiple segments requires you to specify all offsets and durations (also +it was never tested whether it works at all). Interaction with ``mp4_dash`` may +be strange. + +You can describe multiple sub-tracks by using multiple ``delay_open`` headers +before the same source URL. (If there are multiple sub-tracks of the same media +type, then the mapping to the real stream is probably rather arbitrary.) If the +source contains tracks not described, a warning is logged when the delayed +opening happens, and the track is hidden. + +This has the following parameters: + +``media_type`` + Required. Must be set to ``video``, ``audio``, or ``sub``. (Other tracks in + the opened URL are ignored.) + +``codec`` + The mpv codec name that is expected. Although mpv tries to initialize a + decoder with it currently (and will fail track selection if it does not + initialize successfully), it is not used for decoding - decoding still uses + the information retrieved from opening the actual media information, and may + be a different codec (you should try to avoid this, of course). Defaults to + ``null``. + + Above also applies for similar fields such as ``w``. These fields are + mostly to help with user track pre-selection. + +``flags`` + A ``+`` separated list of boolean flags. Currently defined flags: + + ``default`` + Set the default track flag. + + ``forced`` + Set the forced track flag. + + Other values are ignored after triggering a warning. + +``w``, ``h`` + For video codecs: expected video size. See ``codec`` for details. + +``fps`` + For video codecs: expected video framerate, as integer. (The rate is usually + only crudely reported, and it makes no sense to expect exact values.) + +``samplerate`` + For audio codecs: expected sample rate, as integer. + +The ``delay_open`` header is not part of the core EDL format. It may be changed +or removed at any time, depending on mpv's internal requirements. + Timestamp format ================ @@ -189,7 +328,8 @@ Currently, time values are floating point values in seconds. As an extension, you can set the ``timestamps=chapters`` option. If this option is set, timestamps have to be integers, and refer to chapter numbers, starting -with 0. +with 0. The default value for this parameter is ``seconds``, which means the +time is as described in the previous paragraph. Example:: |