Ooyala

OOYALA INGESTION GUIDE
OOYALA INGESTION GUIDE | TOC | 2

WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA
CONTENTS
OVERVIEW: HOW INGESTION WORKS 4
BACKLOT UI 5
BACKLOT API FOR UPLOADING VIDEOS 6
METADATA FILE FORMATS 7
Creating a CSV Metadata File 7
Creating an XML Metadata File 9
Updating Asset Metadata with CSV or XML 11
FTP 12
Setting Up FTP 12
Uploading a Video with FTP 12
ASPERA 14
Setting Up Aspera 14
Downloading Aspera Client 14
Using Aspera 14
MRSS 16
Setting Up MRSS 16
Using MRSS 16
INGESTION LOG AND ERROR MESSAGES 17
OOYALA INGESTION GUIDE | COPYRIGHT NOTICE | 3
COPYRIGHT NOTICE
Copyright Ooyala 2008-2014
Ooyala, Backlot, Ooyala Actionable Analytics, the Ooyala logo, and other Ooyala logos and product and
service names are trademarks of Ooyala, Inc. (Ooyala Marks). Company agrees not to remove any
Ooyala Marks that are contained within and/or affixed to the Services as provided to Company. Except
with respect to the foregoing, Company agrees not to display or use in any manner the Ooyala Marks
without Ooyalas prior written permission. All contents of the Ooyala website and Services are: Copyright
2008-2014. Ooyala, Inc. All rights reserved. Ooyala and Backlot are registered trademarks of Ooyala, Inc.
in the United States, Japan, and European Community. All rights reserved.
For complete information on terms of service, see: http://www.ooyala.com/tos
All other trademarks are the property of their respective companies.
This content was last updated on 2014-06-12.
OOYALA INGESTION GUIDE | OVERVIEW: HOW INGESTION WORKS | 4
OVERVIEW: HOW INGESTION WORKS
The term ingestion means loading video or other content into a system. Ooyala supports several methods
for uploading videos to Backlot.
These methods currently include:
Backlot UI
Ooyala Import Services (OIS), with or without metadata about the videos in either comma-separated
value (CSV) format or XML, via the following transport mechanisms:
FTP
Aspera
MRSS
Backlot API, specifically the /v2/assets routes
The figure below shows your options, plotted by required development time and by feature/performances.
Figure 1: Ooyala Ingestion Options
1. If you have no programming resources available or have few files to upload, use the Backlot UI. After
uploading a video, you can manually associate it with ad sets, add metadata, and other features.
2. If you have many files to upload (bulk ingestion), use FTP or Aspera, with or without metadata.
3. If you have many files to upload (bulk ingestion) and want to include thumbnails (preview images)
with them or associate custom metadata with them, use FTP or Aspera with metadata in CSV format.
4. If you have many files to upload (bulk ingestion) and want to include thumbnails (preview images)
with them, associate custom metadata with them, and associate them with existing ad sets, use FTP or
Aspera with metadata in XML format.
5. If you want Ooyala to pull files from your content management system (CMS) (that is, to use MRSS),
use FTP or Aspera with metadata in XML format.
6. If you have programming resources, use the Backlot API directly.
: If you intend to use FTP, Aspera, or MRSS, and either CSV or XML metadata files, contact your
Customer Success Manager or Technical Support to inform them.
ABOUT CONTENT REPLACEMENT
You cannot use content replacement with the FTP, Aspera, or MRSS mechanisms. Attempting to do so will
result in duplicate assets.
Instead, use the /v2/assets API request, with the /replacement qualifier for each asset. See the
Backlot API Reference for more details.
OOYALA INGESTION GUIDE | BACKLOT UI | 5
BACKLOT UI
The Backlot UI is a convenient tool that enables you to quickly upload and manage videos.
Although the Backlot UI is a useful tool that you are likely to use to manage content, it is not the fastest
way to upload large numbers of videos and uploading is a manual process.
If you want to use the Backlot UI for occasional uploading, refer to the Backlot User Guide
OOYALA INGESTION GUIDE | BACKLOT API FOR UPLOADING VIDEOS | 6
BACKLOT API FOR UPLOADING VIDEOS
The Backlot API enables you to integrate your content management system (CMS) or workflows directly
with the Backlot platform.
The Backlot API provides the highest level of integration and customization, but it requires development
time and resources.
If you want to integrate with the Backlot platform using the Backlot API, refer to the Ooyala Developer
Guide and the Backlot API Reference.
The primary call for uploading files (called "assets") is the /v2/assets route.
: Do not add a video with a null external_id, that is, an external_id with no value ("") or a
value of "null". Such null external IDs cannot be searched for later.
OOYALA INGESTION GUIDE | METADATA FILE FORMATS | 7
METADATA FILE FORMATS
In addition to the video files themselves, both FTP and Aspera can read metadata about the videos from
files in either CSV or XML format.
The term metadata is used in two ways here:
1. "Metadata" meaning information describing the video itself, which you put in a CSV or XML file for
uploading along with the videos themselves.
2. "Metadata" fields you yourself create to associate with the assets created after or during ingestion.
These metadata fields are marked as metadata in the CSV or XML file described above.
Ooyala supports three types of uploads:
Basicyou upload one or more videos to Ooyala, Backlot immediately begins processing them. All
metadata, including the title and description, must be configured through the Backlot UI or Backlot API.
CSVyou upload one or more videos to Ooyala. After the videos are uploaded, you upload a CSV
file which contains all the video metadata. After Backlot receives the CSV file, it automatically begins
processing the received videos.
XMLyou upload one or more videos to Ooyala. After the videos are uploaded, you upload an XML
file which contains all the video metadata. After Backlot receives the XML file, it automatically begins
processing the received videos.
You must let Ooyala know which option you will use. You can change it if needed, but you can only use
one.
If you choose CSV or XML, Backlot does not begin processing any of the videos until the XML or CSV file
is received. As a result, it is important to choose a batch upload strategy.
If your videos must be available quickly (e.g., news distribution), you should create very small batches or
even batch them individually (one CSV or XML file per video). If your videos do not need to be available
quickly, you can upload larger batches and upload the CSV or XML file when you are ready to begin
processing.
CREATING A CSV METADATA FILE
A CSV metadata file contains information about videos that you uploaded in a standard comma-delimited
spreadsheet format, including thumbnails and custom metadata.
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.
The following fields are the first line (column headings) of your CSV file, with actual data fields following on
subsequent rows.
Column Heading (field name) Description
video Filename of the video or the URL where the video is located; only
URLs beginning with http are allowed, not https.
title Name or title of the video.
thumbnail Filename of the thumbnail or the URL where the thumbnail is located.
description Description of the video.
Column Heading (field name) Description
hosted_at Permanent URL where you embed the video. Maps to the value of
the hosted_at property for a remote asset.
: 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.
flight_start_time The start time when the asset can be played, in UTC. Example:
2011-06-01T00:00:00Z
flight_end_time The end time when the asset can be played, in UTC. Example:
2011-07-01T00:00:00Z
labels One or more labels, separated by commas. For example: /sports,/
sports/jogging.
metadata Metadata for the video. You can have a column for each type of
metadata; for example, metadata:type_1 metadata:type_2
and so on).
embed_code 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. See more
details in Updating Asset Metadata with CSV or XML on page 11.
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:
1. Upload one or more videos.
2. Open a spreadsheet program, such as Microsoft Excel.
3. Add the column headings described above to the first row.
4. Add a row for each video. For example:
5. 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.
6. With your upload method of choice, upload the CSV file as you uploaded the video(s). See either FTP
or Aspera.
CREATING AN XML METADATA FILE
An XML metadata file contains information about videos that you uploaded in a standard XML format.
Like the CSV format, the XML format allows you to specify thumbnails (preview images) and custom
metadata to associate with a video.
Elements in the XML metadata file are as follows; these elements are nested under <item> for each
video to be ingested.
Column Heading
(field name)
Description
<media:content> Filename of the video that you uploaded or (for ingestion via MRSS) the URL where
the video is located; only URLs beginning with http are allowed, not https. For
more details on ingestion via MRSS; see Setting Up MRSS on page 16).
<media:title> Name or title of the video.
<media:thumbnail> Filename of the thumbnail or the URL where the thumbnail is located.
<media:description> Description of the video.
<link> Permanent URL where you embed the video; maps to the created assets
hosted_at property.
<dcterms:valid> Flight times: 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>
<ooyala:labels> One or more labels, separated by commas (e.g., /sports,/sports/jogging).
<ooyala:metadata> Metadata for the video. You can have an element for each type of metadata; for
example, <ooyala:metadata name="internal_id">, <ooyala:metadata
name="category">, and so on).
<guid> Maps to the created asset's external_id property: a custom identifier you define
that you can use instead of the content ID. See more details in Updating Asset
Metadata with CSV or XML on page 11.
To create an XML metadata file:
1. Upload your videos.
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. Also, the second video has flight times
and advertisements.
<?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>

<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. Make 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 file as you uploaded the video(s). See either FTP
or Aspera.
UPDATING ASSET METADATA WITH CSV OR XML
With the id column in CSV format and the guid element in the XML format, you can use your own
identifiers for your ingested content. You can later use those identifiers to update the asset, including its
metadata.
The id column in the CSV format and the guid element in the XML format work as follows:
If you do not explicitly set the field when the file is first ingested, the identifier is the embed code
(content ID or asset ID) assigned by the system.
If you do set the field in the initial upload, you need to provide it in the CSV or XML files for later
updates to a previously uploaded file.
If the CSV or XML file includes the field with the external ID or embed code (content ID or asset ID) of a
previously uploaded video file, the system updates the asset's metadata.
If the CSV or XML file references a video file, the system looks for that video file locally in the
customer's directory. If the system cannot find it, the entry is skipped.
: If you are not including your external identifiers, do not include these fields with a null value. Null
values cannot be searched for later. Omit the field from your metadata file.
OOYALA INGESTION GUIDE | FTP | 12
FTP
FTP is a convenient and easy way to upload large numbers of videos (bulk ingestion).
FTP is a standard network protocol for transferring files from one computer to another. Most operating
systems support FTP natively and there are many FTP applications. As a result, you can automate FTP
uploads by writing scripts, have users bulk upload videos through a Windows, Mac, or Linux application, or
have users bulk upload videos through a browser (e.g., FireFTP).
:
Files older than seven days are automatically deleted from the ingestion server.
Your account is limited to a maximum of 100GB on the ingestion server at any time. If you expect to
upload more content, you can request a temporary increase from your Customer Success Manager
or Technical Support.
SETTING UP FTP
Ooyala must know that you plan to use FTP and must provide you with credentials before you can begin
uploading videos.
To use FTP, contact Ooyala Support and let them know the following:
That you would like to use FTP to upload content to Ooyala.
Whether you would like to provide metadata through an XML file, metadata through a CSV file, or no
metadata at all.
After making a support request, Ooyala Support will return a set of credentials. The following are sample
FTP credentials:
ftp://d0b206YlR6etqD1HscU4iP3R223:2kg15iBvFOo3ffg@ftp.upload.ooyala.com
server: ftp.upload.ooyala.com
username: d0b206YlR6etqD1HscU4iP3R223
password: 2kg15iBvOo3fVfg

UPLOADING A VIDEO WITH FTP
With FTP ingestion, you can use any FTP client to upload videos to Backlot.
To upload a video:
1. Prepare videos to upload.
2. Locate your credentials provided by Ooyala. For example:
username: 11amo6qGw2oucN78R-BYbDpCESk
password: 2kg15iBvOo3fVfg

3. Select one of the following FTP endpoints:
uk.ftp.upload.ooyala.com (UK/EMEA)
OOYALA INGESTION GUIDE | FTP | 13
jp.ftp.upload.ooyala.com (Asia/Pacific)
ftp.upload.ooyala.com (All others)
4. Start your FTP client and begin uploading to the root directory of the selected FTP endpoint. Videos
uploaded to any subdirectories will be ignored.
If you are using a UI-based tool, you specify your credentials in the UI. If you are using a command-line
tool, your request looks similar to: ftp://username:password@endpoint For example: ftp://
d0b206YlR6etqD1HscU4iP3R223:2kg15iBvFOo3ffg@ftp.upload.ooyala.com. For more
information, refer to the documentation that accompanied your FTP client.
With a Basic FTP account, Backlot immediately begins processing any uploaded videos. With a CSV or
XML FTP account, Backlot will not begin processing the video(s) until the metadata file is uploaded.
5. To check whether the videos processed, see Ingestion Log and Error Messages on page 17.
6. Continue uploading videos until you are finished.
Files are deleted after all of the videos are processed. Any video specified in the metadata file that
cannot be found is ignored.
OOYALA INGESTION GUIDE | ASPERA | 14
ASPERA
Aspera is a high-performance client for uploading videos to Ooyala that uses encryption to transfer data.
The process for using Aspera is exactly the same as FTP, except that you use an Aspera client instead of
an FTP client.
:
Files older than seven days are automatically deleted from the ingestion server.
Your account is limited to a maximum of 100GB on the ingestion server at any time. If you expect to
upload more content, you can request a temporary increase from your Customer Success Manager
or Technical Support.
SETTING UP ASPERA
Ooyala must know that you plan to use Aspera and must provide you with credentials before you can begin
uploading videos.
To use Aspera, contact Ooyala Support and let them know the following:
That you would like to use Aspera to upload content to Ooyala.
Whether you would like to provide metadata through an XML file, metadata through a CSV file, or no
metadata at all.
Ooyala Support will send you your login credentials. The following are sample Aspera credentials:
username: d0b206YlR6etqD1HscU4iP3R223
password: ovCrfllsEnFrnNers

DOWNLOADING ASPERA CLIENT
Aspera is available as a free browser plug-in or a licensed desktop client.
If you want to download the free browser plugin, go to aspera connect.
If you want to download the desktop client, go to aspera client.
USING ASPERA
After you download and install Aspera, you can uploaded videos, thumbnails, and metadata files.
To use Aspera:
1. Add a new host, specifying aspera.upload.ooyala.com as the host and the username and
password that were provided by Ooyala.
2. Begin uploading videos, thumbnails, and metadata files.
With a Basic FTP account, Backlot immediately begins processing any uploaded videos. With a CSV or
XML FTP account, Backlot will not begin processing the video(s) until the metadata file is uploaded.
OOYALA INGESTION GUIDE | ASPERA | 15
3. To check whether the videos processed, see Ingestion Log and Error Messages on page 17.
4. Continue uploading videos until you are finished.
Files are deleted after all of the videos are processed. Any video specified in the metadata file that
cannot be found is ignored.
OOYALA INGESTION GUIDE | MRSS | 16
MRSS
Media RSS (MRSS) is a variant of RSS that you can use to have your videos pulled by Ooyala from your
own system.
SETTING UP MRSS
Ooyala must know that you plan to use MRSS and you must provide server information before Ooyala can
start ingesting videos.
To use MRSS, contact Ooyala Support and provide one or more MRSS URLs.
USING MRSS
To use MRSS, you upload videos and thumbnails to a web server and create an XML file that references
the videos and thumbnails.
To use MRSS:
1. Upload one or more videos to a web server.
2. Upload one or more thumbnails to a web server.
3. Create an XML metadata file as described in Creating an XML Metadata File on page 9. Make sure the
entries in the file reference the videos and thumbnails on your server.
In particular, the value of the <media:content> elements href attribute must be an HTTP URL to the file
on your server, like the following example:
<media:content url="http://mysite.com/upload/lacrosse_70.mov" />

4. Upload the XML metadata file to one of the MRSS locations you provided. Make sure the filename and
path exactly matches one of the paths you provided to Ooyala.
5. Unfortunately, the concept of "client logging" does not apply to MRSS feed-based processing. The best
way to verify that your feed is processing successfully is to check for the appearance of your assets,
either with the Backlot UI or the Backlot API /v2/assets request.
6. After the videos are processed, you can put another MRSS file in the agreed-upon location to upload
more files.
OOYALA INGESTION GUIDE | INGESTION LOG AND ERROR MESSAGES | 17
INGESTION LOG AND ERROR MESSAGES
When you start using FTP or Aspera, Ooyala creates a log file in the home directory called ooyala.log.
You can view this file to check the status of uploads.
EXAMPLE OF SUCCESS MESSAGE
The following snippet shows what is recorded in the ingestion log for a successful upload.
.
.
.
2012-10-31 02:25:48 INFO importing "http://
d18tka3ecu2l5z.cloudfront.net/39206_MOV01E_1228612704000.flv"
2012-10-31 02:26:04 INFO fetching http://
d18tka3ecu2l5z.cloudfront.net/39206_MOV01E_1228612704000.flv
2012-10-31 02:26:07 INFO succeeded: received 41351347.0 bytes
2012-10-31 02:26:14 INFO assigned embed_code
o2b2lnNjq28XhRGgF26cVEJP1iF2hv2R
2012-10-31 02:26:21 INFO updating metadata for
o2b2lnNjq28XhRGgF26cVEJP1iF2hv2R
2012-10-31 02:26:22 INFO success
.
.
.

ERROR MESSAGES
The following table describes possible error messages.
Error Message Description
expecting X bytes; got Y bytes The downloaded file wasn't the correct size; resend
the metadata file.
remote server said 404 or remote server said 505 OIS couldn't find the file on your server; check that
the video file is there and send the metadata file
again.
remote server said ### An error occurred on your server; check your server
and resend the metadata file.
hash mismatch: expecting ..., got ... The file was corrupt; resend the metadata file.
failed to upload thumbnail The movie was ingested, but the thumbnail upload
failed. You can manually fix this by uploading a new
thumbnail in the Backlot UI or upload the video,
thumbnail, and metadata file for that video again.
error fetching feed ... There was a problem retrieving the MRSS feed;
make sure the MRSS server is working properly.
failed: workflow error There was a problem with the content you provided.
You can manually fix this by checking the state
and configuration of the video in the Backlot UI or
OOYALA INGESTION GUIDE | INGESTION LOG AND ERROR MESSAGES | 18
Error Message Description
upload the video, thumbnail, and metadata file for
that video again.
failed: system busy; try again There was an issue with the uploading the video.
You can manually fix this by checking the state
and configuration of the video in the Backlot UI or
upload the movie, thumbnail, and metadata file for
that video again.
failed: internal error Retry the upload. If it is not fixed within five minutes,
contact Ooyala Support.

Ooyala

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Ooyala

Uploaded by

Copyright:

Available Formats

OOYALA INGESTION GUIDE

OOYALA INGESTION GUIDE | TOC | 2

You might also like