Wednesday, September 19, 2012

F4M File Format Specification ( HTTP Dynamic Streaming)


Flash Media Manifest (F4M) File Format

Overview

The Flash Media Manifest is a file format that contains information about a Flash media asset. This information includes the location of the media, DRM authentication information, media bootstrap information, multi-bitrate information (MBR), etc. The intended workflow is that a media player loads and "plays" a manifest file as if it were an atomic media file. The load process might involve DRM authentication, HTTP bootstrapping, and selection of the appropriate MBR rendition.
The manifest file itself is an XML document that represents a single piece of media, for example, a music video. That music video might have multiple variations (e.g. related instances of the video with different bit rates, localized content, etc.), but a single manifest file would never encapsulate more than that one music video. To represent more than one distinct piece of media (for example, an entire album of music videos) requires multiple manifests or the use of other encapsulation formats (such as SMIL or RSS/Atom).
A manifest file can include metadata, DRM settings, and/or bootstrap information, and each can be assigned to the piece of media as a whole (that is, to all instances of the media), or to a specific instance. In the former case, the information is placed under the root of the manifest, while in the latter case the information is placed directly under the representation to which it applies.
This document describes the structure of the F4M file format, which is currently at version 2.0. It is published as an open specification.

Terminology

Manifest File
An instance of a file of this format.
F4M
The file extension for a file of this format.
DRM
Digital Rights Management, as implemented in Flash Player v10.1.
MLM
Multi-level manifest, a concept introduced in F4M 2.0 to provide support for manifest file hierarchies.
Set-Level Manifest
A manifest file that groups individual stream-level manifest files.
Stream-Level Manifest
A manifest file describing a single <media> instance.


Highlights

Some important aspects of the file format:
  • A manifest file can contain multiple representations of the same piece of media. These representations could vary by bit rate, dimensions, or MIME type. For example, a manifest file could contain pointers to five different bit rate FLV files and three different bit rate MP4 files.
  • No assumptions are made about the media type(s) that a manifest file contains. The primary use case is video, but there's no reason to assume that a manifest would never contain something else.
  • A manifest file can contain one shared DRM additional header block which applies to all media files, or per-file DRM additional header blocks.
  • A manifest file can contain one shared bootstrap information block which applies to all media files, or per-file bootstrap information. For example, there could be one bootstrap information block which applies to all FLV versions of the media, and a second bootstrap information block which applies to all MP4 versions of the media (assuming there are FLV- and/or MP4-specific bootstrapping algorithms).
  • The bootstrap information block contains the raw data included in the bootstrapinfo box. As such, consumers of a manifest file need to parse this binary data to find the info that's relevant to the bootstrapping algorithm.
  • Both the DRM additional header and bootstrap info can be specified as external files (via URLs).
  • The DVR info can be specified as an external file, so that the client application can periodically re-retrieve it.
  • Each URL in the document can be absolute, relative to a manifest-wide base URL, or (if no manifest-wide base URL is specified) relative to the manifest file itself.
  • A manifest file can contain the moov atom, the metadata block, and the XMP metadata block for each file.
    • Note: Starting with F4M 2.0, the moov atom and the XMP metadata block are deprecated.
  • The manifest file is an XML structure in a specific namespace. This enables the inline integration of manifest XML documents in other XML documents (e.g. RSS or SMIL).
  • As with most XML languages, developers can extend the manifest file format by placing their own elements in a custom namespace. 


Document Structure

The following sections describe the semantics of each element.


<manifest>

The root element in the document is <manifest>.


<id>

The <id> element represents a unique identifier for the media. It is optional.


<label>

The <label> element is a string representing the default user-friendly description of the media. It is assumed that all representations of the media have the same description, except the alternatives tracks, hence its placement under the document root. It is optional.


<lang>

The <lang> element is a string representing the base language of the piece of media. It is assumed that all representations of the media have the same description, except the alternatives tracks, hence its placement under the document root. It is optional.


<duration>

The <duration> element represents the duration of the media, in seconds. It is assumed that all representations of the media have the same duration, hence its placement under the document root. It is optional.
For live or DVR content, the duration represents the total expected time of the media, not the current duration of the media. Usually for live content, it is 0.


<startTime>

The <startTime> element represents the date/time at which the media was first (or will first be) made available. It is assumed that all representations of the media have the same start time, hence its placement under the document root. The start time must conform to the "date-time" production in RFC3339. It is optional.


<mimeType>

The <mimeType> element represents the MIME type of the media file. It is assumed that all representations of the media have the same MIME type, hence its placement under the document root. It is optional.


<streamType>

The <streamType> element is a string representing the way in which the media is streamed. Valid values include "live", "recorded", and "liveOrRecorded". It is assumed that all representations of the media have the same stream type, hence its placement under the document root. It is optional.


<deliveryType>

The <deliveryType> element indicates the means by which content is delivered to the player. Valid values include "streaming" and "progressive". It is optional. If unspecified, then the delivery type is inferred from the media protocol. For media with an RTMP protocol, the default deliveryType is "streaming". For media with an HTTP protocol, the default deliveryType is also "streaming". In the latter case, the <bootstrapInfo> field must be present.


<baseURL>

The <baseURL> element contains the base URL for all relative (HTTP-based) URLs in the manifest. It is optional. When specified, its value is prepended to all relative URLs (i.e. those URLs that don't begin with "http://" or "https://" within the manifest file. (Such URLs may include <media> URLs, <dvrInfo> URLs, <bootstrapInfo> URLs, <drmAdditionalHeader> URLs, and <alternativeAudioTracks> URLs.)
The <baseURL> element's scope is the file it resides in. For multi-level manifest use, relative URLs in a file (set-level or stream-level) manifest are relative to the <baseURL> from that specific file (or to the location of that file, if <baseURL> is missing).


<drmAdditionalHeader>

The <drmAdditionalHeader> element represents the DRM AdditionalHeader needed for DRM authentication. It contains either a BASE64 encoded representation of, or a URL to, the DRM AdditionalHeader (including the serialized "|AdditionalHeader" string). It is optional.
Attributes:
  • id: The ID of this <drmAdditionalHeader> element. It is optional. If it is not specified, then this header will apply to all <media> elements that don't have a drmAdditionalHeaderId property. If it is specified, then this header will apply only to those <media> elements that use the same ID in their drmAdditionalHeaderId property.
  • url: A URL to a file containing the raw DRM AdditionalHeader. Either the url attribute or the inline BASE64 header (but not both) must be specified. If a specified URL is non-absolute, then it must be relative to the manifest file itself.
Notes: For multi-level manifest use:
  • This element should only be present in the stream-level manifest.
  • This element's scope is the file it resides in. A stream-level manifest's media cannot reference a <drmAdditionalHeader> from a different stream-level manifest.
    • Because of this, there are no conflicts when two <drmAdditionalHeader> elements from different files have the same id.


<bootstrapInfo>

The <bootstrapInfo> element represents all information needed to bootstrap playback of HTTP streamed media. It contains either a BASE64 encoded representation of, or a URL to, the bootstrap information in the format that corresponds to the bootstrap profile. It is optional.
Attributes:
  • id: The ID of this <bootstrapInfo> element. It is optional. If it is not specified, then this bootstrapping block will apply to all <media> elements that don't have a bootstrapInfoId property. If it is specified, then this bootstrapping block will apply only to those <media> elements that use the same ID in their bootstrapInfoId property.
  • profile: The profile, or type of bootstrapping represented by this element. For the Named Access profile, use "named". For other bootstrapping profiles, use some other string (i.e. the field is extensible). It is required.
  • url: A URL to a file containing the raw bootstrap info. Either the url attribute or the inline BASE64 bootstrap info (but not both) must be specified. If a specified URL is non-absolute, then it must be relative to the manifest file itself (or to the baseURL, if specified).
Notes: For multi-level manifest use:
  • This element should only be present in the stream-level manifest.
  • This element's scope is the file it resides in. A stream-level manifest's media cannot reference a <bootstrapInfo> from a different stream-level manifest.
    • Because of this, there are no conflicts when two <bootstrapInfo> elements from different files have the same id.


<dvrInfo>

The <dvrInfo> element represents all information needed to play DVR media. It contains no content, only attributes. It is optional.
Attributes:
  • [deprecated] id: The ID of this <dvrInfo> element. It is optional. If it is not specified, then this DVR info applies to all <media> elements that don't have a dvrInfoId property. If it is specified, then this DVR info applies only to those <media> elements that use the same ID in their dvrInfoId property.
    • Deprecated starting with F4M 2.0
  • url: A URL to a file containing the DVR info. It is optional. If a specified URL is non-absolute, then it must be relative to the manifest file itself (or to the baseURL, if specified). If the url attribute is specified, then the client should periodically re-fetch the DVR info at that URL. The document at that URL must be an XML document whose root element is <dvrInfo>, and whose structure is the same as this element, with the exception that there should be no "url" attribute.
  • [deprecated] beginOffset: The offset, in seconds, from the beginning of the recorded stream. Clients can begin viewing the stream at this location. It is optional, and defaults to zero.
    • Deprecated starting with F4M 2.0
  • [deprecated] endOffset: The amount of data, in seconds, that clients can view behind the current duration. If endOffset is zero, then the clients can view the whole content. It is optional, and defaults to zero.
    • Deprecated starting with F4M 2.0
  • windowDuration: The amount of data, in seconds, that clients can view behind the live point. If windowDuration is -1, then the clients can view the whole content. It is optional, and defaults to -1.
    • Introduced in F4M 2.0
  • offline: Indicates whether the stream is offline, or available for playback. It is optional, and defaults to false.
Notes:
  • For multi-level manifest use with DVR, the <dvrInfo> element should be present in the set-level manifest. The <dvrInfo> elements from the stream-level manifests are ignored.


<media>

The <media> element represents one representation of the piece of media. Each representation of the same piece of media has a corresponding <media> element. There must be at least one <media> element.
Attributes:
  • url: The URL of the media file. It is optional (only one of @url and @href should be present). If a specified URL is non-absolute, then it must be relative to the baseURL (if specified) or the manifest file itself (if no baseURL is present).
  • bitrate: The bitrate of the media file, in kilobits per second. If only one <media> element is in the manifest file, then the bitrate attribute is optional. If more than one <media> element is in the manifest file, then the bitrate attribute is required for each element.
  • streamId: The identifier for media file. It is optional.
  • width: The intrinsic width of the media file, in pixels. It is optional.
  • height: The intrinsic height of the media file, in pixels. It is optional.
  • drmAdditionalHeaderId: The ID of a <drmAdditionalHeader> element which contains the DRM AdditionalHeader for this media file. It is optional.
  • bootstrapInfoId: The ID of a <bootstrapInfo> element which contains the bootstrap info that this media file should use. It is optional. If this attribute is present, then the <url> attribute may represent the base URL of the actual media.
  • [deprecated] dvrInfoId: The ID of a <dvrInfo> element which contains the DVRInfo that this media file should use. It is optional.
    • Deprecated starting with F4M 2.0
  • groupspec: The group specifier for multicast media. It is optional. Multicast is only supported over RTMFP, and only for a single (non-MBR) stream. If specified, then the "url" attribute contains the connection URL, and the "multicastStreamName" attribute must also be specified.
  • multicastStreamName: The stream name for multicast media. It is optional. Multicast is only supported over RTMFP, and only for a single (non-MBR) stream. If specified, then the "url" attribute contains the connection URL, and the "groupspec" attribute must also be specified.
  • type: The type for alternative track. Valid values include "audio+video", "video", "audio", "data" and "text". It is optional and defaults to "audio+video".
  • alternate: Indicate if this representation is an alternate version. Fixed value to true. It is optional.
  • label: The description for alternative track. It is required only if the alternate attribute is present.
  • lang: The language code for alternative track (should be ISO 639-1 or ISO 639-3 codes). It is required only if the alternate attribute is present.
  • href: The URL of an external F4M file. It is optional (only one of @url and @href should be present). If the URL is non-absolute, then it must be relative to the baseURL (if specified) or the manifest file itself (if no baseURL is present in the manifest)
    • Introduced in F4M 2.0
Notes:
  • The stream-level manifest indicated by the @href attribute should only contain one <media> element
  • When working with a multi-level manifest, the following attributes are read only from the set-level manifest and ignored in the stream-level manifest:
    • bitrate, streamId, width, height, type, alternate, label, lang
  • When working with a multi-level manifest, the following attributes are read only from the stream-level manifest:
    • drmAdditionalHeaderId, bootstrapInfoId
  • The stream-level manifest's <media> element should link directly to the media file via the @url attribute. It is not allowed to link to another manifest.
  • The set-level manifest should only contain <media> elements with @href.


<moov> (deprecated with F4M 2.0)

Note that the <moov> element was not implemented for the 1.0 version of the HTTP Streaming File Packager.
The <moov> element represents the Movie Box, or "moov" atom, for one representation of the piece of media. It contains a BASE64 encoded representation of the Movie Box for the given representation. It is an optional child element of <media>.
Deprecated starting with F4M 2.0


<metadata>

The <metadata> element represents the stream metadata (i.e. the metadata that is typically dispatched in the onMetaData event) for one representation of the piece of media. It contains a BASE64 encoded representation of the stream metadata for the given representation. It is an optional child element of <media>.


<xmpMetadata> (deprecated with F4M 2.0)

Note that the <xmpMetadata> element was not implemented for the 1.0 version of the HTTP Streaming File Packager.
The <xmpMetadata> element represents the XMP metadata for one representation of the piece of media. It contains a BASE64 encoded representation of the XMP metadata for the given representation. It is an optional child element of <media>.
Deprecated starting with F4M 2.0




 

at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)