Skip to main content

FTP Manifests: Creation and Formatting Instructions

Updated

This article details how to create .manifest files for ordering via FTP.

Prerequisites

  • This is not available to Express customers

 

Media files should be uploaded to an FTP folder named hold_for_manifest.  This will park the media assets, and they will not enter the 3Play system until a manifest is uploaded to describe what services you would like to order.

Manifests contain XML markup, and the names of the manifests themselves should be unique. The manifest file must use a .manifest extension.

ex. my_upload_92015979219160803.manifest

Please ensure .manifest files are utf-8 encoded with plain text.  Special characters such as "smart quotes" (or Microsoft quotation marks) will result in an error.

 

In the examples below, we assume that the project-id is 99887766.

Simple Overview

Typically, customers limit manifests to a single media file.

All manifests should begin with a single XML info line, followed by a <threeplaymedia-file-manifest> tag containing a project-id attribute (required):

<?xml version="1.0" encoding="utf-8"?>
<threeplaymedia-file-manifest project-id="99887766">

Below is a very simple example of a complete manifest file that would:

  • Place an order for English ASR for a new media file located at hold_for_manifest/ForceUp10071.mp4
  • Name this file as:  "ForceUp FTP (Take 1)"
<?xml version="1.0" encoding="utf-8"?>
<threeplaymedia-file-manifest project-id="99887766">
<media-file>
  <source-location>hold_for_manifest/ForceUp10071.mp4</source-location>
  <name>ForceUp FTP (Take 1)</name>
  <order>
    <service>ASR</service>
  </order>
</media-file>
</threeplaymedia-file-manifest>

 

You will notice several multi-word XML tags in these examples, such as media-file, source-location, etc.  These should all use a hyphen "-", with the exception of these two which require an underscore "_":

  • turnaround_level
  • target_language_code

 

Configuration Details

Under the root element may be one “notify” element and any number of (but at least 1) “media-file” elements.  The notify element must have an “email” attribute, e.g.:

<notify email="my.name@company.com; someone.else@company.com "/>

If provided, that address will be sent a summary of the actions resulting from the processing of the manifest.

If your manifest is ordering services for an existing media file that is already in 3Play:

  • Each media-file provided must already exist in the project.
  • The media-file must be identified by providing at least one of an “id”, “name” or “video-id” element. If more than one of these is provided, then the media-file is identified according to the first of these, in that order, and the other elements are interpreted as fields to update on the existing media-file.

Otherwise, if your manifest is ordering services for a new media file that is not yet in 3Play (and will be / has been uploaded to a hold_for_manifest folder as described here):

  • A new media-file will be created from the file at that source location in the FTP folder hierarchy, and this media-file will be given an “id” by the system. In this case, providing an “id” element in the manifest will be an error. The “name” or “video-id” elements may still be provided, in which case they are set as attributes in the new media-file. (If the “video-id” element is provided on a file linked to a video-platform integration, that link will be updated to have this new video-id).
  • Here is an example valid fragment of a manifest specified in this way:
<threeplaymedia-file-manifest project-id="99887766">
  <media-file>
    <source-location>hold_for_manifest/ForceUp10071.mp4</source-location>
    <name>ForceUp FTP (Take 1)</name>
    <video-id>ltF7P_0g_oGXZvTJuXphx2Z0udfyn5Pl</video-id>
    ...


The remaining optional media-file sub-elements (description, attribute1, attribute2, attribute3, callback-url, public) are processed as attribute updates on the media file in our system.

 

  • Any number of “order” sub-elements may also be provided per Media File.  Each “order” sub-element requires a “service” sub-sub-element.
  • If any orders are specified, at least one order in the manifest must have one of the following values:
    “Transcription”, “ASR”, “Caption Import”, or “Video Clip Captioning”

Add-on orders of “Translation”, “Caption Placement” and/or “Audio Description” are only supported in the presence of the primary order types. Alignment orders are not currently supported through the FTP Manifest.

  • “Transcription” and “ASR” orders may include a “language” element whose value may be one of “English” or “Spanish”. The default is “English”.
  • “Transcription” orders may include a “turnaround_level” element whose value may be one of: “standard”, “same_day”, “two_hour”, “rush”, “expedited”, or “extended”. The default is “Standard”.

Here is an example Transcription order with both language and turnaround_level specified:

...
<order>
 <service>Transcription</service>
 <language>Spanish</language>
 <turnaround_level>rush</turnaround_level>
</order>
...

If you'd instead like to use your own captions, you would place a "Caption Import" order instead of the "Transcription" order shown above.  For Caption Import orders, you specify the caption file location with a <source-captions> tag.  The <source-location> tag is optional for these orders, and can be used to upload an audio/video file along with your captions.

 

Here is an example Caption Import order that also uploads a media file:

...
<media-file>
 <source-location>hold_for_manifest/my-new-media-file.mp4</source-location>
 <source-captions>hold_for_manifest/my-new-caption-file.srt</source-captions>
 <name>A Video about Bricks and Sneakers</name>
 <order>
   <service>Caption Import</service>
 </order>
</media-file>
...

 

Note: Caption Import orders are assumed to be in “English”.  Other languages cannot currently be specified for Caption Import orders.

Any number of “Translation” orders may be provided, with “target_language_code” as a required element of the “order”. The source language is currently assumed to be “English”.  For example:

...
<order>
 <service>Translation</service>
 <target_language_code>ru</language>
</order>
...

 

An Audio Description order may be provided. A “type” element may be provided with this order and may have the values “Auto”, "Standard" or "Extended”. The default is “Standard”.  For example:

...
<order>
 <service>Audio Description</service>
 <type>Extended</type>
</order>
...

In summary, here is an example FTP manifest that illustrates a common scenario, ordering:

  • 2-hour turnaround English transcription
  • Vertical Caption Placement (Automated)
  • Audio Description, using the “Auto” feature to determine if the AD should be Standard or Extended
<?xml version="1.0" encoding="utf-8"?>
<threeplaymedia-file-manifest project-id="38934">
 <notify email="my.name@company.com"/>
 <media-file>
   <source-location>hold_for_manifest/another_video.mp4</source-location>
   <name>A Video about Me</name>
   <folder-name>Recent Videos</folder-name>
   <description>A very self-centered video</description>
   <order>
     <service>Transcription</service>
     <turnaround_level>two_hour</turnaround_level>
   </order>
   <order>
     <service>Caption Placement</service>
     <type>Automated</type>
   </order>
   <order>
     <service>Audio Description</service>
     <type>Auto</type>
   </order>
 </media-file>
</threeplaymedia-file-manifest>

 

Related articles