Product Updates | Contact Support | System Status
Page Contents

    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
    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
    labels Array Array of labels (full path) assigned to the video; see Working with Labels for more information.
    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
    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. The reference id should not contain spaces, commas, or special characters.
    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
    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

    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 Account Manager
    • [1-4] state can be set to ACTIVE or INACTIVE, but not to PENDING or DELETED.

      The meaning of the states is as follows:

      • ACTIVE - the video is playable
      • INACTIVE - the video is not playable, either because it has been manually deactivated, or is missing a value for a required field
      • PENDING - the video has been shared to this account by another account, but has not yet been accepted (see Media Sharing for more information)
      • DELETED - the video has been deleted from the account
    • [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
    id String System id for the cue point
    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. Note that you can use a date-time value that includes a timezone when you set the schedule, but that values stored and returned are always UTC.
    starts_at String in ISO-8601 date format Date-time when the video becomes available for viewing. Note that you can use a date-time value that includes a timezone when you set the schedule, but that values stored and returned are always UTC.

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

    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
    Page last updated on 27 Oct 2021