MPTS Migrate Perfect Streamer Toolkit v1.2 — migración de la identidad MPTS

Parte del Perfect Streamer Toolkit — https://meshwork.pstreamer.tv

Captura los identificadores DVB SI/PSI de un flujo MPEG-TS multiprograma (MPTS) en funcionamiento y los reproduce en una instancia de Perfect Streamer (PSS) del mismo host. Por eso, los receptores de los abonados (STB / TV) siguen funcionando sin volver a explorar los canales después de una migración o de una conmutación al equipo de reserva.

La herramienta forma parte del paquete pstreamer y, tras la instalación, se encuentra en /opt/pss/tools/mpts_migrate: no es necesario instalar nada por separado.

Requisitos previos

Antes de ejecutar la utilidad, compruebe que:

  • PSS está en ejecución en el mismo host (o en el host indicado en --pss-base). La utilidad busca pss en /proc y lee pss.json para obtener el puerto de administración (43971 si la configuración no lo contiene).

  • El MPTS de origen está accesible si se prevé una captura (modos 1, 2, save+apply): la URL indicada como argumento posicional <input> debe entregar un flujo MPEG-TS. Para multicast UDP, IGMP / el cortafuegos deben permitir la recepción; para los archivos, la ruta debe existir.

  • El MPTS de destino ya está configurado en PSS: la utilidad no crea flujos nuevos. El objeto MPTS y al menos tantos alimentadores SPTS como servicios haya en el inventario deben existir de antemano. Los servicios que se quedan sin alimentador libre se muestran en el diálogo y se omiten (respuesta predeterminada: s); con --non-interactive se omiten automáticamente.

  • La API HTTP de administración está disponible en localhost para leer /data/stream (se utiliza durante la verificación) y escribir /config/stream (aplicación).

Qué se migra

Todos los identificadores visibles para el receptor, a nivel de flujo de transporte y de servicio:

  • Flujo de transporte: TSID, ONID, network ID, network name, provider name (se aplica como sdt-provider-name común a todo el múltiplex si todos los servicios de origen tienen el mismo valor), descriptor de entrega (parámetros de emisión terrestre / por cable / por satélite), versiones de PAT/SDT/NIT

  • Por servicio: service_id, pmt_pid, pcr_pid, service_type, nombre del servicio, número lógico de canal (LCN), indicador free-CA, indicadores EIT-present / EIT-schedule

  • Flujos elementales: los PID (se aplica identity remap; véase Limitaciones y escollos), tipos de flujo, etiquetas de idioma

  • Acceso condicional: descriptores CA a nivel de programa y de ES

Los nombres de servicio / proveedor en codificaciones DVB distintas de ASCII (por ejemplo, ISO-8859-5 para el cirílico) se decodifican a UTF-8 automáticamente.

El remapeo de PID de ES se construye como pares de identidad (mpegts-pid-old ≡ mpegts-pid-new) para cada PID de PCR / vídeo / audio / teletexto / datos de todos los servicios, por lo que a la salida del multiplexor se conservan los PID originales byte-exact. Los receptores antiguos que almacenan en caché la PMT tras la primera exploración siguen funcionando sin reconfiguración.

En PSS 2.0.0.193 y posteriores, el plan habilita además, en la entrada del multiplexor del MPTS de destino, el modo nativo de conservación de los PID originales (Automatic PID mapping desactivado) y fija para cada servicio el número de orden de programa capturado en la PAT (program order). Así, el orden de programas en antena se conserva tras la migración. La compatibilidad se detecta automáticamente a partir de la configuración del streamer de destino; en versiones anteriores estas claves no se envían (la utilidad imprime una advertencia), los PID se fijan solo mediante los pares de identidad y el orden de programas en la PAT no se conserva.

Casos de uso

  • Failover: conmutación de los decodificadores del MPTS principal al de reserva conservando los canales en el lado del receptor

  • Migración de hardware: traslado de un múltiplex en funcionamiento de un host PSS a otro sin instrucciones para los espectadores

  • Instantánea antes / después de la actualización: captura del múltiplex antes de actualizar PSS y nueva aplicación posterior para garantizar un SI/PSI idéntico bit a bit

  • Edición manual y nueva aplicación: captura, edición de migrate.json (renombrar servicios, cambiar los LCN, ajustar service_type) y nueva aplicación

  • Comprobación en dry-run: impresión de cada HTTP POST que se enviaría, sin afectar a PSS

Inicio rápido

# Capture from a live stream and apply to local PSS in one run
mpts_migrate udp://239.1.1.1:1234

# Capture, save to migrate.json and apply
mpts_migrate -s udp://239.1.1.1:1234

# Capture only — write to file, do not apply
mpts_migrate -o backup.json udp://239.1.1.1:1234

# Apply a previously saved JSON
mpts_migrate -i backup.json

# No arguments — load ./migrate.json and apply
mpts_migrate

# Preview what apply would do, without changes
mpts_migrate -i backup.json --dry-run

Flujo de trabajo

  1. Captura — la utilidad abre el flujo, durante -t segundos (30 por defecto) analiza PAT / PMT / SDT / NIT / EIT, construye el inventario y mide la tasa de bits total del flujo.

  2. (Opcional) Guardado — con -s o -o el inventario se escribe en JSON para su reutilización posterior.

  3. Búsqueda de PSS — encuentra el PSS en ejecución explorando /proc y lee pss.json para obtener el puerto de administración (43971 si la configuración no lo contiene); --pss-base http://host:port omite la detección automática.

  4. Confirmación de la correspondencia — un diálogo interactivo pregunta cómo asociar cada servicio capturado con un alimentador SPTS existente; --non-interactive acepta las propuestas y termina si hay conflicto; --target-mpts <id> omite la petición de selección del MPTS.

  5. Reanudación automática de los alimentadores — para cada SPTS / muxer-output asociado, la utilidad envía {"pause":false} si el alimentador estaba en pausa, para que tras la aplicación el multiplexor reciba datos.

  6. Ajuste automático de la tasa de bits — si captured_bitrate × (1 + headroom%) supera el mpegts-output-bitrate del MPTS de destino, la utilidad eleva ese límite en PSS con un único POST (con redondeo al alza al múltiplo de 1000 kbps más próximo). Se desactiva con --no-bitrate-adjust.

  7. Planificación — compara el inventario con el árbol /config/stream actual de PSS y prepara peticiones HTTP POST solo para los campos que difieren. El remapeo de PID de ES se genera como pares de identidad (mpegts-pid-old ≡ mpegts-pid-new) para que a la salida del multiplexor todos los PID originales, incluidos PCR, vídeo, audio, teletexto, SCTE-35 y DSM-CC, permanezcan sin cambios. En PSS 2.0.0.193 y posteriores, el plan habilita además el modo de conservación de los PID originales en la entrada del multiplexor de destino y fija el orden de programas en la PAT (véase Qué se migra).

  8. Aplicación — envía las peticiones POST planificadas y a continuación pone el MPTS en pausa y lo reanuda para que PSS relea la configuración; con --dry-run el plan solo se imprime.

  9. Verificación (activada por defecto, incluso si el plan está vacío) — captura el MPTS resultante a través de una de las salidas UDP de PSS y lo compara con el destino; las discrepancias críticas (TSID, ONID, service_id, name, type, LCN) → código de salida 5.

Volver a ejecutar toda la cadena es idempotente: la segunda pasada informa no changes needed si PSS ya coincide con el inventario, y la verificación lo confirma con una captura nueva.

Opciones de la CLI

Selección de modo

Opción

Descripción

Predeterminado

-f, --file <path>

Ruta al JSON de migración (se usa como importación por defecto en ausencia de -i y como destino de guardado con -s)

./migrate.json

-s, --save

Guardar el inventario capturado en el archivo de migración (se combina con una entrada de flujo; la aplicación se realiza igualmente)

—

-o, --output <file>

Solo captura: escritura en archivo, sin aplicar

—

-i, --input <file>

Solo aplicación: carga del archivo, sin captura

—

Captura

Opción

Descripción

Predeterminado

-t, --time <sec>

Duración máxima de la captura

30

-b, --bitrate <Mbps>

Sugerencia de tasa de bits del TS para la regulación de ritmo en modo archivo

38.8

Apply / Verify

Opción

Descripción

Predeterminado

--target-mpts <id>

Omitir la petición de selección del MPTS; aplicar a este stream id en PSS

—

--non-interactive

Aceptar automáticamente las propuestas del diálogo; terminar si hay conflicto

—

--dry-run

Imprimir el plan de POST sin enviar nada

—

--pss-base <url>

Anular la detección automática de PSS (por ejemplo, http://host:8808)

automático

--no-verify

Omitir la captura y el diff posteriores a la aplicación

verificación activada

--verify-time <s>

Ventana de captura para la verificación

10

--no-bitrate-adjust

No elevar mpegts-output-bitrate en el MPTS de destino

elevación activada

--bitrate-headroom <pct>

Margen de tasa de bits por encima del valor medido al ajustar

15

Varios

Opción

Descripción

-v, --verbose

Registro detallado (cada HTTP POST y cada rama del diálogo)

-h, --help

Mostrar la ayuda y salir

Archivo de migración (migrate.json)

JSON legible por humanos con format_version: 1. La ubicación por defecto es ./migrate.json; se anula con -f. Ejemplo de estructura:

{
  "format_version": 1,
  "tool": "mpts_migrate",
  "capture": {
    "source": "udp://239.1.1.1:1234",
    "captured_at_utc": "2026-04-30T08:15:00Z",
    "duration_s": 8.2,
    "packets": 109344
  },
  "transport_stream": {
    "transport_stream_id": 1234,
    "original_network_id": 8442,
    "network_name": "Operator",
    "delivery": { "type": "terrestrial", "frequency_khz": 522000 }
  },
  "services": [
    {
      "service_id": 1, "pmt_pid": 256, "pcr_pid": 256,
      "service_type": 1, "service_name": "Channel 1",
      "provider_name": "MyProvider", "logical_channel_number": 101,
      "program_order": 1,
      "free_ca_mode": false,
      "elementary_streams": [
        { "pid": 256, "stream_type": 27, "language": "rus" }
      ]
    }
  ]
}

El archivo puede editarse antes de una nueva aplicación: renombrar servicios, cambiar los LCN, cambiar service_type, ajustar network_name. El comando mpts_migrate -i migrate.json envía solo los campos modificados.

Conexión con PSS

  • Detección automática: la utilidad busca pss en /proc/<pid>/comm, lee su archivo --config y toma web-server.bind-port (43971 si la clave no existe).

  • Manualmente: --pss-base http://host:port omite por completo la detección automática. Resulta útil para un PSS remoto o cuando --dry-run debe generar el plan sin un PSS en ejecución.

  • La API REST de administración no requiere autenticación en localhost.

Verificación

Si --no-verify no se especifica (comportamiento por defecto), tras aplicar el plan la utilidad:

  1. Busca una salida UDP hacia localhost en el MPTS de destino o añade una temporalmente en 127.0.0.1:<auto> (con la marca added by mpts_migrate for verification).

  2. Captura el MPTS en vivo a través de esa salida durante --verify-time segundos (10 por defecto).

  3. Compara el inventario capturado con el destino:

    • Discrepancia crítica (TSID, ONID, network name, service_id, name, type, LCN) → código de salida 5.

    • Discrepancia leve (PMT PID, número de ES, nombre del proveedor, orden de programas en la PAT) → se muestra como advertencia, código de salida 0.

  4. Si el MPTS de destino está sobrecargado (tasa de bits de salida ≥ el mpegts-output-bitrate configurado), se imprime WARNING: target MPTS is overloaded; véase Bitrate adjust.

Dry-run

--dry-run imprime cada petición HTTP que la utilidad enviaría (ruta y cuerpo JSON), pero no envía ninguna. Resulta útil para:

  • Revisar el plan con el operador antes de confirmarlo.

  • Generar conjuntos de cambios reproducibles en CI / gestión de cambios.

  • Trabajar cuando PSS no está accesible (combinar con --pss-base http://host:port).

El dry-run no ejecuta la verificación.

Bitrate adjust

Por defecto, si captured_bitrate × (1 + headroom%) supera el mpegts-output-bitrate del MPTS de destino, la utilidad eleva ese límite en PSS antes de aplicar los cambios de SI/PSI. Sin un margen suficiente, un MPTS sobrecargado pierde los datos de baja prioridad. Síntomas típicos: cortes de audio en los servicios de radio y errores CRC intermitentes en la EIT. Se desactiva con --no-bitrate-adjust; el margen se regula con --bitrate-headroom <pct> (15 por defecto).

Códigos de salida

Código

Significado

0

Éxito — la aplicación y (si está activada) la verificación han finalizado sin errores. Un --dry-run correcto también termina con este código.

1

Error de argumentos / de archivo / de detección

2

No se ha encontrado ninguna PAT en la fuente: la entrada no contiene un MPEG-TS válido o la ventana de captura es demasiado corta; también se devuelve cuando el operador ha rechazado la confirmación de la correspondencia o ha salido del diálogo (aplicación abortada)

3

Una o varias peticiones HTTP POST de la aplicación han fallado

4

La aplicación se ha completado, pero el MPTS de destino no ha vuelto al estado Running

5

La verificación ha fallado — el flujo capturado difiere del destino en campos críticos

Limitaciones y escollos

  • PSS debe disponer de antemano del MPTS de destino y de los alimentadores: la utilidad no crea flujos nuevos. El MPTS de destino y al menos tantos alimentadores SPTS como servicios haya en el inventario ya deben existir; los servicios sin alimentador libre se omiten en el diálogo.

  • El MPTS de origen debe estar accesible durante la captura (modos 1, 2, save+apply): la URL indicada como argumento posicional <input> debe entregar un flujo MPEG-TS, y para multicast UDP IGMP / el cortafuegos deben permitir la recepción.

  • El remapeo de PID de ES se aplica automáticamente: se genera un remapeo de identidad (mpegts-pid-old ≡ mpegts-pid-new) para cada PID de PCR/vídeo/audio/teletexto/datos de todos los servicios, de modo que a la salida del multiplexor los PID originales se conserven byte-exact. La disposición de la PMT permanece estable de una migración a otra, por lo que incluso los receptores antiguos (STB anteriores a 2015, Samsung anteriores a la serie H, LG anteriores a WebOS 3.0) que almacenan los PID en caché no requieren una nueva exploración.

  • El descriptor de entrega debe corresponder al portador real para los receptores que se resintonizan mediante la NIT (DVB-T/T2/C/S). Un bloque delivery que no coincida puede llevar al receptor a una frecuencia incorrecta.

  • La coherencia de los LCN entre el MPTS principal y el de reserva es crítica para el failover — si difieren, las posiciones de los canales en la lista del receptor se desplazarán tras la conmutación.

  • El provider name en PSS es común a todo el múltiplex (un único sdt-provider-name por muxer-input del MPTS). La utilidad lo aplica automáticamente si todos los servicios capturados tienen el mismo valor; si los servicios tienen valores de provider_name diferentes, la utilidad imprime una advertencia y deja el campo intacto: la decisión corresponde al operador.

  • No es una herramienta de configuración de PSS: mpts_migrate solo modifica los campos de identificadores SI/PSI, el indicador pause de cada alimentador, (opcionalmente) mpegts-output-bitrate y, en PSS 2.0.0.193 y posteriores, las claves del modo de conservación de PID y del orden de programas. No configura codificadores, entradas, cifrado, programaciones ni similares.

  • En PSS anteriores a 2.0.0.193 no se admiten el modo de conservación de los PID originales del multiplexor ni el orden de programas en la PAT: la utilidad imprime una advertencia, los PID se fijan únicamente mediante los pares de identidad y el orden de programas tras la migración puede diferir del original.

Diagnóstico

Síntoma

Causa probable / solución

Error: no PAT seen in stream

la fuente no es MPEG-TS, IGMP/el cortafuegos bloquea el multicast o -t es demasiado corto

Error: cannot reach PSS

utilizar --pss-base http://host:port para omitir la detección automática

La aplicación se ha completado, pero el MPTS sigue en pausa

revisar el registro de PSS; volver a ejecutar con -v para ver el plan completo de POST

La verificación indica una discrepancia crítica

comparar el destino y el flujo capturado en JSON; normalmente, en el diálogo se ha asociado un alimentador al servicio equivocado

WARNING: target MPTS is overloaded

elevar mpegts-output-bitrate en PSS o usar --bitrate-headroom <higher %>; sin margen se corrompen el audio de los servicios de radio y las tablas PSI