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 WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA 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 WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA 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 WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA 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 WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA 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 WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA 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. OOYALA INGESTION GUIDE | METADATA FILE FORMATS | 8 WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA 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. OOYALA INGESTION GUIDE | METADATA FILE FORMATS | 9 WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA 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. OOYALA INGESTION GUIDE | METADATA FILE FORMATS | 10 WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA 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> <!-- 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. 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. OOYALA INGESTION GUIDE | METADATA FILE FORMATS | 11 WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA 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 WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA 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 WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA 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 WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA 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 WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA 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 WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA 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 WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA 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 WWW.OOYALA.COM SALES@OOYALA.COM 1-877-3-OOYALA 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.