Getting Started with Once

Product(s)
SSAI
Role(s)
API Developer
Task(s)
Add Videos/Assets
Manage Videos
Publish Videos
Topic(s)
Advertising

This guide provides the information you need to implement Once VOD.

Prerequisites

This document assumes prior general knowledge of API architecture and XML language.

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(GUID)
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.

API Ingest

Description

Brightcove’s Once Ingest service receives and transcodes your video, making it ready for the Once VOD delivery system. Two ingest methods are supported:

As a best practices recommendation, source video should be uploaded as an mp4, utilizing H.264 encoding, with a video bitrate between 5-10 Mbps. Audio tracks should use AAC audio with a sample rate of 44.1kHz and a minimum bitrate of 40kbps. Additional recommendations are a framesize of 1920x1080 pixels, a framerate of 30 fps, and keyframes at least every 6 seconds.

Profiles and Renditions

The following table shows the standard renditions created for videos.

Once VOD profiles for your channel
Profile Guid Name Width Height Video Bitrate (kbps) Audio Bitrate (kbps) Keyframe Interval Audio Sample Rate Audio Channels
1bc47d0d-fd08-4b85-b26c-4829a98a24e8 Once 4500 1080p 1920 1080 4500 40 1 44.1 2
ec44b899-8a22-4912-8e4f-12f4638a7d2a Once 3200 720p 1280 720 3200 40 1 44.1 2
e9c723f9-c1c0-49cc-8c7a-b686f49b76d8 Once 2500 720p 1280 720 2500 40 1 44.1 2
b2f1ecaa-1190-4b1e-b0a7-859c39986bfb Once 1800 864 480 1800 40 1 44.1 2
3a41c6e4-93a3-4108-8995-64ffca7b9106 Once 1200 864 480 1200 40 1 44.1 2
8c913e59-c00a-4d37-925b-27b6ed698fcc Once 800 400 224 800 40 1 44.1 2
f8de0ae7-aab1-4005-bf4a-71346bd47921 Once 600 400 224 600 40 1 44.1 2
a07db314-1579-44ce-93cd-ee9c63cfc294 Once 512 400 224 512 40 1 44.1 2
681f29c5-81eb-4229-9801-ebe21531a57c Once 400 400 224 400 40 1 44.1 2
7d9ebac9-8315-4aba-b422-832ebf12f21d Once 320 400 224 300 40 1 44.1 2
c93d8088-8546-408f-bfd0-84985747fc72 Once 3GP 320 480 272 250 48 1 22 2
1500a936-6f3b-4a5d-bdee-c16d51b73896 Once 200 400 224 200 40 1 44.1 2
25245ee1-3061-4b5e-b86f-d297249a1704 Once 110 400 224 110 40 1 44.1 2
bea6d4b0-0dbe-4f60-94bc-2e3cd2ca381d Once H263 384kbps 352 288 384 12 1 8 1
89f1217b-fe2f-4b5e-8076-a134bba9442f Once h263 Baseline 176 144 128 12 1 8 1
27e71340-af9c-468d-96c3-ebac95dd884d Once Audio 40 0 0 0 40 1 44.1 2

API ingest

Brightcove’s Once API Ingest service is a RESTful API that accepts a POST with a DownloadURL for your video. When the video has been successfully generated, the core profiles required for delivery on the Once VOD platform are generated, and a notification is sent to the URL you specify in the POST. Videos linked to for DownloadURLs must be progressive formats and publicly addressable URLs. Ingesting files via S3 is also supported by the API Ingest system as a source location. If your files are publicly available, no further action is necessary. If your files require authentication, please see the S3 bucket permission section for authorizing the Once platform to access protected URLs.

Service URL

The URL for the POST request is:

http://apiingest.unicornmedia.com/api/ingest

Simple XML

     Required node

<APIIngestRequest>
    <UserName>{username}</UserName>
    <Password>{password}</Password>
    <DomainName>{domain name}</DomainName>
    <AVItem>
        <CatalogGUID>{catalog GUID}</CatalogGUID>
        <ForeignKey>{unique foreign key}</ForeignKey>
        <IngestInfo>
            <DownloadURL>{URL where video resides}</DownloadURL>
        </IngestInfo>
        <Title>{video title}</Title>
    </AVItem>
    <NotificationURL>{URL notification will be sent to}</NotificationURL>
    <NotificationRequestMethod>GET | POST | PUT</NotificationRequestMethod>
</APIIngestRequest>

Full XML

     Required node

<APIIngestRequest>
    <UserName>{username}</UserName>
    <Password>{password}</Password>
    <DomainName>{domain name}[1]</DomainName>
    <AVItem>
        <CatalogGUID>{catalog GUID}[1]</CatalogGUID>
        <ForeignKey>{unique foreign key}</ForeignKey>
        <IngestInfo>
            <DownloadURL>{URL where video resides}</DownloadURL>
        </IngestInfo>
        <Title>{video title}</Title>
        <ExtendedMetadata>
            <key1>{key1 value}</key1>
            <key2>{key2 value}</key2>
        </ExtendedMetadata>
        <Captions>[2]<Caption>
                <ForeignKey>{unique foreign key}</ForeignKey>
                <IngestInfo>
                        <DownloadURL>{URL where captions file resides}</DownloadURL>
                    </IngestInfo>
                <Language>{ISO 639-1 language code}</Language>
            </Caption>
        </Captions>
        <PublicationRules>[2]
            <PublicationRule>
                <ChannelGUID>{channel GUID}[1]</ChannelGUID>
                    <StartDate>{epoch time in seconds}</StartDate>
                    <EndDate>{epoch time in seconds}</EndDate>
                <ClientFilters>
                    <ClientFilter>
                        <VariableName>{IPAddress|UserAgent|ReferringHost}</VariableName>
                        <Value>required</Value>
                        <FilterType>{EQUALS|NOT_EQUALS|IN|NOT_IN|CONTAINS|NOT_CONTAINS|STARTSWITH|NOT_STARTSWITH|ENDSWITH|NOT_ENDSWITH}</FilterType>
                           <IsDenied>{true|false}</IsDenied>
                    </ClientFilter>
                </ClientFilters>
                <Countries>
                    <Country>
                        <CountryCode>{ISO 3166-1 country code}</CountryCode>
                        <IsDenied>true|false</IsDenied>
                    </Country>
                </Countries>
            </PublicationRule>
        </PublicationRules>
        <CuePoints>[2]<CuePoint>
                    <CuePointType>CuePoint</CuePointType>
                    <SecondsIn>{time in whole seconds}</SecondsIn>
                </CuePoint>
        </CuePoints>
    </AVItem>
    <NotificationURL>{URL notification will be sent to}</NotificationURL>
    <NotificationRequestMethod>GET | POST | PUT</NotificationRequestMethod>
</APIIngestRequest>
Notes

[1] DomainName, CatalogGUID and ChannelGUID values can be obtained from your Brightcove representative.

[2] The required nodes in captions, publication rules, and cue points are only required if those specific options are being utilized in the request. All caption sub-fields are necessary for each caption in the array.

Field explanation

APIIngestRequest node details

A description of each node available in APIIngestRequest
Node Required Description

UserName

Yes

The email address associated with the Upload User, used to authorize the incoming request.

Password

Yes

The password used in association with the email to determine if the Upload User is authorized the incoming request.

DomainName

Yes

The name of the Domain that the Upload User should have access to. Used for authentication.

AVItem

Yes

The Video ingest item this post pertains to.

NotificationURL

No

A URL to receive an item notification callback your newly ingested or versioned items.

NotificationRequestMethod

No

The HTTP method to assign to your item notification callback. Default is GET - POST and PUT are also allowed.

AVItem node details

A description of each node available in AVItem
Node Required Description

CatalogGUID

Yes

The Catalog GUID the video is in or will be ingested into.

ForeignKey

Yes

The Foreign Key assigned to the video.

IngestInfo

Yes

The dictionary containing information relevant to how this video will be ingested or versioned.

Title

No

The Title assigned to the video. The Foreign Key will be used if no title is provided.

ExtendedMetadata

No

A Dictionary that will be stored as the Extended Metadata associated with this video. Extended Metadata is additive on updates.

Captions

No

List of Captions to be associated with the video.

PublicationRules

No

List of Publication Rules to be associated with the video.

CuePoints

No

List of Cue Points to be associated with the video.

IngestInfo node details

A description of each node available in IngestInfo
Node Description

DownloadURL

A URL to download the video from.

Caption node details

A description of each node available in Caption
Node Required Description

ForeignKey

Yes

The Foreign Key assigned to the Caption Item.

IngestInfo

Yes

Contains the required child node DownloadURL, which provides the download URL for the captions file

Language Yes ISO 639-1 language code

PublicationRule node details

A description of each node available in PublicationRule
Node Required Description

ChannelGUID

Yes

The Channel GUID assigned to this Publication Rule. Must be a valid Channel in the Domain that was used in authentication.

StartDate

Yes

The Start Date assigned to the Publication Rule. In epoch time or a DateTime parse-able string. Must not be greater than the End Date. DateTime strings may be UTC or ISO 8601.

EndDate

Yes

The End Date assigned to the Publication Rule. In epoch time or a DateTime parse-able string. Must not be less than the Start Date. DateTime strings may be UTC or ISO 8601.

ClientFilters

No

The Client Filters associated with the Publication Rule.

Countries

No

The Countries associated with the Publication Rule.

ClientFilter node details

A description of each node available in ClientFilter
Node Required Description

VariableName

Yes

The Variable Name assigned to this Client Filter.

Value

Yes

The Value associated with the Variable Name.

FilterType

Yes

The Filter of how the Value is associated with the Variable Name.

IsDenied

Yes

The outcome for when the Client Filter's properties are matched (true | false).

Country node details

A description of each node available in Country
Node Required Description

CountryCode

Yes

The ISO 3166-1 2 character country code.

IsDenied

Yes

The outcome for when the Country properties are matched. (true | false)

CuePoint node details

A description of each node available in CuePoint
Node Required Description

CuePointType

Yes

The type of Cue Point to be created. The only accepted value is CuePoint.

SecondsIn

Yes

The number of whole seconds into the video this Cue Point will fire. Must be non-negative. For multiple Cue Points, each should designate the time from the beginning of the video that the break should be.

API Notifications

Item notification

By default, API Ingest will supply item notifications via the appropriate fields in the ingest XML to the specified location of your choosing. Examples of the URL callback are below. As an alternate method of utilizing Item Notifications through the API Ingest request, a single callback URL can be preconfigured in the Once system to be used instead. Contact your Brightcove representative if you would like this preconfiguration.

Item Notification Required Properties
Property Description

DomainGUID

The unique identifier for the domain

CatalogGUID

The unique identifier for the catalog (optional)

NotificationURL

The default notification URL to use

Request Method

Your preferred HTTP request verb (GET | POST | PUT)

URL Notification Template:

[notificationURL]?Unicorn+Media&Catalog=[CatalogName]&Filename=[MediaItemTitle]&MediaItemGUID=[MediaItemGUID]&MediaItemForeignKey=[MediaItemForeignKey]&Duration=[Duration]&StartTime=[StartTime]

URL Notification Example:

http://tempuri.org/notify?Provider=Unicorn+Media&Catalog=Catalog+Name&FilenameMedia+Item+Title&MediaItemGUID=a43680-29fc-468c-75b&MediaItemForeignKey=876dc-4676-8426ecf6&Duration=30&StartTime=8%2F22%2F2012+1%3A08%3A59+PM

Field explanation

Item Notification URL Elements
Property Description

NotificationURL

The host name the notification will be sent to.

Catalog

The name assigned to the Catalog where the content was ingested.

Filename

The title assigned to the Media Item file

MediaItemGUID

The unique identifier for the Media Item

MediaItemForeignKey

The unique identifier for the Media Item Foreign Key

Duration

The length in seconds of the binary asset

StartTime

Time in GMT at which the asset began transcoding

SNS Ingest

SNS Content Ingest is the service that allows for the automated ingest of assets and metadata from an Amazon SNS Topic into the Once platform. The SNS Ingest API waits for SNS Messages from all topics that it is subscribed to. Content is passed to the API by posting a Notification message to a topic that SNS Ingest API is subscribed to.

For the Once SNS Ingest API to receive messages published to your topic, you should first send a Create Subscription Message to the API's receiving endpoint from the AWS Management Console. The API’s HTTP receiving endpoint is the following:

http://snsingest.unicornmedia.com/api/sns

The SNS Ingest API will automatically accept the subscription confirmation, and it is now ready to ingest content sent via a Notification SNS message.

The SNS Ingest API is capable of ingesting content via HTTP links and Amazon S3 Buckets. To allow the Ingest API permission to receive messages from your Amazon S3 bucket(s), you will need the Once IAM ARN:  "arn:aws:iam::453163911362:root". This permission policy is configured within your AWS account under Permissions for the S3 Bucket. Note that if your S3 content is set to be publicly available, configuring this permission policy is not necessary. If you are not using Amazon S3 Buckets to send your content, the following section can be ignored.

S3 Bucket Permissions
S3 Bucket Permissions

Sample message to allow permissions to an S3 bucket

{
  "Id": "Policy1422291903900",
  "Statement": [
    {
      "Sid": "Stmt1422291901200",
      "Action": [
        "s3:GetObject"
      ],
      "Effect": "Allow",
      "Resource": "arn:aws:s3:::msd-arn/2199827728999/*",
      "Principal": {
        "AWS": [
          "arn:aws:iam::453163911362:root"
        ]
      }
    }
  ]
}
Bucket Policy Editor
Bucket Policy Editor

Once a topic is established and the Once AWS has been subscribed to it, any Notification message published to the topic will be ingested to the Once system for transcoding and processing. Messages may be manually published through the AWS Management Console, or by using the Amazon Web Services SDK. The content and its metadata should be published to your topic via a JSON string following the format below. The SNS Ingest API will then pick it up and processing of the content will begin.

Ingest Example

{
    "___version" : "1.0",
    "jobId" : "{GUID}",
    "passThruMetadata" : "{CLOB}",
    "file" : "{URL for video file}",
    "title" : "{assetTitle}",
    "assetId" : "{assetId}",
    "catalogId" : "{catalogId}",
    "publicationDate" : "{publication date in UTC format}",
    "version" : "6",
     "cuePoints" : [
        {
            "type":"CuePoint",
            "secondsIn":{value in whole seconds}
        },
        {
            "type":"CuePoint",
            "secondsIn":{value in whole seconds}
        },
        ...
    ],
    "extendedMetadata" : {
        "{Key1}" : "{Value1}",
        "{Key2}" : "{Value2}",
        ... (additional key/value pairs)
    },
  "publicationRules" : [
    {
        "channelID":"{CHANNEL-GUID}",
        "startDate":"{epoch time in seconds}",
        "endDate":"{epoch time in seconds}",
        "countries": [
         {
            "countryCode" : "{ISO 3166-1 country code}",
            "isDenied" : {true|false}
         },
         ... additional countries
        ],
        "clientFilters": [
         {
            "variableName":"{IPAddress|UserAgent|ReferringHost}",
            "value":"{VALUE}",
            "filterType":"{EQUALS|NOT_EQUALS|IN|NOT_IN|CONTAINS|NOT_CONTAINS|STARTSWITH|NOT_STARTSWITH|ENDSWITH|NOT_ENDSWITH}",
            "isDenied" : {true|false}
         },
         ... additional client filters
        ]
    },
  ],
  "captions": [
    {
        "file" : "URL for captions file",
        "assetId" : "assetId",
        "publicationDate" : "publication date in UTC format",
        "language" : "{ISO 639-1 language code}",
        "captionAssociationType" : "Default"
    },
    ... additional caption files
  ]
}

Explanation of fields in the SNS request body

Name Required? Description

assetId

Yes

Unique foreign key for the media item

captions

No

Array of captions. All caption sub-fields are necessary for each caption in the array.

catalogId

Yes

Catalog that should be used for ingest

cuePoints

No

For multiple Cue Points, each should designate the time from the beginning of the video that the break should be. SecondsIn value must be a non-negative whole second number. For multiple Cue Points, each should designate the time from the beginning of the video that the break should be.

extendedMetadata

No

A JSON object of Key Value pairs.

file

No

S3 link for the source file. Only required for new assets.

jobId

Yes

Customer identifier for the transcode job.

passThruMetadata

No

If present, should be passed as extended metadata to allow for it to be included in the item notification

publicationDate

Yes

Time this item was modified

version

Yes

Indicates version of asset being ingested. Increment by one (1) from the existing version if uploading a new version of the video asset. Note: This is separate from the ___version field.

publicationRules

No

Array of publication rules. Only channelID, startDate, endDate are necessary. If the clientFilters or countries arrays are present, they will also be added to the publication rule.

SNS notification

SNS notification is similar to Item Notification in function. Once can pass SNS notifications back to your topic, informing you of published items or any errors that may have occurred. These notifications can be for profile complete notification or error notification. The SNS Topic for either notification must be a topic that the Once AWS account has permission to publish to. To enable the SNS Ingest API to publish notifications 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 the AWS Management Console.

AWS Bucket Policy
AWS Bucket Policy

 

Example:

{
  "___version" : "1.0",
  "jobId" : "{GUID}",
  "onceUrl" : " http://once.unicornmedia.com/now/od/auto/88f98026-95a7-4fe9-992a-94b6a1580483/819add68-2b34-442e-86a5-82204835b4ec/48ddf3dd-3849-4b50-8086-b9391afb6e90/content.once”,
  "passThruMetadata" : "{JSON string sent in with ingest}",
  "status": "Completed"
}

Example of an error notification

{
  "___version" : "1.0",
  "errorCode" : "500",
  "errorMessage" : "There was an error in the Media System",
  "jobId" : "{GUID}",
  "passThruMetadata" : "clob",
  "status" : "Error"
}

Field explanation

Property Description
jobid Customer identifier for the transcode job.
onceurl URL that can be used for playback utilizing a predetermined ApplicationGUID
passthrumetadata Any metadata set for passthrough sent on the initial ingest request
status Completed or Error
errorCode Error code if the ingest did not succeed
errorMessage Brief data around why a particular asset failed

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.

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.

Base URL Map:

Host/Service/DeliveryType/RequestedFileType/DomainGUID/ApplicationGUID/MediaItemGUID/VirtualFileName

Example

http://once.unicornmedia.com/now/od/auto/28c23297-a1ab-4eb5-a697-7d6942db4efb/d202862f-bb88-41c0-921e-27baf5ade003/cb4ca200-f10d-451e-9487-410052062a5d/content.once

URL Variables

URL Variables

Parameter

Type

Description

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.

DomainGUID

String

The GUID of the Customer Domain in the Brightcove system obtained by contacting your Brightcove representative.

ApplicationGUID

String

The GUID for the application in which to record metrics and enforce business rules obtained through your Brightcove representative.

MediaItemGUID

or

ForeignKey

String

The MediaItemGUID 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 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/RequestedFileType/DomainGUID/ApplicationGUID/MediaItemGUID/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 and keep 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
adaptive m3u8 m3u8
URL map

Host/Service/DeliveryType/RequestedFileType/DomainGUID/ApplicationGUID/MediaItemGUID/VirtualFileName.Extension

Example

http://.../adaptive/m3u8/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 ProfileGUID of the requested quality must be included in the URL for successful playback. The placement of the ProfileGUID in the Once URL is immediately following the ApplicationGUID, as shown in the example below.

DeliveryType FileType Extension
stitched mp4 mp4
URL map

Host/Service/DeliveryType/RequestedFileType/DomainGUID/ApplicationGUID/ProfileGUID/MediaItemGUID/VirtualFileName.Extension

Example

http://.../stitched/mp4/4989f8db-9187-49ca-86ff-e2cd5342cd4/35217a08- d9db-469f-aec0-7c88406a0c60/3a41c6e4-93a3-4108-8995-64ffca7b9106/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 MediaItemGUIDs 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 MediaItemGUID

63598604-cb88-44f8-bc47-d207af3b7b4a

Example Url using MediaItemGUID

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

Segmenting

Segmenting single video items is a feature that allows for the playback of a specified subset portion of a video at run time. In order to achieve this, the Once URL must have a start time and end time defined. The parameters, StartTime and EndTime, are represented by positive integer values in seconds, i.e. "30" for 30 seconds. StartTime must always precede EndTime. The clip will start playing and end playback at the points in the MediaItem indicated by these parameters.

To add time segments to a Once URL, StartTime and EndTime must be supplied immediately after the (MediaItemGUID or ForeignKey if used).

URL Map:

/.../MediaItemGUID/StartTime/EndTime/VirtualFileName?

Example:

http://...63598604-cb88-44f8-bc47-d207af3b7b4a/15/30/content.m3u8?

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 beacon 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 MediaItemGUID in the URL path and a static MediaItemGUID of 00000000-0000-0000-0000-000000000000 should be used.

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

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.

Temporarily Override the Standard Profile List (umoprofiles)

When the UMOPROFILES={profileGUID} query string is appended to a Once URL, the associated profile(s) will be dynamically inserted in the returned m3u8 to temporarily override the standard profile list for adaptive playback of an asset. The value can be a single profileGUID or can contain a list of multiple comma-separated profileGUIDs. All responses containing overridden profiles will continue to utilize the Once platform's device detection logic to determine the order of profiles and segment size that is most suitable for the requesting device.

URL Map:

/.../MediaItemGUID/VirtualFileName?umoprofiles=PROFILEGUID1,PROFILEGUID2,...,PROFILEGUIDX

Example:

http://once.unicornmedia.com/.../content.m3u8?umoprofiles=c2364425-2267-4eaa-b800-ef544bdd3da3,27e71340-af9c-468d-96c3-ebac95dd884d

Temporarily Add Profiles to the Standard Profile List (umaprofiles)

When the query string is appended with umaprofiles={profileGUID}, the specified profile(s) will be temporarily added to the standard profile list for adaptive playback of an asset.

URL Map:

/.../MediaItemGUID/VirtualFileName?umaprofiles=PROFILEGUID1,PROFILEGUID2,...,PROFILEGUIDX

Example:

http://once.unicornmedia.com/.../content.m3u8?umaprofiles=c2364425-2267-4eaa-b800-ef544bdd3da3,27e71340-af9c-468d-96c3-ebac95dd884d

forcemute

Set forcemute=true to remove all audio streams from the video being returned.

timedtextextension

Use timedtextextension={extension} to modify the output caption type for timedtext adaptive/M3U8 and Once UX responses. Once provides the sidecar in manifest for players/apps/environments that may not be able to use the Apple method of webvtt by default. Additionally, utilizing this sidecar in manifest allows for different caption types to be returned. If captions are enabled for a device rule and present on an item Once will generate the in-manifest webVTT.

The available extensions are:

  • srt
  • vtt (WebVTT)
  • xml (DFXP using .xml extension)
  • dfxp

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 in the runtime database and include that data as part of the tracking or targeting parameters expected by the Beaconing Server or Ad Server, respectively. See Server Side Beaconing and UMADPARAM for URL examples.

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

mediaitem.title

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • String value of mediaitem.title

mediaitem.tremor.title

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • 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

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • String value of mediaitemguid

mediaitem.foreignkey

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • String value of mediaitemforeignkey

mediaitem.duration

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • Content file duration in seconds based on the total length of content

mediaitem.adposition

image2013-7-18 13-4-36.png

 

 

  • Integer value for the ad position, e.g., 1, 2, 3 for pre, mid, post

mediaitem.adpositiontime

image2013-7-18 13-4-36.png

 

 

  • Time in seconds where ad is being played

randomnumber32

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

mediaitem.segmentcount

image2013-7-18 13-4-36.png

 

 

  • calculates the aggregate of segment beacons within a stream starting with base 1 and increase incrementally

integer

 

image2013-7-18 13-4-36.png

 

  • A unique random number

timestamputc

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • A 32 bit representation of the servers current time in epoch time (UTC)

useragent

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • String of the useragent of the client

ipaddress

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • User’s IP address

referringHost

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • String of the referring host

referringURL

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • URL Encoded representation of HTTP Header Referrer

countrycode

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • String of the ISO country code for this user

postalcode

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • String of the user’s postal code (if available)

xm."key"

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • extended metadata. The "key" can be whatever value name you used when ingesting extendedmetadata for an asset.

visitguid

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • Brightcove visit GUID. For use as stream view uniqueness id.
 

latitude

image2013-7-18 13-4-36.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

  • To accommodate ad providers that require lat/long to be sent with ad tag request

longitude

image2013-7-18 13-4-36.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

  • To accommodate ad providers that require lat/long to be sent with ad tag request

beacon.quartile.text

images/metadata.image2013-7-18-13-5-31.png-5-31.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • The quartile text, e.g. Start, FirstQuartile, Midpoint, ThirdQuartile, Complete.

beacon.quartile.value

images/metadata.image2013-7-18-13-5-31.png-5-31.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • The raw value of the quartile in seconds.

beacon.interval.value

images/metadata.image2013-7-18-13-5-31.png-5-31.png

image2013-7-18 13-4-36.png

image2013-7-18 13-4-36.png

  • The interval in whole seconds when the beacon is being fired.

xfp.correlator

image2013-7-18 13-4-36.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

  • (For DFP) Random number correlator specific to DFP. Unique per page view.

xfp.pod

image2013-7-18 13-4-36.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

  • (For DFP) Represents a pod within a video. Pass &pod=1 for first pod, &pod=2 for second pod, and so on.

xfp.ppos

image2013-7-18 13-4-36.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

  • (For DFP) Position within a pod. Pass &ppos=1 for the first position, &ppos=2 for the second position, and so on.

xfp.vpos

image2013-7-18 13-4-36.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

  • (For DFP) Whether ad request is being sent for pre-roll,mid-roll or post-roll.

xfp.scor

image2013-7-18 13-4-36.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

  • (For DFP) Integer generated for each video stream that reflects unique streams.

xfp.ipaddress

image2013-7-18 13-4-36.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

  • (For DFP) To carry the IP value into each standard and optimized pod call.

xfp.ss_req

image2013-7-18 13-4-36.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

images/metadata.image2013-7-18-13-5-31.png-5-31.png

  • (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 ApplicationGUID 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. Contact your Brightcove representative and provide your ad tag for integration.

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 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 ApplicationGUID 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.

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, MMI assets, 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 or MMI Segment MMI Playlist Ad
Play Yes Yes No
segmentPlay No Yes No
Start Yes Yes Yes
First Quartile Yes Yes Yes
Midpoint Yes Yes Yes
Third Quartile Yes Yes Yes
Complete Yes Yes Yes
segmentEnd No Yes No
Quartiles Yes Yes Yes
Interval Yes Yes No

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.

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

Captions

Input

Below are input types supported by Once:

  • Embedded
    • 608/708
  • Sidecar
    • DFXP
    • WebVTT
    • SRT
    • SMPTE-TT

Output

Below are the output types supported by Once:

  • Included/Embedded
    • HLS+WebVTT (in manifest)
    • 608/708 Embedded in TS chunks
    • 608/708 Embedded in progressive download
  • Sidecar
    • WebVTT
    • DXFP
    • SRT
    • SMPTE-TT

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 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 to utilize any of the limits included in the Type of Limits section to automatically be applied. By default this publication rule is a rolling 10 year window with no other restrictions.

API Ingest

If you have a need to more granularly adjust publication rules on a per asset basis rather than utilizing the standard inheritance of publication rules, you can specify this rule via the Brightcove Once API at time of ingest.

These types of publication rules will overwrite the inherited rule that an asset would receive by default.

Please see the extended Ingest XML example 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.
Referring host

Playback is allowed only if the referring host matches the specified value.

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.

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 catalog and ApplicationGUID by ApplicationGUID basis. Videos ingested into a secure catalog will inherit the assigned security settings whereas videos ingested into an unsecured catalog will not.

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 ApplicationGUIDs for secure content and unsecured content. Secure or unsecured content would only be accessible via the appropriate secure and unsecured ApplicationGUIDs, respectively.

Your Brightcove representative can assist in the configuration of AES-128 for your domain.