Skip to content

Transcodificación

El transcodificador de Sapsan (basado en FFmpeg) recodifica el stream de entrada: cambia códecs, bitrate y resolución, y prepara una escalera de calidades multibitrate (MBR) a partir de una sola fuente.

Configuración

La sección transcoder.output describe las pistas de salida. Cada pista toma una fuente (!content video o !content audio) y define un códec:

streams:
  - name: tv1
    inputs:
    - udp: {host: 239.0.0.1, port: 5000}
    transcoder:
      output:
      - source: !content video          # 1080p — la cima de la escalera
        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

Selección de la pista de origen

source Qué toma
!content video / !content audio una pista según el tipo de contenido
!exact v1 una pista concreta por identificador
!best_quality video la mejor calidad disponible
!language_codec [eng, aac] una pista por idioma y códec

El parámetro if_missing define el comportamiento cuando la pista no existe: drop (por defecto — la salida no se crea), blank (señal vacía) o substitute.

Códecs y parámetros

  • codec: !set <name> — recodificar (h264, hevc, av1, aac, opus); codec: same — pasar sin recodificar (por ejemplo, solo reempaquetar el audio).
  • Las salidas de códecs diferentes a partir de una misma fuente mantienen alineados los timestamps y los fotogramas clave — una escalera h264/hevc/av1 se mantiene coherente.
  • gop_size, gop_structure (ip, ibp, ibbp, ibbbp, ibbbbp) — control de la estructura del GOP, importante para los segmentos MBR alineados.
  • Audio: recodificación G.711 → AAC/Opus 48 kHz con conservación de la línea de tiempo — el caso típico de una cámara IP.
  • Las pistas JPEG de capturas pasan por el transcodificador intactas.

Cambio de tamaño

resize Qué hace
!scale escalado exacto a las dimensiones indicadas
!fit encajar conservando la proporción de aspecto (con relleno, color de fondo configurable)
!crop recortar a las dimensiones indicadas

El transcodificador superpone una imagen de logotipo al vídeo — el logotipo del canal en la esquina del fotograma o una marca de agua. El logotipo queda «grabado» en la pista de vídeo: se ve en cualquier dispositivo y llega al archivo. La sección logo vive en los parámetros de vídeo del peldaño y se aplica al fotograma terminado de cada peldaño por separado — después del escalado y de las bandas de fit —, así que el tamaño en píxeles de la imagen no depende de la resolución de salida.

streams:
  - name: tv1
    inputs:
    - udp: {host: 239.0.0.1, port: 5000}
    transcoder:
      output:
      - source: !content video          # 1080p — la cima de la escalera
        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
Campo Qué define
image la dirección de la imagen: una ruta en el nodo, una URL http(s) o una referencia a una entrada de la biblioteca de logotipos logo@<sha256>
position el punto de anclaje en el fotograma — uno de cinco, obligatorio
x, y desplazamientos en píxeles desde el anclaje, 0 por defecto
width, height el tamaño de la imagen en píxeles del fotograma del peldaño

Los anclajes son top_left, top_right, bottom_left, bottom_right y center. Los desplazamientos se cuentan desde el anclaje hacia dentro: en las esquinas, desde la esquina correspondiente; en center, un desplazamiento desde el centro.

El tamaño se da en píxeles del fotograma del peldaño. Con los dos campos — la imagen se ajusta a ellos; con uno — el otro se deriva de la proporción de la imagen, sin distorsión; con ninguno — la imagen se usa en su tamaño nativo. Para que el logotipo ocupe la misma porción del fotograma en toda la escalera, los tamaños de los peldaños se calculan a partir de su altura: en el ejemplo anterior, 72 px a 1080p y 48 px a 720p son la misma porción del fotograma. Los peldaños sin sección logo se quedan como estaban.

Requisitos de la imagen:

  • Formato — PNG o JPEG según la firma de los bytes. Un PNG con canal alfa conserva la transparencia: los píxeles transparentes no tocan el fotograma y los semitransparentes se mezclan con él.
  • Límites — como máximo 1 MB de bytes y 4096 píxeles por lado.
  • La URL se descarga al configurar el peldaño, con un tiempo de espera de 10 segundos.
  • La misma imagen en varios peldaños se carga y se decodifica una sola vez.

Restricciones:

  • El logotipo se superpone solo en una salida con codificación: un peldaño con codec: same y los códecs de emisión en bruto (j2k, v210, uyvy422) no lo soportan — esa sección se rechaza al escribir.
  • width y height son enteros positivos no mayores que 4096; el cero y lo que supera el límite se rechazan al escribir, indicando el campo.
  • La imagen se lee al montar el peldaño, no en cada fotograma: cambiar la dirección, el anclaje o los desplazamientos es una edición ordinaria de la configuración — el peldaño se rearma y el stream sigue.

Un logotipo roto es un error del peldaño

Si la imagen no se puede cargar o decodificar — no hay archivo, la URL no responde, se supera el límite, los bytes no se leen —, el peldaño no se arma: en el estado de la salida y en el registro aparece un error con nombre, mientras los demás peldaños y el propio stream siguen funcionando. El transcodificador nunca servirá el stream sin el logotipo en silencio. La recuperación es editar la dirección de la imagen: la nueva configuración rearma el peldaño sin reiniciar el proceso.

La referencia logo@<sha256> apunta a una entrada de la biblioteca de logotipos de central: el nodo descarga la imagen al aplicar el corte de configuración y entrega al transcodificador un archivo listo. En un nodo suelto (sin central) esa referencia da un error de peldaño con nombre — allí funcionan la ruta en el nodo y la URL http(s). En la consola de Catena el logotipo de la escalera se define con la tarjeta Logotipo de la escalera (Transcodificación y MBR).

Note

TODO: aceleración por hardware (Nvenc/Vulkan), desentrelazado, referencia de parámetros de audio.

Comprobación

Abra el playlist maestro http://server/streaming/v/tv1/index.m3u8 — en él deben aparecer todas las calidades de salida.

Siguientes pasos