FTP batch provisioning is available only for Brightcove Pro and Enterprise customers. If you are interested in upgrading your Brightcove account, please contact Brightcove for more information.
This document is a reference for the XML manifest you need to create in order to use the Brightcove FTP batch provisioning system. See Using FTP batch provisioning for more information, including prerequisites and detailed procedures. In addition, the following files can help you create your XML manifest:
It may be helpful to view a sample batch provisioning manifest as you review these explanations.
The first tag identifies the XML document type and always looks exactly like this:
<?xml version="1.0" encoding="utf-8"?>
This Brightcove-specific tag marks the beginning of the upload manifest.
<publisher-upload-manifest publisher-id="101" preparer="3rd Street Video" report-success="true">
The publisher-upload-manifest tag uses the following attributes.
| name | required? | description |
|---|---|---|
| publisher-id | Required | Identifies which publisher the described files are for. Contact Brightcove Support to obtain the publisher ID needed for a publisher to use the FTP batch upload system. If you've already been authorized to use the FTP batch upload system, you can get your publisher ID in the Brightcove Console by clicking on "My Account" and then "Organization Profile." |
| preparer | Required | This attribute should contain identifying information for who submitted the manifest, this is especially helpful when a third party is preparing assets for a publisher and provisioning them directly to Brightcove. |
| report-success | Optional | TRUE or FALSE. Should Brightcove send an email notification when the upload succeeds? The default is FALSE; if you do not include this attribute and set it to TRUE, you will not receive any notification when your upload succeeds. |
The publisher-upload-manifest tag can include one or more of the following tags, each of which is described in detail in this document:
| name | description |
|---|---|
| notify | Address for notification email [Optional] |
| callback | URL to post status callback by HTTP [Optional] |
| asset | Identify assets for upload [Optional] |
| title | Creating or updating videos [Optional] |
| manual-lineup | Creating or updating manual playlists [Optional] |
| automatic-lineup | Creating or updating smart playlists [Optional] |
The notify tag identifies where Brightcove will send the email notification of success or failure. You will receive notification only of failures, not successes, unless you have set the attribute report-success="true" in the publisher-upload-manifest tag. To send notification to multiple addresses, use a separate instance of this tag for each email address.
<notify email="you@example.com"/> <notify email="me@example.com"/>
The notify tag uses the following attribute:
| name | required? | description |
|---|---|---|
| Required | Identifies one email address to send upload notifications to. |
You can also use the callback tag to send upload notifications to a web page. The notification is sent in a POST to the URL you provide in the entity-url attribute of the callback tag. The POST includes:
referenceId=<the reference id provided in the manifest> id=<the id of the title, playlist, or asset in the database> entity=<VIDEO, LINEUP, or ASSET> action=<CREATE, DELETE, or UPDATE> status=<FAILED,SUCCESS> error=<an error message>
The status is always included in the callback post. In the event of a FAILED status, the other information may or may not be included in the callback post, depending on whether the information is available at the point of failure.
<callback entity-url="http://example.com/batch-callback.php"/>
| name | required? | description |
|---|---|---|
| entity-url | Required | Identifies one URL to post upload status notifications to. |
The asset tag describes a file that is being uploaded. You need to include a separate asset tag for each file being uploaded.
<asset filename="MyVideo.flv" refid="asset1" size="188812" hash-code="a4ade1e2b09d517ff7360f91527639b3" display-name="My Video (FLV)" type="VIDEO_FULL"/>
The asset tag uses the following attributes:
| name | required? | description |
|---|---|---|
| filename | Required | The name of the file as it appears on disk. Maximum length 125 characters. |
| refid | Required | A unique identifier so that a title can reference this asset from within the manifest file. This can be an ID used by your content management system. Use alphanumeric characters only. Maximum length 150 characters. |
| size | Required | The numeric size of the file in bytes. You may need to convert from kilobytes or megabytes to get this number in bytes. |
| encoding-rate | Optional | For multi-bitrate streaming renditions, the encoding rate in bits per second. For example, 150 kbps is specified as 150000. |
| frame-width | Optional | For multi-bitrate streaming renditions, the frame width of the video. |
| frame-height | Optional | For multi-bitrate streaming renditions, the frame height of the video. |
| hash-code | Required | The MD5 checksum (hash code) of the file. For information about how to create a checksum for your files, see Creating checksums. |
| display-name | Optional | A name for the file suitable for showing to the publisher in the Brightcove Media module. If you don't set this attribute, the filename will be used for the display name. |
| encode-to | Optional | FLV or MP4. If present, encode this video file to the specified encoding. If this atttribute is absent, the video file will not be transcoded. |
| encode-multiple | Optional | TRUE or FALSE. If TRUE, encode multiple renditions of this video file for multi-bitrate streaming. The default is FALSE, so unless this is set we will transcode to a single video asset. This attribute must be used in combination with encode-to. |
| h264-preserve-as-rendition | Optional | TRUE or FALSE. If TRUE, Brightcove stores a copy of the original H.264 video file as a video asset. The H.264 file will be preserved as an additional rendition for multi-bitrate streaming. The default is FALSE. The source file must be a valid H.264 video. If true, Brightcove will create multiple renditions of the original file, but will preserve the original and use it as an additional rendition. This option can be useful for providing the highest possible video quality. This attribute must be used in combination with encode-to and encode-multiple="true". The source file must be a valid H.264 video. |
| h264-no-processing | Optional | TRUE or FALSE. If TRUE, allows an H.264 file to be uploaded and not transcoded. The H.264 file will be preserved as an additional rendition for multi-bitrate streaming. The default is FALSE. It cannot be used in combination with encode-to or any of the other transcode options. The source file must be a valid H.264 video. |
| type | Required | Identifies the type of asset for upload. The value must be one of the following uppercase strings: VIDEO_FULL - A VP6 Flash Video (FLV) or H.264 (MP4) encoded full length video. The FLV_FULL value is deprecated for the type attribute; use VIDEO_FULL instead. FLV_BUMPER - A VP6 Flash Video (FLV) or H.264 (MP4) encoded bumper video (maximum 15-sec. clip). THUMBNAIL - An image file used as a thumbnail in listings. VIDEO_STILL - A still image from the video (or a representative image from another source). BACKGROUND - A background image to use in video players. LOGO - A publisher logo image. LOGO_OVERLAY - An image used for branding over video. OTHER_IMAGE - Miscellaneous image type. Note that video files uploaded with FTP batch provisioning must be either VP6 (FLV) or H.264 (MP4) encoded. |
If you are using remote assets, use the remote-asset tag instead of the asset tag to identify your assets. See Creating videos with remote video files for details about using remote assets and the remote-asset tag's attributes.
The title tag describes the videos you want to create or update. Use a separate title tag for each video you want to include in your upload.
<title name="My Title"
refid="title1"
active="TRUE"
start-date="01/01/2007 12:00 AM"
end-date="01/01/2007 12:00 AM"
video-full-refid="asset2"
thumbnail-refid="asset4"
video-still-refid="asset5"
flash-prebumper-refid="asset6"
color="TRUE"
language="English"
rating="TV-Y7"
release-date="10/5/2005"
shared="true"
genre1="3575"
genre2="3576"
economic-type="AD"
ad-keys=";key=value;key=value" >
<short-description>My short description.</short-description>
<long-description>My long description.</long-description>
<related-link-url>http://your-company.com/</related-link-url>
<related-link-text>Come learn about us!</related-link-text>
<award>Two Thumbs Award</award>
<award>Frank's Award</award>
<tag>funny</tag>
<tag>entertaining</tag>
<logo-overlay
asset-refid="12345"
click-thru="http://www.brightcove.com"
tooltip="Go to Brightcove"
alignment="bottom right" />
</title>
Title tags include a mix of attributes and child tags which map closely to the fields found in the Media module's Edit Video's Title creation form. Note, however, that there are two title attributes that you can set in the Brightcove Console, but which you cannot set using FTP batch provisioning:
| name | required? | description |
|---|---|---|
| name | Required | The name of the video as it should appear in a player. Viewers will see this video name when browsing or searching. The name can be no more than 255 characters long. |
| refid | Required | A unique identifier so that lineups can reference this title element from within the manifest file. Maximum length 150 characters. |
| active | Optional | TRUE or FALSE. Should this video should be active as soon as it is created? If you do not set this attribute, its value will be considered to be FALSE. |
| rendition-refid | Optional | A reference ID for one rendition of this video for multi-bitrate streaming. This attribute should only be used when assigning assets that do not require transcoding by Brightcove. |
| start-date | Optional | The primary scheduling start date and time for the video. The required format is MM/DD/YYYY HH:MM AM. For example: start-date="01/01/2008 12:00 AM". Note: The input in the upload manifest for the start date is Pacific time. However, once you have completed your upload, the start date displayed in the Media module will be Eastern time. |
| end-date | Optional | The primary scheduling end date and time for the video. The required format is MM/DD/YYYY HH:MM AM. For example: start-date="12/31/2008 12:00 AM". Note: The input in the upload manifest for the start date is Pacific time. However, once you have completed your upload, the end date displayed in the Media module will be Eastern time. |
| video-full-refid | Optional | The reference ID attribute of a full-length video file to include in this video. This reference ID could be either one previously entered into the system or one specified in an asset tag within the same manifest file. |
| flv-full-refid | Deprecated | The reference ID attribute of a full-length video file to include in this video. This reference ID could be either one previously entered into the system or one specified in an asset tag within the same manifest file. This attribute is deprecated; use video-full-refid instead. |
| thumbnail-refid | Optional | The reference ID parameter of a thumbnail asset. This reference ID could be either one previously entered into the system or one specified in an asset tag within the same manifest file. Do not use this attribute if you are also using the encode-to attribute for the corresponding video asset. When Brightcove transcodes a video, a thumbnail image is automatically created. |
| video-still-refid | Optional | The reference ID parameter of a video still asset. This reference ID could be either one previously entered into the system or one specified in an asset tag within the same manifest file. Do not use this attribute if you are also using the encode-to attribute for the corresponding video asset. When Brightcove transcodes a video, a video still image is automatically created. |
| flash-prebumper-refid | Optional | The reference ID parameter of a bumper video asset. This reference ID could be either one previously entered into the system or one specified in an asset tag within the same manifest file. |
| color | Optional | TRUE or FALSE. Indicates whether or not this video is in color. If you omit this attribute, its value will be considered to be TRUE. |
| language | Optional | The language the video is in. If you omit this attribute, no value will be assigned to this field. |
| rating | Optional | One of the following values: TV-Y, TV-Y7, TV-Y7FV, TV-G, TV-PG, TV-14, TV-MA, MV-G, MV-PG, MV-PG13, MV-R, MV-NC17, Not-Rated, Not Rated, Parental-Advisory, Parental Advisory, No-Parental-Advisory, No Parental Advisory |
| release-date | Optional | The date the video was released. Use the MM/DD/YYYY format. |
| shared | Optional | TRUE or FALSE. Should this video be shared with affiliate accounts? If TRUE, you must also include one or more share-to-id child elements in the title element to specify the account IDs of the affiliates you are sharing with. Read about media sharing. |
| auto-accept-shared | Optional | TRUE or FALSE. If this video is to be shared with affiliate accounts, can the affiliates automatically accept it into their Brightcove media library, rather than explicitly accepting it in the Brightcove Studio Media module? This attribute has no effect unless both shared="TRUE" for this video and the affiliate has enabled automatic acceptance for the account that's the source of the shared video. Read about media sharing. |
| economic-type | Optional | One of the following values: FREE or AD. If no economic type value is specified, the video will default to FREE. |
| ad-keys | Optional | A semi-colon separated string of key/value pairs, starting with a semi-colon. For example: ad-keys=";key=value;key=value;key=value" |
| overlay-update | Optional | TRUE or FALSE. If true, and if this video already exists, only the attributes and child elements of this title that you explicitly set will be modified. If false (the default), any attributes or child elements of this title that you do not explicitly set will be set to null. |
A title tag can contain the following child element tags.
| name | required? | description |
|---|---|---|
| short-description | Required | A brief description of the video, up to 250 characters. Depending on the player template, viewers may see this description. The short description is also typically displayed in RSS feeds that include the video. |
| long-description | Optional | A longer description of the video, up to 5,000 characters. Viewers may see this description when browsing or searching in public search engines or web sites. |
| related-link-url | Optional | A related URL for the video. Maximum length 255 characters. |
| related-link-text | Optional | Text for the optional related link URL. Maximum length 255 characters. |
| custom-string-value | Optional | A String type custom metadata field. Use the name attribute for the field's name and the value attribute for the field's string value. Maximum length 1,024 characters. |
| custom-enum-value | Optional | An Enum type custom metadata field. Use the name attribute for the field's name and the value attribute for the field's string value. Maximum length 100 characters. |
| tag | Optional | One or more tags to assist in filtering and searching for the video, up to 64 characters each. You can have no more than 1,200 tags per video. Tags can also help publishers filter videos in a smart playlist. You can use multiple instances of this element to associate several tags with a single video. For example:
<tag="travel"/> |
| share-to-id | Optional | If you are sharing this video and have set <title shared="true" >, you must include one or more share-to-id child elements in the title element to specify the Brightcove account IDs of the accounts with which you are sharing the video. Read about media sharing. |
| logo-overlay | Optional | The collection of metadata for defining an image that will be positioned over the video window for branding and to drive traffic to a specified location. This tag uses the logo-overlay attributes. Read about logo overlays. |
The logo-overlay tag uses the following attributes to define an image that will be positioned over the video window for branding and to drive traffic to a specified location.
| name | required? | description |
|---|---|---|
| asset-refid | Required | The reference ID parameter of the logo overlay asset. This reference ID could be either one previously entered into the system or one specified in an asset tag within the same manifest file. |
| click-thru | Optional | The URL of the browser window to be opened when the logo overlay image is clicked. Maximum length 128 characters. |
| tooltip | Optional | The tooltip or alt tag to appear over the logo overlay image on rollover. Maximum length 128 characters. |
| alignment | Optional | The alignment of the logo overlay image within the video window. The valid values are one of "top left", "top right", "bottom left" or "bottom right". For example:
<alignment="top right"/> |
There are two types of playlist: manual and smart.
You do not need to create any playlists using FTP batch provisioning; you can instead use FTP batch provisioning just to upload assets, or assets and videos, and create your playlists using the Media module.
For a manual playlist, use the manual-lineup tag. Within the manual-lineup tag, use a series of title-refid tags to list each video that is to be included in the playlist.
<manual-lineup
name="My Manual Lineup"
refid="lineup1"
thumbnail-refid="asset4">
<title-refid>title1</title-refid>
<title-refid>title3</title-refid>
<title-refid>title137</title-refid>
</manual-lineup>
The manual-lineup tag uses a mix of attributes and child element tags which map closely to the fields found in the Media module's playlist creation form.
| name | required? | description |
|---|---|---|
| name | Required | The name of the playlist as it should appear in players. Viewers will see this playlist name when browsing or searching. Maximum length 50 characters. |
| refid | Required | A unique identifier so that the playlist can be referenced later. Maximum length 150 characters. |
| thumbnail-refid | Optional | The refid attribute of a Thumbnail asset to include in this manual lineup. This reference ID could be either one previously entered into the system or one specified in an asset tag within the same manifest file. |
| overlay-update | Optional | TRUE or FALSE. If true, and if this playlist already exists, only the attributes and child elements of this playlist that you explicitly set will be modified. If false (the default), any attributes or child elements of this playlist that you do not explicitly set will be set to null. |
| name | required? | description |
|---|---|---|
| title-refid | Required | The refid parameter of a video to include in this manual playlist. This reference ID could be either one previously entered into the system or one specified in an asset tag within the same manifest file. |
| description | Optional | A brief description of this playlist, not more than 250 characters. |
For smart playlists, use the automatic-lineup tag. You do not explicitly reference videos, but instead specify how to order the videos, using the type attribute. You can also filter videos using the tag-filter attribute and the title-tag child element.
<automatic-lineup name="My Automatic Lineup"
refid="lineup2"
type="NEWEST_TO_OLDEST"
tag-filter="AND"
title-limit="50"
thumbnail-refid="asset4">
<title-tag>sporty</title-tag>
</automatic-lineup>
The automatic-lineup element has a mix of attributes and sub-element tags which map closely to the fields found in the Media module's playlist creation form.
| name | required? | description |
|---|---|---|
| title-tag | Optional | You can use this element to filter the videos to be included in this automatic lineup. Use a separate title-tag element for each tag you want to use for filtering titles. See tag-filter for information about how to handle filtering with more than one tag. For example:
<automatic-lineup name="My Automatic Lineup" |
| description | Optional | A brief description of this playlist, not more than 250 characters. |
You can add cue points to a video using the cuepoint XML element in your batch provisioning manifest. A cue point is a marker at a precise time point in the duration of a video. You can use cue points to trigger mid-roll ads or to separate chapters or scenes in a long-form video.
The cuepoint tag is a top-level tag that you use to set a cue point for a video. It has an optional child tag, metadata. The metadata child tag can contain CDATA or a string to provide information about the cue point.
<cuepoint name="My Cue" type="CHAPTER" time="500000" video-refid="video001" />
<cuepoint name="My Other Cue" type="AD" time="50000" video-refid="video001" />
<cuepoint name="My Third Cue" type="AD" time="120000" video-refid="video001">
<metadata>Something interesting about this cue point.</metadata>
</cuepoint>
<cuepoint name="My Fourth Cue" type="AD" time="270000" video-refid="video055">
<metadata>
<![CDATA[
This is a multi-line
Set of metadata
]]>
</metadata>
</cuepoint>
| name | required? | description |
|---|---|---|
| name | Required | A name for the cue point, so that you can refer to it. Maximum length 128 characters. |
| video-refid | Required | The reference ID of the video to which this cue point applies. |
| time | Required | The time of the cue point, measured in milliseconds from the beginning of the video. |
| forcestop | Optional | If true, the video stops playback at the cue point. This setting is valid only for AD type cue points. |
| type | Required | The type of cue point: one of AD, CODE, or CHAPTER. An AD cue point is used to trigger mid-roll ad requests. A CHAPTER cue point indicates a chapter or scene break in the video. A CODE cue point causes an event that you can listen for and respond to. |
| metadata | Optional | A string that can be passed along with a CODE cue point. Maximum length 512 characters. |
A cuepoint tag can optionally include a single metadata child element. The metadata element encloses a string that can be passed along with the cue point.
You can also use the FTP batch provisioning system to delete assets, videos, playlists, or cue points from your account. Warning: An asset cannot be deleted if it is referenced by a video, and a video can not be deleted if it is referenced by a playlist.
<delete-asset refid="RandomAssetsRefID"/> <delete-title refid="RandomTitlesRefID"/> <delete-lineup refid="RandomLineupsRefID"/> <delete-cuepoint video-refid="video0001" name="cuepoint name"/>
Use the following tags, setting the refid attribute to the refid of the asset, video, or playlist that you want to delete.
| name | required? | description |
|---|---|---|
| delete-asset | Optional | Deletes the asset with the refid specified by the refid attribute. |
| delete-title | Optional | Deletes the video with the refid specified by the refid attribute. |
| delete-lineup | Optional | Deletes the playlist with the refid specified by the refid attribute. |
| delete-cuepoint | Optional | Deletes the cuepoint with the name specified by the name attribute. |
The last tag marks the end of the manifest, indicating that the entire manifest is present.
</publisher-upload-manifest>