Skip to content

Logo overlay

media.transcode.logo

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

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.

In a central-managed cluster, use the logo library as the main delivery method. Upload the picture once in the central console and select it in the Ladder logo card. Central stores the picture, while the stream config contains image: logo@<sha256>. Sapsan downloads missing pictures over the authenticated central synchronization channel, verifies their SHA-256 and caches them locally. You do not need to copy the file to every streamer.

For API configuration, upload JSON with name and bytes (standard base64 image bytes) to POST /central/api-v4/logos, using management authentication. The response contains key and created; set logo.image to logo@ followed by that key. GET /central/api-v4/logos lists library entries; GET /central/api-v4/logos/{key} returns an entry with base64 picture bytes for preview. A local path or an HTTP(S) URL is an alternative, including for a standalone Sapsan without central.

The example uses a placeholder: replace <sha256> with the key returned by central.

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: logo@<sha256>
            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: logo@<sha256>
            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 central console a ladder logo is set with the Ladder logo card (Logo overlay).