Introduction
When ingesting videos, you can use CSV 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 CSV manifest files when you ingest content with FTP or Aspera.
Limitations
Note: This topic applies to OIS v2.5.
The CSV format of the metadata file supports fewer features than does the XML format. The CSV format allows you to specify thumbnails (preview images) and custom metadata to associate with a video. The XML format supports these features as well as the association of the names of existing defined of ad sets.
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:
- By default, each
metadatakey/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 tagmeta::category::cooking - If you would rather use
custom_fieldsto 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.
CSV Manifest Column Headings
The following fields are the first line (column headings) of your CSV file, with actual data fields following on subsequent rows (one row per video).
Note: You can specify these columns in any order, and you can omit columns that you do not need, as long as the data in the data rows match the headings exactly.
| Column Heading | Description | Required/Optional |
|---|---|---|
| video | Filename of the video or the URL where the video is located. The URL can include http:// or https://. | required |
| title | Name or title of the video. | optional |
| thumbnail | Filename of the thumbnail or the URL where the thumbnail is located. | optional |
| content_type | Content type (video or remote asset). If the filename specified in the video column is a URL where the video is located, and if you want to define a remote asset, change the value of the content_type column (from video, the default) to content_type=remoteasset. | required (remote assets only) |
| description | Description of the video. | optional |
| hosted_at | Permanent URL where you embed the video. Maps to the value of the hosted_at property for a remote asset.
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. |
optional |
| flight_start_time | The start time when the asset can be played, in UTC. Example: 2011-06-01T00:00:00Z | required (only if flight_end_timeis specified) |
| flight_end_time | The end time when the asset can be played, in UTC. Example: 2011-07-01T00:00:00Z | optional |
| durationInMs | (OS v2.5 only) The duration representing the length of the video (in milliseconds). Required when content_type=remoteasset. | required (for remote assets only) |
| labels | One or more labels, separated by commas. For example: /sports,/sports/jogging. | optional |
| metadata | Custom metadata for the video. You can have a column for each type of metadata. See the Handling of metadata section above to see how metadata is mapped to Video Cloud video fields. | optional |
| embed_code | (Reserved). Content ID in Backlot of the video asset. | reserved |
| id | Maps to the created asset's external ID property: a custom identifier you define that you can use instead of the content ID. | optional |
| subTitle | Specifies a closed caption file (supported for DFXP files only). One of the following:
|
optional |
| subTitle:lang | (optional) - Language of the closed caption file. Two-letter language code./td> | optional |
| subTitle: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. | optional |
| 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. If you do not want to use the default Video Cloud ingest profile, you must include the ID of the one you want to use. See Managing Ingest Profiles. | optional |
Example CSV Manifest File (OIS v2.5)
video,title,description,labels,hosted_at,id,thumbnail,subTitle,flight_start_time,flight_end_time,profileguid
test.mp4,Test CSV,This is an example,"test,example,csv",http://www.ooyala.com,my_test_guid_csv,my_thumbnail.jpg,my_caption.dfxp,2016-01-01T15:15:00-07:00,2022-01-01T16:00:00-07:00,57d5a5a10f654fe79ef954dc8d29a108
Creating a CSV Manifest File
Keep the following in mind when generating a CSV metadata file:
- If a text value in a data field has a comma (,), you must enclose the field in double quotes (").
- If a text value in a data field has a double quote (") in it, you must enclose the field in double quotes and escape the double quote character in the text field with a second quote (e.g., "She said, ""Have a nice day.""" )
If you are creating your CSV metadata file from Excel, it automatically handles escaping.
To create a CSV metadata file:
- Upload one or more videos.
- Open a spreadsheet program, such as Microsoft Excel.
- Add the column headings to the first row.
- Add a row for each video.
- Save the file as a CSV. For example, you might select Save as from the File menu. When prompted, select the comma-separated value file type.
- With your upload method of choice, upload the CSV file as you uploaded the video(s). See either FTP or Aspera.