Skip to content

Transcoding

The Sapsan transcoder (based on FFmpeg) re-encodes the input stream: changes codecs, bitrate, resolution, and prepares a multibitrate (MBR) ladder from a single source.

Configuration

The transcoder.output section describes output tracks. Each track takes a source (!content video or !content audio) and sets a codec:

streams:
  - name: tv1
    inputs:
    - udp: {host: 239.0.0.1, port: 5000}
    transcoder:
      output:
      - source: !content video          # 1080p — top of the ladder
        codec: !set h264
        bitrate: 2800000
        params: !video
          gop_size: 28
          gop_structure: ibbbp
      - source: !content video          # 720p
        codec: !set h264
        bitrate: 1200000
        params: !video
          gop_size: 28
          gop_structure: ibbbp
          resize: !fit
            height: 720
      - source: !content audio
        codec: !set aac

Source track selection

source What it takes
!content video / !content audio a track by content type
!exact v1 a specific track by id
!best_quality video the best available quality
!language_codec [eng, aac] a track by language and codec

The if_missing parameter sets the behavior when the track is absent: drop (default — the output is not created), blank (empty signal), or substitute.

Codecs and parameters

  • codec: !set <name> — re-encode (h264, hevc, av1, aac, opus); codec: same — pass through without re-encoding (e.g. only repackage audio).
  • Outputs of different codecs from one source keep aligned timestamps and keyframes — an h264/hevc/av1 ladder stays consistent.
  • gop_size, gop_structure (ip, ibp, ibbp, ibbbp, ibbbbp) — GOP structure control, important for aligned MBR segments.
  • Audio: G.711 → AAC/Opus 48 kHz re-encoding with timeline preservation — the typical IP camera case.
  • JPEG screenshot tracks pass through the transcoder untouched.

Resizing

resize What it does
!scale exact scaling to the given dimensions
!fit fit preserving aspect ratio (with padding, background color configurable)
!crop crop to the given dimensions

The transcoder can overlay a logo picture on the video — a channel logo in the corner of the frame or a watermark. The logo is "burned" into the video track: it is visible on every device and lands in the archive. The logo section lives in the video params of an output and is applied to the finished frame of each rung separately — after scaling and fit bars — so the pixel size of the picture does not depend on the output resolution.

streams:
  - name: tv1
    inputs:
    - udp: {host: 239.0.0.1, port: 5000}
    transcoder:
      output:
      - source: !content video          # 1080p — top of the ladder
        codec: !set h264
        bitrate: 2800000
        params: !video
          logo:
            image: /storage/logo.png
            position: top_right
            x: 24
            y: 16
            height: 72
      - source: !content video          # 720p
        codec: !set h264
        bitrate: 1200000
        params: !video
          resize: !fit
            height: 720
          logo:
            image: /storage/logo.png
            position: top_right
            x: 16
            y: 10
            height: 48
Field What it sets
image the address of the picture: a path on the node, an http(s) URL, or a logo library record reference logo@<sha256>
position the anchor on the frame — one of five, mandatory
x, y offsets in pixels from the anchor, 0 by default
width, height the picture size in pixels of the output rung's frame

The anchors are top_left, top_right, bottom_left, bottom_right, center. Offsets are counted from the anchor inward: for the corners from the matching corner, for center a shift from the centre.

The size is given in pixels of the output rung's frame. Both fields set — the picture is scaled to them; one set — the other is derived from the picture's aspect ratio, with no distortion; neither set — the picture is used at its native size. To make the logo take the same share of the frame across the whole ladder, the rung sizes are computed from their height: in the example above, 72 px at 1080p and 48 px at 720p are the same share of the frame. Rungs without a logo section are left as they were.

Picture requirements:

  • Format — PNG or JPEG by byte signature. A PNG with an alpha channel keeps its transparency: transparent pixels leave the frame untouched, semi-transparent ones blend with it.
  • Limits — at most 1 MB of bytes and at most 4096 pixels per side.
  • A URL is fetched when the rung is configured, with a 10-second timeout.
  • The same picture on several rungs is loaded and decoded once.

Restrictions:

  • The logo is overlaid on an encoding output only: a rung with codec: same and the raw broadcast codecs (j2k, v210, uyvy422) do not support it — such a section is rejected on write.
  • width and height are positive integers no greater than 4096; zero and values above the limit are rejected on write, naming the field.
  • The picture is read when the rung is built, not on every frame: changing the address, anchor or offsets is an ordinary configuration edit — the rung is rebuilt, the stream keeps running.

A broken logo is a rung error

If the picture cannot be loaded or decoded — no file, an unresponsive URL, the size limit exceeded, unreadable bytes — the rung is not built: a named error appears in the output state and in the log, while the other rungs and the stream itself keep running. The transcoder will never silently serve the stream without the logo. Recovery is editing the picture address: the new configuration rebuilds the rung with no process restart.

The logo@<sha256> reference points at a central logo library record: the node downloads the picture when it applies the configuration slice and hands the transcoder a ready file. On a standalone node (no central) such a reference yields a named rung error — there the node path and the http(s) URL work. In the Catena console a ladder logo is set with the Ladder logo card (Transcoding and MBR).

Note

TODO: hardware acceleration (Nvenc/Vulkan), deinterlacing, audio parameter reference.

Verification

Open the master playlist http://server/streaming/v/tv1/index.m3u8 — all output qualities should appear in it.

Next steps