Media Resource Locator (MRL)

The MRL-specification is a VLC intrinsic extension to RFC3986, providing means to associate extra media-related information within the resource-identifier. More...

Collaboration diagram for Media Resource Locator (MRL):

Modules
	MRL helpers
	Helper functions related to parsing, as well as generating, data related to the MRL-specification.

Detailed Description

The MRL-specification is a VLC intrinsic extension to RFC3986, providing means to associate extra media-related information within the resource-identifier.

Note

MRLs are only used when an item is to be played by VLC, through a direct (or indirect) call to input_Create and input_CreatePreparser, which means that they are not handled by functions such as vlc_UrlParse and vlc_stream_NewURL (as implied by their names).

Introduction

As an example, with the use of an MRL one can specify that a certain Demultiplexer is to be unconditionally used for a specific resource, such as in the below (forcing usage of demuxdump).

http/demuxdump://example.com/path/to/media

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.

http://example.com/media.mkv#0:1-1:5

Technical Information

The overall specification in RFC3986 are inherited by MRLs, though some entities have been redefined in order to provide support for additional media-related information, other entities (treated as arbitrary data in a URI) is explicitly defined to have special meaning within an MRL.

3.1. Scheme

In an MRL, what RFC3986 refers to as scheme is allowed to contain a forward-slash, and if such is present, the data prior to the slash denotes the scheme (as originally defined by RFC3986), whereas the data that follows specifies a list of demultiplexers to probe when dealing with the resource.

mrl-scheme   = *( %x20-7E )
mrl-demux    = *( %x20-2B / %x2D-7E )
scheme       =/ ( mrl-scheme [ "/" mrl-demux ] )

• If the specified Demultiplexer specified in mrl-demuxer can't handle the resource, the media shall fail to open.

3.5. Fragment

MRL extends the ABNF for fragment-data as specified by RFC3986 so that individual pieces can be identified within the payload.

mrlfrag-query     = query
mrlfrag-subdelims = "$" / "&" / "'" / "(" / ")" / "*" / "+" /
                    "," / ";" / "=" / pct-encoded
mrlfrag-entity    = "!/" *( mrlfrag-subdelims )
fragment          =/ ( *( mrlfrag-entity ) [ "?" mrlfrag-query ] ) /
                    mrlfrag-query / mrl-section

Generating fragment

1. Start with an empty payload
2. For each subentry (from top to bottom)
   • append "!/" to the payload
   • url-encode characters not matching mrlfrag-subdelims
   • append the url-encoded data
3. If the payload is not empty, and there is a mrlfrag-query
   • append "?" to the payload
4. append the mrlfrag-query to the payload

Parsing fragment

1. If the payload begins with "!/"
   • skip the initial two characters
   • extract data up until the first occurance of either ? or !
   • url-decode the extracted data
   • the decoded data is a mrlfrag-entity
   • goto step 1 with the data following the extracted data
2. If the payload begins with "?"
   • skip the initial character
3. the payload contains the mrlfrag-query

Fragment Query

Data within fragment, as defined by the previous section, can have special meaning if it matches the entities listed below (priority in order of appearance).

• mrl-section

  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 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 title and 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 stop has been reached, it does not include the contents of the entity referred to by stop.

• mrlfrag-query

  The data within the mrlfrag-query shall be key=value pairs, each delimited by an ampersand (this means that an ampersand in either key or value must be URL-encoded). key-value pairs not specified in the table below are ignored.

  	Value	Description
  t	Integer	specifies where to start playback (in seconds)
  s	Integer	specifies where to stop playback (in seconds)