Runtime transcode module

transcode can repair browser compatibility when measured keyframe cadence, Layer II audio, or an explicit canonical video target requires it. This module does not generate an ABR ladder.

For container deployments, use the matching Server image with the -transcode suffix or a compatible custom image that supplies the required FFmpeg build. The unsuffixed image intentionally contains no FFmpeg binary. The configured encoder profile must pass startup probes in either case.

Disabled configuration starts no probe or subprocess. Enabled configuration performs an encode probe during startup and fails startup when the selected CPU or GPU profile is unavailable.

"transcode": {
  "enabled": true,
  "hevcInput": false,
  "encoderProfile": "cpu",
  "videoTarget": {
    "schemaVersion": 1,
    "codec": "h264",
    "h264": {
      "profile": "constrained-baseline",
      "level": "3.1",
      "pixelFormat": "yuv420p",
      "scan": "progressive",
      "scaling": "preserve-no-upscale",
      "maxWidth": 1280,
      "maxHeight": 720,
      "maxFrameRate": 30,
      "maxBFrames": 0,
      "maxKeyframeInterval": "2s"
    }
  },
  "ffmpegPath": "ffmpeg",
  "maxWorkers": 1,
  "maxAddressSpaceBytes": 4294967296,
  "queueSize": 0,
  "policy": {
    "defaultMode": "always",
    "streams": {"tenant:already-fine": "auto", "tenant:excluded": "never"}
  }
}

This module requires an offline full license. See licensing for setup and validity.

videoTarget is optional. When omitted, auto keeps the compatibility-only cadence policy. When present, version 1 accepts exactly the H.264 object shown above. Unknown fields, omitted target fields, unsupported values, and unsupported codec variants fail configuration validation.

The target is media intent, while encoderProfile selects its CPU or GPU implementation. The current H.264 target requires Constrained Baseline through Level 3.1, progressive 8-bit 4:2:0 pictures, no B-frames, at most 1280 by 720 at 30 frames per second, aspect-ratio-preserving downscale without upscale, and the configured maximum keyframe interval. Startup probes encode and inspect this target before the node starts. auto bypasses only a source whose current normalized generation has a complete matching measurement and compatible IDR cadence.

policy.defaultMode: "always" forces video normalization for every eligible video stream, including sources that already match the target. It requires enabled transcode and an explicit supported videoTarget; a disabled section with a forced default is rejected. auto retains the measured bypass; never excludes the stream. Per-stream overrides can choose either mode, and per-stream always remains available without a target for legacy compatibility repair. Audio-only streams without Layer II audio have no video to encode. Existing process-wide worker, queue, restart, and timeout limits still apply.

The example allows one worker with a 4 GiB per-process address-space ceiling. In a local 1280 by 720 CPU test, the default 2 GiB ceiling caused a failed encode and transport fallback; 4 GiB succeeded with the default stall and no-media windows. This is a measurement on one host, not a capacity recommendation. Size maxWorkers, maxAddressSpaceBytes, and the target for the deployment hardware before selecting a forced default. Startup's short capability probe does not establish full-size live throughput.

The effective target and its deterministic SHA-256 fingerprint appear in GET /api/v1/features. An active repair includes the same target in stream detail diagnostics. The fingerprint is part of worker ownership but is not used as a metric label.

videoTarget and hevcInput cannot currently be enabled together. HEVC conversion remains a separate input compatibility path.

A source connection receives at most one compatibility-repair attempt. The original source split owns that attempt even after its worker output enters under a new registry generation. A normal transport end does not suppress repair on the next connection. A source-to-worker write failure or buffer overflow retains the one-minute failure suppression window across reconnects.

Releasing the stream clears its source-split ownership before closing the transport, output pipe and worker lease. A late feeder completion still emits its repair-end observation, but cannot change a replacement connection's backoff. Worker process retirement and drain remain owned by the transcode manager; this rule does not bypass its capacity, queue or watchdog bounds. Managed-pull reconnect remains owned by the source-pull manager.

hevcInput is disabled by default. When both enabled and hevcInput are true, local push and managed-pull inputs may convert a bounded HEVC Main source to the normal H.264 MPEG-TS ingest profile with its supported audio tracks before strict demux. The visible video envelope includes progressive HEVC Main profile at Main tier through Level 4.1, 8-bit 4:2:0, 16 by 16 through 1920 by 1080 display dimensions, even width and height, and measured cadence from 1 through 60 frames per second. The source must provide usable VPS, SPS, PPS, VUI timing, and an IRAP picture during the bounded probe. Additional probe, buffering, NALU, timestamp, and decoder-picture bounds also fail closed; a rejected source is not passed through as native HEVC. This mode requires videoTarget to be absent.

This option does not add HEVC output. Every downstream module still receives the converted H.264 profile, and the same process-wide transcode worker limit applies.

queueSize: 0 rejects new repair demand immediately when all workers are busy. Worker limits should be selected from measurements on the deployment hardware.

A positive queueSize bounds distinct worker identities waiting for capacity. Concurrent demand for the same stream, source generation, profile, and target shares one pending reservation. It consumes no additional queue places. Cancellation removes the owning caller's reservation and lets remaining callers retry admission; shutdown wakes all queued callers. An immediately free worker slot does not consume a queue place.

See the runtime configuration rules and complete configuration.

The complete field reference covers every accepted option; the maximal composition shows how modules fit together.