Limited Availability - Do not share this document

This page has moved - you will be directed to the new location in 3 seconds. Please update your bookmarks!

Ooyala-Video Cloud Ingestion Adapter: XML Manifest Files

You can continue to use FTP, Aspera, or MRSS with an XML manifest to ingest your videos to Video Cloud. This topic explains the structure of the XML.

Introduction

When ingesting videos, you can use XML manifest files to specify extra metadata (including the video title, description, flight times, labels, and custom metadata), as well as thumbnail and closed caption files. You can use XML manifest files when you ingest content with FTP, Aspera, or MRSS.

Note: This topic applies to OIS v2.5.

Handling of metadata

If you include metadata for videos when you ingest them, it is mapped to Video Cloud video fields in one of two ways:

  1. By default, each metadata key/value pair is added as a tag in the form: meta::key::value. For example, <ooyala:metadata name="category">cooking</ooyala:metadata> would produce the tag meta::category::cooking
  2. If you would rather use custom_fields to store metadata, Brightcove Support can change a setting on your account to do that. Be aware of the following:
    • You will need to create custom fields with names corresponding to your metadata keys.
    • The number of custom fields is limited to 10 by default, so if you will need more than that to accommodate your metadata, you will need to request additional custom fields from Support.
    • If a custom field corresponding to each metadata item does not exist in your account, the entire metadata operation will fail.

XML Manifest Elements

You can use the following elements in the XML manifest file.

XML Manifest Elements
XML Tag Description Required/Optional
<channel> Contains one or more <item> elements. required
<item> Represents a single video to ingest. You can specify multiple videos (<item> tags) in an XML manifest file. Contains the remaining tags in this table. required
<media:content> Specifies a video to ingest. One of the following: For a remote asset, use <ooyala:remoteasset> instead. required (except for remote assets)
<media:title> Name or title of the video. optional
<media:thumbnail> Specifies a thumbnail (preview image). One of the following:
  • Filename of a thumbnail you uploaded.
  • URL where the thumbnail is located. The URL can include http:// or https://.
 optional
<media:subTitle> Specifies a closed caption file (supported for DFXP, WebVTT, and SRT files). See Ingesting Closed Caption Files. Attributes:
  • href (required) - One of the following:
    • Filename of the closed caption file you uploaded. Example: caption-1.dfxp
    • URL where the closed caption file is located. The URL can include http:// or https://.
    lang (optional) - language of the closed caption file. Two-letter code. See Supported Closed Captions.
  • frameRate (optional) - Frame rate of the closed caption file. Units are in Frames Per Second (FPS). Default is 30. Older closed caption files might be 24.
Note: If specified, it is your responsibility to provide valid values for lang and frameRate. Valid values are added to the DFXP file. Non-compliant values are ignored. Either way, the closed caption file is added into Backlot and linked to the asset.
 optional
<media:description> Description of the video. optional
<link> Permanent URL where you embed the video. Maps to the created asset's hosted_at property. optional
<dcterms:valid> Flight times representing the start and end times when the asset can be played. Example: 
  <dcterms:valid>start=2011-06-28T15:15:00-07:00;
                 end=2022-12-01T16:00:00-07:00;scheme=W3C-DTF
  </dcterms:valid>
 optional
<ooyala:labels> One or more labels, separated by commas. Example: /sports,/sports/jogging. For background, see Labels. optional
<media:keywords> Another way to define labels (without a forward slash). The contents, separated by commas, will be added as tags to the video. A new tag will be created only if a tag with the same name does not already exist.

For example, for the following <media:keywords> tag, the labels label1 and label2 would be created and added to the video as tags. A label named parentlabel would also be created, with the label childlabel nested inside it.

  <media:keywords>label1, label2,
      parentlabel/childlabel</media:keywords>
Note: The contents of <media:keywords> are ignored when the <ooyala:labels> tag is included in the XML manifest file or MRSS.
 optional
<ooyala:embedcode> Video Cloud video ID. optional (required if you are updating a video rather than adding a new one)
<ooyala:profileguid> ID of the processing profile, which is a group of encodes that define the formats a master video must be converted into during transcoding. Contact your Ooyala support representative for details. optional
<ooyala:metadata> Custom metadata for the video. You can have an element for each type of metadata. See the Handling of metadata section for details on how metadata is added to videos as special tags. Example: <ooyala:metadata name="category">cooking</ooyala:metadata> optional
<ooyala:remoteasset> Specifies a remote asset to ingest. A remote asset is a video that is hosted somewhere other than Backlot. Specify the following attributes:
  • durationInMs: media duration (in milliseconds)
  • url: URL of the remote asset. The URL can include http:// or https://.
This setting maps to the value of the hosted_at property for a remote asset. Example: <ooyala:remoteasset durationInMs='5000' url="http://your_website/your_remote_assets.mp4" />
Note: After a remote asset has been created, its propagation to the various CDNs might be delayed 60 seconds or more. If you request a remote asset too soon after its creation, the results will be cached by the CDNs, which might take several minutes to clear. Best practice: after creation, wait 30 or 60 seconds, query with the Backlot API [GET] /v2/assets/asset_id route, and after retrieving the remote asset's embed code (content ID or asset ID), then proceed to embed the asset.
 required (remote assets only)
<ooyala:profileguid> Specifies a Video Cloud ingest profile to use for processing the video. If you do not want to use the account default profile, you must specify the one you want to use instead. See Managing Ingest Profiles. optional

Example

Example XML Manifest File (OIS v2.5)

  <?xml version="1.0" encoding="utf-8"?>
  <rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/"
    xmlns:dcterms="http://purl.org/dc/terms/"
    xmlns:fh="http://purl.org/syndication/history/1.0"
    xmlns:ooyala="http://www.ooyala.com/mrss/">
    <channel>
      <item>
        <media:content url="test.mp4" ></media:content>
        <media:subTitle href="my_caption.dfxp"></media:subTitle>
        <media:thumbnail url="my_thumbnail.jpg" filesize="35712"></media:thumbnail>
        <media:title>Test XML</media:title>
        <media:description>This is an example</media:description>
        <ooyala:labels>/test,/example,/xml</ooyala:labels>
        <dcterms:valid>start=2016-01-01T15:15:00-07:00;
          end=2022-01-01T16:00:00-07:00</dcterms:valid>
        <ooyala:profileguid>57d5a5a10f654fe79ef954dc8d29a108</ooyala:profileguid>
      </item>
    </channel>
  </rss>

Step-by-step

Creating an XML Manifest File

To create an XML metadata file:

  1. Upload your videos and other content (thumbnails, closed caption files, and so on).
  2. Open a text editor, preferably one that validates XML.
  3. Add the required XML headers. For example: 
      <?xml version="1.0" encoding="utf-8"?>
  <rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/"
       xmlns:dcterms="http://purl.org/dc/terms/"
       xmlns:fh="http://purl.org/syndication/history/1.0"
       xmlns:ooyala="http://www.ooyala.com/mrss/">
  4. Create a channel container.
  5. Create an item entry for each video, containing the desired elements from the table above.

    In the following example, the XML specifies metadata for two videos. For the first video, the file and thumbnails are located on an upload server and are pulled from that server. For the second video, the file and thumbnail were already uploaded to an Ooyala server. The second video also has flight times.

      <?xml version="1.0" encoding="utf-8"?>
  <rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/"
       xmlns:dcterms="http://purl.org/dc/terms/"
       xmlns:fh="http://purl.org/syndication/history/1.0"
       xmlns:ooyala="http://www.ooyala.com/mrss/">
  
       <channel>
             <item>
              <media:content url="http://mysite.com/upload/lacrosse_70.mov" />
              <media:thumbnail url="http://mysite.com/upload/lacrosse_70_previewimage.jpg" />
              <media:title>Sports that Really Exist: Lacrosse</media:title>
              <media:description>My description of my video</media:description>
              <ooyala:labels>/sports/lacrosse,/hobbies/lacrosse</ooyala:labels>
              <link>http://mysite.com/videos/sports/real_sports.html</link>
              <ooyala:metadata name="video_ID">70</ooyala:metadata>
              <ooyala:metadata name="season_number">1</ooyala:metadata>
             </item>
  
             <item>
              <media:content url="curling_71.mov" />
              <media:thumbnail url="curling_71_previewimage.jpg" />
              <media:title>Sports that Really Exist: Curling</media:title>
              <media:description>My description of my video</media:description>
              <ooyala:labels>/sports/curling,/hobbies/curling</ooyala:labels>
              <link>http://mysite.com/videos/sports/real_sports.html</link>
              <ooyala:metadata name="video_ID">71</ooyala:metadata>
              <ooyala:metadata name="season_number">1</ooyala:metadata>
              <!-- set flight times -->
              <dcterms:valid>start=2011-06-28T15:15:00-07:00;
                  end=2022-12-01T16:00:00-07:00;scheme=W3C-DTF
                  </dcterms:valid>
  
             </item>
       </channel>
  </rss>
  6. Save the file as XML. Be sure to specify a unique name. If you specify two files with the same name and upload one while the other is processing, the second one might be ignored.
  7. With your upload method of choice, upload the XML manifest file as you uploaded the video(s). See either FTP or Aspera.