Media API Objects Reference

Product
Video Cloud
Applies to Roles
Developer
Version
Brightcove 5
Modules
Media API
Edition
Express 499, Pro, Enterprise
Created by Robert Crooks.

This topic provides a reference to the Video, Playlist, Image, Rendition, CuePoint, and LogoOverlay objects returned by the Media API's read methods:

Note that these Media API objects are similar to, but not identical with the objects used in the Flash-only Player API. The Media API Reference also includes reference information for these related objects:

Video object

The Video object is an aggregate of metadata and asset information associated with a video. A Video has the following properties:

Property name Type Read only? Description
name String no The title of the Video, limited to 255 characters. The name is a required property when you create a video.
id long yes A number that uniquely identifies this Video, assigned by Video Cloud when the Video is created.
referenceId String no A user-specified id that uniquely identifies the Video, limited to 150 characters. A referenceId can be used as a foreign-key to identify this video in another system. Note that that the find_videos_by_reference_ids method cannot handle a referenceId that contain commas, so you may want to avoid using commas in referenceId values.
accountId long yes A number, assigned by Video Cloud, that uniquely identifies the account to which the Video belongs.
shortDescription String no A short description describing the Video, limited to 250 characters. The shortDescription is a required property when you create a video.
longDescription String no A longer description of this Video, limited to 5000 characters.
FLVURL String yes The URL of the video file for this Video. Note that this property can be accessed with the Media API only with a special read or write token. This property applies, no matter whether the video's encoding is FLV (VP6) or MP4 (H.264). See Accessing Video Content with the Media API. Note: URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically.
renditions Array no An array of Renditions that represent the multi-bitrate streaming renditions available for this Video. A Video should have not more than 10 Renditions. Note that this property can be accessed with the Media API only with a special read or write token. See Accessing Video Content with the Media API.
videoFullLength Rendition no A single Rendition that represents the the video file for the Video. Note that this property can be accessed with the Media API only with a special read or write token. See Accessing Video Content with the Media API.
creationDate Date yes The date this Video was created, represented as the number of milliseconds since the UNIX epoch.
publishedDate Date yes The date this Video was last made active, represented as the number of milliseconds since the UNIX epoch.
lastModifiedDate Date yes The date this Video was last modified, represented as the number of milliseconds since the UNIX epoch.
itemState Enum no An ItemStateEnum. One of the properties: ACTIVE, INACTIVE, or DELETED. You can set this property only to ACTIVE or INACTIVE; you cannot delete a video by setting its itemState to DELETED.
startDate Date no The first date this Video is available to be played, represented as the number of milliseconds since the UNIX epoch.
endDate Date no The last date this Video is available to be played, represented as the number of milliseconds since the UNIX epoch.
linkURL String no An optional URL to a related item, limited to 255 characters.
linkText String no The text displayed for the linkURL, limited to 255 characters.
tags List no A list of Strings representing the tags assigned to this Video. Each tag can be not more than 128 characters, and a video can have no more than 1200 tags.
videoStillURL String yes The URL to the video still image associated with this Video. Video stills are 480x360 pixels. Note: URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically.
thumbnailURL String yes The URL to the thumbnail image associated with this Video. Thumbnails are 120x90 pixels. Note: URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically.
length long yes The length of this video in milliseconds.
customFields Object no A map of names and values for custom fields set up for videos in your account. More information and examples.
economics Enum no An EconomicsEnum. Either FREE or AD_SUPPORTED. AD_SUPPORTED means that ad requests are enabled for the Video.
adKeys String no A string representing the ad key/value pairs assigned to the video. Key/value pairs are formatted as key=value and are separated by ampersands (&). For example:
"adKeys":"category=sports&live=true"
geoRestricted boolean no True indicates that the video is geo-restricted.
geoFilteredCountries List no A list of the ISO-3166 two-letter codes of the countries to enforce geo-restriction rules on. Use lowercase for the country codes.
geoFilterExclude boolean no If true, the video can be viewed in all countries except those listed in geoFilteredCountries; if false, the video can be viewed only in the countries listed in geoFilteredCountries.
cuePoints List no A list of the CuePoints objects assigned to this Video.
playsTotal Integer yes How many times the Video has been played since its creation.
playsTrailingWeek Integer yes How many times the Video has been played within the past seven days, exclusive of today.

Playlist object

The Playlist object is a collection of Videos. A Playlist has the following properties:

Property name Type Read only? Description
id long yes A number that uniquely identifies the Playlist. This id is automatically assigned when the Playlist is created.
referenceId String no A user-specified id, limited to 150 characters, that uniquely identifies this Playlist. Note that the find_playlists_by_reference_ids method cannot handle referenceIds that contain commas, so you may want to avoid using commas in referenceId values.
accountId long yes A number that uniquely identifies the account to which this Playlist belongs, assigned by Video Cloud.
name String no The title of this Playlist, limited to 100 characters. The name is a required property when you create a playlist.
shortDescription String no A short description describing the Playlist, limited to 250 characters.
videoIds List no A list of the ids of the Videos that are encapsulated in the Playlist.
videos List no A list of the Video objects that are encapsulated in the Playlist.
playlistType Enum no

For a manual playlist, set this to EXPLICIT. For a smart playlist, indicate how to order the playlist by setting this to one of the following choices: OLDEST_TO_NEWEST (by activated date)
NEWEST_TO_OLDEST (by activated date)
START_DATE_OLDEST_TO_NEWEST
START_DATE_NEWEST_TO_OLDEST ALPHABETICAL (by video name)
PLAYS_TOTAL
PLAYS_TRAILING_WEEK

The playlistType is a required property when you create a playlist.
filterTags List no A list of the tags that apply to this smart playlist. For example:

"filterTags":["Sitka","ticks"]
tagInclusionRule Enum no For a smart playlist, defines whether the video must contain all or contain one or more of the values in filterTags. Use AND for "contains all" and OR for "contains one or more." Not available in Read API methods.
thumbnailURL String yes The URL of the thumbnail associated with this Playlist. Note: URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically.

Image object

This object represents metadata about an image file in your account. Images are associated with videos as thumbnail images, video still images, or logo overlays. An image can be a JPEG, GIF, or PNG-formatted image. Note that when creating a new image asset, the only property that is required is type. If you are not uploading a file, the remoteUrl property is also required. For more information, see Adding Images to Videos with the Media API and Adding Logo Overlays to Videos with the Media API.

Property name Type Read only? Description
id Long yes A number that uniquely identifies the Image. This id is automatically assigned by Video Cloud when the Image is created.
referenceId String no A user-specified id that uniquely identifies this Image.
type ImageTypeEnum no THUMBNAIL, VIDEO_STILL, or LOGO_OVERLAY. The type is writable and required when you create an Image; it cannot subsequently be changed.
remoteUrl String no The URL of a remote image file. This property is required if you are not uploading a file for the image asset.
displayName String no The name of the asset, which will be displayed in the Media module.

Rendition object

The rendition object represents one of the multi-bitrate streaming renditions of a video with an MP4 or FLV container (see the iOS Rendition object for renditions with an M2TS container). A Video should have not more than 10 total rendition and iosrendition objects. For more information, see Using multi-bitrate streaming and Creating videos for multi-bitrate streaming.

Property name Type Read only? Description
audioOnly boolean no If true, this rendition is audio-only and has no video content. Audio-only renditions can be used for mobile streaming over low-bandwidth connections. It is recommended that videos in iOS applications should include a 64 kbps audio-only rendition.
controllerType enum no Depending on your CDN, one of the following values:
  • AKAMAI_STREAMING
  • AKAMAI_SECURE_STREAMING
  • AKAMAI_LIVE
  • AKAMAI_HD
  • AKAMAI_HD_LIVE
  • LIMELIGHT_LIVE
  • LIMELIGHT_MEDIAVAULT
See Setting the controllerType for more information.
encodingRate int yes The rendition's encoding rate, in bits per second.
frameHeight int yes The rendition's display height, in pixels.
frameWidth int yes The rendition's display width, in pixels.
id long no The video ID.
referenceid string no The video reference ID.
remoteUrl string no Required, for remote assets. The complete path to the file hosted on the remote server. If the file is served using progressive download, then you must include the file name and extension for the file. You can also use a URL that re-directs to a URL that includes the file name and extension. If the file is served using Flash streaming, use the remoteStreamName attribute to provide the stream name.
remoteStreamName string no [Optional — required for streaming remote assets only] A stream name for Flash streaming appended to the value of the remoteUrl property.
size long yes Required. The file size of the rendition, in bytes.
uploadTimestampMillis long no The date/time that the video was uploaded to Video Cloud, in Epoch milliseconds form.
url string yes The URL of the rendition file. Note: URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically.
videoCodec enum no Required. Valid values are SORENSON, ON2, and H264.
videoContainer enum no The format of the wrapper that provides metadata and describes how the video and audio are stored in the file. Valid values are FLV and MP4 (for M2TS renditions see the iOS Rendition Object). See Supported Video Codecs and Containers for more information.
videoDuration long no Required. The length of the remote video asset in milliseconds.

Setting the controllerType

The value of the controllerType field in the Rendition object can depend on how you are delivering content and what CDN you are using. Here are the possible values for controllerType:

controllerType value description
AKAMAI_STREAMING Akamai CDN, not live, without TTL
AKAMAI_SECURE_STREAMING Akamai CDN, not live, with TTL
AKAMAI_LIVE Akamai CDN, live, without DVR
AKAMAI_HD Akamai HD
AKAMAI_HD_LIVE live with DVR (whether your account's main CDN is Akamai or not)
LIMELIGHT_LIVE Limelight CDN, live
LIMELIGHT_MEDIAVAULT Limelight CDN, using Limelight's Media Vault service option

iOS Rendition object

The iosrendition object represents one of the multi-bitrate streaming renditions of a video with container type M2TS, meaning an HLS stream playable on iOS devices. A Video should have not more than 10 total rendition and iosrendition objects. For more information, see Using multi-bitrate streaming and Creating videos for multi-bitrate streaming.

Property name Type Read only? Description
audioOnly boolean no If true, this rendition is audio-only and has no video content. Audio-only renditions can be used for mobile streaming over low-bandwidth connections. It is recommended that videos in iOS applications should include a 64 kbps audio-only rendition.
controllerType enum no DEFAULT
encodingRate int yes The rendition's encoding rate, in bits per second.
frameHeight int yes The rendition's display height, in pixels.
frameWidth int yes The rendition's display width, in pixels.
id long no The video ID.
referenceid string no The video reference ID.
remoteUrl string no Required, for remote assets. The complete path to the file hosted on the remote server. If the file is served using progressive download, then you must include the file name and extension for the file. You can also use a URL that re-directs to a URL that includes the file name and extension. If the file is served using Flash streaming, use the remoteStreamName attribute to provide the stream name.
remoteStreamName string no [Optional — required for streaming remote assets only] A stream name for Flash streaming appended to the value of the remoteUrl property.
size long yes Required. The file size of the rendition, in bytes.
uploadTimestampMillis long no The date/time that the video was uploaded to Video Cloud, in Epoch milliseconds form.
url string no The url for the m3u8 stream. Note: URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically.
videoCodec enum no Required. Valid value is H264.
videoContainer enum no The format of the wrapper that provides metadata and describes how the video and audio are stored in the file. Valid values is M2TS. See Supported Video Codecs and Containers for more information.
videoDuration long no Required. The length of the remote video asset in milliseconds.

CuePoint

The CuePoint object is a marker set at a precise time point in the duration of a video. You can use cue points to trigger mid-roll ads or to separate chapters or scenes in a long-form video. For more information, see Adding Cue Points to Videos and Setting CuePoints with the Media API.

Property name Type Read only? Description
name String yes Required. A name for the cue point so that you can refer to it.
videoId String yes A comma-separated list of the ids of one or more videos that this cue point applies to.
time Long yes Required. The time of the cue point, measured in milliseconds from the beginning of the video.
forceStop Boolean no If true, the video stops playback at the cue point. This setting is valid only for AD type cue points.
type Enum yes Required. An integer code corresponding to the type of cue point. One of 0 (AD) or 1 (CODE). An Ad cue point is used to trigger mid-roll ad requests. A Code cue point can be used to indicate a chapter or scene break in the video.
metadata String no A string that can be passed along with a CODE cue point. Not more than 512 characters.

 

LogoOverlay

The LogoOverlay object represents a logo overlay assigned to a video. The logo overlay is displayed over a portion of the video display for the entire duration of the video. For more information, see Creating Logo Overlays and Adding Logo Overlays to Videos with the Media API. You can also set a default logo overlay for your account. If you have a logo overlay set at the account level and also set a logo overlay for a video, the logo overlay set for the video will display and the account level logo overlay will not display.

Property name Type Description
id Long A number that uniquely identifies the LogoOverlay. This id is automatically assigned by Video Cloud when the LogoOverlay is created.
image Image An Image object, defined by its id or referenceId, with type=LOGO_OVERLAY.
tooltip String Optional. A text that is displayed when the viewer mouses over the logo overlay.
linkURL String Optional. A URL to go to if the viewer clicks on the logo overlay.
alignment Enum Optional. A LogoOverlayAlignmentEnum representing the orientation of the logo overlay relative to the video display. One of the following values: TOP_LEFT, BOTTOM_LEFT, TOP_RIGHT, or BOTTOM_RIGHT. The default is BOTTOM_RIGHT.
Tags
reference