XML Manifest File

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 both OIS v2.5 and OIS v1. Certain sections, where indicated, apply to just one version. OIS v1 has been deprecated and is scheduled to be disabled. Customers using OIS v1 should switch to OIS v2.5.

XML Manifest Elements

You can use the following elements in the XML manifest file.
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 files only). 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://. Example: http://ooyala.com/captions/caption-1.dfxp
    lang (optional) - language of the closed caption file. Two-letter code. See Closed Captions - Supported Languages.
  • 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 the customer’s 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 labels to the account (for example, sports,sports/jogging). A new label will be created only if a label with the same name does not already exist.

For example, for the following <media:keywords> tag, the labels label1 and label2 would be created. 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> (Reserved) Content ID of the video asset as specified in Backlot. reserved
<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. Example: <ooyala:metadata name="internal_id">, <ooyala:metadata name="category">, and so on). See Custom Metadata for format requirements. 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)
<guid> External ID (identifier) for the video, such as the embed code. See Updating Asset Metadata Using CSV or XML Manifest Files.

Example:

<guid isPermaLink="false">12345678910</guid>
optional

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>
      <guid isPermaLink="false">my_test_guid_xml</guid>
      <ooyala:profileguid>57d5a5a10f654fe79ef954dc8d29a108</ooyala:profileguid>
    </item>
  </channel>
</rss>

Example XML Manifest File (OIS v1) (Deprecated)

Note: OIS v1 has been deprecated and is scheduled to be disabled. Customers using OIS v1 should switch to OIS v2.5.
In the following example, the XML specifies metadata for two videos. For the first video, the file, closed caption and thumbnail are located on an upload server and are pulled from that server. For the second video, the file, closed caption and thumbnail were already uploaded to an Ooyala server. Also, the second video 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:subTitle href="http://mysite.com/upload/caption-1.dfxp" />
          <media:title>Sports that Really Exist: Lacrosse</media:title>
          <media:description>My emotional and touching 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:subTitle href="caption-1.dfxp" />
          <media:title>Sports that Really Exist: Curling</media:title>
          <media:description>My emotional and touching 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>
            
          <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>         

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 emotional and touching 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 emotional and touching 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.

Was this article helpful?