This document describes how to deliver videos that can be played before (pre-roll) or after (post-roll) your subscription video content. The pre-roll and post-roll videos can, for example, include promo content, ratings, dub credits, logos, and certificates. You deliver these pre-roll and post-roll videos separately, each in its own iTunes Package (.itmsp). See more about asset requirements and guidelines in Overview of Submitting Assets.
Date/Version | Changes Made |
|---|---|
July 19, 2021 - Version 1.4 | Removed CBFC requirement. |
Ratings
References to CBFC requirements have been removed as part of the overall changes to India ratings.
This chapter describes asset requirements and guidelines for pre-roll and post-roll videos.
Note: Each pre- or post-roll video must be a minimum of 5 seconds, up to a maximum of 90 seconds.
You deliver video assets by submitting an XML file as an iTunes package (.itmsp). The .itmsp package must include at a minimum a metadata.xml file and video source; captions are optional but recommended. You can deliver other components, such as subtitles or alternate audio, as needed. See the Subscription Video Specification for details on how to deliver additional components.
In the XML, you supply a unique vendor ID for the video and that vendor ID is referenced in the XML of the subscription video using the <play_sequence> block.
The assets you deliver must conform to specific requirements, which are referred to as "profiles." The list below includes the assets accepted with a link to the asset requirements from the iTunes Video and Audio Asset Guide:
The pre-roll and post-roll videos should follow these guidelines:
The ratings of the pre- or post-roll videos should not be higher than the associated show or movie (for example, if the associated movie is rated for ages 12 and up, the pre- or post-roll videos should not be rated for ages 18 and up).
The accessibility options of the pre- or post-roll videos should match the accessibility options of the associated show or movie where applicable (for example, if the associated movie has closed captions and subtitles, the pre- or post-roll videos should have closed captions and subtitles).
The audio formats of the pre-roll and post-roll should match the audio formats of the associated show or movie as close as possible.
The frame rate, resolution, and color space of the pre-roll and post-roll should match the full asset where possible.
Pre- or post-roll videos must be a minimum of 5 seconds and up to a maximum of 90 seconds.
Pre- or post-roll videos should not contain third party promotions or sponsorships.
Pre- or post-roll video can be used to promote your own services and channel offerings.
This example shows how to deliver a pre- or post-roll video asset.
To see a full description of each block, see XML Annotations for Delivery.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="bookend5.0"> <language>en-US</language> <provider>AppleseedEntertainment</provider> <video> <vendor_id>TheMoviePromo1</vendor_id> <title>The Movie: Promo 1</title> <original_spoken_locale>en-US</original_spoken_locale> <subtype>promo</subtype> <assets> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>moviepromo1-source.mov</file_name> <size>43825952</size> <checksum type="md5">f51c4ea2df6a9330c974b7f298fa393e</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">false</attribute> <attribute name="image.burned_forced_narrative.locale">en-US</attribute> </data_file> <data_file role="captions"> <locale name="en-US"/> <file_name>33bard5f917-english.scc</file_name> <size>9511</size> <checksum type="md5">5a793a8b46037fe8aa2bdd739b49911a</checksum> <attribute name="program.start.timecode">-01:00:00:00</attribute> </data_file> </asset> </assets> </video></package>See the details for each line of the XML example below.
Package Metadata Fields |
|---|
<?xml version="1.0" encoding="UTF-8"?>XML Declaration (required) The character encoding of your document must be defined. Apple only accepts UTF-8 encoding as it efficiently encodes non-Roman characters. Important: The metadata.xml file must not contain a byte-order mark (BOM). |
XPath: /package <package xmlns="http://apple.com/itunes/importer" version="bookend5.0"> Package Container (required) The xmlns (for XML namespace) attribute is required and is needed for schema validation. It is used to declare the namespace (and associated schema) to which the tags in the XML are expected to conform. The version attribute is required and should refer to the version of the specification used to create the metadata. Packages created to this specification must indicate |
XPath: /package/language <language>en-US</language> Language (required) The primary language of the metadata for this package. |
Provider Metadata Fields |
|---|
XPath: /package/provider <provider>AppleseedEntertainment</provider>Provider (required, Apple-supplied) This value should be the Apple-defined provider shortname given for partner identification. The value must match the provider name used in Transporter (the value that is after -s in the Transporter command). The value supplied with the |
Video Metadata Fields |
|---|
XPath: /package/video <video>Video (required) Begins the video element. Only one video element can be defined. |
XPath: /package/video/vendor_id <vendor_id>TheMoviePromo1</vendor_id>Vendor Identifier (required) The permanent value that uniquely identifies this video separately from any other video given by the provider. This ID is used for tracking your assets and sales reporting. Restrictions: The vendor identifier can only contain alphanumeric characters and underscore marks; it cannot contain spaces, dashes, ampersands, other punctuation, or symbols. The vendor identifier is case-sensitive and must not start with an underscore. If a Vendor ID is numeric, it is treated as a string, not numbers; a vendor identifier of ‘00000000012345’ is not the same as ‘12345’. Vendor IDs must be at least six ASCII characters in length but have a limit of 100 ASCII characters. |
XPath: /package/video/title <title>The Movie: Promo 1</title>Title (required, 1-255 bytes) The name of this video. This title is used for internal purposes and will not appear to the customer. |
XPath: /package/video/original_spoken_locale <original_spoken_locale>en-US</original_spoken_locale>Original Spoken Locale (required) Specifies the language spoken by the actors in the video. The value used for locale is case-insensitive, even though the example shows the value in the format xx-XX, such as en-US. In this example, the language the actors’ lips are moving in is English as spoken in the United States, so en-US must be specified as the Note: This tag is different from the |
XPath: /package/video/subtype <subtype>promo</subtype>Video Subtype (required) This value indicates how Apple should represent this short video in the catalog. The accepted values are:
Note: Each pre- or post-roll video must be a minimum of 5 seconds, up to a maximum of 90 seconds. |
Asset Metadata Fields |
|---|
XPath: /package/video/assets <assets>Assets (required) Begins the assets block that references the assets being delivered. New files update by overwriting the previous files. |
XPath: /package/video/assets/asset <asset type="full">Assets (required) Describes the type of asset being delivered. Specify |
XPath: /package/video/assets/asset/data_file <data_file role="source">Data File (required) A data file element specifies the delivered media file and describes the role of the associated file. Since the video is the source file (as opposed to a captions file), the role is “source”. In this block, the |
XPath: /package/video/assets/asset/data_file/locale <locale name="en-US">Locale Name (required) Identifies the language that is spoken in the audio on the source asset. The locale indicates the language and the optional region where the language is spoken. |
XPath: /package/video/assets/asset/data_file/file_name <file_name>moviepromo1-source.mov</file_name>File Name (required) The name of the data file included in this delivery package. The name should be relative to the package (containing no path reference “C:\” or “/Macintosh HD/”) and must contain the file name extension (”.mov” in this example). Important: File names are case-sensitive and spaces are not allowed. |
XPath: /package/video/assets/asset/data_file/size <size>43825952</size>File Size (required) The size in bytes of the data file. Do not include any commas nor period delimiters. |
XPath: /package/video/assets/asset/data_file/checksum <checksum type="md5">f51c4ea2df6a9330c974b7f298fa393e</checksum>Checksum (required) The MD5 checksum of the data file. |
XPath: /package/video/assets/asset/data_file/attribute <attribute name="crop.top">0</attribute>Metadata-Based Cropping (required if video contains inactive pixels) The crop rectangle for the full video’s QuickTime source file. If the video’s QuickTime source file is delivered matted (letterbox, pillarbox, or windowbox), specify the crop rectangle to crop the inactive pixels. Note: Crop dimensions are required for subscription videos that contain inactive pixels. When sending crop dimensions, send accurate dimensions without unnecessary cropping, especially horizontally. If your video does not contain inactive pixels (that is, it is not matted), you can set all the crop values to zero, or omit the crop dimension attribute tags. If you do not supply any crop dimensions, Apple will default to 0,0,0,0. The name attribute specifies the side of the image to be cropped. Accepted values are:
The values must be integers that represent the number of whole pixels of the encoded image. Note: If delivering texted content due to unavailability of textless source material, burned-in text that falls over inactive pixels must be maintained in the attribution of crop values. Additionally, an equal number of pixels that are applied to preserve burned-in text in one region, must also be equally applied to the opposite region so that content can be displayed proportionally. |
XPath:/package/video/assets/asset/data_file/attribute <attribute name="image.textless_master">false</attribute>Textless Master (required) Specifies whether or not the video contains burned-in text, such as narratives burnt into the visual picture or burned-in subtitles. Narrative text is text that appears on screen to supplement the content without the use of a narrator, such as “Paris early morning, 1935.” Opening title sequences and credits are not considered “text” in this case; those are expected to be in the video. This attribute is required for all videos. Allowed values are |
XPath:/package/video/assets/asset/data_file/attribute <attribute name="image.burned_forced_narrative.locale">en-US</attribute>Forced Narrative Locale (required if video contains forced narrative text) Specifies the locale of the narrative text. In this example, the attribute is required because the video source contains burned-in narrative text. If the video had burned-in subtitles, the attribute |
|
XPath: /package/video/assets/asset/data_file/data_file <data_file role="captions">Closed Captioning Data File (optional) Include a data file element block if the associated video contains captions. The " In this block, the |
XPath:/package/video/assets/asset/data_file/data_file/file_name <file_name>42foo666bar17-english.scc</file_name>File Name (required) The name of the caption file included in this delivery package. The name should be relative to the package (containing no path reference “C:\” or “/Macintosh HD/”) and must contain the file name extension (.scc in this example). Important: File names are case sensitive and spaces are not allowed. |
XPath: /package/video/assets/asset/data_file/data_file/size <size>9511</size>File Size (required) The size in bytes of the caption file. Do not include any commas nor period delimiters. |
XPath: /package/video/assets/asset/data_file/data_file/checksum <checksum type="md5">5a793a8b46037fe8aa2bdd739b49911a</checksum>Checksum (required) The MD5 checksum of the caption file. |
XPath:/package/video/assets/asset/data_file/data_file/locale <locale name="en-US"/>Locale Name (required) Identifies the language that is used for the captions. The locale indicates the language and the optional region where the language is spoken. You must supply the When updating a closed caption file, make sure the locale matches the locale of the file you are replacing. If the previously delivered file did not have a locale specified, you can deliver a new file with the new locale and the existing file will be replaced. If the previously delivered file had a locale specified and you want to replace it with a new file that has a different locale, you must first remove the existing captions file ( |
XPath: /package/video/assets/asset/data_file/data_file/attribute <attribute name="program.start.timecode">-01:00:00:00</attribute>Timecode Offset (optional) Indicates the timecode offset for the closed captions. Apple requires that timecodes start at a program start of 00:00:00:00, which may necessitate that captions be offset if they have been mastered to tape timecode. To keep closed captions in sync on the encoded file, use the |
</data_file></asset> |
</assets> </video></package> |
The following table lists the previously-released specifications and the revisions:
Date/Version | Summary |
|---|---|
August 31, 2020 - Version 1.3 | Added a new video subtype. |
June 29, 2020 - Version 1.2 | Added new video subtypes. |
October 28, 2019 - Version 1.1 | Added video asset guidelines. Added a new video subtype. The |
September 2019 - Version 1.0 | First release of the specification. |
Video Subtype
A new video subtype has been added that indicates the type of pre- or post-roll video you are delivering. The subtype is for “call to action” videos and the value to be used with the <subtype> tag is cta.
Tag Changes
Added
cta added as a new video subtype
Video Subtype
New video subtypes have been added that indicate the type of pre- or post-roll video you are delivering. The following values are used with the <subtype> tag:
Subtype values | Use for | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
customwarning | Non-legal warnings (such as sexual abuse or drug abuse) | ||||||||||
preview | Sneak peek of the next episode, season, or movie | ||||||||||
recap | Summary, or recap, of a previous season or episode | ||||||||||
trailer | Promotional purposes | ||||||||||
warning | Legal warning cards (such as a smoking warning required in India) | ||||||||||
Tag Changes
Added
customwarning added as a new video subtype
preview added as a new video subtype
recap added as a new video subtype
trailer added as a new video subtype
warning added as a new video subtype
Video Asset Guidelines
The pre-roll and post-roll videos should follow Apple guidelines. You can review those guidelines in Asset Guidelines.
Textless Master
The textless master attribute (<attribute name="image.textless_master">) is required for all videos; previously it was required only for videos that were textless. This attribute specifies whether or not the video contains burned-in text, such as narratives burnt into the visual picture or burned-in subtitles. Narrative text is text that appears on screen to supplement the content without the use of a narrator.
Video Subtype
A new video subtype can be used to inform the viewer that the content includes product placement. To specify a product placement pre- or post-roll video, deliver the value productplacement in the <subtype> tag.
Corrections/Clarifications
The crop attribute values supplied on the source video in the XML example have been changed to 0 pixels. If your video source file is delivered matted (letterbox, pillarbox, or windowbox), specify the non-zero crop values to crop the inactive pixels.
Each pre- or post-roll video can be a maximum of 90 seconds (the minimum is 5 seconds).
Tag Changes
Added
"image.textless_master" attribute on the source is now required for all videos
"image.burned_forced_narrative.locale" attribute on the source is now required for videos that contain burned-in narrative text
"image.burned_subtitles.locale" attribute on the source is now required for videos that contain burned-in subtitles
productplacement added as a new video subtype