Saltar a contenido

live-common: Módulo NGINX Común del Marco de Medios Kaltura

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:

  • RedHat Enterprise Linux 7, 8, 9 y 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 y Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-live-common

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-live-common

Habilita el módulo añadiendo lo siguiente al principio de /etc/nginx/nginx.conf:

load_module modules/ngx_http_api_module.so;

Este documento describe nginx-module-live-common v2.0.6 lanzado el 13 de noviembre de 2025.

Estado de Construcción

Un marco distribuido para la transmisión de video en vivo. El sistema está compuesto por múltiples componentes, cada uno responsable de una función específica.

Los componentes pueden desplegarse en un solo servidor para implementaciones/pruebas a pequeña escala, pero se recomienda desplegarlos por separado para una utilización de recursos más óptima. Por ejemplo, el transcodificador puede utilizar la GPU, por lo que sería más rentable desplegar los transcodificadores en servidores habilitados para GPU, mientras que los otros componentes funcionarían en servidores sin GPU.

Los medios se transmiten entre los diferentes componentes internamente utilizando protocolos personalizados - 1. Kaltura Media Protocol (KMP) - un protocolo basado en TCP para la entrega de medios en streaming, conceptualmente, similar a una sola pista de fMP4/MPEG-TS 2. Kaltura Segmented Media Protocol (KSMP) - un protocolo basado en HTTP para la entrega de medios en segmentos, conceptualmente, un superconjunto de LLHLS/DASH

La orquestación de los diferentes componentes de medios es realizada por un "controlador". La principal responsabilidad del controlador es construir la topología de la tubería de medios y actualizarla en caso de fallos. El controlador recibe eventos JSON de los componentes de medios enviados como HTTP-POSTs. Además, todos los componentes de procesamiento de medios exponen una API REST basada en JSON, que es utilizada por el controlador para obtener el estado más reciente y tomar acciones. Se proporciona una implementación de muestra del controlador para un servidor todo en uno en la carpeta conf.

Características Principales

  • Protocolos de publicación: RTMP, MPEGTS (sobre SRT/HTTP/TCP)
  • Protocolos de reproducción: HLS/LLHLS, DASH
  • Protocolos de empuje/retransmisión en vivo: RTMP
  • Transcodificación de video/audio - incluyendo soporte para GPU, basado en la API de ffmpeg
  • Persistencia - en almacenamiento de objetos S3 (o compatible)
  • Entrega de bitrate adaptativo
  • Soporte de subtítulos - incluyendo conversión de 608/708 a WebVTT
  • Audio alternativo
  • Cifrado de medios y DRM
  • Captura de fotogramas de video

Comenzando

La carpeta conf contiene código de muestra y configuración para ejecutar un servidor todo en uno.

Glosario

  • Canal - un contenedor que representa una transmisión en vivo, puede contener pistas, variantes, líneas de tiempo, etc.
  • Pista - una única representación de video/audio/subtítulo. Por ejemplo, un canal puede tener 3 pistas de video: 1080p, 720p, 540p.
  • Variante - un agrupamiento de pistas utilizado para empaquetar. Las variantes determinan qué pista de audio se emparejará con cada pista de video, cuando se utilizan segmentos multiplexados. Una variante puede apuntar a múltiples pistas, pero no más de una pista por tipo de medio. Las pistas deben estar asociadas a variantes para ser entregadas a través de HLS/DASH.
  • Segmento - un grupo de fotogramas de una pista específica. Los segmentos son siempre independientes - los segmentos de video siempre comenzarán con un fotograma clave/IDR.
  • Índice de segmento - un número que identifica los segmentos de las diferentes pistas que están asociados con un intervalo de tiempo específico.
  • Período - un conjunto de índices de segmento que pueden reproducirse continuamente.
  • Línea de tiempo - un conjunto de períodos. Se pueden crear múltiples líneas de tiempo, cada una con su propio conjunto de períodos. Las líneas de tiempo pueden ser utilizadas, por ejemplo, para implementar el "modo de vista previa" - el publicador consume una línea de tiempo, mientras que los espectadores consumen otra. La línea de tiempo del publicador siempre está activa, mientras que la línea de tiempo de los espectadores se activa a discreción del publicador.

Topologías de Ejemplo

Los diagramas a continuación demuestran algunas topologías de ejemplo que se pueden crear utilizando los componentes del Marco de Medios.

Passthrough RTMP Simple

flowchart LR;
    enc(Encoder);
    ingest(nginx-rtmp-kmp-module);
    live(nginx-live-module);
    pckg(nginx-pckg-module);
    play(Player);
    enc-->|RTMP|ingest;
    ingest-->|KMP|live;
    live-->|KSMP|pckg;
    pckg-->|LLHLS/DASH|play;

Passthrough + Persistencia S3

flowchart LR;
    enc(Encoder);
    ingest(nginx-rtmp-kmp-module);
    live(nginx-live-module);
    pckg(nginx-pckg-module);
    s3(Amazon S3);
    play(Player);
    enc-->|RTMP|ingest;
    ingest-->|KMP|live;
    live-->|HTTP|s3;
    s3-->|HTTP|live;
    live-->|KSMP|pckg;
    pckg-->|LLHLS/DASH|play;

Entrada SRT + Transcodificación de Video

flowchart LR;
    enc(Encoder);
    ingest(nginx-mpegts-kmp-module);
    srt(nginx-srt-module);
    trans(transcoder);
    live(nginx-live-module);
    pckg(nginx-pckg-module);
    play(Player);
    enc-->|SRT|srt;
    srt-->|MPEG-TS|ingest;
    ingest-->|KMP video|trans;
    trans-->|KMP video|live;
    ingest-->|KMP audio|live;
    live-->|KSMP|pckg;
    pckg-->|LLHLS/DASH|play;

Decodificación de Subtítulos Cerrados

flowchart LR;
    enc(Encoder);
    ingest(nginx-rtmp-kmp-module);
    cc(nginx-cc-module);
    live(nginx-live-module);
    pckg(nginx-pckg-module);
    play(Player);
    enc-->|RTMP|ingest;
    ingest-->|KMP video|cc;
    cc-->|KMP subtitle|live;
    ingest-->|KMP video|live;
    ingest-->|KMP audio|live;
    live-->|KSMP|pckg;
    pckg-->|LLHLS/DASH|play;

Transcodificación + Empuje RTMP

flowchart LR;
    enc(Encoder);
    ingest(nginx-mpegts-kmp-module);
    trans(transcoder);
    live(nginx-live-module);
    pckg(nginx-pckg-module);
    push(nginx-kmp-rtmp-module);
    yt(YouTube);
    play(Player);
    enc-->|MPEG-TS/HTTP|ingest;
    ingest-->|KMP|trans;
    trans-->|KMP|live;
    trans-->|KMP|push;
    push-->|RTMP|yt;
    live-->|KSMP|pckg;
    pckg-->|LLHLS/DASH|play;

Descripción General de Componentes

Componentes de Medios

  • nginx-rtmp-kmp-module - ingestión de medios en vivo, entrada: RTMP, salida: KMP x N

  • nginx-mpegts-kmp-module - ingestión de medios en vivo, entrada: MPEG-TS sobre TCP/HTTP, salida: KMP x N

  • transcoder - transcodificación de video/audio, entrada: KMP, salida: KMP x N

  • nginx-live-module - segmentador de medios en vivo, entrada: KMP x N, salida: KSMP

    Características adicionales: persistencia, relleno, soporte de líneas de tiempo.

  • nginx-pckg-module - empaquetador de medios en vivo (sin estado), entrada: KSMP, salida: HLS/LLHLS, DASH

    Características adicionales: bitrate adaptativo, subtítulos, audio alternativo, cifrado de medios / DRM, captura de fotogramas de video

  • nginx-kmp-cc-module - decodificador de subtítulos cerrados, entrada: KMP video (h264/5), salida: KMP subtitle (WebVTT) x N

  • nginx-kmp-rtmp-module - retransmisión de medios en vivo, entrada: KMP x N, salida: RTMP

Importante: Todos los componentes basados en nginx con estado (=todos excepto nginx-pckg-module), deben desplegarse en un servidor nginx de un solo proceso (worker_processes 1;). El estado del módulo se mantiene por proceso, y cuando se utilizan múltiples procesos, no es posible controlar qué proceso recibirá la solicitud. Por ejemplo, la solicitud para crear un canal en el segmentador puede llegar al trabajador 1, mientras que la conexión KMP con los medios reales, llegará al trabajador 2. En implementaciones que utilizan contenedores, esto no debería ser un problema: múltiples contenedores pueden desplegarse en un solo servidor, en lugar de utilizar múltiples procesos nginx. Otra posibilidad es utilizar un parche como el listener por trabajador de arut, pero probablemente necesitará ser actualizado para aplicarse también a conexiones stream.

Opciones de Depuración

Algunos de los componentes del Marco de Medios admiten macros de preprocesador opcionales para fines de depuración - - NGX_LBA_SKIP (nginx-common) - Omite el uso del módulo "Large Buffer Array" (LBA). Cuando está habilitado, las asignaciones de LBA se dirigen a ngx_alloc / ngx_free. - NGX_RTMP_VERBOSE (nginx-rtmp-module) - Habilita mensajes de registro de depuración adicionales - NGX_LIVE_VALIDATIONS (nginx-live-module) - Habilita comprobaciones de consistencia en tiempo de ejecución en estructuras de datos internas, habilitado por defecto al usar --with-debug - NGX_BLOCK_POOL_SKIP (nginx-live-module) - Omite el uso de grupos de bloques. Cuando está habilitado, las asignaciones de grupos de bloques se dirigen a ngx_palloc / ngx_pfree.

Para probar los módulos con valgrind, se recomienda aplicar el parche no-pool-nginx, y configurar nginx con --with-cc-opt="-O0 -DNGX_BLOCK_POOL_SKIP -DNGX_LBA_SKIP" y --with-debug.

Kaltura Media Protocol (KMP)

Kaltura Media Protocol es un protocolo simple basado en paquetes para transmitir medios a través de TCP. Una conexión KMP puede entregar los medios de una sola pista de video/audio/subtítulo - cuando se necesitan múltiples pistas, se establecen múltiples conexiones TCP.

Cada paquete comienza con un encabezado que contiene los siguientes campos (32 bits cada uno) - - Tipo - el tipo del paquete. Los tipos de paquete son códigos de cuatro caracteres, ver a continuación la lista de tipos actualmente definidos. - Tamaño del encabezado - el tamaño del encabezado del paquete, debe estar entre sizeof(kmp_packet_header_t) y 64KB. Los analizadores deben usar el tamaño del encabezado para acceder a los datos del paquete, esto permite la adición de nuevos campos a los encabezados de los paquetes sin romper los analizadores existentes. - Tamaño de los datos - el tamaño de los datos del paquete, debe estar entre 0 y 16MB. - Reservado - reservado para uso futuro, debe establecerse en 0.

Las estructuras y constantes utilizadas en KMP se pueden encontrar en ngx_live_kmp.h.

Identificadores de Fotogramas KMP

Un identificador de fotograma es un entero de 64 bits que identifica de manera única un fotograma de entrada. Los módulos de ingestión (nginx-rtmp-kmp-module / nginx-mpegts-kmp-module) asignan el identificador de fotograma inicial de acuerdo con el reloj del servidor (en unidades de escala de tiempo), cuando se crea una pista de salida. Para evitar la necesidad de enviar el identificador de fotograma en cada fotograma que se envía, los identificadores de fotograma en KMP son secuenciales - el identificador del N-ésimo fotograma que se envía en una conexión KMP es initial_frame_id + N.

Si la conexión de entrada (por ejemplo, RTMP) se cae y se restablece, se asignarán nuevos identificadores de fotograma KMP. Dado que la escala de tiempo predeterminada es alta (90kHz), y es poco probable que la tasa de fotogramas supere los 60fps, incluso en caso de una reconexión después de un corto período de transmisión, el identificador de fotograma inicial será significativamente mayor que el identificador de fotograma que se envió por última vez en la conexión anterior. Por lo tanto, es extremadamente poco probable que haya un conflicto con identificadores de fotograma utilizados anteriormente debido a la reconexión.

Los identificadores de fotograma se utilizan: - Para identificar qué fotogramas están siendo reconocidos en los paquetes de reconocimiento KMP - Para omitir fotogramas previamente manejados si se restablece una conexión KMP

El transcodificador añade algunas complejidades a la gestión de identificadores de fotograma - - Dado que el transcodificador puede cambiar la tasa de fotogramas de entrada o eliminar fotogramas, los identificadores de fotograma en la entrada del transcodificador, no son necesariamente los mismos que los identificadores de fotograma en la salida del transcodificador. Si se reinicia el transcodificador, necesita saber qué valor enviar como initial_frame_id de su servidor ascendente (generalmente nginx-live-module). El campo upstream_frame_id se utiliza para este propósito. - El transcodificador puede configurarse para cambiar la tasa de muestreo de una pista de audio, y, en este caso, los fotogramas transcodificados no se alinean con los fotogramas de entrada. Para manejar este escenario, el transcodificador necesita tener la capacidad de reconocer solo una parte de un fotograma de entrada. Este es el propósito del campo offset - puede almacenar, por ejemplo, el número de muestras de audio que deben ser reconocidas dentro del fotograma. El significado exacto del campo offset es determinado por el receptor KMP - el receptor establece el offset en los fotogramas de reconocimiento que devuelve, y lo recibe de vuelta en el campo initial_offset del paquete de conexión, en caso de reconexión.

Paquetes KMP del Publicador

Las secciones a continuación enumeran los paquetes KMP que pueden ser enviados por un publicador KMP.

Conectar (cnct)

Enviado inmediatamente después de que se establece la conexión TCP KMP.

El encabezado contiene los siguientes campos: - channel_id - cadena, el identificador del canal que se está publicando. La longitud máxima permitida es de 32 caracteres. - track_id - cadena, el identificador de la pista que se está publicando. La longitud máxima permitida es de 32 caracteres. - initial_frame_id - entero, el identificador del primer fotograma que se envía. - initial_upstream_frame_id - entero, el identificador de fotograma inicial que debe enviarse al servidor ascendente (utilizado por el transcodificador) - initial_offset - entero, el desplazamiento desde el cual comenzar, dentro del fotograma inicial. - flags - entero, una máscara de bits de flags, actualmente se define un solo flag - consistent - este flag se establece cuando el publicador KMP genera una salida consistente (exacta en bits), dado el mismo input. nginx-rtmp-kmp-module y nginx-mpegts-kmp-module son ejemplos de publicadores que son consistentes. El transcodificador, por otro lado, no lo es. El flag consistent es utilizado por el segmentador LL en caso de reconexión. Cuando el publicador es consistente, el segmentador LL puede continuar desde el punto donde se detuvo. Cuando el publicador es inconsistente, el segmentador LL puede continuar solo desde el siguiente GOP - no debe mezclar un GOP parcial de antes de la desconexión, con el GOP recibido después de la desconexión.

Los datos del paquete de conexión son opcionales, el formato esperado de los datos está definido por el receptor KMP específico.

Información de Medios (minf)

Contiene los parámetros de los medios. Algunos de los campos en el encabezado son compartidos por todos los tipos de medios, mientras que el resto se define solo para un tipo específico (unión).

Los campos de encabezado compartidos son: - media_type - entero, el tipo de medio - video / audio / subtitle, utiliza las constantes KMP_MEDIA_XXX. - codec_id - entero, el identificador del códec, utiliza las constantes KMP_CODEC_XXX. - timescale - entero, las unidades utilizadas en los campos dts / pts_delay / created de los paquetes de fotogramas, en Hz. - bitrate - entero, el bitrate, en bits por segundo.

Los campos de encabezado específicos de video son: - width - entero, el ancho del video, en píxeles. - height - entero, la altura del video, en píxeles. - frame_rate - racional, la tasa de fotogramas del video, en fotogramas por segundo. - cea_captions - booleano, establecido en 1 cuando la pista de video contiene subtítulos EIA-608 / CTA-708.

Los campos de encabezado específicos de audio son: - channels - entero, el número de canales de audio. - bits_per_sample - entero, el tamaño de las muestras de audio, en bits. - sample_rate - entero, la tasa de muestreo del audio, en muestras por segundo. - channel_layout - entero, una máscara de bits de posiciones de canal, utiliza las constantes KMP_CH_XXX.

Los datos del paquete de información de medios contienen los datos privados/adicionales del códec. Por ejemplo, al utilizar el códec h264, los datos contienen el cuerpo de un contenedor avcC de MP4.

Los receptores KMP deben manejar los cambios en la información de medios, por ejemplo, un cambio en la resolución de video. Sin embargo, el tipo de medio (video/audio/subtítulo) que se envía en una conexión KMP, no debe cambiar.

Los receptores KMP deben ignorar los paquetes de información de medios, cuando son idénticos al paquete de información de medios recibido anteriormente.

Fotograma (fram)

Representa un único fotograma de video / fotograma de audio / indicación de subtítulo.

El encabezado del fotograma contiene los siguientes campos: - created - entero, el tiempo en el que el fotograma fue recibido por el primer módulo del Marco de Medios en la tubería, en unidades de escala de tiempo. - dts - entero, la marca de tiempo de decodificación del fotograma, en unidades de escala de tiempo. Cuando el tipo de medio es subtitle, contiene la marca de tiempo de inicio de la indicación. - flags - entero, actualmente solo se define un flag - key - habilitado en los fotogramas clave de video. - pts_delay - entero, la diferencia entre la marca de tiempo de presentación del fotograma y la marca de tiempo de decodificación, en unidades de escala de tiempo. Cuando el tipo de medio es subtitle, contiene la duración de la indicación - end_pts - start_pts.

Cuando el tipo de medio es video / audio, los datos del paquete de fotograma contienen los medios comprimidos. Cuando el tipo de medio es subtítulo y el códec es WebVTT, los datos del fotograma siguen el Formato de Muestra WebVTT, como se especifica en ISO/IEC 14496-30 (normalmente, en este caso, una muestra es un contenedor vttc, que contiene un contenedor payl).

Nulo (null)

Enviado para señalar "vitalidad", y prevenir que los temporizadores de inactividad expiren. Los paquetes nulos no llevan ningún dato aparte del encabezado básico KMP. Los analizadores deben ignorar los paquetes nulos.

Fin de Transmisión (eost)

Utilizado para señalar una terminación ordenada de la sesión de publicación. Los paquetes de fin de transmisión no llevan ningún dato aparte del encabezado básico KMP.

Paquetes KMP del Receptor

Las secciones a continuación enumeran los paquetes KMP que pueden ser enviados por un receptor KMP.

Fotogramas de Reconocimiento (ackf)

Reconocen la recepción de fotogramas.

El receptor KMP decide el momento apropiado para enviar un paquete de reconocimiento. Por ejemplo, cuando la persistencia está habilitada, el segmentador envía un reconocimiento solo después de que se guarda un segmento que contiene el fotograma en el almacenamiento.

Algunos receptores no envían reconocimientos en absoluto, en este caso, el productor KMP debe configurarse para descartar los fotogramas después de que se envían (usando la configuración resume_from)

El encabezado del paquete contiene los siguientes campos: - frame_id - entero, el identificador del primer fotograma que debe ser reenviado si la conexión se cae. En otras palabras, un paquete de fotogramas de reconocimiento, reconoce todos los fotogramas que tienen un identificador que es menor que frame_id. Si la conexión KMP se restablece, este valor se enviará en el campo initial_frame_id. - upstream_frame_id - entero, el identificador del fotograma que fue enviado al servidor ascendente. Si la conexión KMP se restablece, este valor se enviará en el campo initial_upstream_frame_id. - offset - entero, el desplazamiento a reconocer dentro del fotograma. Si la conexión KMP se restablece, este valor se enviará en el campo initial_offset. - padding - entero, reservado para uso futuro, debe establecerse en cero.

Los datos de los paquetes de reconocimiento no se utilizan.

Kaltura Segmented Media Protocol (KSMP)

Kaltura Segmented Media Protocol es un protocolo basado en HTTP para entregar medios en segmentos, de manera similar a HLS/DASH.

Una solicitud KSMP es una solicitud HTTP GET, se definen los siguientes parámetros de consulta - - channel_id - cadena requerida, el identificador del canal - timeline_id - cadena requerida, el identificador de la línea de tiempo - flags - entero hexadecimal requerido, los flags: - Seleccionar el subconjunto de datos que se requiere (como la lista de columnas en una declaración SQL SELECT) - Controlar varios comportamientos al atender la solicitud. Por ejemplo, el flag 'closest key', devuelve solo el fotograma clave que está más cerca de la marca de tiempo de la solicitud, en lugar de devolver todo el segmento. - variant_ids - cadena opcional, selecciona un subconjunto de las variantes que deben ser devueltas, por defecto, se devuelven todas las variantes. Si se especifican múltiples variantes, deben estar delimitadas con un guion (-). - media_type_mask - entero hexadecimal opcional, establece los tipos de medios que deben ser devueltos, por defecto, se devuelven todos los tipos de medios. - time - entero opcional, la marca de tiempo solicitada. La marca de tiempo se utiliza, por ejemplo, para capturar un fotograma de video en un momento específico. - segment_index - entero opcional, el índice del segmento - max_segment_index - entero opcional, utilizado para limitar el alcance de los segmentos devueltos en la respuesta. Este parámetro se puede utilizar para reproducir un flujo persistente para depuración. - part_index - entero opcional, el índice basado en cero del segmento parcial dentro del segmento. Una solicitud que utiliza part_index también debe enviar segment_index. - skip_boundary_percent - entero opcional, establece el valor de skip boundary como un porcentaje de la duración objetivo (ver la definición del atributo CAN-SKIP-UNTIL en la especificación HLS para más detalles) - padding - entero opcional, añade bytes cero adicionales al final de la respuesta. Utilizado para cumplir con los requisitos de relleno de ffmpeg sin incurrir en operaciones de copia adicionales.

Una respuesta KSMP utiliza el formato KLPF (ver más abajo), con tipo Serve (serv). Las definiciones específicas de KSMP se pueden encontrar en ngx_ksmp.h

Kaltura Live Persist File (KLPF)

Kaltura Live Persist File es un esquema de serialización que se utiliza en las respuestas KSMP y en los objetos S3 creados por nginx-live-module.

Un KLPF está compuesto de bloques, similar a átomos/cajas de MP4. Cada bloque tiene el siguiente encabezado - - id - un código de cuatro caracteres que identifica el bloque - size - uint32, el tamaño completo del bloque (encabezado y datos) - flags - 4 bits, se definen los siguientes flags: - container (0x1) - el bloque contiene otros bloques - index (0x2) - el bloque es un índice a otro bloque, no se debe usar el tamaño del encabezado - compressed (0x4) - los datos del bloque están comprimidos con zlib - header_size - 28 bits, el tamaño del encabezado del bloque. Los analizadores deben usar el tamaño del encabezado para acceder a los datos del bloque, de modo que se puedan agregar campos al encabezado sin romper la compatibilidad

Un archivo KLPF es un bloque cuyo id está establecido en klpf. Siguiendo los campos del encabezado del bloque genérico (enumerados arriba), un archivo KLPF tiene los siguientes campos en su encabezado - - uncomp_size - uint32, contiene el tamaño no comprimido de los datos, cuando los datos KLPF están comprimidos - version - uint32, la versión del formato del archivo. La versión utilizada para nuevos archivos se actualiza en cada cambio que rompa el formato, el código se actualizará para - soportar la lectura tanto del nuevo formato como del antiguo formato, o - ignorar archivos que utilizan el antiguo formato - type - un código de cuatro caracteres que identifica el tipo de datos almacenados en el KLPF. El tipo determina qué identificadores de bloque son soportados y su estructura interna. El tipo serv (Serve) se utiliza para respuestas KSMP, en la comunicación entre el empaquetador y el segmentador. Se utilizan tipos adicionales internamente por el segmentador. - created - uint64, la marca de tiempo unix cuando se creó el KLPF

Para más detalles sobre la estructura interna de los bloques KLPF, ver KLFP-SPEC.md.

Para inspeccionar el contenido de los objetos KLPF/respuestas KSMP, utiliza klpf_parse.py. El script puede mostrar la estructura del bloque sin información adicional, sin embargo, para analizar los campos dentro de los bloques: - ejecuta generate_persist_spec.py, y guarda la salida en un archivo - proporciona el nombre del archivo a klpf_parse.py usando la opción -s / --spec-file

Descripción General de la API

Todos los componentes de procesamiento de medios exponen una API REST basada en JSON. Esta sección explica las propiedades generales de las APIs del Marco de Medios. Para una referencia detallada de los puntos finales de la API disponibles, consulta la documentación de los módulos específicos.

Tipos de Solicitud

Los siguientes verbos HTTP se utilizan en la API: - GET - obtener el estado completo del módulo, o un subconjunto de él. Se puede agregar el argumento ?pretty=1 a la solicitud, para devolver la respuesta en un formato "bonito" / indentado. - GET con ?list=1 - devolver los nombres de las "carpetas" bajo una cierta ruta en la API. Puede ser utilizado para recorrer el árbol de posibles rutas de API. - POST - crear un objeto. - PUT - actualizar un objeto, el id del objeto a actualizar se pasa en la URI. - DELETE - eliminar un objeto, el id del objeto a eliminar se pasa en la URI.

El cuerpo de la solicitud en las solicitudes POST / PUT debe ser un JSON (generalmente un objeto), y la solicitud debe usar el encabezado Content-Type: application/json.

Cuando el tamaño del cuerpo de la solicitud excede un cierto umbral, nginx lo escribe en un archivo temporal. Sin embargo, la implementación de la API del Marco de Medios requiere que el cuerpo de la solicitud de las solicitudes POST / PUT esté disponible en memoria. Si es necesario, se puede utilizar la directiva client_body_buffer_size de nginx para aumentar el tamaño del búfer asignado para el cuerpo de la solicitud.

Solicitud Múltiple

Configurar un canal en nginx-live-module puede requerir múltiples llamadas a la API - crear el canal, crear una línea de tiempo, crear una variante, etc. Para evitar la penalización de múltiples viajes de ida y vuelta, la capa de API tiene soporte para solicitudes "múltiples". Una solicitud múltiple agrupa varias solicitudes de API en una sola solicitud HTTP.

Las solicitudes múltiples deben usar el verbo POST, y su URI debe estar configurada en /multi. El cuerpo de la solicitud debe ser un array JSON de objetos, cada objeto representa una única solicitud de API.

Los objetos contienen los siguientes campos: - uri - cadena, requerida, la ruta relativa de la API. - method - cadena, requerida, el verbo HTTP de la solicitud - GET / POST / PUT / DELETE. - body - cualquier (generalmente objeto), opcional, el cuerpo de las solicitudes POST / PUT.

La respuesta de las solicitudes múltiples también es un array JSON de objetos. El número de elementos en el array de respuesta siempre coincide con el número de elementos en el array de solicitud, y el orden de los objetos en el array de respuesta coincide con el orden en el array de solicitud. En otras palabras, el N-ésimo elemento del array de respuesta, es la respuesta de la N-ésima solicitud en el array de solicitud.

Cada objeto de respuesta contiene los siguientes campos: - code - entero, requerido, el código de estado HTTP - body - cualquier (generalmente objeto / array), opcional, el cuerpo de la respuesta

GitHub

Puedes encontrar consejos de configuración adicionales y documentación para este módulo en el repositorio de GitHub para nginx-module-live-common.