This topic provides a reference to the objects returned by the Media API's read methods:
Note that these objects are similar to, but not identical with, the objects used in the Player API.
The Video object is an aggregation 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 this 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 Brightcove when the Video is created. |
| referenceId | String | no | A user-specified id that uniquely identifies this Video, limited to 150 characters. A referenceId can be used as a foreign-key to identify this video in another system. Note that the find_videos_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, assigned by Brightcove, that uniquely identifies the account to which this Video belongs. |
| shortDescription | String | no | A short description describing this 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. |
| 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 this 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 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 64 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. |
| thumbnailURL | String | yes | The URL to the thumbnail image associated with this Video. Thumbnails are 120x90 pixels. |
| 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 this Video. |
| geoFiltered | 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 this Video has been played since its creation. |
| playsTrailingWeek | Integer | yes | How many times this Video has been played within the past seven days, exclusive of today. |
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 this 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 Brightcove. |
| name | String | no | The title of this Playlist, limited to 50 characters. The name is a required property when you create a playlist. |
| shortDescription | String | no | A short description describing this Playlist, limited to 250 characters. |
| videoIds | List | no | A list of the ids of the Videos that are encapsulated in this Playlist. |
| videos | List | no | A list of the Video objects that are encapsulated in this Playlist. |
| playlistType | Enum | no | Options are OLDEST_TO_NEWEST, NEWEST_TO_OLDEST, ALPHABETICAL, PLAYSTOTAL, and PLAYS_TRAILING_WEEK (each of which is a smart playlist, ordered as indicated) or EXPLICIT (a manual playlist). The playlistType is a required property when you create a playlist. |
| filterTags | List | no | A list of the tags that define this smart playlist. For example: "filterTags":["Sitka","ticks"] |
| thumbnailURL | String | yes | The URL of the thumbnail associated with this Playlist. |
This object represents metadata about an image file in your account. Images are associated with videos as thumbnail images or video still images. 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.
| property name | type | read only? | description |
|---|---|---|---|
| id | Long | yes | A number that uniquely identifies this Image. This id is automatically assigned by Brightcove when the Image is created. |
| referenceId | String | no | A user-specified id that uniquely identifies this Image. |
| type | ImageTypeEnum | no | THUMBNAIL or VIDEO_STILL. 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. |
The Rendition object represents one of the multi-bitrate streaming renditions of a video. A Video should have not more than 10 Renditions. For more information, see Using multi-bitrate streaming and Creating videos for multi-bitrate streaming.
| property name | type | read only? | description |
|---|---|---|---|
| url | string | yes | The URL of the rendition file. |
| controllerType | enum | no | [Optional — required for live streaming only] Depending on your CDN, one of LIMELIGHT_LIVE or AKAMAI_LIVE. |
| 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. |
| size | long | yes | Required. The file size of the rendition, in bytes. |
| 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. |
| videoDuration | long | no | Required. The length of the remote video asset in milliseconds. |
| videoCodec | enum | no | Required. Valid values are SORENSON, ON2, and H264. |
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), 1 (CODE), or 2 (CHAPTER). An AD cue point is used to trigger mid-roll ad requests. A CHAPTER cue point indicates a chapter or scene break in the video. A CODE cue point causes an event that you can listen for and respond to. |
| metadata | String | no | A string that can be passed along with a CODE cue point. |