On This Page

Once 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:

Full Ad tag of the desired ad adserver

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)

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.

These are recommended selections based on platform and lower or higher quality renditions can be selected to reflect business requirements for start time or stream quality.

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:

A notification endpoint - SNS topic or a direct API endpoint

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.

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.

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.

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.

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.

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.

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.

Example

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 .

Example

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 .

Example

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.

Example

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 Foreign Key

Example URL using Foreign Key

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:

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.

URL Sent by Brightcove to ad provider:

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.

URL Sent by Brightcove Once to ad provider:

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:

Customer Created URL:

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

Example:

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:

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.

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.

Example:

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.

(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:

HTTP endpoint

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:

Application Certificate (AC) (Provided by Apple in the Phase 2 SDK)

Application Secret Key (ASK) (Provided by Apple in the Phase 2 SDK)

Private key used to sign the CSR. (Generated by publisher)

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.

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.