Ingest Fields Reference

This topic provides a reference to the request body fields for the Dynamic Ingest API. Also see the API Reference.

Dynamic Ingest fields

Video Cloud Ingest Fields
Field Type Description
master optional Object

the video master to be ingested
master.url optional Url

URL for the video source; required except for re-transcoding where a digital master has been archived, or you are adding images or text tracks to an existing video
master.use_archived_master optional Boolean

For retranscode requests, will use the archived master if set to true; if set to false, you must also include the url for the source video
master.audio_tracks optional Object

An audio_tracks object within the master object contains metadata for the audio track included in the video file (if any - this is also referred to as the muxed in audio) - this will include metadata only, without a URL for the audio file, since the audio track is already included in the video file - see Implementing Multiple Audio Tracks Using the APIs for more information
master.audio_tracks.language optional String

Language code for the muxed in audio from the subtags in https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry (default can be set for the account by contacting Brightcove Support) Dynamic Delivery only
master.audio_tracks.variant optional String

the type of audio track for the muxed in (default can be set for the account by contacting Brightcove Support) - for the muxed in audio, this is usually main Dynamic Delivery only

Allowed values: "main", "alternate", "commentary", "dub", "descriptive"
audio_tracks optional Dynamic Delivery only Object[]

array of audio track objects - see Implementing Multiple Audio Tracks Using the APIs for more information.
audio_tracks.merge_with_existing optional Boolean

whether to replace existing audio tracks or add the new ones Dynamic Delivery only

Default value: true
audio_tracks.masters optional Object[]

array of audio track objects Dynamic Delivery only
audio_tracks.masters.url optional String

URL for the audio file Dynamic Delivery only
audio_tracks.masters.language optional String

Language code for the audio track from the subtags in https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry (default can be set for the account by contacting Brightcove Support) Dynamic Delivery only
audio_tracks.masters.variant optional String

the type of audio track (default can be set for the account by contacting Brightcove Support) Dynamic Delivery only

Allowed values: "main", "alternate", "commentary", "dub", "descriptive"
forensic_watermarking optional Boolean Whether forensic watermarks should be added to video renditions - if you set it to true the account must be enabled for forensic watermarking, or the field will be ignored - see Overview: Forensic Watermarking for more details
forensic_watermarking_stub_mode optional Boolean WWhether visible forensic watermarks should be added to video renditions - if you set it to true the account must be enabled for forensic watermarking, and the forensic_watermarking field must also be set to true - see Overview: Forensic Watermarking for more details Visible watermarks should be used only for testing integrations, to ensure that forensic watermarks have been successfully added to the video (use a video at least 10 minutes long). Once verification is complete, they must be removed by submitting a new ingest request to retranscode the video - forensic_watermarking_stub_mode must be set to false on the retranscode request.
profile optional String

ingest profile to use for transcoding; if absent, the default profile will be used
transcriptions optional Object[]

Array of transcription objects for auto captions
transcriptions.autodetect optional Boolean true to auto-detect language from audio source. false to use srclang specifying the audio language.
transcriptions.default optional Boolean If true, srclang will be ignored, and the main audio track will be used - language will be auto-detected.
transcriptions.input_audio_track optional Object For multiple audio tracks, defines the audio to extract the captions from. It is composed by language and variant (both required).
transcriptions.input_audio_track.language required if input_audio_track included String BCP-47 style language code for the text tracks (en-US, fr-FR, es-ES, etc.); see supported languages
transcriptions.input_audio_track.variant required if input_audio_track included String Specifies the variant to use:
  • main
  • alternate
  • dub
  • commentary
  • descriptive
transcriptions.kind optional String The kind of output to generate. Allowed values:
  • captions
  • transcripts
Notes:
  1. If the kind is transcripts, and the url for the transcripts file is included, a transcript file will be ingested, and no auto captions will be generated. See Ingesting Transcriptions for more details.
  2. If the kind is transcripts, and the url for the transcripts file is not included, a transcript file and captions will be generated,
  3. If the kind is captions, a captions will be generated, but not a transcript file.
transcriptions.label required String Human readable label.
transcriptions.srclang optional String BCP-47 style language code for the text tracks (en-US, fr-FR, es-ES, etc.); see supported languages
transcriptions.status optional String The status of the text tracks, either published or draft (added but not available to users); use draft if the transcription needs to be reviewed before release, and update it to published using the CMS API
transcriptions.url optional String The URL where a transcript file is located. Must be included in the kind is transcripts. Must not be included if the kind is captions.
text_tracks optional Object[]

array of text_tracks objects - see Ingesting WebVTT Files (Text Tracks)
text_tracks.url Url

URL for a WebVTT file
text_tracks.srclang String

ISO 639 2-letter (alpha-2) language code for the text tracks
text_tracks.kind optional String

how the vtt file is meant to be used

Default value: captions

Allowed values: "captions", "subtitles", "chapters", "metadata", "transcriptions"
text_tracks.label optional String

user-readable title
text_tracks.default optional Boolean

sets the default language for captions/subtitles
text_tracks.status optional String

sets the state of the text_tracks as published, draft, or null (default). If set to draft, the text tracks won't be displayed in the player.
images Array {} Array of objects describing images to be ingested - see Images and Dynamic Ingest for more information
variant String The type of image - one of the following:
  • poster
  • thumbnail
  • portrait
  • square
  • wide
  • ultra-wide
language String Language code for a multi-lingual variant - codes from https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry
height Number Height in pixels
Width Number Width in pixels
url string URL where the image is posted
capture-images optional Boolean

whether poster and thumbnail should be captured during transcoding; defaults to true if the profile has image renditions, false if it does not - see Images and the Dynamic Ingest API for more information
poster optional Object

the video poster to be ingested - see Images and the Dynamic Ingest API for more information
poster.url Url

URL for the video poster image
poster.height optional Integer

pixel height of the image
poster.width optional Integer

pixel width of the image
thumbnail optional Object

the video thumbnail to be ingested - see Images and the Dynamic Ingest API for more information
thumbnail.url Url

URL for the video thumbnail image
thumbnail.height optional Integer

pixel height of the image
thumbnail.width optional Integer

pixel width of the image
callbacks optional String[] Array of URLs that notifications should be sent to