Commit aca5d94f authored by Filip Roséen's avatar Filip Roséen Committed by Thomas Guillem

doc: document Media Resource Locator

There has never been any documentation related to what a MRL actually
is, these changes addresses that by (hopefully) describing the entity
in a way that makes it easier for future developers to treat them
Signed-off-by: Thomas Guillem's avatarThomas Guillem <>
parent 4d41eae3
* \defgroup mrl Media Resource Locator (MRL)
* The \em MRL-specification is a VLC intrinsic extension to <a
* href="">RFC3986</a>, providing means to
* associate extra media-related information within the \em resource-identifier.
* \note \em MRLs are only used when an item is to be played by \em VLC,
* through a direct (or indirect) call to \ref input_Create and \ref
* input_CreatePreparser, which means that they are not handled by
* functions such as \ref vlc_UrlParse and \ref vlc_stream_NewURL (as
* implied by their names).
* \section mrl_introduction Introduction
* As an example, with the use of an \em MRL one can specify that a certain \ref
* demux is to be unconditionally used for a specific resource, such as in the
* below (forcing usage of \em demuxdump).
* \verbatim http/demuxdump,none://\endverbatim
* There is also the possibility of specifying attributes related to the
* playback behavior of the referred to resource, such as what range of titles
* and chapters that are to be played.
* \verbatim\endverbatim
* \section mrl_technical Technical Information
* The overall specification in <a
* href="">RFC3986</a> are inherited by \em
* MRLs, though some entities have been redefined in order to provide support
* for additional \em media-related \em information, other entities (treated as
* arbitrary data in a \em URI) is explicitly defined to have special meaning
* within an \em MRL.
* \subsection mrl_technical_scheme 3.1. Scheme
* In an \em MRL, what <a href="">RFC3986</a>
* refers to as `scheme` is allowed to contain a \em forward-slash, and if such
* is present, the data prior to the slash denotes the \em scheme (as originally
* defined by \em RFC3986), whereas the data that follows specifies a list of
* \link demux demultiplexers\endlink to probe when dealing with the resource.
* mrl-scheme = *( %x20-7E )
* mrl-demux = *( %x20-2B / %x2D-7E )
* mrl-demuxers = mrl-demux *( "," mrl-demux )
* scheme =/ ( mrl-scheme [ "/" mrl-demuxers ] )
* - `mrl-demuxers` is a \em comma-delimited list of individual \ref
* demux that will be tried in order of appearance when the
* resource requires a \ref demux to be created.
* - If the currently processed `mrl-demux` is `"any"`
* (case-insensitive), than any \ref demux is allowed to be probed
* (and potentially used) at that stage.
* - If no specified \ref demux specified in `mrl-demuxers` can
* handle the resource, the media shall fail to open.
* \subsection mrl_technical_fragment 3.5. Fragment
* \em MRL does not inherently change the <a
* href="">ABNF</a> for \em fragment-data as
* specified by <a href="">RFC3986</a>, it
* does however provide special meaning to data matching the patterns listed in
* this section.
* - \parblock
* <h4>`mrl-section`</h4>
* \verbatim
mrl-title = DIGIT *DIGIT
mrl-chapter = DIGIT *DIGIT
mrl-section = mrl-title [ ":" mrl-chapter ] [ "-" mrl-title [ ":" mrl-chapter ] ]
* If the data contained in the `fragmentof` an \em MRL matches
* `mrl-section`, the data denotes the offset to start, and conditionally stop
* (if present), the resource during playback,
* `mrl-title` and `mrl-chapter` refers to the index of the \em title and \em
* chapter, respectively. Data before the optional hyphen denotes the starting
* position, and data following it, if any, denotes where to stop.
* The range is specified as `[start,stop)`, meaning that playback will
* continue until \em stop has been reached, it does not include the contents
* of the entity referred to by \em stop.
* \endparblock
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment