CMS API Video Fields Reference

This is a reference to video fields returned by the CMS API.

Video fields

Video Fields
Field Type Description
account_id String The Video Cloud account id
ad_keys String 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"
clip_source_video_id String The ID of the source video that was clipped to produce this video or null if this video is not a clip of another video.
complete Boolean Whether processing is complete — Note: when you create a new video, the complete property is automatically set to false. As soon as one rendition exists for the video, the complete property will be automatically set to true
created_at Number, milliseconds from epoch When the video was created in the Video Cloud system
created_by Object Information about who created the video, if available
cue_points Array of Maps array of cue point maps
custom_fields Map of field-value pairs (Strings) Custom field values set for the video - note that custom field that do not have a value for this video are not included in this map; custom field values have a maximum length of 1024 single-byte characters
dash_manifest_id String System id for a DASH manifest
delivery_type String Delivery type for the video:
  • dynamic_origin - dynamic delivery
  • live_origin - live stream from Brightcove Live
  • remote - asset
  • static_origin - legacy ingest system
  • unknown - could not be determined (may mean the video has no playable renditions)
description String; takes the place of the old shortDescription Short description of the video (maximum length: 248 single-byte characters)
digital_master_id String The system id for the digital master
drm_disabled Boolean For DRM-enabled accounts, setting this to true will prevent the video from being DRM-packaged. This field will not appear if the account is not DRM-enabled.
duration Number, milliseconds Duration of the video in milliseconds
economics String, must be one of valid enum values either "AD_SUPPORTED" (default) or "FREE"
folder_id String ID of folder to which video belongs
forensic_watermarking String ACTIVE indicates that the video has forensic watermarking. UNAVAILBLE means forensic watermarking was not added. null indicates that the account is not enabled for forensic watermarking.
geo [1-3] Map of property-value pairs Geo-restriction properties for the video
has_digital_master Boolean Whether video has an archived master that can be used for retranscoding. Note that if you are using this field to test whether a video can be retranscoded, it is not reliable for shared videos. If videos are shared to the account, you need to test for both has_digital_master = true and sharing.by_external_acct = false
id String The video id
images Map of property-value pairs Map of information about the poster and thumbnail images
link Map of property-value pairs Map of related link properties
long_description String Long description (up to 5000 characters)
name String The name of the video (maximum length: 248 single-byte characters)
offline_enabled Boolean Whether the video is enabled for offline playback
original_filename String Name of the video file that was ingested - will be null for remote asset videos
playback_rights_id String The unique identifier for the playback restrictions defined in the Playback Rights API.
projection String The mapping projection for 360° videos, e.g. "equirectangular"
published_at String ISO-8601 date-time string indicating when the video was published - note that this field is writable; by default it is set to the date that the video was first activated.
reference_id String 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.
schedule [1-1] Map of property-value pairs Map of start and end date-times for the video availability
sharing Map of property-value pairs Map of the sharing properties for the video
smooth_client_manifest_id String System id for a Smooth manifest
smooth_server_manifest_id String System id for the Smooth manifest server
state [1-4] String ACTIVE, INACTIVE, PENDING, DELETED
tags [1-5] Array of tags (Strings) Array of tags assigned to the video
text_tracks Array of HTML5-style text tracks Array of text tracks (WebVTT files) assigned to the video
transcripts Array of plain text transcripts Array of transcripts (plain text files) assigned to the video
updated_at Date-time string Date-time the video was last modified [1-2]
updated_by Object Information about who last updated the video, if available
variants Array of variant metadata objects Metadata variants for different languages
ingestion_profile_id String The id of Ingestion Profile used to transcode this video. Read only.

Notes

  • [1-1] Note that that a scheduled video is not inactive outside the period of scheduled availability
  • [1-2] The modification may have been made by a user or the Video Cloud system
  • [1-3] Geo-restriction is a paid add-on to Video Cloud; if you want to purchase geo-filtering capability, contact your Customer Success Manager
  • [1-4] state can be set to ACTIVE or INACTIVE, but not to PENDING or DELETED.

    The mean of the states is as follows:

    • ACTIVE - the video is playable
    • INACTIVE - the video has been deactivated or is lacking required metadata fields, and therefore is not playable
    • PENDING - this is related to media sharing; the video has been shared from another account, but has not yet been accepted by this account
    • DELETED - the video has been deleted
  • [1-5] Note the following limitations for tags:
    • Tags can be up to 128 characters. If any tags have more than 128 characters, an error will be displayed when you attempt to save changes
    • Tags can't contain commas; for example, a tag of roof, attic + front yard is not supported
    • A video can have no more than a total of 1200 tags
    • A tag differing only in case (lowercase, uppercase) is handled as an identical tag and the case will automatically match those of the original tag - issues with case sensitivity need to be handled externally to Video Cloud, for example, using JavaScript methods to modify the strings

Video Source Fields

The tables below show fields for the sources (renditions).

Dynamic Delivery sources

Field Type Description
src String URL for the source
type String Segmented video type, usually application/x-mpegURL (for HLS) or application/dash+xml (for DASH)
ext_x_version String HLS version - for HLS sources only
profiles String Profiles - for DASH sources only
codec String Video codec - for MP4 sources only
container String Video container - for MP4 sources only
duration Integer Duration in milliseconds - for MP4 sources only
encoding_rate Integer Encoding rate in BPS - for MP4 sources only
height Integer Frame height in pixels - for MP4 sources only
size integer File size in bytes - for MP4 sources only
uploaded_at String Date the video was uploaded in ISO-8601 date format
width Integer Frame width in pixels - for MP4 sources only

Legacy Ingest Sources (Renditions)

Field Type
src String URL, for PD web assets and HLS assets only
app_name String, for streaming web assets only
stream_name String, for streaming web assets only
codec String
container String
duration Long?
encoding_rate Long?
height Integer
id String
size Long
uploaded_at String in ISO-8601 date format
width Integer

Legacy ingest HLS manifest

Field Type
src String URL
type String (application/x-mpegURL)
codec String
container String

Legacy ingest HDS manifest

Field Type
asset_id String
src String URL
type String (application/f4m)

Legacy ingest Dash manifest

Field Type
asset_id String
src String URL
type String (application/dash+xml)

Legacy ingest Smooth manifests (server and client)

Field Type
asset_id String
src String URL
type String (application/vnd.ms-sstr+xml)

Cuepoint fields

The table below shows fields for cuepoints.

Cuepoint Fields
Field Type Description
force_stop Boolean Whether the video should be stopped at the cue point
metadata String; code point only A metadata string associated with the cue point
name String The cue point name
time Float Time of the cue point in seconds measured from the start of the video
type String The cue point type ( AD or DATA)

Geo fields

The table below shows the geo object fields.

Geo-Filtering Fields
Field Type Description
countries Array of country code Strings Array of ISO 3166 list of 2-letter codes (https://www.iso.org/obp/ui/) for countries in which the video is allowed or not allowed to play
exclude_countries Boolean If true, country array is treated as a list of countries excluded from viewing
restricted Boolean Whether geo-filtering is enabled for this video

Image fields

The table below shows image object fields

Poster fields

Field Type Description
   images.thumbnail Map Map the thumbnail image properties
poster Object Properties for the video poster (aka video still)
   poster.asset_id String System id for the default poster
   poster.src String URL URL for the default poster
   poster.sources Array of Maps Array of maps for posters
     poster.sources.asset_id String System id for the poster
     poster.sources.src String URL URL for the poster
     poster.sources.height Number Poster height in pixels
     poster.sources.width Number Poster width in pixels

Thumbnail fields

Field Type Description
thumbnail Object Properties for the video thumbnail
   thumbnail.asset_id String System id for the default thumbnail image
   thumbnail.src String URL Source URL for the default thumbnail
   thumbnail.sources Array of Maps Array of maps for thumbnail images
     thumbnail.sources.asset_id String System id for the thumbnail
     thumbnail.sources.src String URL URL for the thumbnail
     thumbnail.sources.height Number Image height in pixels
     thumbnail.sources.width Number Image width in pixels

The table below shows the link object fields.

Link Fields
Field Type Description
url String Related link URL
text String Related link text

Schedule fields

The table below shows the fields for the schedule object

Schedule Fields
Field Type Description
ends_at String in ISO-8601 date format Date-time when the video becomes unavailable for viewing
starts_at String in ISO-8601 date format Date-time when the video becomes available for viewing

Sharing fields

The table below shows the sharing object fields

Sharing Fields
Field Type Description
by_external_acct Boolean True if this video was shared from some other account.
by_id String Account id that originated the share
source_id String Video ID of the original video (sharer's copy)
to_external_acct Boolean True if this video is shared to another account
by_reference Boolean True is this video is shared by reference (will always be true for videos shared via the CMS API)

Text Track Fields

The table below shows the text track fields.

Field Type Description
id String System id for the text tracks item
src String Address of the track file (URL)
srclang String Language of the track, e.g. "en"
label String A user-readable title for the text track set
kind String How the track is meant to be used: subtitles, captions, descriptions, chapters, metadata
mime_type String mime type of the text tracks, e.g. "text/vtt"
asset_id String System id for the track file; null if asset is remote
in_band_metadata_track_dispatch_type String System id for the track file; null if asset is remote
status String State of the tracks: published, draft, or null
sources Array read-only
   src String Address of the track file (URL)
default Boolean Indicates that the track should be enabled by default. Should only be true on one track.

Transcript Fields

The table below shows the transcript fields.

Field Type Description
id String System id for the text tracks item
account_id String The system account id
src String Address of the track file (URL)
srclang String Language of the track, e.g. "en" or "ex-MX" - this field can be updated
label String A user-readable title for the text track set - this field can be updated
status String The status of the transcription, either published or draft - this field can be updated
sources Array read-only - array of URLs where the transcript can be retrieved by a client - there will be an http and https URL for each transcript
default Boolean Indicates that the track should be enabled by default. Should only be true on one track.

Created by fields

The table below shows the created_by object fields.

Created by Fields
Field Type Description
type String The type of the updater - either:
  • user - a user in Studio
  • api-key - a user via an API
id String The user id in the Video Cloud system
email String The user's email address in the Video Cloud system

Updated by fields

The table below shows the updated_by object fields.

Updated by Fields
Field Type Description
type String The type of the updater - either:
  • user - a user in Studio
  • api-key - a user via an API
id String The user id in the Video Cloud system
email String The user's email address in the Video Cloud system

Variant fields

The table below shows the variant object fields.

Updated by Fields
Field Type Description
language String The language for this variant in the language-country code format (examples: en-US, es-ES). Note that language is only included when you create a variant - you must NOT include it when updating the variant
name String The title of the video in this language
description String The title of the video in this language
long_description String The title of the video in this language
custom_fields Object map of fieldname: value pairs, where values are for this language; values have a maximum length of 1024 single-byte characters. Note: be sure to use the internal name for the field, not the display name/td>