Once VOD 2.0

Product(s)
SSAI
Role(s)
API Developer
Topic(s)
Accessibility
Advertising
Captions
Ingest Profiles
Notifications
VOD 2.0

Once VOD 2.0 is the next generation content ingest, lifecycle management, media management and dynamic permutation layer (DPL) subsystem for web video monetization and global playback with Once. The new system offers many advantages over its predecessor including simple and modular ingestion formats, cloud-based workflows, faster publishing times, and advanced DPL capabilities for multiple stream formats and content security packaging.

Implementation

New Customer Setup

A new Brightcove Once domain (an "account") will be created on your behalf.

We will need the following information to set up the new domain:

  • Customer name
  • Customer technical contact - first name, last name, email address, and phone number
  • Customer CDN account information exchange
    • Brightcove will provide a hostname to use as CDN Origin with your provider along with configuration requirements
    • Upon configuration we will need your CDN edge hostname, which will be utilized during the playback process for video content delivery
  • An understanding of how your media is broken up to create catalogs in the system for them

We will supply the following information to you for use in subsequent steps:

  • API Key - system generated
  • DomainId- system generated
  • CatalogId(s) - system generated
  • ApplicationId(s) - system generated

Important terms

Domain
The top level account for a Once customer used to tie catalogs, ad provider configurations, applications and publication rules together. In most cases, only one domain will be necessary.
Catalog
A digital library of video assets within a domain. Used for organizing and segregating different types of content. Typical implementations could have catalogs for different content types within a domain such as long form vs. short form or by property type with sports vs. news.
Application(ID)
A URL parameter used to determine preconfigured advertising calls and other business logic. Multiple applications may be configured in a domain to facilitate different configurations as needed.

Existing Customers

If you are currently using the Once service, please contact your account manager to schedule a migration appointment. For the purposes of existing customer testing, a new domain is required to ensure content and configuration segregation from customer production content.

Ad decision server interaction

You can use any ad decisioning server that follows the IAB specification for VAST 2.0 or VAST 3.0, as well as Freewheel Smart XML GET requests or DoubleClick specific formats. Third party ad fill via wrappers will be handled by the Once system and no additional configurations will be necessary. Ad server interactions are configured on a per application basis meaning different ad servers can be used for multiple platforms.

The following information will be needed for proper configurations:

  1. Full Ad tag of the desired ad adserver
  2. Any dynamic values that should be appended to the ad tag request (e.g. metadata, geo information, device information, or page/site level parameters on request)
  3. Any static values that should be appended to the ad tag (i.e. publisher ID)

After the application is configured, Once requests utilizing the application will make a request to the associated Ad Server to retrieve an ad payload. If the Ad Server returns a proper response and includes an ad creative that has not been previously returned, Once will automatically ingest that ad creative video within your domain into the expected encoding renditions. Video requests that receive a new ad response (creative) which is currently being ingested will be served with that slot unmonetized. After ingestion of the ad creative has completed Once will monetize subsequent requests.

Please see the Media Management API section to configure your ad server. Due to the complex nature of ad server configurations, please contact Brightcove for any questions that may arise.

Transcoding renditions

By default, the following rendition set is configured within your Once domain. Variance is allowed in the renditions assigned to your domain, but at this time we do not allow for changes to each rendition's transcode settings.

RenditionId BrevityId Rendition Name Width Height Video Bitrate Audio Bitrate Audio Sample Rate Encoding Profile
5ff484d6-a33d-11e4-bfdb-005056837bc7 sd264 Once 264 ZC 256x144 200.64 B30 256 144 200 64 48 Baseline, 3.0
ac2e7f0b-a345-11e4-bfdb-005056837bc7 sd512 Once 512 ZC 384x216 448.64 B30 384 216 448 64 48 Baseline, 3.0
74ba4d0b-a347-11e4-bfdb-005056837bc7 sd764 Once 764 ZC 480x270 700.64 B30 480 270 700 64 48 Baseline, 3.0
076ea1a2-a35b-11e4-bfdb-005056837bc7 sd1200 Once 1200 ZC 640x360 1104.96 B31 640 360 1104 96 48 Baseline, 3.1
225bd8bb-a577-11e4-bfdb-005056837bc7 sd2000 Once 2000 ZC 960x540 1872.128 M31 960 540 1872 128 48 Main, 3.1
9adf3bc3-a578-11e4-bfdb-005056837bc7 hd3000 Once 3000 ZC 1280x720 2872.128 M31 1280 720 2872 128 48 Main, 3.1
468fb310-a585-11e4-bfdb-005056837bc7 hd4400 Once 4400 ZC 1280x720 4144.256 H40 1280 720 4144 256 48 High, 4.0
8efbb9ca-a586-11e4-bfdb-005056837bc7 hd6500 Once 6500 ZC 1920x1080 6244.256 H40 1920 1080 6244 256 48 High, 4.0
825b7f2a-a31b-11e4-bfdb-005056837bc7 audio Once 56 ZC Audio Only 0 0 4 56 56 NA

Encoding Selection Guide

These recommended setting apply to VOD and considers content streamed via Wi-Fi and cellular networks. Generally you would select all renditions and leave the decisioning on the robust Once device detection logic; however, we understand that from a storage and cost perspective this may not be ideal. The guide below identifies which renditions apply to your target platform(s) to help you define a subset.

Rendition Name iPhone 3+ iPhone 5+ Android < 4.0.3 Android 4.0.3+ Android 4.4+ Tablets Desktop OTT/STB
Once 264 ZC 256x144 200.64 B30                
Once 512 ZC 384x216 448.64 B30                
Once 764 ZC 480x270 700.64 B30                
Once 1200 ZC 640x360 1104.96 B31                
Once 2000 ZC 960x540 1872.128 M31                
Once 3000 ZC 1280x720 2872.128 M31                
Once 4400 ZC 1280x720 4144.256 H40                
Once 6500 ZC 1920x1080 6244.256 H40                
Once 56 ZC Audio Only as needed as needed            

System Notifications

System notifications allow for a programmatic push based messaging service for major milestones through the content lifecycle. It provides significant insight by proactively notifying on specific events and allows easy integration into any invested publishing systems.

Configuring notifications

We will need to collect the following information:

  1. A notification endpoint - SNS topic or a direct API endpoint
  2. Types of notifications desired

Please note that the only method supported is POST and the endpoint must allow for this verb. If desired the same endpoint can be used for multiple notification methods, or each can be configured separately. For best practice we would advise using a single endpoint and parsing by each notification event type. There are currently six types of notification milestones supported:

Type Description
INGEST The content has passed through the queue and has begun processing.
UPDATE A metadata update has been successful
TRANSCODE A rendition of the content has completed processing (does not mean the item is ready to be published)
TIMEDTEXT A timed text file has been validated and finished processing
ERROR An error occurred in the processing of the content
PUBLISH The content has completed processing and is available for delivery

Using a SNS topic for Notifications

The SNS Topic for notifications must be a topic to which the Once AWS account has permission to publish. To enable the Brightcove Once notification system to publish to your topic(s), you will first need to grant permission to the Once IAM ARN: arn:aws:iam::453163911362:root. This is done within your AWS Management Console.

Example policy statement

{
"Sid": "console_pub",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::453163911362:root"
},
"Action": "SNS:Publish",
"Resource": "{Desired_Topic_ARN}"
}

Notification examples

Ingest example:

{
"notification": "ingest",
"requestId": "2796350e-2125-4f04-b33a-59488aaa76c7",
"mediaItem": {
"id": "b8eb0ce9-72f9-4e5c-8772-79d61add60eb",
"foreignKey": "brightcove-once",
"domainId": "b207b479-c841-4095-8918-978be9e18dee",
"catalogId": "bc6cb7d4-be99-471b-adf3-7c501172b317",
"title": "brightcove-once",
"version": 0,
"metadata": {
"key1": "value"
}
},
"details": {
"message": "Media Item Ingested."
}
}

Update example:

{
"notification": "update",
"requestId": "2796350e-2125-4f04-b33a-59488aaa76c7",
"mediaItem": {
"id": "b8eb0ce9-72f9-4e5c-8772-79d61add60eb",
"foreignKey": "brightcove-once",
"domainId": "b207b479-c841-4095-8918-978be9e18dee",
"catalogId": "bc6cb7d4-be99-471b-adf3-7c501172b317",
"title": "brightcove-once",
"version": 0,
"metadata": {
"key1": "value"
}
},
"details": {
"message": "Media Item Metadata Updated."
}
}

Transcode example:

{
"notification": "transcode",
"requestId": "2796350e-2125-4f04-b33a-59488aaa76c7",
"mediaItem": {
"id": "b8eb0ce9-72f9-4e5c-8772-79d61add60eb",
"foreignKey": "brightcove-once",
"domainId": "b207b479-c841-4095-8918-978be9e18dee",
"catalogId": "bc6cb7d4-be99-471b-adf3-7c501172b317",
"title": "brightcove-once",
"version": 0,
"metadata": {
"key1": "value"
}
},
"details": {
"message": "Rendition Transcoded.",
"rendition": {
"id": "45dd911d-54ac-11e4-9f45-005056835b09",
"name": "Once 64 Audio-Only MP4 ZC 32x18 9 29.97 B3_0"
}
}
}

Timed Text example:

{
"notification" : "timedtext",
"requestId" : "8c337db5-801d-49f8-9f73-ef217ee7fac3",
"mediaItem" : {
"id" : "57f25048-f204-4996-8680-21452760a406",
"foreignKey" : "brightcove-once-subtitle",
"domainId" : "88f98026-95a7-4fe9-992a-94b6a1580483",
"catalogId" : "b72da5a6-20ee-4bfb-aa2c-5722b6acc223",
"title" : "brightcove-once-subtitle9",
"version" : 0,
"metadata" : { }
},
"timedTextItem" : {
"id" : "ef5c6aa0-6745-4faa-b1d8-8d4f87a4e12b",
"alternateId" : "microlanguage",
"domainId" : "88f98026-95a7-4fe9-992a-94b6a1580483",
"timedTextType" : "SUBTITLE",
"version" : 0,
"languages" : [ "en", "fr" ]
},
"details" : {
"message" : "Timed Text Published."
}
}

Error example:

{
"notification":"error",
"requestId":"2796350e-2125-4f04-b33a-59488aaa76c7",
"mediaItem":{
"id":"b8eb0ce9-72f9-4e5c-8772-79d61add60eb",
"foreignKey":"brightcove-once",
"domainId":"b207b479-c841-4095-8918-978be9e18dee",
"catalogId":"bc6cb7d4-be99-471b-adf3-7c501172b317",
"title":"brightcove-once",
"version":0,
"metadata":{
"key1": "value"
}
},
"details":{
"message":"Description of the error event that occurred"
}
}

Publish example:

{
"notification":"publish",
"requestId":"2796350e-2125-4f04-b33a-59488aaa76c7",
"mediaItem":{
"id":"479656c9-ec6d-464b-aba3-4739cdcc019b",
"foreignKey":"brightcove-once",
"domainId":"b207b479-c841-4095-8918-978be9e18dee",
"catalogId":"bc6cb7d4-be99-471b-adf3-7c501172b317",
"title":"brightcove-once",
"version":0,
"metadata":{
"key1": "value"
}
},
"details":{
"message":"Media Item Published.",
"onceUrl":"(Desired ApplicationId will need to be configured to utilize this field)"
}
}

Notification Retry

Typically notifications will succeed on the first attempt, but there are myriad reasons for why it may fail. If the initial attempt does not result in a successful response from the endpoint, Brightcove will attempt to retry the initial delivery attempt up to three times. Any HTTP status codes 400-499, 500-599, connection timeouts, unreachable endpoints, or bad SSL certificates will result in a failed attempt. Each subsequent retry will be 30 seconds apart not including any queueing that may add an additional delay. If the final attempt does not succeed the notification will be dequeued and require a manual intervention. Please see the Status API documentation for re-sending failed notifications.

Content Ingestion

Creating an API-based ingest job

Brightcove’s Once API Ingest service is a RESTful API that accepts HTTPS POST requests, supplying JSON as the data structure and passing the API key in the header.

For more detailed information, see:

Captioning/Subtitles

Brightcove Once enables multinational publishers to provide subtitles or closed-captioning to global audiences. These subtitles or closed captions can be rendered by players and native OS playback components that allow the viewer to choose the language of their choice, either via OS default localization settings or via a UI selection. Subtitles should not be confused with closed captions for the purpose of this implementation. While both utilize timed-text and in many cases in a similar manner, it is important to make the distinction from a regulatory and user experience perspective. In some cases, both will be required as a given piece of content could be published in North America and rest-of-world simultaneously. As digital technology evolves, closed-captioning will no longer be restrained by formatting by embedded captions and can be used in conjunction with timed-text outputs.

Subtitles input/output:

Subtitles

Output
embedded 608 SRT WebVTT (in-manifest) WebVTT sidecar DFXP
Input Sidecar SRT   [1-1]
Sidecar WebVTT   [1-1]
Sidecar DFXP  
Notes:

[1-1] A simple timed-text input format to a rich output is not recommended, although supported by using default styling to work with most platforms.

Current Restrictions/Limitations

For SRT:

  • Positioning and styling are not supported.
  • Text formatting derived from HTML tags will be treated as text.
  • Output as a sidecar through Once UX only

For WebVTT:

  • Input files must not be segmented.
  • Sidecar output file will be outputted as a full file.
  • Positioning and styling are not supported.
  • Text formatting derived from HTML tags will be treated as text.
  • Output as a sidecar through Once UX only

For DFXP:

  • Multiple languages in <div> tags in a single document is supported, but the languages must be defined at ingest.
  • Output files will not support more than one <div> tag with its associated language. Each language will be a separate sidecar file.
  • Output as WebVTT in-manifest for HLS will be segmented and follow the IETF HLS standard.
Example Once UX presentation:
...
<uo:timedText>
<uo:item type="subtitle" language="en">
<![CDATA[http://.../en/content.{output_extension}]]>
</uo:item>
<uo:item type="subtitle" language="fr" alternateId="{altId}">
<![CDATA[http://.../fr/content.{output_extension}]]>
</uo:item>
</uo:timedText>
...

Note: The alternateId attribute will only be rendered if declared on ingest.

Example in-manifest WebVTT (master playlist):
...
#EXT-X-MEDIA:TYPE=SUBTITLES,URI="http://.../content.m3u8",GROUP-ID="subs",LANGUAGE="en",NAME="English"
#EXT-X-MEDIA:TYPE=SUBTITLES,URI="http://.../content.m3u8",GROUP-ID="subs",LANGUAGE="fr",NAME="French{altId}"
...

Note: The Name of the language code will have the alternateId appended in parentheses if declared on ingest. This allows for multiple files with the same language, microlanguages, or multiple selected audio streams.

Example in-manifest WebVTT (media playlist):
...
#EXTINF:240.000,0
http://.../segment1.vtt
#EXTINF:240.000,0
http://.../segment2.vtt
...
#EXT-X-ENDLIST

Closed-Captioning input/output:

Closed-Captioning

Output
CEA-608 SRT WebVTT (in-manifest) WebVTT sidecar DFXP
Input CEA-608 [2-1]        
Sidecar SRT     [2-2]
Sidecar WebVTT     [2-2]
Sidecar DFXP [2-1]  
Sidecar SAMI [2-1]        
Sidecar SCC        
Notes:

[2-1] If the input document (or file) contains multiple languages, only the first language is selected. The file format must be in a MP4/M4V video container with caption tracks in CEA-608 format.

[2-2] A simple timed-text input format to a rich output is not recommended, although supported by using default styling to work with most platforms.

Current Restrictions/Limitations

For CEA-608:

  • Sidecar output will not be generated for extracted closed captioning
  • Output as Closed-Captioning will be presented in HLS manifests following the IETF HLS document.

For SRT:

  • Positioning and styling are not supported.
  • Text formatting derived from HTML tags will be treated as text.
  • Output as a sidecar through Once UX only

For WebVTT:

  • Input files must not be segmented.
  • Sidecar output file will be outputted as a full file.
  • Positioning and styling are not supported.
  • Text formatting derived from HTML tags will be treated as text.
  • Output as a sidecar through Once UX only

For DFXP:

  • Multiple languages in <div> tags in a single document is supported, but the languages must be defined at ingest.
  • Output files will not support more than one <div> tag with its associated language. Each language will be a separate sidecar file.
  • Output as Closed-Captioning will be presented in HLS manifests following the IETF HLS standard.
  • As CEA-608 output:
    • Animation, layout, and region features are not supported.
    • Styles can be inline or referenced by ID, but only the tts:textAlign property is applied.
    • Nested DIV and P tags are ignored
    • SPAN tags are ignored
    • Explicit breaks may be inserted with BR tags

For SAMI:

  • Inline styles are not supported
  • Layout-related styling tags are not supported
  • Explicit breaks may be inserted by using separate P tags.
  • Output as Closed-Captioning will be presented in HLS manifests following the IETF HLS standard.

Example Once UX presentation:

...
<uo:timedText>
<uo:item type="caption" language="en">
<![CDATA[http://.../en/content.{output_extension}]]>
</uo:item>
<uo:item type="caption" language="fr" alternateId="{altId}">
<![CDATA[http://.../fr/content.{output_extension}]]>
</uo:item>
</uo:timedText>
...

Note: the alternateId attribute will only be rendered if declared on ingest.

Status API

The Status API is a RESTful API which allows customers to query the processing statuses of a particular Request ID (returned in the response body of an ingest request).

For detailed information, see:

Media Management API

The Media Management API is a RESTful API for accessing and configuring the components of the domain for an authorized user. The multi-faceted and cascading configuration hierarchy gives the domain owner the ability to set-up domain, application, catalog and mediaitem level settings.

For detailed information, see:

Once URL Creation

Brightcove Once VOD uses a proprietary URL syntax. You configure this URL through a programmatic URL generation method that you customize for your particular business needs. This URL employs the Brightcove Once platform to detect viewer devices, distribute content and insert and target ads according to your specifications.

There are two APIs for requesting content to be played back as either VOD or UX. Once UX is an add-on for Once VOD for defining the VOD stream by normalizing Ad Server requests into a VAST 3.0 and embedded the information into a VMAP object. The stream definition includes, stream timeline, stream duration, third-party audience measurement information, ad breaks, normalized ad metadata, closed captioning and subtitles.

If content is being delivered from secure pages the request can be made to the same endpoint with HTTPS protocol to ensure secure delivery of the content using a single virtual host.

URL Syntax

The Once VOD URL is constructed by using a programmatic URL syntax. This section will cover the URL structures and the available parameters.

API hostname:

http://once.unicornmedia.com

Syntax:

{Protocol}://{Host}/{Service}/{DeliveryType}/{RequestedFileType}/{domainId}/{applicationId}/{mediaItemId}/{VirtualFileName}.extension

Example:

http://once.unicornmedia.com/now/od/auto/c6589dd5-8f31-4ae3-8a5f-a54ca3d7c973/5291cc2e-c90c-4f05-889e-af8067f8c1ec/31d1ef83-70f4-4de8-9f4e-2f3608d25517/content.once

URL Variables

Parameter Type Description
Protocol String HTTP or HTTPS for delivery from secure pages
Host String "once.unicornmedia.com" or CNAME pointing to "once.unicornmedia.com"
Service String "now" is the only value currently available
DeliveryType String Used to determine video delivery behavior. Please see Output Formats for more information.
RequestedFileType String Used to determine video delivery behavior. Please see Output Formats for more information.
DomainId String The Id of the Customer Domain in the Brightcove system obtained by contacting your Brightcove representative.
ApplicationId String The Id for the application in which to record metrics and enforce business rules obtained through your Brightcove representative.
MediaItemId

or

ForeignKey

String The MediaItemId or ForeignKey for the base asset being requested.
VirtualFileName String Arbitrary file name for the request.
  • The value is a preference; however, the file extension should accurately represent the requested file type
  • Regardless of the file type, the system will return a media file
  • May help you identify the delivery format and play back properly

Extensions are determined by the output format used in your request. Please see Output Formats for more information.

Output formats

Utilizing various combinations of delivery type, file type, and extension in your Once URLs, the response can be modified to suit various environments as needed. This behavior can either be handled completely by Once's automatic decision logic, or can be narrowed to respond with only adaptive or progressive formats. The URL variables outlined in the following sections are the only supported combinations for each delivery method.

Auto

To utilize the Once platform's innate device detection to determine proper delivery and file type for the requesting client device, use the combination for Auto delivery. This device detection will determine a number of different playback variables depending on the requesting device including optimal file format, video quality, and for HLS, segment length. The Once platform's Auto detection will prioritize adaptive delivery to a device if supported, otherwise the device will receive an appropriate progressive response.

DeliveryType FileType Extension
od auto once

URL map

Host/Service/ DeliveryType/ FileType/DomainId/ApplicationId/MediaItemId/VirtualFileName. Extension

Example

http://.../ od/ auto/4989f8db-9187-49ca-86ff-e2cd5342cd4/35217a08-d9db-469f-aec0-7c88406a0c60/63598604-cb88-44f8-bc47-d207af3b7b4a/content. once

Adaptive

The Once platform utilizes the HTTP Live Streaming (HLS) protocol for adaptive, multi-bitrate playback to devices that support this method. Requesting an adaptive response will force an HLS response with discontinuities between content switching and keeps the Once platform's logic in place for determining remaining device specific parameters including the range of profiles to be returned and segment length. If you wish to tailor the profiles returned on a request, you can denote those specific profiles by using the additional query string parameters: umoprofiles or umaprofiles .

DeliveryType FileType Extension
master playlist m3u8
URL map

Host/Service/DeliveryType/FileType/DomainId/ApplicationId/MediaItemId/VirtualFileName.Extension

Example

http://.../master/playlist/4989f8db-9187-49ca-86ff-e2cd5342cd4/35217a08-d9db-469f-aec0-7c88406a0c60/63598604-cb88-44f8-bc47-d207af3b7b4a/content.m3u8

Continuous Adaptive (ctAdaptive)

Similar to an adaptive request, the ctadaptive response will force a HLS response with the discontinuities removed to create a single linear stream playable on even the most simple implementations of HLS devices (e.g. native Android players). We recommend using a regular adaptive stream where possible for the best cache efficiency, but ctadaptive will solve difficult platforms and the majority of devices or player implementations for HLS. If you wish to tailor the profiles returned on a request, you can denote those specific profiles by using the additional query string parameters: umoprofiles or umaprofiles .

DeliveryType FileType Extension
master ct-playlist m3u8
URL map

Host/Service/ DeliveryType/ FileType/DomainId/ApplicationId/MediaItemId/VirtualFileName. Extension

Example

http://.../ master/ ct-playlist/4989f8db-9187-49ca-86ff-e2cd5342cd4/35217a08-d9db-469f-aec0-7c88406a0c60/63598604-cb88-44f8-bc47-d207af3b7b4a/content. m3u8

Progressive

If the desired or required video output is a progressive download in an mp4 format, the stitched combination should be used. When requesting a progressive playback experience, a renditionId of the requested quality must be included in the URL for successful playback. The placement of the renditionId in the Once URL is immediately following the ApplicationId, as shown in the example below.

DeliveryType FileType Extension
media progressive mp4

URL map

Host/Service/ DeliveryType/ FileType/DomainId/ApplicationId/ RenditionId/MediaItemId/VirtualFileName. Extension

Example

http://.../ media/ progressive/4989f8db-9187-49ca-86ff-e2cd5342cd4/35217a08-d9db-469f-aec0-7c88406a0c60/ 468fb310-a585-11e4-bfdb-005056837bc7/63598604-cb88-44f8-bc47-d207af3b7b4a/content. mp4

Foreign key use

The Brightcove Once platform allows for the use of foreign key values to be used instead of system generated MediaItemIds within the URL construct to identify the video for playback. This allows for the flexibility of using existing unique ID values associated to customer videos to be reused. Foreignkey values must be unique to each video item and cannot be used multiple times in the same Domain.

Example MediaItemId

63598604-cb88-44f8-bc47-d207af3b7b4a

Example Url using MediaItemId

http://once.unicornmedia.com/.../63598604-cb88-44f8-bc47-d207af3b7b4a/content.once

Example Foreign Key

video-co-ca-2113

Example URL using Foreign Key

http://once.unicornmedia.com/.../video-co-ca-2113/content.once

Note: for foreign keys that have special characters such as colons, please see the UMFKEY query string parameter.

Parameters

Query string

Description

Query string parameters can be used to modify the standard Once URL to append page level data for ad or beacon requests, modify response behavior, or other special use cases as needed.

Ad params

UMADPARAM - Specify the Ads Served Back by Ad Provider

UMADPARAM{Key}={Value}

Use this parameter to pass along page level and client side data to the Once platform to be appended to ad calls made to your ad provider, enabling this data to be used in their ad targeting/decisioning.

Example Key/Value pairs:
  • cc=US
  • state=Arizona
Customer Created URL:

http://once.unicornmedia.com/.../content.m3u8?UMADPARAMcc=US&UMADPARAMstate=Arizona

Brightcove consumes this Once VOD URL, removes the UMADPARAM key designator, and serves the resulting key-value pair to the ad provider who in turn can utilize that data to respond with the appropriate ad creative based on their decisioning and logic.

URL Sent by Brightcove Once to ad provider:

http://ad.provider.url?cc=US&state=Arizona

The Once VOD URL example above would make the ad call and return ads specific to the country and state values provided.

UMPTPARAM - Pass Values Through with No System Manipulation

UMPTPARAM{Key}={Value}

This is used to pass key/value pairs into a call to an ad provider when the value should not be URL decoded by the Once service. In contrast to UMADPARAM , this parameter lets you pass a string directly through the system without manipulation by Brightcove. For example, you have the ability to pass a string value of comma delimited key-value pairs that require URL Encoding.

Example Key/Value pairs:
  • Cust_params=Denver%Android_4_0%26tile%Video
  • Video_param=26iu%3D%252F7646
Customer Created URL:

http://once.unicornmedia.com/.../content.once?&UMPTPARAMCust_Params=Denver%Android_4_0%26 tile%Video&UMPTPARAMVideo_param=26iu%3D%252F7646

URL Sent by Brightcove to ad provider:

http://ad.provider.url?Cust_Params=Denver%Android_4_0%26tile%Video&Video_param=26iu%3D%252F7646

UMLITERAL - Pass Set Number of Characters Right of '&' as One String Value

UMLITERAL{Key},{Integer}&{Value}

This is used to collectively set a defined number of characters right of a specified '&' query string delimiter as one value for inclusion in the Ad Provider URL. UMLITERAL can be utilized to include ad targeting data that may otherwise be unsafe to include in a URL such as semi-colons. The example below assumes you are passing an 81-character string through as one value.

Example of string value:

slau=midroll&tpos=180;;ptgt=a&slau=midroll&tpos=360;&ptgt=a&slau=midroll&tpos=540

Number of Characters in String:

81

Customer Created URL:

http://once.unicornmedia.com.../VirtualFileName?UMLITERALmidrolls,81&slau=midroll&tpos=180;;ptgt=a&slau=midroll&tpos=360;;ptgt=a&slau=midroll&tpos=540

URL Sent by Brightcove Once to ad provider:

http://ad.provider.url?slau=midroll&tpos=180;;ptgt=a&slau=midroll&tpos=360;;ptgt=a&slau=midroll&tpos=540

Beacon parameters

UMBEPARAM

Similar to the use of UMADPARAM , the UMBEPARAM parameter can be utilized to pass along page level and client side data to the Once platform to instead be appended to third party audience measurement URLs made to an external analytics provider, enabling this data to be used in the tracking of a number of playback events. For more information please see the Beaconing section.

Example Key/Value pairs:
  • Localadid=55
  • Uniqueid=country
Customer Created URL:

http://once.unicornmedia.com/.../content.once?UMBEPARAMLocaladid=55&UMBEPARAMuniqueid=country

Parameter Examples:
  • UMBEPARAMLocaladid=55
  • UMBEPARAMuniqueid=country
Fired Beaconing URL:

http://tracking.exampleurl?Localadid=55&uniqueid=$country

UMXBEACON

UMXBEACON enables the specification of a standalone URL to be called to at play start that can be used independently or in addition to pre-configured beacons. The URL to beacon to must be encoded and if other query strings are utilized, UMXBEACON must be the last appended to the URL.

Independent Tracking

UMXBEACON={encodedURL}

Example:

http://once.unicornmedia.com/.../content.once?UMXBEACON=http%3A%2F%2Ftracking.exampleurl%3Fkeyone%3D111

Fired beaconing URL:

http://tracking.exampleurl?keyone=111

Utility params

UMFKEY - Alternative method of requesting videos by Foreign Key

UMFKEY={URLEncodedForeignKey}

UKFKEY allows for requesting Once URLs utilizing the Foreign Key as a query string parameter rather than in the URL path. This function allows for the inclusion of characters that would otherwise be disallowed in the URL path, including potentially unsafe characters. Any value used with UMFKEY must be appended to the Once URL encoded. If present, UMFKEY will take priority over the standard MediaItemId in the URL path and a static value should be used in place of the MediaItemId .

Example Key/Value pairs:
  • ForeignKey=uma:video:movie.com:480337
Example Static MediaItemId

00000000-0000-0000-0000-000000000000

Customer Created URL:

http://once.unicornmedia.com/.../00000000-0000-0000-0000-000000000000/content.once?UMFKEY=uma%3Avideo%3Amovie.com%3A480337

NOTE: The UMFKEY value must be URL-encoded.

Modifying Delivery Renditions

The robust Once device detection logic caters to specific devices based on device capabilities and hardware, but also allows users to bypass the decisioning logic. There are two methods used to override or add standard renditions at run-time per the query string. When appended as a query string to the Once URL, the associated profile(s) will be dynamically inserted in the returned m3u8 to temporarily override or add the standard rendition list for adaptive playback. The value can be a single RenditionId or BrevityId, a comma-delimited list of Ids, or utilize pre-defined profile setIds (see Default profile sets for umo/umaprofiles). All responses containing overridden profiles will continue to utilize the Once platform's device detection logic to determine the order of renditions and segment size that is most suitable for the requesting device.

Temporarily Override the Standard Rendition List ( umoprofiles )

Using UMOPROFILES={RenditionId} or UMOPROFILES={BrevityId} or UMOPROFILES={profile} query string parameter will override any renditions that have been selected by the Once Device Detection logic.

URL Map:

/.../MediaItemId/VirtualFileName?umoprofiles=Id1,Id2,...,Id(n)

Examples:

http://once.unicornmedia.com/.../content.m3u8?umoprofiles=74ba4d0b-a347-11e4-bfdb-005056837bc7,sd1200

http://once.unicornmedia.com/.../content.m3u8?umoprofiles=720p,1080p

http://once.unicornmedia.com/.../content.m3u8?umoprofiles=hd6500,hd4400

Temporarily Add Renditions to the Standard Rendition List (umaprofiles)

Using UMAPROFILES={RenditionId} or UMAPROFILES={BrevityId} or UMAPROFILES={profile} query string parameter will add the defined renditions to the rendition set selected by the Once Device Detection logic.

URL Map:

/.../MediaItemId/VirtualFileName?umaprofiles=Id1,Id2,...,Id(n)

Example:

http://once.unicornmedia.com/.../content.m3u8?umaprofiles=74ba4d0b-a347-11e4-bfdb-005056837bc7,sd2000

http://once.unicornmedia.com/.../content.m3u8?umaprofiles=1080p

Default rendition sets for umo/umaprofiles:

Default rendition sets are tailored to cover a broad set of profile configurations for the most commonly used settings. Custom rendition sets and profiles are configurable, please contact your Brightcove representative to define your own requirement.

Note: When defining your own set of renditions on delivery, any duplicate renditions will be ignored (e.g. defining sdmed,sdhigh will discard the duplicate sd1200)

RenditionId BrevityId Default Profiles
825b7f2a-a31b-11e4-bfdb-005056837bc7 audio          
5ff484d6-a33d-11e4-bfdb-005056837bc7 sd264 mobile sd sdlow    
ac2e7f0b-a345-11e4-bfdb-005056837bc7 sd512 sdmed  
74ba4d0b-a347-11e4-bfdb-005056837bc7 sd764  
076ea1a2-a35b-11e4-bfdb-005056837bc7 sd1200 tablet sdhigh
225bd8bb-a577-11e4-bfdb-005056837bc7 sd2000    
9adf3bc3-a578-11e4-bfdb-005056837bc7 hd3000 720p hd    
468fb310-a585-11e4-bfdb-005056837bc7 hd4400      
8efbb9ca-a586-11e4-bfdb-005056837bc7 hd6500 1080p      

Dynamic ad params

DAP key/value pairs are functional throughout the system; preconfigured and mapped. The Once platform will dynamically pull known client device information from the mapping during runtime and include that data as part of the tracking or targeting parameters expected by the audience measurement systems or Ad Servers, respectively. See Server Side Beaconing and UMADPARAM for URL examples.

Available Dynamic Ad Parameters (DAP's) Ad Request Content Beacon Ad Beacon

mediaitem.title

  • String value of mediaitem defined by the title ingest object. Spaces will be encoded as %2B.
mediaitem.tremor.title ✓✓
  • String value of mediaitem.tremor.title (necessary when using Tremor as an ad provider) Media Item Title with space URL encoded using %20.
mediaitem.guid
  • String value of the system generated mediaitemId
mediaitem.foreignkey
  • String value of foreignkey defined by the foreignkey ingest object.
mediaitem.duration
  • Content file duration in seconds based on the total length of content
mediaitem.adposition    
  • Integer value for the ad position, e.g., 1, 2, 3 for pre, mid, post
mediaitem.adpositiontime    
  • Time in seconds relative to the content where ad is being played
randomnumber32
  • A unique system generated random number
timestamputc
  • A 32 bit representation of the servers current time in epoch time (seconds) (UTC)
useragent
  • String of the useragent of the requesting client device
ipaddress
  • User's IP address
dma
  • Designated Market Area - 3 digit numeric code
state
  • Abbreviated State code
region
  • Name of the region
referringHost
  • String of the referring host from which the content was requested
referringURL
  • URL encoded representation of the HTTP Header: Referrer
countrycode
  • String of the ISO country code retrieved through ip intelligence.
postalcode
  • String of the user's postal code (if available) from ip intelligence.
xm."key"
  • Used to extract extended metadata defined at ingest by the "metadata" object for the key and its set value.
latitude    
  • To accommodate ad providers that require lat/long to be sent with ad tag request. Value based on ip intelligence.
longitude    
  • To accommodate ad providers that require lat/long to be sent with ad tag request. Value based on ip intelligence.
beacon.quartile.text  
  • The quartile text, e.g. Start, FirstQuartile, Midpoint, ThirdQuartile, Complete.
beacon.quartile.value  
  • The quartile time in seconds relative to the content or ad.
beacon.interval.value  
  • The time in seconds relative to the content or ad based for heartbeat intervals.
mediaitem.segmentcount    
  • Used only for play or end segment beacons. Programmatic way to provide an incremental count for play and/or end beacons.
beacon.smartxml.adcreativeid    
  • (For Freewheel Smart XML). The creative Id pulled from the Ad Server response. Xpath: adResponse/siteSection/videoPlayer/videoAsset/adSlots/temporalAdSlot/selectedAds/adReference@creativeId
beacon.smartxml.adpodid    
  • (For Freewheel Smart XML). The customId pulled from the Ad Server response. Xpath: adResponse/siteSection/videoPlayer/videoAsset/adSlots/temporalAdSlot:customId
beacon.smartxml.adpodposition    
  • (For Freewheel Smart XML). Programmatically generated based on the position sequence of the adCreativeId within a temporal pod.
xfp.correlator    
  • (For DFP) Random number correlator specific to using the DFP ad server. Unique per page view. The value will persist to each standard and optimized pod call.
xfp.pod    
  • (For DFP) Represents a pod within a video. Pass &pod=1 for first pod, &pod=2 for second pod, and so on.
xfp.ppos    
  • (For DFP) Position within a pod. Pass &ppos=1 for the first position, &ppos=2 for the second position, and so on.
xfp.vpos    
  • (For DFP) Whether ad request is being sent for preroll, midroll or postroll.
xfp.scor    
  • (For DFP) Integer generated for each video stream that reflects unique streams. The value will persist to each standard and optimized pod call.
xfp.ipaddress    
  • (For DFP) To carry the IP value into each standard and optimized pod call.
xfp.ss_req    
  • (For DFP) Required for all initial and subsequent ad tags for the Brightcove-to-XFP session.

Note: all xfp.{value} params are for DFP.

Advertising

Description

Once serves up and distributes ads through ad campaigns associated with your ApplicationId to dynamically request the payload from your Ad Server(s). Advertising calls are made server-side on behalf of the client to the ad server configured within your Brightcove account. Our platform supports VAST XML, SmartXML, DFP XFP, and nearly any VAST-like XML format.

Types supported

  • VAST
  • VAST-Wrapper
  • DFP
    • VAST
    • VAST-Wrapper
    • Ad Pods
  • Freewheel
    • VAST
    • VAST-Wrapper
    • SmartXML

Value generation

Populating the values necessary to correctly call to an Ad Provider can be accomplished through three methods: via the query string parameter UMADPARAM, statically mapped and inserted within the Once system, dynamically inserted via DAP (dynamic ad parameters) or any combination of the three.

Static

Static values for ad tag parameters will be preconfigured and set in place in the Brightcove Once database to be fired in each call to your ad provider.

Contextual

The Once platform can utilize Dynamic Ad Parameters to generate some contextual information based off of known client device information and include that data as part of the targeting parameters expected by your ad server. Please see the full list of dynamic ad parameters for more information.

Page level

For values that are not static or contextually generated, targeting information can be appended to the initial Once URL via the query string values like UMADPARAM. Please see the advertising query string section for more information.

Other features

Ad Cache

If an ApplicationId configured to make ad calls is used in a request for video, Once will send a request to the associated Ad Server to retrieve an ad payload. If the Ad Server returns ad creative that has not been previously returned, the Ad Cache service will automatically ingest that ad creative video within your ad catalog. Video requests that receive ad responses for a particular creative that is currently being ingested will be served with that slot unmonetized. After ingestion of the ad creative has completed, Once will monetize subsequent responses.

Ad Unit Waterfall Method

Brightcove Once Supports ad creative waterfall behavior for VAST XML, Freewheel SmartXML, and DFP XFP. Once makes an ad request to the first node in sequence and, if an ad unit is returned, the ad is rendered with appropriate tracking. If an ad unit is not returned, Once will try the next node in sequence and continue until all nodes have been tried.

With this methodology, an ad creative in the sequence will be used if the ad server response is not empty and includes a valid media file.

Audience Measurement/Beacons

Audience Measurement Systems

The Once system allows for the configuration and beaconing of HTTP based audience tracking URIs for both internal or external use. It allows the utilization of existing investments in reporting or analysis tools including providers like Omniture, Comscore, Nielsen, etc. The beaconing of these URIs can track both ads and/or content with measurements such as quartiles, heartbeats, content segments, start, and end events.

We will need to collect the following information:

  1. HTTP endpoint
  2. Any dynamic values that should be appended to the ad tag request (e.g. metadata, geo information, device information, or page/site level parameters on request)

These events will be configured on an application level. Please see the beacons section for additional configuration details.

Beacons

Beacons are a service within the Once platform that can fire predetermined events to a third-party analytics provider when your content is played. Beacons can be set up for base content or ads and can fire at a number of different times depending on what configuration is requested. You may configure a single play beacon to be fired, quartile events (Start, First Quartile, etc.), or at set intervals of time such as every 5 seconds. You may also have multiple beaconing URLs per application or event.

 

Beacon Type

Event Type Single Video Ad
Play Yes No
  • Content has been requested and first segment returned
Start Yes Yes
  • Content or Ad has been requested and first segment returned.
First Quartile Yes Yes
  • Content or Ad has reached 25% of its total duration.
Midpoint Yes Yes
  • Content or Ad has reached 50% of its total duration.
Third Quartile Yes Yes
  • Content or Ad has reached 75% of its total duration
Complete Yes Yes
  • Content or Ad has completed
Quartiles Yes Yes
  • Creates all the quartiles (first/mid/third/complete)
Interval Yes No
  • Heartbeat beacon that can ping on any defined interval.
segmentPlay Yes No
  • Indicate a segment has started. A segment is defined by content separated by ad breaks.
segmentEnd Yes No
  • Indicate a segment has ended. A segment is defined by content separated by ad breaks.

Value generation

Each variable in a beaconing URL can be specified according to preferences and passed dynamically to the beacon call via the query string parameter UMBEPARAM , statically mapped and inserted within the Once system, dynamically inserted via DAP (dynamic ad parameters) or any combination of these 3 options. Beaconing URLs do not require additional variables. However, the variables must be included if you want to use the UMBEPARAM query string parameter.

Static

Static values for beacons can be preconfigured and set in place in the Brightcove Once database to always be fired with the associated beacon server base URL.

DAP

The Once platform can automatically generate some contextual information based off of known client device information from the mapping in the runtime database and include that data as part of the tracking or targeting parameters expected by the Beaconing Server or Ad Server. See the full list of dynamic ad parameters.

Page level

For values that are not static or DAP generated, beacon key value pairs can be appended to the initial Once URL request to be utilized as well. See the Beacon query string section for more information.

Your Brightcove representative can assist in the process of configuring beacons. The information required is below:

  • Example URL to be utilized
  • Explanation of the various query string parameters included on the beacon URL and what their values should be on each request.
  • Information as to what events should be reported against.

CDN

Brightcove Once utilizes existing customer CDN relationships to provide the delivery of content to end users. All requests will be brokered by the Once platform, with Once acting as origin, and your CDN delivering the content. This section outlines support and the steps your Brightcove representative will go through with you to configure the Once service along with your CDN provider. Note: If the use of token authentication is desired please see the list of supported hashing algorithms and configuration details here.

Supported providers

  • Akamai
  • CloudFront
  • Limelight
  • Level3

Details

  • Brightcove will generate and provide a host name for you to use. (Example: customername.dpl.unicornmedia.com)
  • If your use case will include delivering stitched MP4, your CDN provider will need to set up an HTTP Large Object configuration utilizing the provided hostname as the Origin.
  • Your CDN will need to enable or verify that the following settings are enabled:
    • Cache on Query String or Unique-Cache
    • If there is a tiered caching option available, this should be enabled as well.
    • "Keep alive" should be on
    • Cache control should be set to honor Origin headers
  • If you are using Akamai as their CDN (or when setting up a new Akamai CDN), the following configuration needs to be enabled:

    Forward Host Header must be set to: Origin Hostname

Content Restriction

Publication rules

Publication Rules are a set of optional business logic parameters that may be applied to the content you upload into the Brightcove Once platform to restrict playback in a number of ways.

Source

Inherited from domain

By default, a domain is created with a publication rule is set to a 10 year window with no other restrictions. Any catalog created within the domain will inherit the publication rule from the domain. This rule can be modified through the Media Management API to include other default restrictions.

Inherited from catalog

By default, media items created will inherit the publication rule that is assigned to the catalog that the asset is created in. This rule can be edited through the Media Management API to include other default restrictions.

Ingest

At ingest, publication rules can be defined on a per asset basis via the Brightcove Once ingestion methods. Note* If the catalog contains default catalog publication rules, defining rules at ingest will be additive to the media item.

Please see the ingest schema for more information on how to include publication rules into your ingest request.

Start date / end date

Playback is only allowed within the start and end dates.

Geo restrictions

Once supports geo-restriction at the country level both by inclusion and exclusion. Countries are specified by ISO 3166-1 country codes.

  • Allow country or countries: when you allow one or more countries, viewing in all other countries is automatically disallowed.
  • Deny country or countries: when you disallow viewing in one or more countries, viewing is automatically allowed in all other countries.
Client restrictions
IpAddress

Playback is allowed or denied based on the IP address of the request.

UserAgent

Playback is allowed or denied based on the value of the useragent from the requesting device.

Referring host

Playback is allowed or denied based on the value of the referring host retrieved from the HTTP header.

Multiple publication rules

Multiple rules can be used if a particular behavior is desired. For example, using two publication rules, you could limit playback to a particular country for a set amount of time before offering the video globally. In practice, creating this implementation would go as follows: Publication rule 1 would allow video playback for a particular specified date range to a particular single country only. Publication rule 2 would start at the end time of rule 1 with a 10 year time limit and no country restriction.

Content Security

AES-128

AES-128 is the Advanced Encryption Standard, which utilizes 128 bit keys for additional protection of HLS content. The Once platform will handle key generation and authorization with the device. When a request for encrypted content is made, authorization information is passed to the requesting device within the HLS manifest as the attribute EXT-X-KEY and must be successfully validated in order for playback to begin.

Configuration of AES within a domain may be done across the entire domain or may be configured to provide multi-mode delivery. Security can be specified on a catalog by and must use an application with the same setting or playback will be denied. Videos ingested into a secure catalog will inherit the assigned security settings whereas videos ingested into an unsecuredcatalog will not. Note* When AES-128 is configured, delivery through progressive download will be restricted.

For example, a domain may contain a catalog for secure content such as feature films, episodic, or other premium types as well as a catalog for unsecured content such as clips or trailers. Additionally, that domain would have ApplicationIds for secure content and unsecured content. Secure or unsecured content would only be accessible via the appropriate secure and unsecured ApplicationIds, respectively. Your Brightcove representative can assist in the configuration of AES-128 for your domain.

There are two modes offered for AES-128.

  • Mode A - Unencrypted ads with encrypted content
  • Mode B - The entire stream will be encoded (content + ads)

Note: Mode A is recommended when delivering both secure and unsecure content to maximize caching efficiency of ad creatives.

Apple FairPlay DRM

FairPlay is an Apple DRM technology that is exclusively used to protect streamed and downloaded content on Apple devices. Apple licenses this technology to enable content owners to deliver content to apps running on Apple TV.

Current limitations:

  • One license server configuration per Once domain
  • FairPlay packaged content will not be playable outside of iOS or AppleTV approved applications
  • The Brightcove License server configuration and storing your content key must be done by Brightcove.

Due to complexities with Fairplay configurations please contact your Brightcove representative to appropriately configure your domain and setup of your application to communicate with the license server. Brightcove requires the following information:

  1. Application Certificate (AC) (Provided by Apple in the Phase 2 SDK)
  2. Application Secret Key (ASK) (Provided by Apple in the Phase 2 SDK)
  3. Private key used to sign the CSR. (Generated by publisher)
  4. Password for the private key (if private key is encrypted) (See 3)

The CSR is not security sensitive, but the private key is. The CSR Private Key is generated by the publisher and would have been passed to Apple during the CSR signing process. Due to the secure nature of the private key, we ask that the Private Key is sent in a secure manner, preferably wrapped and encrypted in some manner.

CDN Token Authentication

As an added layer of security, CDN token based authentication and hashing algorithms are supported for content delivery through Brightcove Once. The authorization tokens to the CDN will be generated by the Once service and requires the hashing and appendage of specific parameters on the Once URL to pass the Once authorization.

Currently Once supports Token Authentication for the following CDNs:

  • Akamai EdgeAuth 1.0/2.0
  • Level 3
  • Amazon Cloudfront

Contact your Brightcove representative for assistance on configurations.

Shared Secrets

The Once token authentication system utilizes two shared secrets that are required; the CDN shared secret and a customer defined shared secret. The customer shared secret is used by Once as a gateway to authentication through the Once API and should not be confused by the CDN shared secret for resource access. By default, the same shared secret is used for both layers of authentication, but if desired can be different on an application basis.

Appending token authentication parameters

This section assumes knowledge of the Once URL Creation, please see creating a Once URL Creation for the URL structure. The following parameters are necessary for utilizing token authentication.

Parameter Required Description
umsstime Yes Start time of authorized content. (UNIX epoch time (seconds))
umsetime Yes, if umsttl is not used End time of authorized content. (UNIX epoch time (seconds))
umsttl Yes, if umsttl is not used Number in seconds after the start time to keep the content authorized.
umshash Yes HMAC-SHA1 hash of URL path and query - using the common shared secret

Akamai EdgeAuth

This section covers the required information for Brightcove Once to handle token authentication through Akamai, but assumes all the configurations between the customer and CDN have been complete.

Customer Requirements:

  • Akamai shared secret
  • Customer common shared secret
  • CDN hostname
  • Hashing requirements for full or partial
  • Full (host/path/resource?key=value)
  • Partial (path/resource?key=value)
  • Failover URL for unauthenticated requests (optional)

Level 3

This section covers the required information for Brightcove Once to handle token authentication through Level 3, but assumes all the configurations between the customer and CDN have been complete.

Customer Requirements:

  • Level 3 shared secret(s) (Up to 10 active keys)
  • Customer common shared secret
  • CDN hostname
  • Hashing requirements for full or partial
  • Full (host/path/resource?key=value)
  • Partial (path/resource?key=value)
  • Failover URL for unauthenticated requests (optional)

Shared Secret Configuration:

It is important that the key and entry associations be the same between the CDN and the Once system. If multiple tokens are available in the same window, the Once system will choose the first available to utilize for the hashing the authentication request.

Entry Secret (up to 64 chars) Not Valid Before Not Valid After
0 sharedsecret0 20071113050000 20081225080000
1 sharedsecret1 20081225080000 20090211120000

Note: The chosen parameters to be passed to the CDN must be set between the customer and the CDN. By default the following are passed:

  • Hash token : token
  • Not valid before token : nvb
  • Not valid after token : nva

Error Events

Error Code

Explanation

Suggested Steps

DownloadAccessDeniedError

Once attempted to download the submitted media file at the specified address, but received a permission error. If the source URL is hosted on S3, read access has likely not been granted for the file or the bucket in which it's contained. The simplest way to grant read permissions is to utilize an S3 client, like Amazon's AWS Console.

In technical speak, Once received a 403 Access Denied response from the hosting server.

Check your source content and retry ingest.

DownloadFailureError

This error occurs when Once is unable to download a file for a reason other than Access Denied or File Not Found. If the server returns a response code, Once will display it in the error message so that you can determine what happened and make any necessary updates to the file.

Check your source content and retry ingest.

DownloadTimeoutError

Once attempted to download the submitted media file, but did not receive a response from the hosting server in a reasonable amount of time..

Check your source content and host and retry ingest.

FileNotFoundError

When attempting to download the submitted file at the specified address, Once was unsuccessful. Most commonly this could indicate that there was a typo in the source url, the file has been removed, a redirect loop was encountered, or another cause preventing successful download.

In the case of HTTP this means that Once received an HTTP response code >= 300 when attempting to download the file. (403 errors will be classified separately as DownloadAccessDenied errors.)

Check your source content and host and retry ingest.

FilePermanentlyMovedError

Once attempted to download a file at the specified address, but the source server returned a 301 code.

Check your source content and retry ingest.

InaccurateDurationError

The output generated for this file has a duration that is significantly longer than the input file's duration. Generally this is the result of invalid/inaccurate metadata or timestamps that cause the encoder to create a long file.

Check your source content and retry ingest.

InvalidDownloadedFileTypeError

Once tried to download a file at the specified address, but instead of a video or audio file, got back something else, like a HTML or XML document.

Check your source content and retry ingest.

NoMediaError

The input file is not an audio or video file. It could be a PDF, an image, an .exe, or something else, but it does not appear to be a video or a sound file.

Check your source content.

QuicktimeReferenceError

The input file references audio or video tracks that aren't actually present in the file. The file is effectively acting as a placeholder that links to outside media tracks.

Check your source content.

S3BucketNotFoundError

No bucket was found on S3 with the specified name. If you are using the s3:// protocol in your URLs, make sure that you only include the bucket name - "s3://my_bucket" - and not the "s3.amazonaws.com" domain.

Check your source content url and retry ingest.

TimedTextValidationError

The timed text file did not pass validation, or is not a supported format. Check the message of the error and compare it against your input.

Check your source content and retry ingest.

TranscodeError

Indicates that transcoding the submitted file was not successful.

Contact Brightcove Support.

TruncatedFileError

The input file is smaller than the headers say it should be. Generally this means the file got cut off at some point previous to being transferred.

Check your source content.

UnexpectedResultError

An unexpected error occurred. Contact Brightcove Support for more information.

Contact Brightcove Support.

UnreadableFileError

Indicates that a media file was unable to be decoded, typically due to the source being corrupt.

Check your source content.

UnsupportedCodecError The source content is using a codec that Once currently does not support. See Supported Video Formats for a list of formats that are not supported. Contact Brightcove Support.
UnsupportedEncodingError This error occurs when the submitted file was encoded in a way that Once does not currently support. Contact Brightcove Support.
UnsupportedEncryptionError This error occurs because the submitted file is encrypted, preventing us from opening it. Contact Brightcove Support.

Ingest Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "title": "root",
  "description": "Ingest API Container",
  "additionalProperties": false,
  "properties": {
    "title": {
      "type": "string",
      "description": "The title of the asset",
      "minLength": 0,
      "maxLength": 255,
      "additionalProperties": false
    },
    "foreignKey": {
      "type": "string",
      "description": "The unique identifier for the asset",
      "minLength": 1,
      "maxLength": 150,
      "additionalProperties": false
    },
    "keywords": {
      "type": "array",
      "description": "An array of strings for the asset",
      "additionalProperties": false,
      "items": [
        {
          "type": "string",
          "description": "A keyword string value for the asset",
          "minLength": 1,
          "maxLength": 1000,
          "additionalProperties": false
        }
      ],
      "required": [
        "0"
      ]
    },
    "description": {
      "type": "string",
      "description": "A description of the asset",
      "minLength": 0,
      "maxLength": 4000,
      "additionalProperties": false
    },
    "metadata": {
      "type": "object",
      "description": "An array of key value pairs for Extended Metadata",
      "additionalProperties": true,
      "properties": {
        "key": {
          "type": "string",
          "description": "The key of an Extended Metadata key value pair",
          "minLength": 0,
          "additionalProperties": false
        }
      }
    },
    "media": {
      "type": "object",
      "description": "Container for the source URL of the asset being ingested",
      "additionalProperties": false,
      "properties": {
        "sourceURL": {
          "type": "string",
          "description": "The URL string to the source asset",
          "minLength": 1,
          "maxLength": 1000,
          "additionalProperties": false
        }
      },
      "required": [
        "sourceURL"
      ]
    },
    "publicationRules": {
      "type": "array",
      "description": "An array of Publication Rules for the asset",
      "minItems": 1,
      "uniqueItems": false,
      "additionalProperties": false,
      "items": {
        "type": "object",
        "description": "Container for Client Filters and Country Rules for the Publication Rules",
        "additionalProperties": false,
        "properties": {
          "channel": {
            "type": "string",
            "description": "The Channel Guid for the Publication Rule",
            "minLength": 36,
            "maxLength": 36,
            "additionalProperties": false
          },
          "startDate": {
            "type": "integer",
            "description": "The start date for the Publication Rule",
            "minimum": 0,
            "maximum": 2147483647,
            "additionalProperties": false
          },
          "endDate": {
            "type": "integer",
            "description": "The end date for the Publication Rule",
            "minimum": 0,
            "maximum": 2147483647,
            "additionalProperties": false
          },
          "clientFilters": {
            "type": "array",
            "description": "And array of Client Filters for the Publication Rule",
            "minItems": 1,
            "uniqueItems": false,
            "additionalProperties": false,
            "items": {
              "type": "object",
              "description": "Container for a Client Filter",
              "additionalProperties": false,
              "properties": {
                "variableName": {
                  "type": "string",
                  "description": "The variable name that the Client Filter will key off of",
                  "additionalProperties": false,
                  "enum": [
                    "IpAddress",
                    "UserAgent",
                    "ReferringHost"
                  ]
                },
                "value": {
                  "type": "string",
                  "description": "The value that the Client Filter will key off of",
                  "minLength": 0,
                  "maxLength": 255,
                  "additionalProperties": false
                },
                "filterType": {
                  "type": "string",
                  "description": "The type of filtering used to compare the value",
                  "additionalProperties": false,
                  "enum": [
                    "Equals",
                    "NotEquals",
                    "In",
                    "NotIn",
                    "Contains",
                    "NotContains",
                    "StartsWith",
                    "NotStartsWith",
                    "EndsWith",
                    "NotEndsWith"
                  ]
                },
                "isDenied": {
                  "type": "boolean",
                  "description": "Denotes whether a successful comparison of the Client Filter is denied or allowed",
                  "additionalProperties": false
                }
              },
              "required": [
                "variableName",
                "value",
                "filterType",
                "isDenied"
              ]
            },
            "required": [
              "0"
            ]
          },
          "countryRules": {
            "type": "array",
            "description": "An array of Country Rules for the asset",
            "minItems": 1,
            "uniqueItems": false,
            "additionalProperties": false,
            "items": {
              "type": "object",
              "description": "Container for the Country Rule",
              "additionalProperties": false,
              "properties": {
                "countryCode": {
                  "type": "string",
                  "description": "The Country Code for the Country Rule",
                  "minLength": 2,
                  "maxLength": 2,
                  "additionalProperties": false,
                  "enum": [
                    "AF",
                    "AL",
                    "DZ",
                    "AS",
                    "AD",
                    "AO",
                    "AI",
                    "AQ",
                    "AG",
                    "AR",
                    "AM",
                    "AW",
                    "AU",
                    "AT",
                    "AZ",
                    "BS",
                    "BH",
                    "BD",
                    "BB",
                    "BY",
                    "BE",
                    "BZ",
                    "BJ",
                    "BM",
                    "BT",
                    "BO",
                    "BA",
                    "BW",
                    "BR",
                    "IO",
                    "VG",
                    "BN",
                    "BG",
                    "BF",
                    "MM",
                    "BI",
                    "KH",
                    "CM",
                    "CA",
                    "CV",
                    "CF",
                    "TD",
                    "CL",
                    "CN",
                    "CX",
                    "CC",
                    "CO",
                    "KM",
                    "CK",
                    "CR",
                    "HR",
                    "CU",
                    "CY",
                    "CZ",
                    "CD",
                    "DK",
                    "DJ",
                    "DM",
                    "DO",
                    "EC",
                    "EG",
                    "SV",
                    "GQ",
                    "ER",
                    "EE",
                    "ET",
                    "FK",
                    "FO",
                    "FJ",
                    "FI",
                    "FR",
                    "PF",
                    "GA",
                    "GM",
                    "GE",
                    "DE",
                    "GH",
                    "GI",
                    "GR",
                    "GL",
                    "GD",
                    "GU",
                    "GT",
                    "GN",
                    "GW",
                    "GY",
                    "HT",
                    "VA",
                    "HN",
                    "HK",
                    "HU",
                    "IS",
                    "IN",
                    "ID",
                    "IR",
                    "IQ",
                    "IE",
                    "IM",
                    "IL",
                    "IT",
                    "CI",
                    "JM",
                    "JP",
                    "JE",
                    "JO",
                    "KZ",
                    "KE",
                    "KI",
                    "KW",
                    "KG",
                    "LA",
                    "LV",
                    "LB",
                    "LS",
                    "LR",
                    "LY",
                    "LI",
                    "LT",
                    "LU",
                    "MO",
                    "MK",
                    "MG",
                    "MW",
                    "MY",
                    "MV",
                    "ML",
                    "MT",
                    "MH",
                    "MR",
                    "MU",
                    "YT",
                    "MX",
                    "FM",
                    "MD",
                    "MC",
                    "MN",
                    "ME",
                    "MS",
                    "MA",
                    "MZ",
                    "NA",
                    "NR",
                    "NP",
                    "NL",
                    "AN",
                    "NC",
                    "NZ",
                    "NI",
                    "NE",
                    "NG",
                    "NU",
                    "KP",
                    "MP",
                    "NO",
                    "OM",
                    "PK",
                    "PW",
                    "PA",
                    "PG",
                    "PY",
                    "PE",
                    "PH",
                    "PN",
                    "PL",
                    "PT",
                    "PR",
                    "QA",
                    "CG",
                    "RO",
                    "RU",
                    "RW",
                    "BL",
                    "SH",
                    "KN",
                    "LC",
                    "MF",
                    "PM",
                    "VC",
                    "WS",
                    "SM",
                    "ST",
                    "SA",
                    "SN",
                    "RS",
                    "SC",
                    "SL",
                    "SG",
                    "SK",
                    "SI",
                    "SB",
                    "SO",
                    "ZA",
                    "KR",
                    "ES",
                    "LK",
                    "SD",
                    "SR",
                    "SJ",
                    "SZ",
                    "SE",
                    "CH",
                    "SY",
                    "TW",
                    "TJ",
                    "TZ",
                    "TH",
                    "TL",
                    "TG",
                    "TK",
                    "TO",
                    "TT",
                    "TN",
                    "TR",
                    "TM",
                    "TC",
                    "TV",
                    "UG",
                    "UA",
                    "AE",
                    "GB",
                    "US",
                    "UY",
                    "VI",
                    "UZ",
                    "VU",
                    "VE",
                    "VN",
                    "WF",
                    "EH",
                    "YE",
                    "ZM",
                    "ZW"
                  ]
                },
                "isDenied": {
                  "type": "boolean",
                  "description": "Denotes whether a successful comparison of the Client Filter is denied or allowed",
                  "additionalProperties": false
                }
              },
              "required": [
                "countryCode",
                "isDenied"
              ]
            },
            "required": [
              "0"
            ]
          }
        },
        "required": [
          "channel",
          "startDate",
          "endDate"
        ]
      },
      "required": [
        "0"
      ]
    },
    "cuePoints": {
      "type": "array",
      "description": "An array of Cue Points for the asset",
      "minItems": 1,
      "uniqueItems": true,
      "additionalProperties": false,
      "items": [
        {
          "type": "object",
          "description": "A key value pair of the time in which the Cue Point and unit type of the value",
          "additionalProperties": false,
          "properties": {
            "valueIn": {
              "type": "integer",
              "description": "The time in which the Cue Point will be inserted",
              "minimum": 0,
              "maximum": 2147483647,
              "additionalProperties": false
            },
            "unit": {
              "type": "string",
              "description": "The type of unit the time value",
              "minLength": 0,
              "additionalProperties": false,
              "enum": [
                "Seconds"
              ]
            }
          },
          "required": [
            "valueIn",
            "unit"
          ]
        }
      ],
      "required": [
        "0"
      ]
    },
    "timedText": {
      "type": "array",
      "description": "An array of Timed Text items for the asset",
      "minItems": 1,
      "uniqueItems": true,
      "additionalProperties": false,
      "items": [
        {
          "type": "object",
          "description": "Container describing a timed text item and its contents",
          "additionalProperties": false,
          "properties": {
            "media": {
              "type": "object",
              "description": "Container for the source URL of the timed text file being ingested",
              "additionalProperties": false,
              "properties": {
                "sourceURL": {
                  "type": "string",
                  "description": "The URL string to the source asset",
                  "minLength": 1,
                  "maxLength": 1000,
                  "additionalProperties": false
                }
              },
              "required": [
                "sourceURL"
              ]
            },
            "timedTextType": {
              "type": "string",
              "description": "The type to categorize the timed text item",
              "additionalProperties": false,
              "enum": [
                "Subtitle",
                "Caption"
              ]
            },
            "languages": {
              "type": "array",
              "description": "An array of languages contained in the timed text asset",
              "additionalProperties": false,
              "items": [
                {
                  "type": "string",
                  "description": "A ISO-639 language code to be found in the asset",
                  "minLength": 2,
                  "maxLength": 255,
                  "additionalProperties": false
                }
              ],
              "required": [
                "1"
              ]
            },
            "alternateId": {
              "type": "string",
              "description": "The optional id to associate with the timed text item, used as a descriptor or to create uniqueness",
              "minLength": 1,
              "maxLength": 255,
              "additionalProperties": false
            }
          },
          "required": [
            "media",
            "timedTextType",
            "languages"
          ]
        }
      ],
      "required": [
        "0"
      ]
    }
  },
  "required": [
    "foreignKey",
    "media"
  ]
}