FFmpeg video/audio processing via Hot Box containers.

Provides functions for video transcoding, thumbnail extraction, audio extraction, and media probing using ffmpeg in isolated containers.

Each function runs ffmpeg inside a container with appropriate resource sizing. Input files are referenced by hot:// storage URLs and outputs are written back to hot:// storage.

Quick Start

// Probe a media file
info ::ffmpeg/probe("hot://uploads/video.mp4")
tap(info.format.duration)

// Extract a thumbnail
thumb ::ffmpeg/thumbnail("hot://uploads/video.mp4")
tap(thumb.url)

// Transcode to mp4
out ::ffmpeg/transcode("hot://uploads/video.mov", {format: "mp4", codec: "libx264"})
tap(out.url)

// Extract audio as mp3
audio ::ffmpeg/extract-audio("hot://uploads/video.mp4")
tap(audio.url)

// With explicit output path
thumb ::ffmpeg/thumbnail("hot://uploads/video.mp4", {
    output: "hot://media/video-thumb.jpg",
})

Container Requirements

Minimum Size medium

Values

DEFAULT_IMAGE

DEFAULT_IMAGE: Str "jrottenberg/ffmpeg:7-alpine"

Functions

build-extract-audio-args

fn (input-path: Str, output-path: Str, bitrate: Str, sample-rate: Int?, channels: Int?, extra-args: Vec<Str>?): Vec<Str>

Build ffmpeg CLI arguments for audio extraction.

Example

::ffmpeg/build-extract-audio-args("in.mp4", "out.wav", "128k", 16000, 1, null)
// ["-y", "-i", "in.mp4", "-vn", "-b:a", "128k", "-ar", "16000", "-ac", "1", "out.wav"]

build-extract-frames-args

fn (input-path: Str, output-pattern: Str, fps: Str, start: Str?, duration: Int?, width: Int?, height: Int?, quality: Int, extra-args: Vec<Str>?, keyframes-only: Bool?): Vec<Str>

Build ffmpeg CLI arguments for multi-frame image extraction.

Example

::ffmpeg/build-extract-frames-args("in.webm", "frame-%03d.jpg", "1/2", "5", null, 320, null, 2, null, false)
// ["-y", "-i", "in.webm", "-vf", "trim=start=5,fps=1/2,scale=320:-1", "-q:v", "2", "frame-%03d.jpg"]

build-probe-args

fn (input-path: Str): Vec<Str>

Build ffprobe CLI arguments for media probing.

Example

::ffmpeg/build-probe-args("in.mp4")
// ["-v", "quiet", "-print_format", "json", "-show_format", "-show_streams", "in.mp4"]

build-thumbnail-args

fn (input-path: Str, output-path: Str, time: Str, width: Int?, height: Int?, quality: Int, extra-args: Vec<Str>?): Vec<Str>

Build ffmpeg CLI arguments for thumbnail extraction.

Example

::ffmpeg/build-thumbnail-args("in.mp4", "out.jpg", "00:00:05", 320, null, 2, null)
// ["-y", "-i", "in.mp4", "-ss", "00:00:05", "-vframes", "1", "-q:v", "2", "-vf", "scale=320:-1", "out.jpg"]

build-transcode-args

fn (input-path: Str, output-path: Str, opts: TranscodeOpts): Vec<Str>

Build ffmpeg CLI arguments for video transcoding.

Example

::ffmpeg/build-transcode-args("in.mov", "out.mp4", {format: "mp4", codec: "libx264", crf: 23, resolution: "1280x720"})
// ["-y", "-i", "in.mov", "-c:v", "libx264", "-crf", "23", "-vf", "scale=1280:720", "out.mp4"]

extract-audio

fn (input: Str): Map
fn (input: Str, opts: ExtractAudioOpts): Map

Extract the audio track from a video file.

Returns {url: Str, format: Str} with the output file URL in Hot storage.

Example

// Default: extract as MP3 at 192k
audio ::ffmpeg/extract-audio("hot://uploads/video.mp4")
audio.url     // "hot://ffmpeg/<uuid>/audio.mp3"

// Extract as FLAC
audio ::ffmpeg/extract-audio("hot://uploads/video.mp4", {format: "flac"})

// Extract mono WAV at 16kHz (good for speech processing)
audio ::ffmpeg/extract-audio("hot://uploads/video.mp4", {
    format: "wav",
    sample-rate: 16000,
    channels: 1
})
Container: small

extract-frames

fn (input: Str): Map
fn (input: Str, opts: ExtractFramesOpts): Map

Extract multiple image frames from a video.

Returns {frames: Vec<Map>, format: Str, output_prefix: Str}. Each frame has {url, index} where url is a hot:// URL.

Example

frames ::ffmpeg/extract-frames("hot://uploads/window.webm", {
    fps: "1/2",
    format: "jpg",
    output-prefix: "hot://hot-live/frames/window-1"
})
Container: medium

parse-probe-output

fn (stdout: Str?): Map

Parse ffprobe JSON output into a structured Map.

Example

::ffmpeg/parse-probe-output("{\"format\": {\"duration\": \"12.5\"}}").format.duration  // "12.5"
::ffmpeg/parse-probe-output(null)  // {}

probe

fn (input: Str): Map
fn (input: Str, image: Str): Map

Get media file metadata using ffprobe.

Returns a Map containing format and streams information from ffprobe's JSON output: duration, size, bitrate, codecs, resolution, sample rates, etc.

Example

info ::ffmpeg/probe("hot://uploads/video.mp4")
info.format.duration     // "120.500000"
info.format.bit_rate     // "2500000"
info.streams             // [{codec_name: "h264", width: 1920, ...}, ...]
Container: small

start-extract-audio

fn (input: Str): Map
fn (input: Str, opts: ExtractAudioOpts): Map

Start an audio extraction task without awaiting. Returns TaskInfo for use with ::hot::task/await.

Example

info ::ffmpeg/start-extract-audio("hot://uploads/video.mp4", {format: "wav", channels: 1})

result ::hot::task/await(info.id)
result.status
info.data.output  // The hot:// URL the audio is written to
Container: small

start-extract-frames

fn (input: Str): Map
fn (input: Str, opts: ExtractFramesOpts): Map

Start multi-frame image extraction without awaiting. Returns TaskInfo for use with ::hot::task/await.

Example

info ::ffmpeg/start-extract-frames("hot://uploads/window.webm", {
    fps: "1",
    output-prefix: "hot://media/window-1/frames"
})

// stdout is the frame count. Files are frame-001.jpg, frame-002.jpg and so on under the prefix.
result ::hot::task/await(info.id)
Int(trim(result.stdout))
Container: medium

start-probe

fn (input: Str): Map

Start a probe task without awaiting. Returns TaskInfo for use with ::hot::task/await.

Example

info ::ffmpeg/start-probe("hot://uploads/video.mp4")

// Do other work, then collect the result
result ::hot::task/await(info.id)
media ::ffmpeg/parse-probe-output(result.stdout)
media.format.duration
Container: small

start-thumbnail

fn (input: Str): Map
fn (input: Str, opts: ThumbnailOpts): Map

Start a thumbnail extraction task without awaiting. Returns TaskInfo for use with ::hot::task/await.

Example

info ::ffmpeg/start-thumbnail("hot://uploads/video.mp4", {time: "00:00:10", width: 320})

result ::hot::task/await(info.id)
result.status
info.data.output  // The hot:// URL the thumbnail is written to
Container: small

start-transcode

fn (input: Str, opts: TranscodeOpts): Map

Start a transcode task without awaiting. Returns TaskInfo for use with ::hot::task/await.

Example

info ::ffmpeg/start-transcode("hot://uploads/video.mov", {format: "mp4", codec: "libx264"})

result ::hot::task/await(info.id)
result.status
info.data.output  // The hot:// URL the video is written to
Container: medium

thumbnail

fn (input: Str): Map
fn (input: Str, opts: ThumbnailOpts): Map

Extract a thumbnail frame from a video file.

Returns {url: Str, format: Str} with the output file URL in Hot storage.

Example

// Default: first frame at 1 second, JPEG
thumb ::ffmpeg/thumbnail("hot://uploads/video.mp4")
thumb.url     // "hot://ffmpeg/<uuid>/thumbnail.jpg"

// With options
thumb ::ffmpeg/thumbnail("hot://uploads/video.mp4", {
    time: "00:00:10",
    width: 320,
    format: "png"
})
Container: small

transcode

fn (input: Str, opts: TranscodeOpts): Map

Transcode a video file to a different format or encoding.

Returns {url: Str, format: Str} with the output file URL in Hot storage.

Example

// Convert MOV to MP4 with H.264
out ::ffmpeg/transcode("hot://uploads/video.mov", {
    format: "mp4",
    codec: "libx264",
    crf: 23
})
out.url     // "hot://ffmpeg/<uuid>/output.mp4"

// Convert to WebM with VP9
out ::ffmpeg/transcode("hot://uploads/video.mp4", {
    format: "webm",
    codec: "libvpx-vp9",
    audio-codec: "libopus",
    bitrate: "2M"
})
Container: medium

version

fn (): Map
fn (image: Str?): Map

Return ffmpeg version information.

Example

ver ::ffmpeg/version()
ver.version
Container: small

Types

ExtractAudioOpts

ExtractAudioOpts type {
    format: Str?,
    bitrate: Str?,
    sample-rate: Int?,
    channels: Int?,
    output: Str?,
    extra-args: Vec<Str>?,
    image: Str?,
    size: Str?,
    timeout: Int?
}

Options for audio extraction.

Fields

  • format — Output format: "mp3", "aac", "flac", "wav", "opus" (default: "mp3")
  • bitrate — Bitrate, e.g. "192k", "320k" (default: "192k")
  • sample-rate — Sample rate in Hz, e.g. 44100, 48000
  • channels — Number of channels: 1 for mono, 2 for stereo
  • output — Output hot:// URL (default: auto-generated)
  • extra-args — Additional ffmpeg arguments, one token per element
  • image — Custom Docker image with ffmpeg
  • size — Box size override (default: "small")
  • timeout — Execution timeout in seconds (default: 300)

ExtractFramesOpts

ExtractFramesOpts type {
    fps: Str?,
    start: Str?,
    duration: Int?,
    width: Int?,
    height: Int?,
    format: Str?,
    quality: Int?,
    output-prefix: Str?,
    extra-args: Vec<Str>?,
    keyframes-only: Bool?,
    image: Str?,
    size: Str?,
    timeout: Int?
}

Options for extracting multiple image frames from a video.

Fields

  • fps — Frame extraction rate, e.g. "1/2" for one frame every two seconds (default: "1/2")
  • start — Optional start position, e.g. "00:00:05" or "8.5". Applied as a trim filter (accurate on index-less streaming inputs), so the whole input up to this point is still decoded.
  • duration — Optional extraction duration in seconds
  • width — Output width in pixels (default: source width)
  • height — Output height in pixels (default: source height)
  • format — Output format: "jpg", "png", "webp" (default: "jpg")
  • quality — Quality 1-31, lower is better (default: 2)
  • output-prefix — Output hot:// directory/prefix (default: auto-generated)
  • extra-args — Additional ffmpeg arguments, one token per element appended before the output pattern
  • keyframes-only — When true, pass -skip_frame nokey before input so only decodable keyframes are extracted (default: false)
  • image — Custom Docker image with ffmpeg
  • size — Box size override (default: "medium")
  • timeout — Execution timeout in seconds (default: 300)

ThumbnailOpts

ThumbnailOpts type {
    time: Str?,
    width: Int?,
    height: Int?,
    format: Str?,
    quality: Int?,
    output: Str?,
    extra-args: Vec<Str>?,
    image: Str?,
    size: Str?,
    timeout: Int?
}

Options for thumbnail extraction.

Fields

  • time — Seek position, e.g. "00:00:05" (default: "00:00:01")
  • width — Output width in pixels (default: source width)
  • height — Output height in pixels (default: source height)
  • format — Output format: "jpg", "png", "webp" (default: "jpg")
  • quality — Quality 1–31, lower is better (default: 2)
  • output — Output hot:// URL (default: auto-generated)
  • extra-args — Additional ffmpeg arguments, one token per element
  • image — Custom Docker image with ffmpeg (default: jrottenberg/ffmpeg:7-alpine)
  • size — Box size override (default: "small")
  • timeout — Execution timeout in seconds (default: 300)

TranscodeOpts

TranscodeOpts type {
    format: Str,
    codec: Str?,
    audio-codec: Str?,
    bitrate: Str?,
    audio-bitrate: Str?,
    resolution: Str?,
    preset: Str?,
    crf: Int?,
    output: Str?,
    extra-args: Vec<Str>?,
    image: Str?,
    size: Str?,
    timeout: Int?
}

Options for video transcoding.

Fields

  • format — Output format, e.g. "mp4", "webm", "mkv" (required)
  • codec — Video codec, e.g. "libx264", "libvpx-vp9" (default: auto)
  • audio-codec — Audio codec, e.g. "aac", "libopus" (default: auto)
  • bitrate — Video bitrate, e.g. "2M", "500k"
  • audio-bitrate — Audio bitrate, e.g. "128k", "192k"
  • resolution — Output resolution, e.g. "1280x720"
  • preset — Encoding preset, e.g. "fast", "medium", "slow"
  • crf — Constant Rate Factor 0–51 (default: 23 for x264)
  • output — Output hot:// URL (default: auto-generated)
  • extra-args — Additional ffmpeg arguments, one token per element
  • image — Custom Docker image with ffmpeg
  • size — Box size override (default: "medium")
  • timeout — Execution timeout in seconds (default: 300)