This specification outlines the submission process for Apple Subscription Video partners. The subscription service offers movies, TV shows, seasons, and episodes. This specification covers the requirements for submitting your movies and TV content assets.
Customers can discover, purchase, and play subscription video content through Apple’s TV app and its Universal Media Catalog (UMC). You deliver your content assets, information about your catalog, and availability of your content.
The metadata you deliver about your content provides information for viewers to search for and to help make subscription purchasing decisions. For example, the metadata you deliver includes titles, descriptions, ratings, genres, and so on. It also shows the content quality and additional components available, such as subtitles, SDH, and audio description (also known as DVS). Viewers can browse through and make selections based on your offerings. See the UMC Catalog Data Interface Spec and the UMC Availability Data Interface Spec for more information on catalog and availability metadata.
Changes Made in This Release
Date/Version
Changes Made
September 2025—Version 1.11
Removed information about ambient videos, background videos, and production stills; additional minor corrections.
There are three components of the submissions process:
asset submission including video source (full and preview) and components (such as closed captions, subtitles, previews, and others)
catalog metadata (such as titles, descriptions, genres, ratings, artwork, and so on)
availability metadata (includes dates that the content will be made available, video quality choices, and the availability of options, such as audio description, SDH and in which languages)
For each item you want displayed in your catalog, you must submit the item asset(s), its catalog metadata, and its availability metadata. For example, in the case of a TV season, each episode video would be delivered in its own asset XML submission, but you must include catalog and availability metadata for the entire season in one catalog XML and one availability XML for each country.
You must assign each content item a catalog ID, content ID, and variant ID.
Identifier
Description
Catalog ID
Identifies your content catalog and tells Apple which catalog the content belongs to
Content ID
Identifies an individual item in the catalog
Variant ID
Distinguishes between different versions of the content, for example, the same asset with different territory-specific editorial or compliance requirements
Keep the following in mind when using these identifiers:
Catalog ID is assigned to the entire catalog, not a specific content item.
When you submit the catalog feed, only the Catalog ID and Content ID are required.
When you submit the availability feed, the Catalog ID, Content ID, and Variant ID are required.
When you submit the assets XML feed (as described in this document), the Catalog ID, Content ID, and Variant ID are required.
The combination of the content ID and variant ID must be unique across a catalog.
When you are ready to deliver your assets, the matching catalog metadata and availability metadata for those assets must be delivered as well.
The assets and asset XML files are delivered using an Apple tool called Transporter. The catalog metadata and availability metadata files are hosted by you on servers. You point Apple to the locations of those files, which Apple then accesses.
Content Types
The supported content types include:
Content Type
Description
Movie
Full-length movies (including feature films, short films, concert films, and documentaries)
TV Show
A TV show (sometimes referred to as a series) consists of episodes which can be linear (meant to be watched in order) or non-linear (which can be watched in any order). A TV show can also consist of seasons
TV Season
A TV season is a collection of episodes and is part of an episodic TV show
TV Episode
A TV episode is part of a TV show and can be part of a TV season
Submitting Assets
Introduction
You deliver video assets by submitting an XML file as a subscription video asset package (.itmsp). The .itmsp package must include at a minimum a metadata.xml file, video source, and captions (required for US). You can also submit a preview source and additional (and optional) components: subtitles (.itt), alternate audio, and other asset components. The encoded contents of the package you deliver is linked to your catalog metadata by the Content ID, which is supplied using the <umc_content_id> tag in the XML file.
You submit the file to Apple using the tool called Transporter (make sure to download and use the latest version). See the Transporter guide for information on how to download, install, and use Transporter.
Important: You must run the PSE (photosensitive epilepsy) test on your content prior to delivery.
Asset Requirements
The assets you deliver must conform to specific requirements, which are referred to as "profiles." The list below shows the assets accepted with a link to the asset requirements from the Video and Audio Asset Guide:
This example shows how to deliver a video asset for a movie. Delivering a TV video uses the same format and tags. In this example, the movie is in U.S. English, with French and Mexican Spanish localized asset components.
In addition to the main video asset, you can deliver pre-roll videos (videos that should play before the main video) and post-roll videos (videos that should play after the main video). The pre-roll and post- roll videos can, for example, include promo content, ratings, dub video, a logo, and certificates. You deliver the pre-roll and post-roll videos in separate XML deliveries (see Pre-Roll and Post-Roll Video Specification) and reference those videos by Vendor ID in the subscription video asset delivery XML using the <play_sequence> block. The videos are referenced in the order you want them to play.
To see a full description of each block, see XML Annotations for Full Source Delivery. For questions regarding this document, contact your Apple Technical Partner Representative.
Note: When you deliver your catalog metadata (described in another document), you can provide information on multiple videos (movies and TV content). However, each video must be delivered in its own subscription video asset delivery package. You can’t deliver multiple videos in the XML file.
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 version="subscriptionvideo5.0". The "subscriptionvideo" portion of the attribute must be in lowercase letters.
XPath: /comments
<comments>This video contains macro blocking at 03:25.</comments>
Comments (optional)
You can deliver quality control notes (for example, for describing a known issue with the asset). Use the <comments> tag to deliver comments that are less than 4,000 characters (approximately 2 double-spaced pages). For QC notes that are over 4,000 characters, use the attribute role="notes" with the <data_file> tag in the <asset> block. See the annotations later in this table.
XPath: /package/language
<language>en-US</language>
Language (required)
The primary language of the metadata for this package. See Languages and Locales for information on formatting.
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 <provider> tag is case-sensitive. Note that it is the value you pass as an argument to Transporter, not the value in the XML, that determines the account you are delivering to.
Video Metadata Fields
XPath: /package/video
<video>
Video (required)
Begins the video element. Only one video element can be defined per subscription video XML.
Universal Media Catalog Catalog ID (required; 1-255 characters)
Supplies the unique catalog identifier (as identified during Apple catalog registration). The value can contain both numbers and letters. Example: com.catalog.acme.
XPath: /package/video/umc_content_id
<umc_content_id>42abc33def17</umc_content_id>
Universal Media Catalog Content ID (required; 1-255 characters)
Defines the unique ID you are providing for this item. The value can contain both numbers and letters. Example: CP012391
This ID must be unique across all content types; no two items should have the same contentId even if their contentType is different.
The contentId for a given content item must be consistent and cannot be changed.
XPath: /package/video/umc_variant_id
<umc_variant_id>1</umc_variant_id>
Universal Media Catalog Variant ID (required; 1-32 characters)
Distinguishes between different versions of the content, for example the same asset with different territory-specific editorial or compliance requirements. The value can contain both numbers and letters, and underscores. If you do not have multiple versions, Apple suggests using 1 as the value.
XPath: /package/video/title
<title>The Movie</title>
Title (required, 1-255 bytes)
The name of this subscription video. This title is used for internal purposes and will not appear to the customer.
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 <original_spoken_locale>.
Note: This tag is different from the <language> tag. <original_spoken_locale> is the language the actors are seen speaking in. <language> is the primary language used for the metadata.
XPath: /package/video/production_number
<production_number>9406F</production_number>
Production Number (optional, 1-255 characters, can be updated)
Your production number for this episode. This value should be unique for each episode.
Note: Episode production numbers can contain only alphanumeric characters, spaces, hyphens (-), and underscores (_).
Asset Metadata Fields
XPath: /package/video/assets
<assets>
Assets (required, multiple from a set)
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">
Asset (required)
Describes the type of asset being delivered. Specify type="full" to indicate that the asset is the feature asset (as opposed to a preview). Only one full source asset can be delivered in one XML delivery.
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 or audio file, for example), the role is "source".
The <locale>, <file_name>, <size>, and <checksum> tags are 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.
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>2595225600</size>
File Size (required)
The size in bytes of the data file. Do not specify any commas nor period delimiters.
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:
crop.top: The number of whole pixels from the top of the encoded image to remove.
crop.bottom: The number of whole pixels from the bottom of the encoded image to remove.
crop.left: The number of whole pixels from the left of the encoded image to remove.
crop.right: The number of whole pixels from the right of the encoded image to remove.
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.
Intro and Credit Videos Start and End Times (optional)
Specifies the start and end times for intros at the beginning of the video (intro.) and credits at the end of the video (credits.). You can deliver up to ten intro videos and ten credits videos. The attribute names should include the number of the video (the "index value"), starting with 0 (zero) up to 9. The index value is required, so even if you are delivering only one starting video, for example, you must include the index value: "intro.0.start_time".
Keep the following in mind when delivering credits:
Index value is required and can be numbered from 0 up to 9
Index values must be consecutive, starting at 0, for each type
The time intervals must not overlap (for example, intro.1.start_time should not be before intro.0.end_time)
The time intervals must be consecutive
Credits should not be before intros
Use the attributes intro.[0-9].start.time and intro.[0-9].end.time for the beginning credits and use credits.[0-9].start.time and credits.[0-9].end.time for the ending credits.
If you are delivering these attributes, you must supply both the start time and end time.
You can supply these attributes with source and source.hdr assets. If you deliver both source and source.hdr, the timecodes must match.
Important: Do not include the Director and Writer credits within the intro or end credit time codes.
Specifies the end time for the main video. You can supply this attribute with source and source.hdr assets. This attribute is optional and can be used to indicate when the main portion of the video ends, before the Director and Writer credits begin.
Indicates that the video contains product placement. You can supply this attribute with source and source.hdr assets. Some countries require notification at beginning and end of a video if it contains product placement.
Allowed values are true or false. In this example, the subscription video has product placement, so the attribute is set to true.
Specifies the timecode used for the intros and credits videos. The format can be qt_text (default) or one of the SMPTE formats shown in Timecode Formats in Apple Transactional Film Specification.
If you omit the <timecode_format> tag, the format defaults to qt_text.
Specifies whether or not the subscription 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 plot of the story 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 subscription video.
This attribute is required for all subscription videos. Allowed values are true or false. In this example, the subscription video has burned-in narrative and burned-in subtitles, so the attribute is set to false.
Use this attribute to specify whether the video content has varying aspect ratios. Allowed values are true or false. The value defaults to false if you omit this attribute. This attribute can be used on all video sources.
Set this attribute to true to have the asset analyzed to detect the active regions of the video. This option applies the Per Frame Rectangular Mask (PFRM). Using the metadata that is generated by the analysis, the video player’s canvas size grows or shrinks with the video content when viewed on Apple Vision Pro.
To remove metadata generated by a previous analysis, deliver an update with this attribute set to false.
Photosensitive epilepsy (PSE) risk (required if a PSE test indicates a risk or if you are unable to run a PSE test)
Specifies whether to display a warning message that the content may trigger photosensitive epilepsy.
Allowed values are true or false.
If a PSE test indicates a possible risk, then set this attribute to true.
If you are unable to run a PSE test and your content may be affected, then set this attribute to true.
If your content is unaffected, then set this attribute to false or omit the attribute.
</data_file>
Ends the role="source" data file element block.
XPath: /package/video/assets/asset/data_file
<data_file role="captions">
Closed Captioning Data File (required for U.S. deliveries)
A data file element block must be included if the captions are delivered for the associated video. The "captions" role specifies that the delivered file is intended to be used as the closed captioning file for the Apple service encode. This role must be specified, or the package will be rejected.
In this block, the <locale>, <file_name>, <size>, and <checksum> tags are 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/size
<size>9511</size>
File Size (required)
The size in bytes of the caption file. Do not specify any commas nor period delimiters.
Identifies the language that is used for the captions on the full source asset. The locale indicates the language and the optional region where the language is spoken.
You must supply the <locale> tag for closed captions even if the language of the captions is the same as the language specified with the <language> tag.
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 (<data_file role="captions" remove="true">). Note that the full asset can have only one caption file. See the annotation in Change Locales for how to use the remove="true" attribute.
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 "program.start.timecode" attribute. The value is a SMPTE HH:MM:SS:FF timecode in non-drop frame with an optional negative (-) sign for negative offsets, for example, -01:00:00:00. This feature is supported for both non-drop and drop frame timecodes.
Begins the data file block that delivers an AD audio file. An Audio Description (AD) file allows visually-impaired customers to follow the subscription video with audio that describes the plot and what is being displayed visually on the screen. The “audio.visually_impaired” role specifies that the delivered file is intended to be used as an alternate audio file for Audio Description for the Apple service encode. If you are delivering an AD audio file, the file must be in 2.0 stereo and you can optionally deliver an additional AD file in 5.1 surround format (no 7.1 surround).
In this block, the <file_name>, <size>, <checksum>, and <locale> tags are required.
Important: File names are case sensitive and spaces are not allowed.
Identifies the language that is used for the AD audio track. The locale indicates the language and the optional region where the language is spoken.
You must supply the <locale> tag for the AD audio track even if the language of the audio is the same as the language specified with the <language> tag. If you deliver a package and do not include the locale for the AD file, you will see a warning that the locale is missing and that English ("en") will be used by default.
Note: Audio Description (AD) files are accepted for all languages and Apple includes the Audio Description when creating the final product. To be included in the final product, the locale of the audio description must match the locale of a corresponding source audio or alternate audio file. If you send an Audio Description file that doesn’t have a corresponding audio file, it will not go live in the catalog. For example, if you deliver a movie in English with French alternate audio, French AD, English AD, and Spanish AD, the final product for Canada would include English audio, French audio, English AD, and French AD; it would not include Spanish AD because there is no corresponding Spanish audio.
</data_file>
Ends the role="audio.visually_impaired" data file element block.
To deliver Dolby Digital Plus audio, use the role attribute (role="audio.7_1") with the <data_file> tag. The 7.1 surround audio is optional and is delivered as a role for the full asset.
Note: The video source can only contain 2.0 stereo and an optional 5.1 surround audio; 7.1 surround audio cannot be combined with the source.
Use the "audio.surround.force_5_1_downmix" attribute indicate how to handle existing 5.1 surround audio.
When you deliver 7.1 surround audio and a 5.1 surround audio file, you do not need to supply the "audio.surround.force_5_1_downmix" attribute; however, if you do supply it, it must be set to false.
When you deliver 7.1 surround audio and a 5.1 surround audio file, you do not need to supply the "audio.surround.force_5_1_downmix" attribute; however, if you do supply it, it must be set to true. 5.1 surround audio will be automatically downmixed.
For additional content considerations for 7.1 audio, see 7.1 Surround Audio Delivery in Apple Transactional Film Specification.
Important: File names are case sensitive and spaces are not allowed.
To deliver Dolby Atmos audio, use the role attribute (role="audio.object_based") with the <data_file> tag. The Dolby Atmos audio is optional and is delivered as a role for the full asset.
Note: The video source can only contain 2.0 stereo and an optional 5.1 surround audio; Dolby Atmos audio cannot be combined with the source.
The <locale> tag should match the associated stereo audio locale (which could be the audio on the video source or an alternate audio). If the locales do not match, the availability of the Atmos audio will not be listed.
Territory and language-specific audio (stereo and optionally 5.1 surround) can be supplied using the "locale" metadata structure. If used, the language must be included to specify the language; the region where the language is spoken is optional. One audio file can be provided for each desired language (and region). The <locale> tag is required for localized audio assets.
Subtitles are delivered as a role for the full asset. The files must be in the iTT file format with the extension .itt. See iTunes Timed Text Profile in Apple Transactional Film Specification for information on the iTT file format.
The <locale> identifies the language in which the subtitles appear. The locale indicates both the language and the optional location where the language is spoken.
The forced subtitles data file contains the set of subtitles that must be forced-displayed when the matching dubbed audio locale is played by a viewer.
Forced subtitles are delivered as a role for the full asset. The files must be in the iTT file format with the extension .itt. See iTunes Timed Text Profile in Apple Transactional Film Specification for information on the iTT file format.
The <locale> identifies the language in which the forced subtitles appear. The locale indicates both the language and the optional location where the language is spoken.
Note: Forced subtitles are tied to audio and automatically display in a player if that audio is selected for playback. Therefore, the locale value of any delivered forced subtitle file must be the same as its corresponding audio. For example, if the film’s audio is German, the German forced subtitle file must have a locale name of de-DE. Text in forced subtitles must be duplicated in the full subtitle file of the same language because they do not automatically play back when the full subtitle is selected.
Important: File names are case sensitive and spaces are not allowed.
A data file element block must be included if the SDH are delivered for the associated video. The "subtitles.hearing_impaired" role specifies that the delivered file is intended to be used as the SDH file for the video. The files must be in the iTT file format with the extension .itt. See iTunes Timed Text Profile in Apple Transactional Film Specification for information on the iTT file format.
Important: File names are case sensitive and spaces are not allowed.
The <locale> identifies the language of the text in the SDH file delivered in this <data_file> block.
A data file element block must be included to deliver quality control notes (for example, for describing a known issue with the asset). To deliver QC notes that are over 4,000 characters, use the attribute role="notes" with the <data_file> tag.
In this block, the role attribute and <filename>, <checksum>, and <size> tags are required.
Note: The text of the quality control note can also be delivered using a <comments> tag.
Important: File names are case sensitive and spaces are not allowed.
</asset> </assets>
Video Metadata Fields
XPath: /package/video/chapters
<chapters>
Chapters (optional)
Defines chapters within a video.
Note: Chapter titles and chapter artwork can be added or changed, however you must send all chapters, not just the ones being updated. Chapter artwork can be provided in an artwork file or specified by a timecode.
The format can be qt_text or one of the SMPTE formats illustrated in Timecode Formats in Apple Transactional Film Specification. If you omit the <timecode_format> tag, the format defaults to qt_text.
Each chapter requires an artwork image, either an artwork file or a frame specified by a timecode. If you specify a timecode but use the qt_text format, the frame nearest the timecode is used for the chapter image: you cannot specify a frame for the chapter image using qt_text.
Important: The frame modes (for example, nonDrop and dropNTSC) are case-sensitive.
XPath: /package/video/chapters/chapter
<chapters>
Chapters (required if providing chapters)
Defines the first chapter within the <chapters> tag.
There is no limit to the number of chapters you can define.
XPath: /package/video/chapters/chapter/start_time
<start_time>00:00:00:00</start_time>
Chapter Start Time (required if providing chapters)
Specifies the start of each chapter as dictated by the <timecode_format> above. End time is inferred from the start time of the next defined chapter. Refer to Timecode Formats in Apple Transactional Film Specification for <start_time> examples.
The first chapter must start at 00:00:00:00 and the chapters must be listed in chronological order.
<titles> <title locale="en-US">The Story Begins</title> <title locale="fr-FR">L'Histoire Commence</title> <title locale="es-MX">La historia comienza</title></titles>
Chapter Titles (required if providing chapters; 1-255 bytes)
The titles of the chapter, one for each locale.
Use the locale attribute to specify both the language and the optional region where the language is spoken. See Languages and Locales for more information.
If you are providing only one title, you do not need to use the <titles></titles> tag.
Note: It is recommended that the chapters provided match what is on the original content. In addition, include a chapter for video credits as the last chapter. There is a 255-byte limit strictly enforced. The data is stored in the UTF-8 encoding, so for single-byte characters (such as those drawn from the ASCII character set), this equates to a 255-character limit; for multiple-byte (e.g., Japanese) characters, this can equate to as few as 71 characters.
Artwork File (required, if providing an image file)
The filename of the image to be used to represent this chapter. Do not include a path. You must provide the <file_name>, <size>, and <checksum>. Each chapter must have an associated image: either an artwork file or an artwork timecode. See the annotation below for how to deliver an artwork timecode.
Include the artwork files in the package directory along with the basic metadata file. The artwork can be JPEG with .jpg extension or PNG with .png extension. Chapter images must be cropped (no letterbox, pillarbox, or windowbox). Each artwork file image must have a unique filename.
Important: File names are case sensitive and spaces are not allowed.
Artwork Time (required, if specifying a frame by timecode)
The timecode of the frame to be used to represent this chapter. You must provide a valid timecode from within the chapter. Each chapter must have an associated image: either an artwork file or an artwork timecode. See the annotation above for how to deliver an artwork file.
In qt_text format, the frame nearest the timecode is used for the chapter image: you cannot specify a frame for the chapter image using qt_text.
Each artwork timecode must be unique.
</chapter></chapters>
XPath: /package/video/play_sequences
<play_sequences>
Play Sequences (optional)
Begins the play sequences block where you deliver your pre-roll and post-roll videos. You can deliver a different sequence of pre-roll and post-roll videos for a territory by specifying a separate <play_sequence> for that territory (see the Play Sequence Item by Territory annotation below).
To make changes to the play sequence, you must deliver the entire <play_sequences> block with all the <play_sequence> tags, even if you are not making changes to a particular play sequence. To remove a play sequence, deliver the entire <play_sequences> block, omitting the play sequence you want to remove. To remove all previously delivered play sequences, send an empty tag: <play_sequences/>.
Note: Only the full asset will be played in a territory if any of the following apply:
the <play_sequences> tag is not supplied
an empty tag <play_sequences/> is supplied
a <play_sequence> tag is supplied that excludes a territory
Begins the play sequence block where you deliver your pre-roll and post-roll videos. The first example is not territory-specific and these videos will be played for world-wide viewers. If a territory requires/has territory-specific videos, you can deliver those videos in their own <play_sequence> block. See the Play Sequence Item by Territory annotation below.
Keep the following guidelines in mind when creating the play sequence:
The rating of the video should not be higher than the associated show or movie.
The frame rate, resolution, and color space of the pre- or post-roll video should match the associated show or movie if possible.
The accessibility options of the pre- or post-roll video should match the accessibility options of the associated show or movie.
For each pre-roll and post-roll video, supply the item type (pre-roll or post-roll) with the type attribute and the vendor ID of the video item with the vendor_id attribute. This vendor ID must match the vendor ID of the video as supplied in the separate video asset delivery. See the Pre-Roll and Post-Roll Video Specification for how to deliver the pre-roll and post-roll videos.
Add as many pre-roll or post-roll videos as needed in the order in which you want them to appear.
In this example, the default pre-roll or post-roll videos will play in all territories except MX. To exclude videos from playing in a territory, add a <play_sequence> enclosing the <territories> tag, where you add the code for the excluded territory.
To indicate that the viewer can skip the pre-roll video, use the skippable attribute set to "true". Note that the skippable attribute can be used only on pre-roll videos, except for a pre-roll video that contains ratings; those cannot be skipped.
Use the <territories> block to indicate one or more territories where the specified pre- roll and post-roll videos should play. For each pre-roll and post-roll video, supply the item type (pre-roll or post-roll) with the type attribute and the vendor ID of the video item with the vendor_id attribute. This vendor ID must match the vendor ID of the video as supplied in the separate video asset delivery. See Pre-Roll and Post-Roll Video Specification for how to deliver the pre-roll and post-roll videos.
Add as many pre-roll or post-roll videos as needed in the order in which you want them to appear.
</play_sequences> </video></package>
XML Example for Preview Delivery
This example shows how to deliver a package for a preview video asset using the <subtype> tag. In this example, the preview is in U.S. English and includes closed captions.
Note: For shows, you can add a preview for the show as a whole, and you can add previews for each episode. Note that each preview must be delivered in its own package; you can’t deliver multiple preview assets in one delivery.
Keep the following in mind when delivering a preview:
If you deliver a package with the <subtype> tag set to preview, you cannot also deliver a full video in the same package.
Delivering <territories> for previews is not supported.
Defined previews are not supported.
To see a full description of each block, see XML Annotations for Preview Source Delivery. For questions regarding this document, contact your Apple Technical Partner Representative.
This example shows how to deliver a package for an epic stage video asset using the <subtype> tag. Use "featuredpromo" as the subtype and "preview" as the asset type in the XML.
Keep the following in mind when delivering an epic stage video:
Although you can have multiple epic stage videos for a single TV show or movie, each video must be delivered in its own package with a unique content ID. You can’t deliver multiple epic stage video assets with the same content ID.
If you deliver a package with the <subtype> tag set to featuredpromo, you cannot also deliver a full video in the same package.
An epic stage video needs to be exclusively featured. Contact your Apple Technical Partner Representative before providing content of this type.
To see a full description of each block, see XML Annotations for Preview Source Delivery. For questions regarding this document, contact your Apple Technical Partner Representative.
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 version="subscriptionvideo5.0". The "subscriptionvideo" portion of the attribute must be in lowercase letters.
XPath: /package/language
<language>en-US</language>
Language (required)
The primary language of the metadata for this package. See Languages and Locales for information on formatting.
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 <provider> tag is case-sensitive. Note that it is the value you pass as an argument to Transporter, not the value in the XML, that determines the account you are delivering to.
Video Metadata Fields
XPath: /package/video
<video>
Video (required)
Begins the video element. Only one video element can be defined per subscription video XML.
Universal Media Catalog Catalog ID (required; 1-255 characters)
Supplies the unique catalog identifier (as identified during Apple catalog registration). The value can contain both numbers and letters. Example: com.catalog.acme.
XPath: /package/video/umc_content_id
<umc_content_id>42abc33def17</umc_content_id>
Universal Media Catalog Content ID (required; 1-255 characters)
Defines the unique ID you are providing for this item. The value can contain both numbers and letters. Example: CP012391
This ID must be unique across all content types; no two items should have the same contentId even if their contentType is different.
The contentId for a given content item must be consistent and cannot be changed.
XPath: /package/video/umc_variant_id
<umc_variant_id>1</umc_variant_id>
Universal Media Catalog Variant ID (required; 1-32 characters)
Distinguishes between different versions of the content, for example the same asset with different territory-specific editorial or compliance requirements. The value can contain both numbers and letters, and underscores. If you do not have multiple versions, Apple suggests using 1 as the value.
XPath: /package/video/title
<title>The Preview</title>
Title (required, 1-255 bytes)
The name of this subscription video preview. This title is used for internal purposes and will not appear to the customer.
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 <original_spoken_locale>.
Note: This tag is different from the <language> tag. <original_spoken_locale> is the language the actors are seen speaking in. <language> is the primary language used for the metadata.
Asset Metadata Fields
XPath: /package/video/assets
<assets>
Assets (required, multiple from a set)
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="preview">
Asset (required)
Describes the type of asset being delivered. Specify type="preview" to indicate that the asset is a preview trailer.
Use the <asset type="preview"> to deliver a custom preview.
Deliver the custom preview source in a <data_file> block. The preview source data file contains the preview length video and audio streams.
The <locale name> is required and it identifies the language that is spoken in the audio on the source asset, regardless of the territories in which it is to be sold. It indicates the language and the optional region where the language is spoken.
One custom preview file can be provided for each territory. For each territory, the preview can have optional data files for alternate audios or subtitles.
</asset>
XPath: /package/video/assets/asset/data_file
<data_file role="captions">
Closed Captioning Data File (required for U.S. deliveries)
A data file element block must be included if the captions are delivered for the associated video. The "captions" role specifies that the delivered file is intended to be used as the closed captioning file for the Apple service encode. This role must be specified, or the package will be rejected.
In this block, the <locale>, <file_name>, <size>, and <checksum> tags are 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/size
<size>9511</size>
File Size (required)
The size in bytes of the caption file. Do not specify any commas nor period delimiters.
Identifies the language that is used for the captions on the preview source asset. The locale indicates the language and the optional region where the language is spoken.
You must supply the <locale> tag for closed captions even if the language of the captions is the same as the language specified with the <language> tag.
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 (<data_file role="captions" remove="true">). See the annotation in Change Locales for how to use the remove="true" attribute.
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 "program.start.timecode" attribute. The value is a SMPTE HH:MM:SS:FF timecode in non-drop frame with an optional negative (-) sign for negative offsets, for example, -01:00:00:00. This feature is supported for both non-drop and drop frame timecodes.
</data_file> </asset></assets>
HDR Dolby Vision
HDR Dolby® Vision Full Source Video Metadata Example
To deliver HDR Dolby® Vision video, two roles have been added for use with the <asset> tag: source.hdr and mapping.hdr. The following metadata example shows how to use the roles in a subscription video update. This example adds an HDR Dolby® Vision video to a previously-delivered subscription video. The package delivered would consist of the metadata file, the HDR Dolby® Vision source video, and the sidecar metadata file. The primary subscription video source must be referenced by its content identifiers (<umc_catalog_id>, <umc_content_id>, and <umc_variant_id>).
Note: An SDR asset is required for a Dolby Vision delivery unless you are using <attribute name="video.hdr.force_sdr_downconvert">true</attribute> to down-convert to SDR.
To deliver the HDR and SDR video at the same time, see the example in HDR and SDR Delivery.
Universal Media Catalog Catalog ID (required; 1-255 characters)
Specifies the unique catalog identifier of the primary subscription video source (as identified during Apple catalog registration). The value can contain both numbers and letters.
When adding HDR to an existing subscription video, you must supply the content identifiers. Those values must match the identifiers of the existing subscription video. You do not need to re-deliver the subscription video data file.
XPath: /package/video/umc_content_id
<umc_content_id>42abc33def17</umc_content_id>
Universal Media Catalog Content ID (required; 1-255 characters)
Defines the unique ID you assigned to the primary subscription video source. The value can contain both numbers and letters.
When adding HDR to an existing subscription video, you must supply the content identifiers. Those values must match the identifiers of the existing subscription video. You do not need to re-deliver the subscription video data file.
XPath: /package/video/umc_variant_id
<umc_variant_id>1</umc_variant_id>
Universal Media Catalog Variant ID (required; 1-32 characters)
Distinguishes between different versions of the primary subscription video source, for example the same asset with different territory-specific editorial or compliance requirements. The value can contain both numbers and letters, and underscores. If you do not have multiple versions, Apple suggests using 1 as the value.
When adding HDR to an existing subscription video, you must supply the content identifiers. Those values must match the identifiers of the existing subscription video. You do not need to re-deliver the subscription video data file.
Asset Metadata Fields
XPath: /package/video/assets
<assets>
Assets (required)
Begins the assets block that references the assets being delivered.
XPath: /package/video/assets/asset/data_file
<asset type="full"> <data_file role="source.hdr">
HDR Source Asset (required)
The data file block specifies the source video file and describes the role of the associated file. In this example, the file sent is used as the HDR source, so the role must be "source.hdr".
The secondary source video must be the same duration as the primary subscription video source so that components such as subtitles and audio can be used with the secondary video.
In this block, the <locale>, <file_name>, <size>, and <checksum> tags are required.
For additional content considerations about HDR delivery, see HDR Delivery in Apple Transactional Film Specification.
In this example, the HDR video source is Dolby® Vision, which must be specified with the hdr.format attribute. Specifying the HDR format is required. Roles allowed for the hdr.format attribute include DolbyVision and HDR10. Only one hdr.format value can be specified.
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.
The value for textless master for the HDR source video must match the value for textless master primary subscription video. If they do not match, delivery will fail.
If the value is set to false, you must also supply the "image.burned_subtitles.locale" and/or "image.burned_forced_narrative.locale" attributes. See the annotation in XML Annotations for Delivery.
The data file block specifies the sidecar file and describes the role of the associated file. The maximum frame number (edit unit) referenced in the sidecar metadata file must be less than or equal to the last frame number of the secondary HDR video.
For initial delivery, both the source HDR video file and the mapping file must be included or delivery will fail. When you send an update to deliver a new source HDR, the mapping file should be supplied (either by sending it with the update delivery or by using the previously-delivered mapping file). The mapping file, however, can be delivered (and updated) without specifying the source HDR.
In this block, the <locale>, <file_name>, <size>, and <checksum> tags are required.
Both Dolby Vision CM version 2.9 and CM version 4.0 sidecar metadata files are supported.
</asset> </assets>
</video></package>
HDR Dolby Vision Preview Source Video Metadata Example
To deliver HDR Dolby® Vision preview source video, two roles have been added for use with the <asset> tag: source.hdr and mapping.hdr. The following metadata example shows how to use the roles in a subscription video update. This example adds an HDR Dolby® Vision preview video to a previously-delivered subscription video. The package delivered would consist of the metadata file, the HDR Dolby® Vision preview source video, and the sidecar metadata file. The primary subscription video source must be referenced by its content identifiers (<umc_catalog_id>, <umc_content_id>, and <umc_variant_id>). To deliver the HDR and SDR video at the same time, see the example in HDR and SDR Delivery.
Universal Media Catalog Catalog ID (required; 1-255 characters)
Specifies the unique catalog identifier of the primary subscription video source (as identified during Apple catalog registration). The value can contain both numbers and letters.
When adding HDR to an existing subscription video, you must supply the content identifiers. Those values must match the identifiers of the existing subscription video. You do not need to re-deliver the subscription video data file.
XPath: /package/video/umc_content_id
<umc_content_id>42abc33def17</umc_content_id>
Universal Media Catalog Content ID (required; 1-255 characters)
Defines the unique ID you assigned to the primary subscription video source. The value can contain both numbers and letters.
When adding HDR to an existing subscription video, you must supply the content identifiers. Those values must match the identifiers of the existing subscription video. You do not need to re-deliver the subscription video data file.
XPath: /package/video/umc_variant_id
<umc_variant_id>1</umc_variant_id>
Universal Media Catalog Variant ID (required; 1-32 characters)
Distinguishes between different versions of the primary subscription video source, for example the same asset with different territory-specific editorial or compliance requirements. The value can contain both numbers and letters, and underscores. If you do not have multiple versions, Apple suggests using 1 as the value.
When adding HDR to an existing subscription video, you must supply the content identifiers. Those values must match the identifiers of the existing subscription video. You do not need to re-deliver the subscription video data file.
Asset Metadata Fields
XPath: /package/video/assets
<assets>
Assets (required)
Begins the assets block that references the assets being delivered.
The data file block specifies the preview source video file and describes the role of the associated file. In this example, the file sent is used as the HDR source, so the role must be "source.hdr".
The secondary preview source video must be the same duration as the primary subscription video preview source so that components such as subtitles and audio can be used with the secondary video.
In this block, the <locale>, <file_name>, <size>, and <checksum> tags are required.
In this example, the HDR video source is Dolby® Vision, which must be specified with the hdr.format attribute. Specifying the HDR format is required. Roles allowed for the hdr.format attribute include DolbyVision and HDR10. Only one hdr.format value can be specified.
The locale for the HDR preview source video must match the locale of the primary subscription video preview source. If they do not match, delivery will fail.
The name of the preview 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.
The value for textless master for the HDR preview source video must match the value for textless master primary subscription video preview. If they do not match, delivery will fail.
If the value is set to false, you must also supply the "image.burned_subtitles.locale" and/or "image.burned_forced_narrative.locale" attributes. See the annotation in XML Annotations for Delivery.
XPath: /package/video/assets/asset/data_file
<data_file role="mapping.hdr">
HDR Preview Sidecar Mapping File (required)
The data file block specifies the sidecar file for the preview asset and describes the role of the associated file. The maximum frame number (edit unit) referenced in the sidecar metadata file must be less than or equal to the last frame number of the secondary HDR preview video.
For initial delivery, both the HDR preview video file and the mapping file must be included or delivery will fail. When you send an update to deliver a new HDR preview, the mapping file should be supplied (either by sending it with the update delivery or by using the previously-delivered mapping file). The mapping file, however, can be delivered (and updated) without specifying the preview.
In this block, the <locale>, <file_name>, <size>, and <checksum> tags are required.
Both Dolby Vision CM version 2.9 and CM version 4.0 sidecar metadata files are supported.
</asset> </assets>
</video></package>
Dolby® Vision-Only (No SDR) Delivery with Embedded Audio
You can deliver Dolby Vision HDR video without a corresponding SDR video delivery and specify a tag to down-convert to SDR. Apple will create the SDR video using the Dolby Vision SDR trim metadata. Using this method is optional, but it could streamline the delivery process for you. When you deliver a Dolby Vision-only package, you can choose to include embedded audio or you can deliver the audio in a separate file.
Note: This delivery method is not available for HDR 10 videos.
To deliver a Dolby Vision-only package, you must use the attribute that indicates you want the HDR video to be down-converted to SDR: <attribute name="video.hdr.force_sdr_downconvert">true</attribute>.
This example shows how to deliver Dolby Vision HDR video without an SDR video delivery. When you deliver a Dolby Vision-only package, you can choose to include embedded audio or you can deliver the audio in a separate file. In this example, the HDR full source video includes embedded audio. Since there is no SDR audio in this delivery (the default audio source), the HDR source is used as the primary audio source.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="subscriptionvideo5.0"> <provider>AppleseedEntertainment</provider> <video> <umc_catalog_id>AppleseedEntertainment.service1.US</umc_catalog_id> <umc_content_id>42abc33def17</umc_content_id> <umc_variant_id>1</umc_variant_id> <!-- To save space, several tags have been omitted from this XML. See the basic example for all the tags. --> . . . <assets> <asset type="full"> <data_file role="source.hdr"> <attribute name="hdr.format">DolbyVision</attribute> <attribute name="video.hdr.force_sdr_downconvert">true</attribute> <locale name="en-US"/> <file_name>09736156444-hdr-source.mov</file_name> <size>3244032000</size> <checksum type="md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</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="intro.0.start_time">00:00:32.052</attribute> <attribute name="intro.0.end_time">00:01:15.002</attribute> <attribute name="intro.1.start_time">00:01:20.044</attribute> <attribute name="intro.1.end_time">00:01:55.009</attribute> <attribute name="credits.0.start_time">00:42:06.011</attribute> <attribute name="credits.0.end_time">00:42:21.003</attribute> <attribute name="credits.1.start_time">00:56:13.024</attribute> <attribute name="credits.1.end_time">00:57:01.008</attribute> <attribute name="main.end_time">00:00:40.050</attribute> <attribute name="timecode_format">qt_text</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <data_file role="mapping.hdr"> <file_name>09736156444-mapping.xml</file_name> <size>16659</size> <checksum type="md5">df86c3eeabb2ddfe4b843e7b943dda42</checksum> </data_file> <!-- Other data files (such as captions, subtitles) go here --> </asset> </assets> </video></package>
Dolby® Vision HDR-Only (No SDR) Delivery with Embedded Audio Metadata Annotations
These annotations cover only the tags for use for downconverting HDR to SDR.
Asset Level Tags
XPath: /package/video/assets/asset
<asset type="full">
<data_file role="source.hdr">
HDR Source Asset (required)
The data file block specifies the source video file and describes the role of the associated file. In this example, the file sent is used as the HDR source, so the role must be "source.hdr".
In this block, the <locale>, <file_name>, <size>, and <checksum> tags and the "image.textless_master" attribute are required.
For additional content considerations about HDR delivery, see HDR Delivery in Apple Transactional Film Specification.
In this example, the HDR video source is Dolby® Vision, which must be specified with the hdr.format attribute. Specifying the HDR format is required. Roles allowed for the hdr.format attribute include DolbyVision and HDR10, but for this Dolby HDR-only delivery, the role must be DolbyVision. Only one hdr.format value can be specified.
HDR Down-Convert to SDR (required for HDR-only deliveries)
In this example, the HDR video source is being delivered without a corresponding SDR video. To deliver a Dolby Vision-only package, you must use this attribute that indicates you want the HDR video to be down-converted to SDR.
XPath: /package/video/assets/asset/data_file
<asset type="full">
<data_file role="mapping.hdr">
HDR Sidecar Mapping File (required)
The data file block specifies the sidecar file and describes the role of the associated file. The maximum frame number (edit unit) referenced in the sidecar metadata file must be less than or equal to the last frame number of the secondary HDR video.
For initial delivery, both the source HDR video file and the mapping file must be included or delivery will fail. When you send an update to deliver a new source HDR, the mapping file should be supplied (either by sending it with the update delivery or by using the previously-delivered mapping file). The mapping file, however, can be delivered (and updated) without specifying the source HDR.
In this block, the <file_name>, <size>, and <checksum> tags are required.
Both Dolby Vision CM version 2.9 and CM version 4.0 sidecar metadata files are supported.
Dolby® Vision-Only (No SDR) Preview Source Video Delivery with Embedded Audio
You can deliver Dolby Vision HDR preview video without a corresponding SDR video delivery and specify a tag to down-convert to SDR. Apple will create the SDR video using the Dolby Vision SDR trim metadata. Using this method is optional, but it could streamline the delivery process for you. When you deliver a Dolby Vision-only package, you can choose to include embedded audio or you can deliver the audio in a separate file.
Note: This delivery method is not available for HDR 10 videos.
To deliver a Dolby Vision-only package, you must use the attribute that indicates you want the HDR video to be down-converted to SDR: <attribute name="video.hdr.force_sdr_downconvert">true</attribute>.
This example shows how to deliver Dolby Vision HDR preview video without an SDR video delivery. When you deliver a Dolby Vision-only package, you can choose to include embedded audio or you can deliver the audio in a separate file. In this example, the HDR full source video includes embedded audio. Since there is no SDR audio in this delivery (the default audio source), the HDR source is identified as the primary audio source.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="subscriptionvideo5.0"> <provider>AppleseedEntertainment</provider> <video> <subtype>preview</subtype> <umc_catalog_id>AppleseedEntertainment.service1.US</umc_catalog_id> <umc_content_id>42abc33def17</umc_content_id> <umc_variant_id>1</umc_variant_id> <!-- To save space, several tags have been omitted from this XML. See the basic example for all the tags. --> . . . <assets><!-- Required. World Trailer. Will be used where territory-specific trailer has not been provided --> <asset type="preview"> <data_file role="source.hdr"> <attribute name="hdr.format">DolbyVision</attribute> <attribute name="video.hdr.force_sdr_downconvert">true</attribute> <attribute name="primary_audio">true</attribute> <locale name="en-US"/> <file_name>09736156444-hdr-preview.mov</file_name> <size>9987212</size> <checksum type="md5">739b43b793a8b46037fe8aa29dd9911e</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">true</attribute> </data_file> <data_file role="mapping.hdr"> <file_name>09736156444-preview-mapping.xml</file_name> <size>16659</size> <checksum type="md5">b8ddfe443e7df86c3eeabb2b943dda42</checksum> </data_file> </asset> </assets> </video></package>
Audio Delivery Examples and Annotations
Dolby Atmos Audio Downmixing
If you deliver a Dolby Atmos audio file, you can specify that you want Apple to downmix to other formats. This allows you to deliver a single Atmos audio file and derive all of the other formats (7.1, 5.1, and stereo). You use the following attributes on the Dolby Atmos source audio:
audio.transform_to.2.0
audio.transform_to.5.1
audio.transform_to.7.1
If you downmix Atmos audio to stereo (2.0) for the main locale, you must specify it as the primary audio using <attribute name="primary_audio">true</attribute> and you must also use ignore_audio on any video sources with embedded audio (HDR or SDR):
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="subscriptionvideo5.0"> <provider>AppleseedEntertainment</provider> <video> <umc_catalog_id>AppleseedEntertainment.service1.US</umc_catalog_id> <umc_content_id>42abc33def17</umc_content_id> <umc_variant_id>1</umc_variant_id><!-- NOTE: Some tags not related to this example have been omitted (as indicated by the three dots) for brevity and focus; see the basic example for information on sending other tags. Do not omit this data from your package. --> . . .<!-- SDR asset with embedded audio. --> <assets> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>2028660952</size> <checksum type="md5">9dd73937fe8aa22a793a8b460b49911a</checksum> <attribute name="ignore_audio">true</attribute> <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">true</attribute> </data_file><!-- Dolby Atmos audio to be used as primary audio --> <data_file role="audio.object_based"> <locale name="en-US"/> <file_name>audio_atmos.wav</file_name> <size>1142644642</size> <checksum type="md5">bc5b28a6200e5273202b7609f626fec0</checksum> <attribute name="audio.transform_to.2_0">true</attribute> <attribute name="audio.transform_to.5_1">true</attribute> <attribute name="audio.transform_to.7_1">true</attribute> <attribute name="primary_audio">true</attribute> </data_file> </asset> </assets> . . . </video></package>
Dolby Atmos Audio Downmixing Annotations
These annotations cover only the tags for use with Dolby Atmos audio.
Ignore Embedded Audio (required if a video file has embedded audio and if delivering another primary audio file)
In this example, Dolby Atmos audio is being delivered and used to provide 2.0, 5.1, and 7.1 audio formats. The source video includes embedded audio, but the Dolby Atmos audio file will be used as the primary audio. In this case, you must use the ignore_audio attribute.
Note that ignore_audio is not required if the video has no audio to ignore.
To deliver Dolby Atmos audio, use the role role="audio.object_based" with the <data_file> tag. The Dolby Atmos audio is optional and is delivered as a role for the full asset. In this example, the Dolby Atmos audio file will be downmixed to 7.1, 5.1, and 2.0 formats. This is specified using the <attribute> tag, one for each format and set to true. If you downmix Atmos audio to stereo (2.0) for the locale you want for the package, you must specify the Dolby Atmos audio file as the primary audio using <attribute name="primary_audio">true</attribute> and you must also use ignore_audio on the source video.
This primary audio aligns with the primary audio locale you want for the package. For example, if the movie has dubbed Russian and is sold only in Russia, the primary audio would be “ru” even though the video source is “en-US”.
Notes:
Dolby Atmos must be delivered in ADM BWAV format.
These attributes can only be specified for data files with the role of audio.object_based
As long as you downmix a Dolby Atmos audio to 2.0 format, you do not need to deliver other audio asset files. This allows you to deliver a single Atmos audio file and derive all of the other formats (7.1, 5.1, and stereo).
If the source video contains embedded audio, you must use the attribute ignore_audio on the source video.
For each locale, you can have only one audio by type. For example, if you deliver a 7.1 surround audio asset for en-US and also downmix the Dolby Atmos audio to 7.1 for en-US, you will get an error. If the source video contains embedded stereo (and you do not specify ignore_audio) and also downmix the Dolby Atmos audio to 2.0 for en-US, you will get an error.
In this delivery, the SDR source does not have embedded audio. An alternate audio is delivered as a separate file and it will be used as the primary audio. If you deliver more than one alternate audio file, the audio file with the locale that matches the source video will be used as the primary audio, unless you specify a different primary locale.
For the sake of brevity, the example is an excerpt from a full metadata delivery. The example shows the tags relevant to SDR delivery with no embedded audio; see the XML Annotations for Full Source Delivery for explanations of the remaining tags.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="subscriptionvideo5.0"> <provider>AppleseedEntertainment</provider> <video> <umc_catalog_id>AppleseedEntertainment.service1.US</umc_catalog_id> <umc_content_id>42abc33def17</umc_content_id> <umc_variant_id>1</umc_variant_id><!-- NOTE: Some tags not related to this example have been omitted (as indicated by the three dots) for brevity and focus --> . . .<!-- SDR asset with no embedded audio. --> <assets> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>2028660952</size> <checksum type="md5">9dd73937fe8aa22a793a8b460b49911a</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">true</attribute> </data_file><!-- Audio to be used as primary audio, which should include both stereo and 5.1 --> <data_file role="audio"> <locale name="en-US"/> <file_name>audio_09736156444.mov</file_name> <size>8730177839</size> <checksum type="md5">a765a9fc88ac893ead51366fbeb04d82</checksum> <attribute name="primary_audio">true</attribute> </data_file> </asset> </assets> . . . </video></package>
Basic Example SDR Delivery with no Embedded Audio Annotations
These annotations cover only the tags for use with an SDR video with no embedded audio.
Primary Audio (required if source does not have embedded audio)
In this example, the SDR video source does not have embedded audio, and another audio file will be used as the primary audio. You must use the primary_audio attribute on the audio source file you want to use as the main audio. Note that there can only be one primary audio per package. Keep in mind that the primary audio must include stereo (and ideally 5.1).
Note: This primary audio should align with the primary audio locale you want for the package. For example, if the video is dubbed in Russian and is sold only in Russia, the primary audio would be "ru" even though the video source is "en-US".
HDR10 Metadata
HDR10 Full Source Video Metadata Example
To deliver HDR10 full source video, you must supply the source.hdr role with the hdr.format set to HDR10. A mapping file is not required; if you deliver a mapping file, delivery will fail. Instead, you provide the attributes in the metadata XML file as shown below. This example adds an HDR10 full source video to a previously-delivered SDR subscription video. The package delivered would consist of the metadata file, the HDR10 full source video, and the required attributes. The primary subscription video source must be referenced by its content identifiers (<umc_catalog_id>, <umc_content_id>, and <umc_variant_id>).
Note: An SDR asset is required for an HDR10 delivery. To deliver the HDR and SDR video at the same time, see the example in HDR and SDR Delivery. Down-convert to SDR is not available for HDR10 videos.
Note: The chromaticity values listed in the example and annotations below are for a P3 display with D65 white point. For a BT.2020 display with D65, see the annotation on HDR10 Chromaticity Attributes for examples of value formatting.
Only the tags related to the HDR10 delivery are described. The attributes follow the SMPTE ST 2086 metadata guidelines. Refer to Subscription Video Asset Delivery XML Annotations for annotations on other tags.
Note: It is beyond the scope of this document to describe the details of the mastering display attributes. Refer to "SMPTE ST 2086:2014" and the Blu-ray / DECE definitions of Maximum Content Light Level (MaxCLL) / Maximum Frame Average Light Level (MaxFALL) metadata for further information. This document covers only how to deliver the attribute values.
Asset Metadata Fields
XPath: /package/video/assets
<assets>
Assets (required)
Begins the assets block that references the assets being delivered.
XPath: /package/video/assets/asset/data_file
<asset type="full"> <data_file role="source.hdr">
HDR Source Asset (required)
The data file block specifies the source video file and describes the role of the associated file. In this example, the file sent is used as the HDR source, so the role must be "source.hdr".
The secondary source video must be the same duration as the primary subscription video source so that components such as subtitles and audio can be used with the secondary video.
In this block, the <locale>, <file_name>, <size>, and <checksum> tags are required.
In this example, the HDR video source is HDR10, which must be specified with the hdr.format attribute. Specifying the HDR format is required. Roles allowed for the hdr.format attribute include DolbyVision and HDR10. Only one hdr.format value can be specified. The value for HDR10 is case-sensitive and must be delivered as: HDR10
The minimum luminance attribute is required and the value must be a number with up to 3 significant digits and up to 4 decimal places. Value must be greater than or equal to 0.0.
The minimum luminance attribute can only be used for source HDR file with format HDR10.
The maximum light level attribute is optional. The value is an unsigned short integer. Value must be between 0 and 65535 inclusive.
If you provide 0 (zero) as the value, Apple will compute the value based on the cropped source content and insert the calculated value in the encoded bitstream.
The maximum light level attribute can only be used for source HDR file with format HDR10.
HDR10 Max Frame Average Light Level Attribute (optional)
The maximum frame average light level attribute is optional. The value is an unsigned short integer. Value must be between 0 and 65535 inclusive.
If you provide 0 (zero) as the value, Apple will compute the value based on the cropped source content and insert the calculated value in the encoded bitstream.
The maximum frame average light level attribute can only be used for source HDR file with format HDR10.
HDR10 Preview Source Video Metadata Example
To deliver HDR10 previews, you must supply the source.hdr role with the hdr.format set to HDR10. A mapping file is not required; if you deliver a mapping file, delivery will fail. Instead, you provide the attributes in the metadata XML file as shown below. This example adds an HDR10 preview video to a previously-delivered SDR subscription video. The package delivered would consist of the metadata file, the HDR10 preview source video, and the required attributes. The primary subscription video source must be referenced by its content identifiers (<umc_catalog_id>, <umc_content_id>, and <umc_variant_id>).
Note: The chromaticity values listed in the example and annotations below are for a P3 display with D65 white point. For a BT.2020 display with D65, see the annotation on HDR10 Chromaticity Attributes for examples of value formatting.
Only the tags related to the HDR10 preview delivery are described. The attributes follow the SMPTE ST 2086 metadata guidelines. Refer to Subscription Video Asset Delivery XML Annotations for annotations on other tags.
Note: It is beyond the scope of this document to describe the details of the mastering display attributes. Refer to "SMPTE ST 2086:2014" and the Blu-ray / DECE definitions of Maximum Content Light Level (MaxCLL) / Maximum Frame Average Light Level (MaxFALL) metadata for further information. This document covers only how to deliver the attribute values.
Video Metadata Fields
XPath: /package/video/subtype
<subtype>preview</subtype>
Video Subtype (required for preview delivery)
Identifies the type of video you are delivering. The <subtype> tag is required when delivering previews and the value must be preview.
Universal Media Catalog Catalog ID (required; 1-255 characters)
Specifies the unique catalog identifier of the primary subscription video source (as identified during Apple catalog registration). The value can contain both numbers and letters.
When adding HDR to an existing subscription video, you must supply the content identifiers. Those values must match the identifiers of the existing subscription video. You do not need to re-deliver the subscription video data file.
XPath: /package/video/umc_content_id
<umc_content_id>42abc33def17</umc_content_id>
Universal Media Catalog Content ID (required; 1-255 characters)
Defines the unique ID you assigned to the primary subscription video source. The value can contain both numbers and letters.
When adding HDR to an existing subscription video, you must supply the content identifiers. Those values must match the identifiers of the existing subscription video. You do not need to re-deliver the subscription video data file.
XPath: /package/video/umc_variant_id
<umc_variant_id>1</umc_variant_id>
Universal Media Catalog Variant ID (required; 1-32 characters)
Distinguishes between different versions of the primary subscription video source, for example the same asset with different territory-specific editorial or compliance requirements. The value can contain both numbers and letters, and underscores. If you do not have multiple versions, Apple suggests using 1 as the value.
When adding HDR to an existing subscription video, you must supply the content identifiers. Those values must match the identifiers of the existing subscription video. You do not need to re-deliver the subscription video data file.
Asset Metadata Fields
XPath: /package/video/assets
<assets>
Assets (required)
Begins the assets block that references the assets being delivered.
The data file block specifies the preview video file and describes the role of the associated file. In this example, the file sent is used as the HDR source, so the role must be "source.hdr".
The secondary preview video must be the same duration as the primary subscription video preview so that components such as subtitles and audio can be used with the secondary video.
In this block, the <locale>, <file_name>, <size>, and <checksum> tags are required.
In this example, the HDR preview video source is HDR10, which must be specified with the hdr.format attribute. Specifying the HDR format is required. Roles allowed for the hdr.format attribute include DolbyVision and HDR10. Only one hdr.format value can be specified. The value for HDR10 is case-sensitive and must be delivered as: HDR10
The mastering display chromaticity attributes are required and include:
hdr.red.chroma.x
hdr.red.chroma.y
hdr.green.chroma.x
hdr.green.chroma.y
hdr.blue.chroma.x
hdr.blue.chroma.y
hdr.whitepoint.chroma.x
hdr.whitepoint.chroma.y
The value listed for each attribute above must be a number with 4 decimal places and the value must be between 0.0 and 1.0 inclusive. The chromaticity attributes can only be used for a source HDR file with format HDR10.
For a BT.2020 mastering display with D65, the following values are expected:
The minimum luminance attribute is required and the value must be a number with up to 3 significant digits and up to 4 decimal places. Value must be greater than or equal to 0.0.
The minimum luminance attribute can only be used for source HDR file with format HDR10.
The maximum light level attribute is optional. The value is an unsigned short integer. Value must be between 0 and 65535 inclusive.
If you provide 0 (zero) as the value, Apple will compute the value based on the cropped source content and insert the calculated value in the encoded bitstream.
The maximum light level attribute can only be used for source HDR file with format HDR10.
HDR10 Max Frame Average Light Level Attribute (optional)
The maximum frame average light level attribute is optional. The value is an unsigned short integer. Value must be between 0 and 65535 inclusive.
If you provide 0 (zero) as the value, Apple will compute the value based on the cropped source content and insert the calculated value in the encoded bitstream.
The maximum frame average light level attribute can only be used for source HDR file with format HDR10.
HDR and SDR Delivery
The following XML example shows how to deliver HDR and SDR videos in the same delivery.
Note: The HDR file must contain audio tracks. For information on how to handle the audio tracks—for example, ignore, use, or set as primary—see Dolby Atmos Audio Downmixing.
Below are examples of updates to remove an alternate audio asset from the product and to change the <locale> of a previously delivered file. The correct identifiers that reference the already delivered subscription video must be supplied in the metadata.xml file for asset removal updates.
You can also use the same structure using remove="true" to remove QC notes. Keep in mind that the use of the remove="true" attribute is intended only for removing audio files permanently, changing the locale of a previously delivered asset, and removing QC notes. Using remove="true" for any other purpose can result in unintended languages included in the final product.
Note: When you need to update or change assets for an existing product, you can simply send an update and deliver a new asset with the same locale; you do not need to remove the asset using the remove="true" attribute.
Remove Alternate Audio
This example shows how to remove an alternate German audio from a previously-delivered subscription video. Only the audio asset along with associated data files is referenced in the XML. Only the metadata.xml need be included in the Subscription Video Package. The role, <filename>, <checksum>, and <size> provided will be compared to the asset currently in the catalog, and if the role attribute, <filename>, <checksum>, and <size> match, the asset will be removed. Note that the asset could also be removed in a metadata-plus-asset update.
A data file element block must be included if the asset is to be removed. For the audio data file, set the attribute remove to "true".
In this block, the role attribute and <file_name>, <size>, and <checksum> tags are required. Additionally, <locale> is required if sent previously.
Change Locales
The following example shows how to change the <locale> on a source video. In this case, when the package was first delivered, the <locale> tag was incorrect. To correct the <locale>, the old source asset must be removed and redelivered with the correct <locale>. Only the source asset along with the associated data file needs to be referenced in the XML. The role, <filename>, <locale>, <checksum>, and <size> provided will be compared to the asset currently in the catalog, and if the role, <filename>, <locale>, <checksum>, and <size> match, the asset will be removed. To add the source with the correct locale, include another <data_file> block within the same <asset> block as shown in the example below. Both the metadata.xml and the redelivered source asset must be included in the Subscription Video Package.
Important: There should be only one <asset> block for the same upload of the same video with the same type and territories. For example, the only way to change the locale of a source is to remove the existing source and add the new source; the <data_file> elements used to remove the source (remove="true") and the <data_file> elements used to add the source should go under the same <asset type="full"> block.
To change the locale, remove the asset with the incorrect locale. Include a data file element block for the asset to be removed. For the source data file, set the attribute remove to "true".
Include another data file element block to re-deliver the asset with the correct locale.
In this block, the role attribute and <file_name>, <locale>, <size>, and <checksum> tags are required.
Update Assets and Metadata
Updating Assets
You can redeliver assets (including video, audio, and so on) if the assets need to be replaced in the catalog due to encoding or other issues.
To deliver the subscription video content for updating, you must reference the correct content identifiers (<umc_catalog_id>, <umc_content_id>, and <umc_variant_id>) of the already delivered content when sending the update XML. When delivering updated source video, keep in mind that the duration of the source video must match the durations of related components (such as subtitles, forced subtitles, alternate audio, SDH, AD, and CC). If the duration of the source video has changed, you must also deliver updates of any related components intended to track to the same timeline as the source video.
Updating Metadata
Chapter titles and chapter artwork can be added or changed, however you must send all chapters on redelivery, not just the ones being updated.
For any questions regarding update deliveries, contact your Apple Technical Partner Representative.
Appendix A: Data Formatting Guidelines
Languages and Locales
Several language and locale elements and attributes in the following document require data in the BCP-47 format.
Language codes should be formatted according to the best practices recommended by the Internet Engineering Task Force (IETF) in a group of documents known collectively as BCP 47, and in particular, RFC 5646, which is part of BCP 47. An overview of these best practices is provided here. When specifying languages, you can use any language as long as it is a valid BCP 47 code that consists of the language subtag, optional region subtag, and optional script subtag as appropriate.
As a best practice when specifying a language, use the region subtag (for example, the US of en-US) only when it conveys helpful information, such as spelling variations between countries. For example, there is generally not a need to distinguish between Japanese as used in one country versus another, so you should use only the language code subtag (ja) instead of the language code and region subtags (ja-JP). In cases where specifying a region is appropriate, use the hyphen character to combine a language subtag with a region subtag. This identifies both the language and the specific location where the language is used. For English with American spelling, use en-US; for English with British spelling, use en-GB.
FORMAT If a video asset contains Chinese audio, the locale values must not contain script information. For example, the locale for Mandarin audio must be cmn, not cmn-Hant or cmn-Hans; the locale for Cantonese audio must be yue, not yue-Hant.
Note: If you do not supply a locale value for a specific element, the locale provided with the defaultLocale element for the catalog feed will be used.
ISO 3166-2 for Countries
Several elements of the catalog require a country to be specified in the ISO 3166-2 format. For more information about this standard, visit www.iso.org.
ISO 8601 for Dates
Several elements in the Catalog and Availability Data Interfaces require dates in the ISO 8601 format. ISO 8601 is defined as “YYYY-MM-DDThh:mm:ss.sTZD”, where:
YYYY is four-digit year
MM is two-digit month (01=January, etc.)
DD is two-digit day of month (01 through 31)
hh is two digits of hour (00 through 23) (am/pm NOT allowed)
mm is two digits of minute (00 through 59)
ss is two digits of second (00 through 59)
s is one or more digits representing a decimal fraction of a second
TZD is time zone designator (Z or +hh:mm or -hh:mm)
For more information about this standard, visit www.iso.org.
Note: If you do not provide the +/- offset, the timezone will be assumed to be GMT.
Revision History
Previous Spec Revisions
The following table lists the previously-released specifications and the revisions:
Date/Version
Summary
May 2024—Version 1.10
Clarifications on using forced subtitles and specifying the PSE (photosensitive epilepsy) test results; additional minor corrections.
February 2024—Version 1.9
Clarification on audio tracks for HDR delivery; additional minor corrections.
December 2022—Version 1.8
Added information about epic stage videos. Other corrections in XML annotations.
September 2022—Version 1.7
Added information about forced subtitles. Fixed issues with printing the document.
November 29, 2021—Version 1.6
Made corrections, clarifications, and reorganized one section.
March 15, 2021—Version 1.5
Made name corrections.
December 21, 2020—Version 1.4
Added a new tag for episode production number (<production_number>). Dolby Vision CM version 4 metadata files are now supported.
June 29, 2020—Version 1.3
Previews are now delivered in separate package deliveries.
March 16, 2020—Version 1.2
Added a new video asset for ambient videos. Added an attribute "main.end_time" to specify when the main video is over. Added an attribute "product_placement" to indicate the video contains product placement. Added delivery of a Dolby Vision video with an option to down-convert to SDR. Added delivery of a Dolby Atmos audio file with an option to downmix to other formats. Added an attribute to indicate that a pre-roll video can be skipped by the viewer. Defined previews and dub card video are no longer supported.
November 18, 2019 - Version 1.1
Corrected crop dimensions. Corrected locale on source attributes.
September 2019 - Version 1.0
First release of this specification.
Changes in Apple TV Channels Subscription Video Asset Specification 1.10
Changes in Apple TV Channels Subscription Video Asset Specification 1.6
Corrections/Clarifications
Removed the sentence “Specifies the frame to use for the still image that will be displayed on the episode page” from the annotation on the production still image time. Renamed the section “Dolby Atmos Audio and Dolby HDR Delivery” to “Audio Delivery Examples and Annotations,” and reorganized the sections to remove duplications. Clarified that an SDR asset is required for an HDR10 delivery.
Changes in Subscription Video Specification 1.5
Corrections
The titles for the annotations for umc_catalog_id, umc_content_id, and umc_variant_id have been changed to reflect the name of the tag. For example, Universal Media Catalog Identifier has been changed to Universal Media Catalog Catalog ID. In addition, the title for Universal Media Content Identifier has been corrected from Universal Media Catalog Identifier to Universal Media Catalog Content ID.
Changes in Subscription Video Specification 1.4
Production Number
A new, optional tag allows you to specify the production number for an episode. You deliver the production number using the <production_number> tag and the value should be unique for each episode. The value can be 1 to 255 characters and can contain only alphanumeric characters, spaces, hyphens (-), and underscores (_).
Film Profile: Dolby Vision
Dolby Vision CM 4 sidecar metadata files are now supported. Dolby Vision CM version 4.0 provides an improved tone curve, updated trims, additional 6-vector trims for saturation and hue, and new adjustments for mid tones.
Tag Changes
Added
<production_number>
Changes in Subscription Video Specification 1.3
Previews
The method of delivering previews has changed. A preview video is now delivered in its own package, separate from the full video delivery. You use the <subtype> tag to indicate the asset is a preview. Previews have been removed from the full video examples and new sections describe how to deliver previews.
Tag Changes
Added
preview for use with the <subtype> tag
Changes in Subscription Video Specification 1.2
Ambient Video
You can deliver ambient video (also called motion background) that is specific to an episode. The ambient video plays in a continuous loop. You also deliver a keyframe (a production still of the first frame of the ambient video). When users first land on an episode page, they will see a static picture (which is the production still). After a certain amount of time, the ambient video starts, providing a seamless transition between the production still and the ambient video. You deliver the ambient video in its own <asset> block. The type can be ambient (<asset type="ambient">) or ambient_vertical for iPhone (<asset type="ambient_vertical">). Both the horizontal and vertical formats are required. You define the first frame using the <production_still_image_time> tag.
Video Attributes
New attributes have been added to use on source and source.hdr videos:
Use the attribute "main.end_time" to specify when the main video is over. This attribute is optional and can be used to indicate when the main portion of the video ends, before the Director and Writer credits begin.
Use the attribute "product_placement" to indicate if there is product placement in the video source. Some countries require notification at the beginning and end of a video if it contains product placement.
Dolby Atmos Delivery
If you deliver a Dolby Atmos audio file, you can specify that you want Apple to downmix to other formats. This allows you to deliver a single Atmos audio file and derive all of the other formats (7.1, 5.1, and stereo). You use the following attributes on the Dolby Atmos source audio:
audio.transform_to.2_0
audio.transform_to.5_1
audio.transform_to.7_1
If you downmix Atmos audio to stereo (2.0) for the main locale, you must specify it as the primary audio using <attribute name="primary_audio">true</attribute> and you must also use ignore_audio on any video sources with embedded audio (HDR or SDR):
You can now deliver Dolby Vision HDR video without a corresponding SDR video delivery and specify a tag to down-convert to SDR. Apple will create the SDR video using the Dolby Vision SDR trim metadata. Using this method is optional, but it could streamline the delivery process for you. When you deliver a Dolby Vision-only package, you can choose to include embedded audio or you can deliver the audio in a separate file. Note that this delivery method is not available for HDR 10 videos.
To deliver a Dolby Vision-only package, you must use the attribute that indicates you want the HDR video to be down-converted to SDR: <attribute name="video.hdr.force_sdr_downconvert">true</attribute>. In addition, if the HDR video has embedded audio, include both 5.1 and stereo audio. It is also recommended that you use the <attribute name="primary_audio">true</attribute> tag to indicate which audio to use as the primary audio.
If you deliver an HDR video source that has embedded audio and you deliver alternate audio files, you can use the "ignore_audio" attribute to indicate you do not want to use the embedded audio. Then you specify that the separate audio component should be considered the primary audio.
Below are two examples of an HDR-only package:
For HDR with embedded audio:
HDR source with embedded audio (5.1 and 2.0)
Audio on the HDR source is used
HDR source can be down-converted to SDR by specifying the attribute: <attribute name="video.hdr.force_sdr_downconvert">true</attribute>
Optional: Use the <attribute name="primary_audio">true</attribute> tag on the source HDR video
For HDR with no audio:
HDR source with no audio
Alternate Audio 1 is delivered and designated as the primary audio: <attribute name="primary_audio">true</attribute>
Alternate Audio 2 is delivered but not used as the primary audio
HDR source can be down-converted to SDR by specifying the attribute: <attribute name="video.hdr.force_sdr_downconvert">true</attribute>
Note that there can only be one primary audio per package. It is recommended that you always specify which audio to use as primary using the primary_audio attribute.
SDR Delivery without Embedded Audio
You can now deliver an SDR source without embedded audio. In this case, you deliver an alternate audio as a separate file and it will be used as the primary audio. If you deliver more than one alternate audio file, the audio file with the locale that matches the source video will be used as the primary audio, unless you specify a different locale as primary using <attribute name="primary_audio">true</attribute>. Note that there can only be one primary audio per package.
If you deliver an SDR video source that has embedded audio and you deliver alternate audio files, you can use the "ignore_audio" attribute to indicate you do not want to use the embedded audio. Then you specify that the separate audio component should be considered the primary audio.
Below are two examples of the existing and new SDR delivery methods (see the subsection below for HDR deliveries):
Current delivery method (will still be supported):
SDR source with embedded audio
Optional HDR source with embedded audio
Audio on the HDR source is ignored and the SDR audio is used
New delivery method with SDR source with no audio:
SDR source with no audio
Alternate audio is used as the primary audio and delivered with the <attribute name="primary_audio">true</attribute>
Pre-roll Videos
You can indicate that a pre-roll video can be skipped by the viewer. In the <play_sequence> block for the video that can be skipped, use the skippable="true" attribute with the <play_sequence_item> tag. If you set the value to true, viewers will see a “skip” button. Note that a pre-roll video that contains ratings cannot be skipped.
Defined Previews
Defined previews are no longer supported and the examples and annotations have been removed.
Dub Card Videos
Dub Card videos as a component type are no longer supported and the examples and annotations have been removed.
Tag Changes
Added
"main.end_time" for use in the <attribute> tag on a video data file
"product_placement" for use in the <attribute> tag on a video data file
"ambient_vertical" and "ambient" for use in the type attribute on an <asset> tag data file
video.hdr.force_sdr_downconvert as an attribute in a Dolby Vision-only package
audio.transform_to.2_0 as an attribute for Dolby Atmos audio
audio.transform_to.5_1 as an attribute for Dolby Atmos audio
audio.transform_to.7_1 as an attribute for Dolby Atmos audio
"ignore_audio" for use in the <attribute> tag on a source data file
skippable="true" attribute for use in the <play_sequence_item> tag
Changed
primary_audio as an attribute can be used for alternate audio files
Removed
"video.end.dub_credits" as a role for a data file on the full source for dub card video
<previews> <preview> used to deliver defined previews
Changes in Subscription Video Specification 1.1
Corrections
The crop attribute values supplied on the source video in the XML examples 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.
The locales for the image.burned_forced_narrative.locale attribute and the image.burned_subtitles.locale attribute for the source video have changed to fr-FR.
