[vlc-devel] [RFC 02/10] doc: document Media Resource Locator

[Rémi Denis-Courmont]

On November 28, 2016 4:22:21 AM GMT+02:00, "Filip Roséen" <filip at atch.se> wrote:
>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
>correctly.
>---
>doc/standalone/mrl.dox | 90
>++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 90 insertions(+)
> create mode 100644 doc/standalone/mrl.dox
>
>diff --git a/doc/standalone/mrl.dox b/doc/standalone/mrl.dox
>new file mode 100644
>index 0000000..6d9b0fc
>--- /dev/null
>+++ b/doc/standalone/mrl.dox
>@@ -0,0 +1,90 @@
>+/**
>+ * \defgroup mrl Media Resource Locator (MRL)
>+ *
>+ * The \em MRL-specification is a VLC intrinsic extension to <a
>+ * href="https://tools.ietf.org/html/rfc3986">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://example.com/path/to/media\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 http://example.com/media.mkv#0:1-1:5\endverbatim
>+ *
>+ * \section mrl_technical Technical Information
>+ *
>+ * The overall specification in <a
>+ * href="https://tools.ietf.org/html/rfc3986">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="https://tools.ietf.org/html/rfc3986">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="https://tools.ietf.org/html/rfc5234">ABNF</a> for \em
>fragment-data as
>+ * specified by <a
>href="https://tools.ietf.org/html/rfc3986">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 ] ]
>+\endverbatim
>+ *  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
>+ *
>+ **/
>-- 
>2.10.2
>
>_______________________________________________
>vlc-devel mailing list
>To unsubscribe or modify your subscription options:
>https://mailman.videolan.org/listinfo/vlc-devel

Hi,

AFAICT, the comma syntax in MRL only works by accident, and FWIW, it also affects the access. I have never seen it used and don't think it should be formally supported.

As for the slash syntax, it is legacy. A number of code paths won't work with it, or will ignore it. The modern way to select the demux is with the demux item option. This patch seems to imply that it is fully supported, which is not true.
-- 
Rémi Denis-Courmont