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

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

Captura la identidad DVB SI/PSI de un flujo MPEG-TS multi-programa (MPTS) en funcionamiento y la reproduce en una instancia de Perfect Streamer (PSS) en el mismo host. Resultado: los receptores de los usuarios (STB / TV) siguen funcionando sin volver a escanear los canales tras una migración o failover.

Requisitos previos

Antes de ejecutar la utilidad, asegúrese de que:

  • PSS está en ejecución en el mismo host (o en un host accesible por --pss-base). La utilidad busca pss en /proc y lee pss.json para obtener el puerto admin (por defecto 43971).

  • Fuente MPTS accesible, si se planea capturar (modos 1, 2, save+apply): la URL pasada como argumento posicional <input> debe entregar un flujo MPEG-TS. Para UDP multicast — IGMP / firewall deben permitir la recepción; para archivos — la ruta debe existir.

  • MPTS de destino ya configurado en PSS: la utilidad no crea nuevos flujos. Un objeto MPTS y al menos tantos feeders SPTS como servicios haya en el inventario deben existir previamente. Los servicios sin feeder disponible se muestran en el diálogo y pueden omitirse.

  • La API HTTP admin está abierta en localhost para leer /data/stream (usado por verify) y escribir en /config/stream (apply).

Qué se migra

Todos los identificadores visibles por el receptor a nivel del flujo de transporte y los servicios:

  • Transport stream: TSID, ONID, network ID, network name, provider name (se aplica como sdt-provider-name mux-wide cuando todos los servicios de origen comparten un mismo valor), descriptor de delivery (parámetros terrestre / cable / satélite), versiones PAT/SDT/NIT

  • Por servicio: service_id, pmt_pid, pcr_pid, service_type, nombre del servicio, LCN, free-CA, EIT-present / EIT-schedule

  • Flujos elementales: PIDs (se aplica identity remap — ver Limitaciones), tipos de flujo, etiquetas de idioma

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

Los nombres de servicios / proveedores en codificaciones DVB no ASCII (p. ej. ISO-8859-5 para cirílico) se decodifican a UTF-8 automáticamente.

El ES PID remap por servicio se construye como pares de identidad (mpegts-pid-old ≡ mpegts-pid-new) para cada PCR / video / audio / teletext / data PID, de modo que la salida multiplexada resultante mantiene los PID de origen byte-exact. Los receptores legacy que cachean el PMT tras el primer escaneo siguen funcionando sin reconfiguración.

Casos de uso

  • Failover: cambio de decodificadores del MPTS principal al de respaldo manteniendo los canales en el receptor

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

  • Snapshot pre/post actualización: capturar el multiplex antes de actualizar PSS y volver a aplicarlo después para garantizar SI/PSI bit-idénticos

  • Edición manual y reaplicar: capturar, editar migrate.json (renombrar servicios, cambiar LCN, ajustar service_type) y volver a aplicar

  • Verificación dry-run: se imprime cada HTTP POST que se enviaría, sin afectar a PSS

Inicio rápido

# Захват из live-потока и применение к локальному PSS за один запуск
mpts_migrate udp://239.1.1.1:1234

# Захват, сохранение в migrate.json и применение
mpts_migrate -s udp://239.1.1.1:1234

# Только захват — запись в файл, без применения
mpts_migrate -o backup.json udp://239.1.1.1:1234

# Применение ранее сохранённого JSON
mpts_migrate -i backup.json

# Без аргументов — загрузка ./migrate.json и применение
mpts_migrate

# Просмотр того, что сделает apply, без изменений
mpts_migrate -i backup.json --dry-run

Flujo de trabajo

  1. Captura — la utilidad abre el flujo, parsea PAT / PMT / SDT / NIT / EIT durante -t segundos (30 por defecto) y construye el inventario; se mide el bitrate total.

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

  3. Búsqueda de PSS — detecta un PSS en ejecución con un escaneo de /proc y lee pss.json para obtener el puerto admin (por defecto 43971); --pss-base http://host:port salta el autodescubrimiento.

  4. Confirmación del mapeo — un diálogo interactivo pregunta cómo asociar cada servicio capturado a un feeder SPTS existente; --non-interactive acepta las sugerencias y aborta en caso de conflicto; --target-mpts <id> omite la selección de MPTS.

  5. Auto-despausar feeders — para cada SPTS/muxer-output mapeado, la utilidad envía {"pause":false} si estaba en pausa, para que el multiplexor reciba realmente los datos tras el apply.

  6. Ajuste automático de bitrate — si captured_bitrate × (1 + headroom%) supera mpegts-output-bitrate del MPTS de destino, la utilidad eleva ese límite en PSS con un único POST (redondeado al múltiplo superior de 1000 kbps). Desactivable con --no-bitrate-adjust.

  7. Planificación — compara el inventario con el árbol actual /config/stream en PSS y prepara HTTP POSTs solo para los campos que difieren. El ES PID remap se genera como pares de identidad (mpegts-pid-old ≡ mpegts-pid-new) para que la salida multiplexada conserve cada PID de origen sin cambios — incluyendo PCR, video, audio, teletext, SCTE-35, DSM-CC.

  8. Apply — envía los POSTs planeados y luego conmuta pause/unpause del MPTS para que PSS recargue la configuración; con --dry-run solo se imprime el plan.

  9. Verify (activo por defecto, incluso si el plan está vacío) — captura el MPTS resultante por una de las salidas UDP de PSS y lo compara con el objetivo; las divergencias críticas (TSID, ONID, service_id, name, type, LCN) → exit 5.

Volver a ejecutar el pipeline completo es idempotente: la segunda pasada informa no changes needed si PSS ya coincide con el inventario, y verify lo confirma con una nueva captura.

Opciones CLI

Selección de modo

Opción

Descripción

Predeterminado

-f, --file <path>

Ruta del JSON de migración (importación por defecto sin -i y destino de guardado con -s)

./migrate.json

-s, --save

Guardar el inventario capturado en el archivo de migración (combinable con entrada por flujo; el apply se realiza igualmente)

—

-o, --output <file>

Solo captura: escribir en archivo, sin apply

—

-i, --input <file>

Solo apply: cargar archivo, sin captura

—

Captura

Opción

Descripción

Predeterminado

-t, --time <sec>

Duración máxima de captura

30

-b, --bitrate <Mbps>

Sugerencia de bitrate TS para el pacing en modo de archivo

38.8

Apply / Verify

Opción

Descripción

Predeterminado

--target-mpts <id>

Omitir el diálogo de elección del MPTS; aplicar a este stream id en PSS

—

--non-interactive

Aceptar automáticamente las sugerencias del diálogo; abortar en caso de conflicto

—

--dry-run

Imprimir el plan de POSTs sin enviar nada

—

--pss-base <url>

Sobrescribir el autodescubrimiento de PSS (ej. http://host:43971)

auto

--no-verify

Omitir la captura post-apply y el diff

verify habilitado

--verify-time <s>

Ventana de captura para verificación

10

--no-bitrate-adjust

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

ajuste habilitado

--bitrate-headroom <pct>

Margen de bitrate sobre el valor medido al ajustar

15

Otros

Opción

Descripción

-v, --verbose

Log detallado (cada POST HTTP y rama de diálogo)

-h, --help

Mostrar ayuda y salir

Archivo de migración (migrate.json)

JSON legible por humanos con format_version: 1. Ubicación por defecto ./migrate.json; se redefine 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,
      "free_ca_mode": false,
      "elementary_streams": [
        { "pid": 256, "stream_type": 27, "language": "rus" }
      ]
    }
  ]
}

El archivo puede editarse antes de un nuevo apply: renombrar servicios, cambiar LCN, alternar service_type, ajustar network_name — mpts_migrate -i migrate.json enviará solo los campos modificados.

Conexión a PSS

  • Auto-descubrimiento: escanear /proc/<pid>/comm buscando pss, leer su archivo --config y tomar web-server.bind-port (por defecto 43971).

  • Manual: --pss-base http://host:port omite por completo el autodescubrimiento. Útil con PSS remoto o cuando --dry-run debe generar un plan sin PSS activo.

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

Verificación

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

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

  2. Captura el MPTS en vivo por esa salida durante --verify-time segundos (10 por defecto).

  3. Compara el inventario capturado con el objetivo: - Divergencia crítica (TSID, ONID, service_id, name, type, LCN) → código de salida 5. - Divergencia suave (PMT PID, PCR PID, ES PID) → impresa como warning, código de salida 0.

  4. Si el MPTS de destino está sobrecargado (bitrate de salida ≥ mpegts-output-bitrate configurado), se imprime WARNING: target MPTS is overloaded — ver Bitrate adjust abajo.

Dry-run

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

  • Revisión del plan con el operador antes del commit.

  • Generación de conjuntos de cambios reproducibles en CI / change-management.

  • Trabajo con PSS inaccesible (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 mpegts-output-bitrate del MPTS de destino, la utilidad eleva ese límite en PSS antes de aplicar los cambios SI/PSI. Sin reserva suficiente, un MPTS sobrecargado pierde datos de baja prioridad — síntomas típicos: pérdida de audio en servicios de radio, errores intermitentes de CRC EIT. Desactivable con --no-bitrate-adjust; la reserva se ajusta con --bitrate-headroom <pct> (predeterminado 15).

Códigos de salida

Código

Valor

0

Éxito — apply y (si está habilitada) la verificación pasaron sin problemas. También lo devuelve un --dry-run exitoso.

1

Error de argumentos / archivo / detección

2

No se ha encontrado PAT en la fuente — la entrada no es un MPEG-TS válido o la ventana de captura es demasiado corta

3

Una o más peticiones HTTP POST del apply fallaron

4

Apply tuvo éxito, pero el MPTS de destino no volvió al estado Running

5

La verificación falló — el flujo capturado difiere del objetivo en campos críticos

Limitaciones y advertencias

  • PSS debe alojar previamente el MPTS de destino y los feeders: la utilidad no crea nuevos flujos. El MPTS de destino y al menos tantos feeders SPTS como servicios haya en el inventario deben existir previamente; los servicios sin feeder disponible se omiten en el diálogo.

  • La fuente MPTS debe ser accesible durante la captura (modos 1, 2, save+apply): la URL pasada como argumento posicional <input> debe entregar un flujo MPEG-TS; para UDP multicast, IGMP / firewall deben permitir la recepción.

  • El ES PID remap se aplica automáticamente: el remap de identidad por servicio (mpegts-pid-old ≡ mpegts-pid-new) se genera para cada PCR/video/audio/teletext/data PID para que la salida multiplexada preserve los PID de origen byte-exact. La disposición PMT permanece estable entre migraciones — incluso receptores legacy (STB anteriores a 2015, Samsung anteriores a la serie H, LG anteriores a WebOS 3.0) que cachean PIDs no requieren rescaneo.

  • El descriptor de delivery debe corresponder al portador real para receptores que se reconfiguran vía NIT (DVB-T/T2/C/S). Un bloque delivery no concordante puede llevar al receptor a una frecuencia incorrecta.

  • Consistencia de LCN entre el MPTS principal y el de respaldo es crucial para el failover — si difieren, tras la conmutación las posiciones de canales en el receptor cambiarán.

  • Provider name en PSS — común para todo el multiplex (un único sdt-provider-name en el muxer-input MPTS). La utilidad lo aplica automáticamente cuando todos los servicios capturados comparten un mismo valor; si distintos servicios tienen valores provider_name diferentes, se imprime un warning y el campo permanece intacto — la decisión queda al operador.

  • No es una herramienta de configuración del propio PSS: mpts_migrate toca solo los campos de identidad SI/PSI, la flag pause por feeder y (opcionalmente) mpegts-output-bitrate. Encoders, inputs, cifrado, planificación, etc. — no los configura.

Diagnóstico

Síntoma

Causa probable / solución

Error: no PAT seen in stream

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

Error: cannot reach PSS

use --pss-base http://host:port para evitar el autodescubrimiento

Apply tuvo éxito, pero el MPTS sigue en pausa

comprobar el log de PSS; relanzar con -v para ver el plan completo de POSTs

La verificación muestra una discrepancia crítica

comparar goal y capture en el JSON; normalmente un feeder está mapeado por error con el servicio equivocado en el diálogo

WARNING: target MPTS is overloaded

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