The OutputSpec object

The OutputSpec object defines a single output rendition within a transcoding job. Each job can have 1—10 output specifications, and each output can produce a progressive download file or a streaming package with multiple variants.

Output specifications are passed in the outputs array when creating a job. You can define outputs inline with full configuration, or reference a preset for reusable encoding settings.

Fields

Field	Type	Required	Description
`type`	enum	Yes*	Output format. One of: `mp4`, `webm`, `mkv`, `mov`, `hls`, `dash`, `adaptive`. *Required unless using `preset`. See Output types.
`video`	array	Yes*	Video variants (1—20). Each defines an encode rendition. *Required unless using `preset`. See Video Variants.
`audio`	array	No	Audio track configuration (max 8 tracks). Only valid for streaming types (`hls`, `dash`, `adaptive`). See Audio tracks.
`hls`	object	No	HLS-specific configuration. Only valid when `type` is `hls` or `adaptive`. See HLS configuration.
`dash`	object	No	DASH-specific configuration. Only valid when `type` is `dash` or `adaptive`. See DASH configuration.
`segments`	object	No	Segment configuration for streaming outputs. Only valid for `hls`, `dash`, `adaptive`. See Segment configuration.
`path_template`	string	No	Per-output path template. Overrides the job-level `output_path_template`. Max 512 characters. See Path templates.
`preset`	string	No	Preset ID (e.g., `pst_abc123`) or slug (e.g., `web_1080p_standard`). When set, `type` and `video` are inherited from the preset. See Inline vs preset.
`subtitle_tracks`	array	No	Subtitle track configuration (max 8 tracks). See Subtitles.
`drm`	object	No	DRM encryption configuration. Only valid for streaming types (`hls`, `dash`, `adaptive`). See DRM & Encryption.
`content_aware`	object	No	Content-aware encoding configuration. See Content-Aware Encoding.

{
  "type": "hls",
  "video": [
    {"codec": "h264", "resolution": "1080p", "quality": "standard"},
    {"codec": "h264", "resolution": "720p", "quality": "standard"},
    {"codec": "h264", "resolution": "480p", "quality": "economy"}
  ],
  "audio": [
    {"language": "eng", "label": "English", "is_default": true}
  ],
  "hls": {
    "manifest": "master",
    "segment_format": "fmp4",
    "playlist_type": "vod"
  },
  "segments": {
    "duration": 6,
    "gop_alignment": "aligned"
  }
}

Output types

Type	API Value	Description	Container	Multiple Variants
MP4	`mp4`	Progressive download. Most widely supported format.	`.mp4`	No (1 variant)
WebM	`webm`	Open format for web. VP9 and AV1 only.	`.webm`	No (1 variant)
MKV	`mkv`	Matroska container. Supports all codecs.	`.mkv`	No (1 variant)
MOV	`mov`	Apple QuickTime format.	`.mov`	No (1 variant)
HLS	`hls`	HTTP Live Streaming. Apple’s adaptive streaming protocol.	`.m3u8` + segments	Yes (ABR ladder)
DASH	`dash`	Dynamic Adaptive Streaming over HTTP.	`.mpd` + segments	Yes (ABR ladder)
Adaptive	`adaptive`	Both HLS and DASH from shared CMAF segments. Maximum compatibility with minimal storage.	`.m3u8` + `.mpd` + shared segments	Yes (ABR ladder)

Progressive types (mp4, webm, mkv, mov) accept exactly one video variant. Streaming types (hls, dash, adaptive) accept up to 20 variants for ABR ladders.

Inline vs preset

There are two ways to define an output: inline with full configuration, or by referencing a saved preset.

Inline

Specify type and video directly on the output. This gives you full control over every encoding parameter.

{
  "type": "mp4",
  "video": [
    {"codec": "h264", "resolution": "1080p", "quality": "standard"}
  ]
}

Preset

Reference a saved configuration by preset ID or slug. The preset supplies type, video, and any other saved settings.

{
  "preset": "pst_x9y8z7w6v5"
}

{
  "preset": "web_1080p_standard"
}

When using a preset, you can still override per-output settings like path_template, subtitle_tracks, drm, and content_aware. These fields are applied on top of the preset configuration.

type/video and preset are mutually exclusive. Provide one or the other, not both.

Audio tracks

The audio array configures multi-language audio tracks for streaming outputs. Each track maps to an audio rendition in the HLS/DASH manifest. Audio tracks are only valid for streaming types (hls, dash, adaptive).

Attributes

Attribute	Type	Required	Description
`language`	string	Yes	ISO 639-2 three-letter language code (e.g., `eng`, `spa`, `fra`, `deu`, `jpn`).
`label`	string	No	Human-readable label displayed in the player (e.g., `"English"`, `"Español"`). Max 64 characters.
`source_track`	integer	No	Zero-based index of the audio track in the input file (0—15). Default: `0`.
`is_default`	boolean	No	Whether this is the default audio track. Only one track should be marked as default.

{
  "type": "hls",
  "video": [
    {"codec": "h264", "resolution": "1080p", "quality": "standard"},
    {"codec": "h264", "resolution": "720p", "quality": "standard"}
  ],
  "audio": [
    {"language": "eng", "label": "English", "source_track": 0, "is_default": true},
    {"language": "spa", "label": "Spanish", "source_track": 1},
    {"language": "fra", "label": "French", "source_track": 2}
  ]
}

Audio tracks are free — they do not add to the per-minute cost. Progressive outputs (mp4, webm, mkv, mov) automatically include the default audio track without explicit configuration.

HLS configuration

The hls object configures HLS-specific settings. Only valid when type is hls or adaptive.

Attributes

Attribute	Type	Default	Description
`manifest`	string	`"master"`	Name of the master playlist file (without extension). Pattern: `[a-zA-Z0-9_-]+`. Max 64 characters.
`segment_format`	enum	`fmp4`	Segment container format. One of: `fmp4` (fragmented MP4 / CMAF), `ts` (MPEG-TS). `fmp4` is recommended for modern players.
`playlist_type`	enum	`vod`	Playlist type. One of: `vod` (Video on Demand — complete playlist), `event` (event — playlist can be appended to).
`variant_pattern`	string	Auto	Naming pattern for variant playlists. Variables: `{codec}`, `{resolution}`, `{bitrate}`, `{index}`. Max 128 characters.

{
  "hls": {
    "manifest": "master",
    "segment_format": "fmp4",
    "playlist_type": "vod",
    "variant_pattern": "{codec}_{resolution}"
  }
}

Use fmp4 segment format when targeting modern players and devices. It enables CMAF compatibility, which means HLS and DASH can share the same segments when using the adaptive output type. Use ts only when you need to support legacy devices that do not support fragmented MP4.

DASH configuration

The dash object configures DASH-specific settings. Only valid when type is dash or adaptive.

Attributes

Attribute	Type	Default	Description
`manifest`	string	`"manifest"`	Name of the MPD manifest file (without extension). Pattern: `[a-zA-Z0-9_-]+`. Max 64 characters.

{
  "dash": {
    "manifest": "stream"
  }
}

Segment configuration

The segments object controls how streaming outputs are segmented. Only valid for streaming types (hls, dash, adaptive).

Attributes

Attribute	Type	Default	Description
`duration`	integer	`6`	Target segment duration in seconds (1—30). Shorter segments reduce latency, longer segments improve compression.
`gop_alignment`	enum	`aligned`	GOP alignment mode. `aligned` aligns keyframes across all variants for seamless ABR switching. `fixed` uses a fixed GOP size.
`gop_size`	integer	null	Fixed GOP size in seconds (1—10). Only valid when `gop_alignment` is `fixed`.

{
  "segments": {
    "duration": 4,
    "gop_alignment": "aligned"
  }
}

aligned is recommended for ABR streaming. It ensures all variants have keyframes at the same timestamps, enabling instant quality switching without buffering or visual glitches.

Path templates

Customize output file paths using template variables. The path_template field on an output overrides the job-level output_path_template for that specific output.

Variables

Variable	Description	Example
`{job_id}`	Job identifier	`job_a1b2c3d4e5f6`
`{output_id}`	Output identifier	`out_m1n2o3p4q5`
`{date}`	Job creation date	`2025-02-28`
`{type}`	Output format	`hls`
`{codec}`	Video codec	`h264`
`{resolution}`	Resolution	`1080p`
`{quality}`	Quality tier	`standard`

{
  "path_template": "{date}/{job_id}/{type}/{codec}_{resolution}"
}

Produces: 2025-02-28/job_a1b2c3d4e5f6/hls/h264_1080p

Path templates are appended to the output origin’s base path. For streaming outputs with multiple variants, the {codec} and {resolution} variables resolve per-variant within the output directory structure.

Validation rules

Transcodely validates output specification configuration at job creation time. The following constraints are enforced:

Rule	Description
`type` or `preset` required	Every output must have either `type` + `video` or a `preset` reference.
Progressive = 1 variant	`mp4`, `webm`, `mkv`, `mov` outputs accept exactly 1 video variant.
Streaming = 1—20 variants	`hls`, `dash`, `adaptive` outputs accept 1—20 video variants.
`audio` requires streaming	Audio tracks are only valid for `hls`, `dash`, `adaptive`.
`hls` config requires HLS	`hls` config is only valid when `type` is `hls` or `adaptive`.
`dash` config requires DASH	`dash` config is only valid when `type` is `dash` or `adaptive`.
`segments` requires streaming	Segment config is only valid for `hls`, `dash`, `adaptive`.
`drm` requires streaming	DRM is only valid for `hls`, `dash`, `adaptive`.
Max 8 subtitle tracks	Each output supports up to 8 subtitle tracks.
Max 8 audio tracks	Each output supports up to 8 audio tracks.
Max 20 video variants	Each output supports up to 20 video variants.
WebM requires VP9 or AV1	`webm` outputs only accept `vp9` or `av1` codecs.
Path template length	`path_template` must not exceed 512 characters.
Preset identifier length	`preset` must be 1—128 characters.

Examples

Simple MP4 output

A single progressive MP4 file with H.264 encoding at 1080p.

{
  "type": "mp4",
  "video": [
    {"codec": "h264", "resolution": "1080p", "quality": "standard"}
  ]
}

HLS ABR ladder with multi-language audio

An HLS streaming package with three quality tiers and three audio languages. Uses CMAF segments with aligned GOPs for seamless ABR switching.

{
  "type": "hls",
  "video": [
    {"codec": "h264", "resolution": "1080p", "quality": "standard"},
    {"codec": "h264", "resolution": "720p", "quality": "standard"},
    {"codec": "h264", "resolution": "480p", "quality": "economy"}
  ],
  "audio": [
    {"language": "eng", "label": "English", "source_track": 0, "is_default": true},
    {"language": "spa", "label": "Spanish", "source_track": 1},
    {"language": "fra", "label": "French", "source_track": 2}
  ],
  "hls": {
    "manifest": "master",
    "segment_format": "fmp4",
    "playlist_type": "vod"
  },
  "segments": {
    "duration": 6,
    "gop_alignment": "aligned"
  }
}

Adaptive output with DRM, subtitles, and content-aware encoding

A full-featured adaptive output that produces both HLS and DASH manifests from shared CMAF segments. Includes DRM encryption, multi-language subtitles, and content-aware encoding with VMAF targeting.

{
  "type": "adaptive",
  "video": [
    {"codec": "h265", "resolution": "2160p", "quality": "premium"},
    {"codec": "h265", "resolution": "1080p", "quality": "standard"},
    {"codec": "h265", "resolution": "720p", "quality": "standard"},
    {"codec": "h265", "resolution": "480p", "quality": "economy"}
  ],
  "audio": [
    {"language": "eng", "label": "English", "is_default": true},
    {"language": "spa", "label": "Spanish"}
  ],
  "hls": {
    "manifest": "master",
    "segment_format": "fmp4"
  },
  "dash": {
    "manifest": "manifest"
  },
  "segments": {
    "duration": 4,
    "gop_alignment": "aligned"
  },
  "subtitle_tracks": [
    {
      "operation": "convert",
      "source_url": "gs://my-bucket/subs/en.srt",
      "output_format": "webvtt",
      "language": "eng",
      "label": "English",
      "is_default": true
    },
    {
      "operation": "convert",
      "source_url": "gs://my-bucket/subs/es.srt",
      "output_format": "webvtt",
      "language": "spa",
      "label": "Spanish"
    }
  ],
  "drm": {
    "systems": ["widevine", "fairplay"],
    "scheme": "cbcs",
    "key_server": {
      "license_server_url": "https://drm.example.com/v1/keys",
      "auth_token": "Bearer eyJhbGciOiJIUzI1NiJ9..."
    }
  },
  "content_aware": {
    "mode": "per_title",
    "vmaf_target": 95
  },
  "path_template": "{date}/{job_id}/adaptive"
}

Preset-based output with overrides

Reference a saved preset and add subtitle tracks and a custom path template on top.

{
  "preset": "web_1080p_standard",
  "subtitle_tracks": [
    {
      "operation": "passthrough",
      "source_stream_index": 0,
      "language": "eng",
      "label": "English",
      "is_default": true
    }
  ],
  "path_template": "{date}/{job_id}/preset"
}

#The OutputSpec object

#Fields

#Output types

#Inline vs preset

#Inline

#Preset

#Audio tracks

#Attributes

#HLS configuration

#Attributes

#DASH configuration

#Attributes

#Segment configuration

#Attributes

#Path templates

#Variables

#Validation rules

#Examples

#Simple MP4 output

#HLS ABR ladder with multi-language audio

#Adaptive output with DRM, subtitles, and content-aware encoding

#Preset-based output with overrides

The OutputSpec object

Fields

Output types

Inline vs preset

Inline

Preset

Audio tracks

Attributes

HLS configuration

Attributes

DASH configuration

Attributes

Segment configuration

Attributes

Path templates

Variables

Validation rules

Examples

Simple MP4 output

HLS ABR ladder with multi-language audio

Adaptive output with DRM, subtitles, and content-aware encoding

Preset-based output with overrides