| TOC |
|
This document is an Internet-Draft and is NOT offered in accordance with Section 10 of RFC 2026, and the author does not provide the IETF with any rights other than to publish as an Internet-Draft.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”
The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 19, 2010.
This document presents an extension to the Atom Syndication Format that defines how media objects such as photos and videos might be represented in Atom and allows additional metadata to be published about linked media representations.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (, “RFC 2119,” .) [RFC2119].
1.
Introduction
2.
Notational Conventions
3.
Media Objects as Atom Entries
4.
Link Relations
4.1.
The "enclosure" link relation
4.2.
The "preview" link relation
4.3.
The "alternate" link relation
5.
Link Extension Attributes
5.1.
The media:width and media:height Extension Attributes
5.2.
The media:duration Extension Attribute
6.
The media:description Extension Element
7.
Publishing Conventions For Specific Media Types
7.1.
Photos and Other Images
7.2.
Video
7.3.
Audio
7.4.
Conventions for All Media Types
8.
Security Considerations
9.
IANA Considerations
10.
Normative References
Appendix A.
Acknowledgements
Appendix B.
Examples
B.1.
Photo Entry
B.2.
Video Entry
§
Author's Address
| TOC |
This document presents an extension to the Atom Syndication Format (, “The Atom Syndication Format,” .) [RFC4287] that defines how media objects such as photos and videos might be represented in Atom and allows additional metadata to be published about linked media representations.
The capabilities described herein are an adaptation to Atom of some of the core capabilities of [MediaRSS] (, “MediaRSS,” .).
This specification primarily considers the image, video and audio media types. The extensions described herein MAY be used with other media types in a way that is consistent with the definitions described in this specification, but this specification does not consider the processing expectations for such use.
| TOC |
The XML Namespaces URI [W3C.REC-xml-names-19990114] for the XML elements and attributes described in this specification is: http://purl.org/syndication/atommedia.
In this document, the namespace prefix "media:" is used for the above Namespace URI. The namespace prefix "atom:" is used for the namespace URI http://www.w3.org/2005/Atom. Note that the choices of namespace prefix are arbitrary and not semantically significant.
This specification uses a shorthand form of terms from the XML Infoset [W3C.REC-xml-infoset-20040204]. The phrase "Information Item" is omitted when naming Element and Attribute Information Items. Therefore, when this specification uses the term "element," it is referring to an Element Information Item in Infoset terms. Likewise, when this specification uses the term "attribute," it is referring to an Attribute Information Item.
This specification allows the use of IRIs [RFC3987]. Every URI [RFC3986] is also an IRI, so a URI may be used wherever an IRI is named. When an IRI that is not also a URI is given for dereferencing, it MUST be mapped to a URI using the steps in Section 3.1 of [RFC3987]. When an IRI is serving as an identifier, it MUST NOT be so mapped.
Some sections of this specification are illustrated with a non- normative RELAX NG Compact schema [RELAXNG]. In those sections, this specification uses the atomCommonAttributes, atomMediaType, and atomURI patterns, defined in [RFC4287].
However, the text of this specification provides the sole definition of conformance.
This specification uses "the Atom specification" to refer to [RFC4287] (, “The Atom Syndication Format,” .).
| TOC |
The Atom Syndication Format defines a set of elements which are designed primarily for use in describing weblog entries. When an Atom entry is used instead to represent a media object, such as a photo, video or audio recording, several additional items of information are useful, including links to a variety of representations of the media object as well as smaller "preview" representations that a user may view to decide whether to retrieve a representation of the full media object.
| TOC |
This specification refines the existing "enclosure" and "alternate" link relations, and adds an additional "preview" link relation. These are described in the following sections.
| TOC |
The "enclosure" link relation is defined by section 4.2.7.2 of [RFC4287] (, “The Atom Syndication Format,” .). This section describes additional requirements for the use of this link relation in entries that represent media objects.
When used in a media object entry, the enclosure link relation indicates that the link is to a representation of the media object. The type attribute indicates the media type of the representation.
Links with this relationship SHOULD include any appropriate extension attributes from Section 5 (Link Extension Attributes) as a hint to processors about which representations may be most appropriate for their capabilities or circumstances or those of the user.
The title attribute MAY be used to provide a human-readable label to distinguish one representation from another. For example, title="Full Size". Including media type information in the title attribute is however NOT RECOMMENDED, since this information can be derived from the type attribute if needed.
As advised by the Atom specification, the length attribute SHOULD be used for link elements with this relation.
Because this link relation is defined by the Atom specification, publishers should be aware that it may be processed by general Atom processors that do not support the media extensions described in this specification.
| TOC |
The "preview" link relation indicates that the link is to a reduced-fidelity and/or reduced-content representation of the media object that is intended to allow the user to sample the content before retrieving a full representation. For example, if the media object is an image a thumbnail of the photograph can be linked using this relationship. If the media object is a video, the preview could be a thumbnail image of a representative frame from the video, or a clip showing a short segment of the full video. The type attribute indicates the media type of the representation.
Resources linked with this relationship SHOULD be small in all appropriate senses of the word. In all cases they SHOULD have a lower filesize than the corresponding full representation. For preview representations with a visible manifestation, such as images and videos, the resource SHOULD have a small physical size in both dimensions such that the preview could readily be displayed on-screen with the previews from several other media items. For time-based media, the preview resource SHOULD have a short duration. No hard limits are placed on previews by this specification since it is anticipated that future technological advances such as larger or higher-resolution displays will lead to more more liberal definitions of "small".
Links with this relationship SHOULD include any appropriate extension attributes from Section 5 (Link Extension Attributes) as a hint to processors about which representations may be most appropriate for their capabilities or circumstances or those of the user.
| TOC |
When used in an Atom entry representing a media object, the "alternate" link relation is interpreted as a link to a document that itself contains the metadata about the media object and embeds or links to one or more representations of the media object.
For example, if the type attribute contains text/html, the target of the link SHOULD be a HTML page that describes the media object, including metadata such as the title and description, and embeds and/or links to one or more representations of the object.
If the type attribute contains a media type for embedded applets, such as application/x-shockwave-flash, the linked object SHOULD be an applet that can display or plays back the media object when executed. This applet MAY also make available through its user interface metadata such as the title and description for use when the applet is displayed alone without any other context. The media:width and media:height extension attributes described in Section 5.1 (The media:width and media:height Extension Attributes) SHOULD be included and SHOULD indicate the applet's native or ideal display size and aspect ratio.
Because this link relation is defined by the Atom specification, publishers should be aware that it may be processed by general Atom processors that do not support the media extensions described in this specification.
| TOC |
The following extension attributes apply to the atom:link element. They provide a processing application with hints about the nature of the linked resource such that the application can choose an appropriate representation or representations from those available without retrieving all of the resources for examination. These extension attributes MUST NOT be assumed to provide completely accurate information about the linked resource. The non-authoritative nature of "external reference metadata", like the replies link attributes, is discussed in detail in Section 3.3 of [TAG12] (, “TAG Finding 12: Authoritative Metadata,” .).
Implementors must be aware that although the Atom specification explicitly allows the link element to contain arbitrary extensions, the specification does not require that implementations support such extensions. In particular, these extension attributes may be lost if a feed is accessed through a feed re-publishing system that does not support these extensions.
These extension attributes are intended to be used with links using the enclosure and preview link relations. They MAY be used with other link relations, but the processing expectations for such usage is not considered by this specification.
| TOC |
For media types that have an on-screen visible representation, in particular media types matching image/* and video/*, the media:width and media:height attributes specify the physical dimensions of the linked representation in whole media pixels.
When used with arbitrarily scalable media such as vector graphics, these attributes specify an ideal or standard rendering size and aspect ratio. The same representation MAY be linked several times with different values of width and height.
| TOC |
For time-based media types, in particular media types matching video/* and audio/*, the media:duration attribute specifies the length of time that the media object plays in whole seconds. If the exact duration is not a whole number of seconds, publishers MUST round the value to an integer in any way they deem appropriate.
For links with the relation preview, this attribute (as well as the duration of the linked resource) SHOULD be less than or equal to the duration of the corresponding full representation.
If a given entry contains several links with the enclosure relation that have a media:duration attribute, the duration of all of the resources linked in this way SHOULD have the same or at least a similar duration since they are alternative representations of the same content.
| TOC |
The media:description extension element is used as a child of atom:entry and contains a human-readable description, usually provided by the author of the media object, of the content of the media object. It is distinct from the atom:content element because the latter contains more general content suitable for displaying this object in a general Atom processor that does not support the media extensions described in this specification.
The content model and processing requirements of this element are the same as for atom:content, including attributes, as described in section 4.1.3 of the Atom specification.
An atom:entry element MUST NOT contain more than one media:description element.
| TOC |
This section defines specific applications of the above mechanisms for publishing the three different media types considered by this specification.
| TOC |
When publishing images, all representations are usually in media types that match image/*. While publishers are free to provide representations in any number of formats, a representation of type image/jpeg, image/png or image/gif SHOULD be provided. Processors SHOULD support at least these three media types for both images and image previews.
Although both the "enclosure" and "preview" link relations can link to representations of any size, publishers SHOULD use "enclosure" only for representations that are of a size suitable for viewing alone on-screen. Conversely, publishers SHOULD use "preview" only for representations that are of a size suitable for displaying alongside other image previews, such that the user may choose one image to view in full.
At least one "enclosure" link SHOULD be provided. Including at least one "preview" link is RECOMMENDED.
If the author has provided a title or short caption for the image, it SHOULD be included in the atom:title element. In the absense of such a title, publishers MAY substitute a filename or other identifier that might allow a human to recognise the image.
| TOC |
When publishing video, representations with various container formats and codecs are generally published for maximum compatibility. Publishers may choose also to provide audio-only versions of the content. Finally, at least one image is often provided showing a representative frame from the video.
When linking to the actual video content rel="enclosure" MUST be used with a suitable media type. Including such a link is RECOMMENDED. Implementers should be aware that for video content the base media type often refers only to the container format and does not describe the audio or video codecs used. Identifying the codecs used within particular container formats is the responsibility of each container's media type; it is out of scope for this specification. Publishers SHOULD include the media:duration extension attribute on each enclosure link, but the duration SHOULD be the same or similar for all such links since they represent the same content. Processors MAY display the duration from any included enclosure link as a single display duration for all representations.
Publishers SHOULD provide at least one thumbnail image of type image/jpeg, image/png or image/gif that is taken from a representative frame of the video, and link to this image with rel="preview".
If an audio-only representation of the content is provided, and the audio is considered to be a usable full representation of the content, it MUST be included with rel="enclosure" and a suitable media type. Publishers SHOULD include the media:duration extension attribute on such links and the duration SHOULD be the same or similar to the corresponding video representation. If the audio is provided only as a preview of the resource, rel="preview" MUST be used.
If an applet such as a Flash player is available to play back the video, it SHOULD be linked with rel="alternate" and an appropriate media type. For a Flash-based player the appropriate media type is application/x-shockwave-flash, and href should contain a URL that could be used in the src attribute of the HTML embed element with this type. It is acknowledged that in many cases more than just a URL is required to successfully embed a movie player applet, but a mechanism for obtaining the additional information is out of scope for this specification. Publishers MAY include more complete embedding code as part of the value of atom:content.
| TOC |
When linking to the actual audio content rel="enclosure" MUST be used with a suitable media type. Publishers SHOULD include the media:duration extension attribute on each enclosure link, but the duration SHOULD be the same or similar for all such links since they represent the same content. Processors MAY display the duration from any included enclosure link as a single display duration for all representations.
If an applet such as a Flash player is available to play back the audio, it SHOULD be linked with rel="alternate" and an appropriate media type. For a Flash-based player the appropriate media type is application/x-shockwave-flash, and href should contain a URL that could be used in the src attribute of the HTML embed element with this type.
| TOC |
This section describes some conventions that are applicable to all media types, in many cases relating to handling of media entries by general Atom processors that do not support media extensions.
If the author has provided a textual description for the image, it SHOULD be included in the media:description extension element. Publishers SHOULD include an atom:content element in each media object entry containing HTML that, when displayed to a user, communicates all information necessary to interact with the resource in conjunction with the values of other elements defined by the Atom specification. This content will be used by Atom processors that do not support media extensions.
Processors that do support media extensions MAY use the information provided by the extension attributes and elements defined in this specification in place of the value of atom:content. This is because atom:content will in most cases contain information that duplicates that provided by the media extension constructs. Processors MAY offer to users a way to access the fallback content in preference to the information provided by the media extension constructs.
Publishers SHOULD include in each media object entry an atom:link element with the relation "alternate" and the media type text/html whose target is an HTML page that represents the media object, includes metadata such as the title and description and embeds and/or links to one or more representations of the media object for the benefit of a human user.
| TOC |
As this specification defines an extension to the Atom Syndication Format, it is subject to the same security considerations defined in [RFC4287] (, “The Atom Syndication Format,” .).
[TODO: Write some more here.]
| TOC |
[TODO: Write up a registration entry for the new "preview" link relation.]
| TOC |
| [MediaRSS] | “MediaRSS.” |
| [RFC2119] | “RFC 2119.” |
| [RFC3987] | “Internationalized Resource Identifiers (IRIs).” |
| [RFC4287] | “The Atom Syndication Format.” |
| [TAG12] | “TAG Finding 12: Authoritative Metadata.” |
| TOC |
...
| TOC |
This appendix is non-normative.
The examples in this section are given as standalone entries without a containing feed. It should be assumed that in each of these examples the following XML namespace declarations are in scope: xmlns="http://www.w3.org/2005/Atom" xmlns:media="http://example.com/to-be-confirmed".
| TOC |
The following example shows an Atom entry representing a photo
<entry>
<title>My Cats</title>
<link rel="alternate" type="text/html"
href="http://photopanic.example.com/cats.html"/>
<id>tag:photopanic.example.com,2008:cats</id>
<published>2008-12-13T23:09:02Z</published>
<updated>2008-12-13T23:09:02Z</updated>
<link rel="enclosure" type="image/jpeg"
href="http://photopanic.example.com/cats_m.jpg"
media:width="640" media:height="480"
title="Medium-size" length="53433" />
<link rel="enclosure" type="image/jpeg"
href="http://photopanic.example.com/cats_f.jpg"
media:width="1280" media:height="1024"
title="Full-size" length="4353433" />
<link rel="preview" type="image/jpeg"
href="http://photopanic.example.com/cats_t.jpg"
media:width="100" media:height="100"
length="2048" />
<media:description>My cats: Tom, Henrietta and Billy.</media:description>
<content type="html">
<p>
<a
href="http://photopanic.example.com/cats.html"
title="My Cats">
<img
src="http://photopanic.example.com/cats_m.jpg"
width="640"
height="480"
/>
</a>
</p>
</content>
</entry>| TOC |
The following example shows an Atom entry representing a video.
<entry>
<title>Duct Tape</title>
<link rel="alternate" type="text/html"
href="http://ubertube.example.com/ducttape.html"/>
<id>tag:ubertube.example.com,2005:ducttape</id>
<published>2008-12-13T23:09:02Z</published>
<updated>2008-12-13T23:09:02Z</updated>
<link rel="enclosure" type="video/mp4"
href="http://ubertube.example.com/ducttape.mp4"
media:width="640" media:height="480"
length="3635674756" media:duration="170" />
<link rel="enclosure" type="video/x-flv"
href="http://ubertube.example.com/ducttape.flv"
media:width="640" media:height="480"
length="153463454" media:duration="170" />
<link rel="preview" type="image/jpeg"
href="http://ubertube.example.com/ducttape_t.jpg"
media:width="100" media:height="100"
length="2032" />
<link rel="alternate" type="application/x-shockwave-flash"
href="http://ubertube.example.com/ducttape_e.swf"
media:width="640" media:height="480" />
<media:description>
Talking with Duct Tape over my mouth.
</media:description>
<content type="html">
<embed
src="http://ubertube.example.com/ducttape_e.swf"
type="application/x-shockwave-flash"
width="640" height="480">
</content>
</entry>The video itself is provided in two different formats. A small preview image is provided. An applet to play back the video is also provided and embedded in the HTML included in the content element.
| TOC |
| Martin Atkins | |
| Six Apart Ltd |