Ingest Profiles API Fields Reference (Legacy Ingest)

Product(s)
Video Cloud
Role(s)
API Developer
Task(s)
Add Videos/Assets
Topic(s)
Ingest Profiles
References
API(s)
Ingest Profiles API

This is a reference to fields for ingest profiles for the legacy ingest system.

Profile fields

Property Type Description Default
id string The profile id (read-only) none
version integer The profile version (read-only) none
account_id integer The Video Cloud account id none
name string The profile name - must be unique within the account none
description string The profile description none
date_created integer (epoch timestamp (milliseconds) Date profile was created (read-only) none
date_last_modified integer (epoch timestamp in milliseconds) Date profile was last modified (read-only) none
brightcove_standard boolean Read-only - false for all custom profiles false
digital_master object Defines if and how to archive a digital master false
numRenditions integer Number of renditions in the profile, including image renditions (read-only) none
renditions array Array of rendition objects []
packages array Array of DRM packages []

Rendition fields

Property Type Description Default
id string the rendition id (read-only) none
aspect_mode enum (string) how to handle mismatches between source and target aspect ratio - preserve, stretch, crop, pad - note that if you choose a value other than preserve, both width and height may be modified to achieve the desired aspect ratio preserve
audio_bitrate integer audio bitrate in kbps match source
audio_sample_rate integer sample rate in Hz - (AAC: 8000, 11025, 12000, 16000, 22050, 32000, 44100, 48000, 96000; FLV: 11025, 22050, and 44100) match source
max_audio_sample_rate integer max audio sample rate in Hz, overrides audioSampleRate (AAC: 8000, 11025, 12000, 16000, 22050, 32000, 44100, 48000, 96000; FLV: 11025, 22050, and 44100) match source
audio_constant_bitrate boolean force CBR, not compatible with VP6 false
audio_channels integer Number of audio channels (null (don't change), 1 or 2) null
audio_codec string Audio codec - aac | mp3 Determined by the format or profile
max_aac_profile string Max aac profile: aac-lc, he-aac, or he-aac-v2 we recommend using aac-lc when the audio bitrate of the rendition is less than 48kbps
constant_bitrate boolean whether CBR should be forced for the rendition none
crf integer a bitrate-control setting, and sets a constant ratefactor. Valid values are 0-51, with lower values being better quality.[1-3] none
decoder_bitrate_cap integer in kbps, the max bitrate fed to the decoder via a buffer none
decoder_buffer_size integer in kbps, the size of the buffer fed to the decoder when using a bitrate_cap none
encryption_method string encryption method to use, e.g. aes-128[1-1] none
encryption_key_rotation_period integer use a different key for each set of segments, rotating to a new key after this many segments[1-1] null
fixed_keyframe_interval boolean prevent things like scenecut from placing additional keyframes false
forced_keyframe_interval integer forces a keyframe every X frames, but still allows additional keyframes for scenecut, etc. none
forced_keyframe_rate float force the keyframe rate, h264 only, ignored if forced_keyframe_interval is used none
format string Video format - ts, mp4, flv none
frame_rate float frames per second same as source
h264_reference_frames integer Number of reference frames to use. Determined partly by speed.[1-4] 3
h264_profile string H.264 has three commonly-used profiles: Baseline (lowest), Main, and High.[1-5] baseline
h264_level float Constrains the bitrate and macroblocks.[1-6] calculated
h264_bframes integer Maximum number of consecutive B-frames (0-16)[1-7] 0
hls_optimized_ts boolean Time segments optimized for HLS - only applies to HLS output none
keyframe_interval integer Maximum number of frames between keyframes 250, overrides keyframe_rate
keyframe_rate float Maximum keyframes per second keyframe_interval of 250
label string Image type for image renditions - poster or thumbnail none
live_stream boolean whether this will be live video stream none
live_dvr_sliding_window_duration integer Duration of stream to keep available for LiveDVR delivery in seconds 300
max_video_bitrate integer in kbps, 123 = 123kbps - h264 only none
max_frame_rate float limits the cframe_rate rather than sets it, use as an alternative to frame_rate none
max_hls_protocol_version integer Sets the maximum HLS protocol version to use. Special features will be used as available (2-5) 3 for Live Streaming, 5 for AES encrypted output, otherwise 2
media_type string video, audio, or image none
one_pass boolean force one pass encoding false
reference_id string an identifier for the rendition unique within the account - required for DRM none
segment_seconds integer number of seconds of content to include in segments 10 for HLS, 2 for DASH
skip object a set of conditions for skipping creation of the rendition see Conditional Output for details null
skip_video boolean do not include the video stream - use for audio-only renditions false
speed integer 1-5 - a target transcoding speed. Slower transcoding allows for more advanced file compression, while faster transcoding is possible by skipping some advanced compression features 3
streaming_delivery_format string Sets the format/protocol for an output that will be delivered using a specific streaming configuration, including necessary manifests, directory structures, or other packaging none
streaming_delivery_profile string Sets the profile of the streaming delivery format, ensuring options are selected for compatibility with the profile. Typically used for MPEG-DASH renditions. Valid options depend on the selected streaming_delivery_format[1-8] live
tuning string H264Tuning: film, animation, grain, psnr, ssim, fastdecode, zerolatency none
type string The only value supported currently is segmented (for HLS) none
upscale boolean increase the frame size if the source is smaller than the target false
video_bitrate integer in kbps, 123 = 123kbps none
video_codec string e.g. h264, ts Determined by the format or profile
watermarks[1-9] array array of watermark objects  
width integer frame width in pixels none
height integer frame height in pixels none

Notes

  • [1-1] to reproduce the behavior of the old Video Cloud ingest system use a value of 10 - see Content Security (DRM and HLSe) for more details
  • [1-2] Higher quality means higher bitrate and vice versa. Possible values:
    1. Highly compressed. Mediocre visual quality, but small files
    2. Acceptable quality
    3. Good quality. Better than most web video
    4. Great quality. Looks excellent
    5. Nearly lossless. Large files. Not recommended unless you plan to encode this output again
  • [1-3] You shouldn't have to go below 16; 16 is nearly lossless for most files. Around 24 usually looks pretty good. Around 35 looks pretty compressed
  • [1-4] More reference frames result in slightly higher compression quality, but increased decoding complexity. In practice, going above 5 rarely has much benefit. We default to 3 as a good compromise of compression and decoding complexity. Set to "auto" to allow our speed setting to naturally choose this number
  • [1-5] Lower levels are easier to decode, but higher levels offer better compression. For example, the iPhone 3gs only supports the Baseline profile. The Main and High profiles are a definite step up in compression, and work fine for web playback, though be careful with HD High profile video in Flash Player
  • [1-6] Primarily used for device compatibility. For example, the iPhone supports H.264 Level 3, which means that a video’s decoder_bitrate_cap can’t exceed 10,000 kbps. Typically, you should only change this setting if you’re targeting a specific device that requires it.
  • [1-7] B-frames are only supported by H.264 Main or High profile, not Baseline. Using B-frames can increase quality at the same bitrate, but is more demanding on CPUs. This may be problematic on old computers or devices, but generally plays smoothly on modern hardware.Video Cloud defaults to 0 for widest compatibility. We recommend a value of 3 for compression/quality improvements. Values higher than 5 or 6 rarely provide much benefit, and greatly increase encoding time
  • [1-8] For 'dash' outputs, the currently supported profiles are:
    • live - Will set the DASH profile to "urn:mpeg:dash:profile:isoff-live:2011" and use a single SegmentTemplate for each AdaptationSet. For DRM, it will use an 8-byte IV, and for PlayReady will use version 1.1, including a PSSH atom in the media
    • hbbtv_1.5 - Will set the DASH profile to "urn:hbbtv:dash:profile:isoff-live:2012" and include required attributes for audio and video representations. For DRM, it will use a 16-byte IV, and for PlayReady will use version 1.0, excluding PSSH atoms
  • [1-9] Watermarks must be added at the rendition level - to each rendition that you want watermarked

Digital master fields

The digital_master object defines if and how to store a digital master that you can use for retranscoding later. See Archiving Masters for details.

Property Type Description Default
rendition string The rendition to archive - either passthrough to archive the original source video or the reference_id for one of the renditions defined in the profile or none if you do not want to archive a master passthrough
distribute boolean Whether the digital_master should be pushed to the CDN to available for playback false

Package fields

Packages are used for DRM. If your account is not enabled for DRM, just leave the packages array empty.

Note: packages reference renditions by reference_id. To use packages, your renditions must have reference_ids, and the renditions must be defined in the JSON for the profile before the packages are defined.

Property Type Description Default
drm array DRM type (for MPEG-DASH only)[2-2] none
package_type string DRM package type[2-2] none
renditions array An array of strings, each of which is the reference_id for rendition in the profile[2-3] []

Notes

  • [2-1] Currently supported value for the drm array are marlin, playready, and widevine
  • [2-2] See Content Security (DRM and HLSe) for details
  • [2-3] Note that the renditions in the profile must be defined in the JSON before the packages, so that the reference_ids exist

Watermark Fields

Watermark images are burned into each video frame in the lower right corner.

Watermark Sample
Property Type Description Default
url string url for the image none
width string[3-2] width of the watermark as pixels or a percentage of the frame width - e.g. 20%[3-1] none
height string[3-2] height of the watermark as pixels or a percentage of the frame height - e.g. 10%[3-1] none
x string[3-2] distance from the left edge of the video frame to the center of the watermark as pixels or a percentage of the frame width none
y string[3-2] distance from the top edge of the video frame to the center of the watermark as pixels or a percentage of the frame width none

Notes

  • [3-1] If you specify the width only, the image aspect ratio will be maintained automatically
  • [3-2] Although the width, height, x, and y fields are string values, they contain numbers (pixels or percentage) that must be integers - decimal values like "5.2%" will be rejected.