Convert videos to HLS, MPEG-Dash and CMAF

🤖/video/adaptive encodes videos into HTTP Live Streaming (HLS), MPEG-Dash and CMAF supported formats and generates the necessary manifest and playlist files.

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET
Access-Control-Allow-Headers: *

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET"],
    "AllowedOrigins": ["*"],
    "ExposeHeaders": []
  }
]

Usage example

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "encoded_1080p": {
      "ffmpeg_stack": "v7",
      "preset": "hls/1080p",
      "robot": "/video/encode",
      "use": ":original"
    },
    "encoded_480p": {
      "ffmpeg_stack": "v7",
      "preset": "hls/480p",
      "robot": "/video/encode",
      "use": ":original"
    },
    "encoded_720p": {
      "ffmpeg_stack": "v7",
      "preset": "hls/720p",
      "robot": "/video/encode",
      "use": ":original"
    },
    "hls_bundled": {
      "playlist_name": "my_playlist.m3u8",
      "robot": "/video/adaptive",
      "technique": "hls",
      "use": {
        "bundle_steps": true,
        "steps": [
          "encoded_480p",
          "encoded_720p",
          "encoded_1080p"
        ]
      }
    }
  }
}

Parameters

• interpolate

  boolean | Record<string, boolean>

  Controls whether Assembly Variables are interpolated for individual instruction fields.

  By default, most Robot instruction fields interpolate Assembly Variables. Set this to false to treat every instruction field as literal text, or set an individual field path to false to treat only that field as literal text. For Robot-specific fields that are literal by default, set this to true or set that field path to true to opt back into interpolation.

  Use field names such as path, or dotted paths such as ffmpeg.vf for nested objects.

• output_meta

  Record<string, boolean> | boolean | Array<string>

  Allows you to specify a set of metadata that is more expensive on CPU power to calculate, and thus is disabled by default to keep your Assemblies processing fast.

  For images, you can add "has_transparency": true in this object to extract if the image contains transparent parts and "dominant_colors": true to extract an array of hexadecimal color codes from the image.

  For images, you can also add "blurhash": true to extract a BlurHash⁠ string — a compact representation of a placeholder for the image, useful for showing a blurred preview while the full image loads.

  For images, "thumbhash": true instead extracts a base64-encoded ThumbHash⁠ into meta.thumbhash, together with meta.has_alpha (whether an alpha channel exists, even when fully opaque). It describes EXIF-oriented pixels and uses the first frame of animated images. Extraction is best-effort: images above 40 megapixels, unsupported formats, or a failed/bounded decode produce no placeholder. Successful extraction adds a metadata charge equivalent to 20% of that file's bytes. No ThumbHash surcharge applies when disabled or when no hash is produced.

  Set this option on the Step producing the image, such as /upload/handle for uploaded originals or /image/resize for processed outputs. Setting it only on /transloadit/store does not request extraction: storage preserves the producer's metadata. Transloadit Storage persists a generated hash with its immutable version and returns it in stored results and native asset reads. Direct S3 uploads do not generate placeholders. A placeholder contains image information, so protect it with the same access controls as the full image.

  For videos, you can add the "colorspace": true parameter to extract the colorspace of the output video.

  For videos, you can also add "interlaced": true to detect whether the video is interlaced. This combines the cheap ffprobe field_order flag with a bounded idet sampling pass over the first frames of the source, exposing interlaced, field_order, and a diagnostic interlace_detection object under file.meta. This is computationally expensive and billed accordingly.

  For audio, you can add "mean_volume": true to get a single value representing the mean average volume of the audio file.

  You can also set this to false to skip metadata extraction and speed up transcoding.

• user_meta

  Record<string, any>(default: {})

  Adds custom JSON metadata to each emitted file without changing its contents. Nested objects and arrays are supported.

  Inheritance depends on the Robot. Values merge with existing user_meta on the output file; the current Step replaces matching top-level keys. Assign required keys explicitly when a Robot creates fresh outputs.

  In processing Steps, ${file.*} refers to the first input and ${result.*} to the emitted file. Values are evaluated per output after the Robot runs, before subsequent metadata extraction and temporary storage. On :original, values are evaluated per upload before metadata extraction.

  Downstream Steps read ${file.user_meta.key}. See Custom metadata for a complete example and inheritance rules.

• result

  boolean(default: false)

  Whether the results of this Step should be present in the Assembly Status JSON

• queue

  batch

  Setting the queue to 'batch', manually downgrades the priority of jobs for this step to avoid consuming Priority job slots for jobs that don't need zero queue waiting times

• force_accept

  boolean(default: false)

  Force a Robot to accept a file type it would have ignored.

  By default, Robots ignore files they are not familiar with. 🤖/video/encode, for example, will happily ignore input images.

  With the force_accept parameter set to true, you can force Robots to accept all files thrown at them. This will typically lead to errors and should only be used for debugging or combatting edge cases.

• ignore_errors

  boolean | Array<meta | execute>(default: [])

  Ignore errors during specific phases of processing.

  Setting this to ["meta"] will cause the Robot to ignore errors during metadata extraction.

  Setting this to ["execute"] will cause the Robot to ignore errors during the main execution phase.

  Setting this to true is equivalent to ["meta", "execute"] and will ignore errors in both phases.

• use

  string | Array<string> | Array<object> | object

  Specifies which Step(s) to use as input.

  • You can pick any names for Steps except ":original" (reserved for user uploads handled by Transloadit)
  • You can provide several Steps as input with arrays:

    {
      "use": [
        ":original",
        "encoded",
        "resized"
      ]
    }
    

  • You can also tag input Steps with as to pass semantic intent to robots:

    {
      "use": [
        {
          "name": ":original",
          "as": "image"
        },
        {
          "name": ":original",
          "as": "mask"
        }
      ]
    }
    

  Tip

  That's likely all you need to know about use, but you can view Advanced use cases.

• ffmpeg

  object

  Custom FFmpeg options are supported for the "hls" and "cmaf" techniques. Non-empty custom options are rejected for "dash", the default technique.

  These options apply to the packaging command, which copies the input streams by default. Set encoding options, such as keyframe intervals, in the preceding 🤖/video/encode Step.

• ffmpeg_stack

  v6 | v7 | v8 | string(default: "v7.0.0")

  Selects the FFmpeg stack for packaging. Defaults to "v7.0.0". This Robot always uses at least "v7.0.0"; older stack selections are upgraded automatically.

• width

  string | number | null

  This parameter has no effect on this Robot. Set the rendition width in the preceding 🤖/video/encode Step.

• height

  string | number | null

  This parameter has no effect on this Robot. Set the rendition height in the preceding 🤖/video/encode Step.

• preset

  android | android-high | android-low | android_high | android_low | dash-1080p-video | dash-1080p_video | 195 more ↓

  This parameter has no effect on this Robot. Set the encoding preset in the preceding 🤖/video/encode Step.

• technique

  dash | hls | cmaf(default: "dash")

  Determines which streaming technique should be used. Supports "dash" for MPEG-Dash, "hls" for HTTP Live Streaming and "cmaf" for FFmpeg-based CMAF output with both MPEG-Dash and HLS manifests that reference the same fMP4 segments.

• playlist_name

  string

  The filename for the generated manifest/playlist file. The default is "playlist.mpd" if your technique is "dash", and "playlist.m3u8" if your technique is "hls". For "cmaf", this value names the MPEG-Dash manifest and defaults to "playlist.mpd".

• hls_playlist_name

  string

  Only used when technique is "cmaf". Defines the filename for the generated HLS master playlist. The default is "playlist.m3u8".

• segment_duration

  string | number

  The duration for each segment in seconds. When omitted, defaults to 4 seconds for MPEG-Dash and CMAF, and 10 seconds for HLS.

• closed_captions

  boolean(default: true)

  Determines whether you want closed caption support when using the "hls" technique.

• audio_group

  boolean(default: false)

  When set to true and using the "hls" technique, audio-only input files are treated as alternate audio renditions instead of standalone stream variants. This enables players to offer audio track selection (e.g. for multiple languages). Audio-only files are listed as #EXT-X-MEDIA:TYPE=AUDIO entries in the multivariant playlist, and video variants reference them via the AUDIO attribute.

  When enabled, video inputs only include their video stream in the output segments (any muxed audio is excluded). Provide audio separately as audio-only input files.

  Each rendition’s LANGUAGE comes from the first audio stream’s language tag in its audio-only input file, or "und" when the tag is missing. Set the tag on 🤖/audio/encode with "ffmpeg": {"metadata:s:a:0": "language=deu"}, for example.

  The first audio-only input in use.steps order becomes DEFAULT=YES; the other renditions have DEFAULT=NO. All audio renditions have AUTOSELECT=YES. Their NAME uses the audio stream’s title tag when present, otherwise its language’s English name (for example, "eng" becomes “English” and "deu" becomes “German”). Untagged audio is named “Unknown”; unrecognized language codes are used as the name. Duplicate names receive a numeric suffix.

  This option only enables alternate audio renditions with the "hls" technique and does not change packaging with "dash" or "cmaf". CMAF puts all audio in one adaptation set labeled with the first audio language. Setting audio_group: true with CMAF, or providing CMAF inputs with more than one known audio language (including tracks muxed in a single video), adds an Assembly warning; packaging continues with the existing CMAF output. For multi-language audio, use technique: "hls" with audio_group: true.

Demos

Related blog posts