TS Analyze Perfect Streamer Toolkit v2.2 — TR 101 290

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

Analizador en consola de flujos de transporte MPEG-TS con verificación de conformidad ETSI TR 101 290 V1.4.1 y validación del modelo de buffers T-STD ISO/IEC 13818-1.

Lee UDP multicast/unicast o archivos TS, detecta automáticamente los PCR PIDs por PAT/PMT y emite un informe detallado o breve en stdout.

Qué se verifica

El analizador recorre cada paquete TS e informa de las violaciones:

• Priority 1 (decodificabilidad TS): sync TS, pérdida de sync, presencia y CRC de PAT/PMT, contador de continuidad, presencia de PIDs

• Priority 2 (monitorización recomendada): indicador TEI, errores CRC, repetición / precisión / discontinuidades del PCR, intervalo PTS, presencia de CAT

• Priority 3 (monitorización extendida): intervalos NIT/SDT/EIT/TDT, PIDs no referenciados, overflow / underflow de buffers T-STD

Adicionalmente se emite:

• Precisión de PCR hasta ±500 ns — regresión por posiciones de byte

• Drift de PCR en ppm (solo modo live)

• Modelo de buffers T-STD para cada flujo elemental (modo live)

• Validación de los tamaños de las secciones SI frente a los límites ISO/EN con advertencias de compatibilidad EIT-on-STB (>1024 B)

• UDP IAT (inter-arrival time) — estadísticas de jitter a nivel de datagrama (solo modo live)

Uso

ts_analyze [options] <input>

Entradas

Forma	Descripción
udp://239.1.1.1:1234	UDP multicast
udp://eth0@239.1.1.1:1234	UDP multicast en la interfaz indicada
udp://192.168.1.100:1234	UDP unicast
udp://lo@127.0.0.1:12655	UDP unicast en loopback (fuente de prueba)
/path/to/file.ts	Archivo TS local

El UDP encapsulado en RTP se detecta y desencapsula automáticamente.

Opciones

Opción	Descripción	Predeterminado
-t, --time <sec>	Duración del análisis en segundos	30
-s, --short	Informe resumido breve	–
-f, --full	Informe detallado completo	sí
-b, --bitrate <Mbps>	Sugerencia de bitrate TS para el modo de archivo	38.8
-p, --pcr-pid <pid>	Analizar solo el PCR PID indicado (decimal o 0xHHHH)	automático
-l, --pcr-limit <ms>	Límite de error de repetición de PCR en ms	40
--no-eit	Omitir el análisis EIT — P3.7..P3.10 se muestran como N/A; se elimina la contribución EIT a P2.2 y al resumen de tamaños SI	EIT habilitado
--no-nit	Omitir el análisis NIT — P3.1, P3.2 se muestran como N/A; se elimina la contribución NIT a P2.2 y al resumen de tamaños SI	NIT habilitado
--no-color	Desactivar colores ANSI en la salida	colores activados
--xml	XML estructurado en stdout (sin stderr)	texto
-h, --help	Mostrar ayuda	–

Ejemplos

# 30-секундная проверка TR 101 290 на multicast-потоке
ts_analyze -t 30 udp://239.10.10.1:1234

# краткая сводка, сохранение в лог (без цвета)
ts_analyze -s --no-color -t 60 udp://239.10.10.1:1234 > report.txt

# анализ TS-файла
ts_analyze -t 30 recording.ts

# анализ только одного PCR PID
ts_analyze -p 0x0100 -t 30 udp://239.10.10.1:1234

# машинно-читаемый XML для CI / мониторинга
ts_analyze --xml -t 30 udp://239.10.10.1:1234 > result.xml

# пропустить анализ EIT/NIT (например, для потоков, где их намеренно нет)
ts_analyze --no-eit --no-nit -t 30 udp://239.10.10.1:1234

Desactivar el análisis de EIT o NIT

En algunos flujos, EIT o NIT se omiten deliberadamente (redes cerradas, fuentes de laboratorio, contribución OTT-only, etc.). En ese caso, las verificaciones P3 correspondientes del TR 101 290 fallarán siempre en el veredicto OVERALL — es solo ruido.

Use --no-eit y/o --no-nit para excluir estas comprobaciones:

Indicador	Comprobaciones omitidas	Efectos secundarios
--no-eit	P3.7 (EIT actual P/F), P3.8 (EIT other P/F), P3.9 (EIT actual schedule), P3.10 (EIT other schedule)	Las secciones EIT no se ensamblan; su contribución a P2.2 (CRC) y al resumen de tamaños SI es cero. Se suprime el aviso de compatibilidad EIT-on-STB.
--no-nit	P3.1 (NIT actual), P3.2 (NIT other)	Las secciones NIT no se ensamblan; su contribución a P2.2 (CRC) y al resumen de tamaños SI es cero.

Las verificaciones omitidas aparecen en el informe como N/A con la marca disabled (--no-eit) / disabled (--no-nit), y en XML como applicable="false" result="N/A". En el informe corto se muestra NIT=off / EIT=off en lugar del contador de errores.

Los flags solo afectan al procesado de EIT (PID 0x0012) y NIT (PID 0x0010) — el resto de comprobaciones TR 101 290 (P1.x, P2.x, SDT, TDT, CAT, T-STD, drift PCR, IAT) se ejecutan como siempre.

Modo de salida XML (--xml)

--xml hace que el analizador emita un único documento XML UTF-8 autosuficiente en stdout. Toda la información complementaria (banner, «Stream locked», «PCR PIDs discovered», progreso por segundo, resumen de captura, advertencias por duración corta) se suprime; stderr permanece vacío, salvo que ocurra un fallo real (entrada no abrible, sin datos PCR, flujo demasiado corto, interrupción por señal). Los colores ANSI se desactivan obligatoriamente.

El código de salida es el mismo que en modo texto: 0 para OVERALL=PASS, 65 para OVERALL=FAIL, más los códigos estándar de error / señales (1, 2, 3, 130, 143).

Estructura XML de nivel superior:

<?xml version="1.0" encoding="UTF-8"?>
<ts_analyze version="2.2">
  <source>udp://239.1.1.1:5000</source>
  <timestamp>2026-04-30T12:00:00+0300</timestamp>
  <duration_s>30.00</duration_s>
  <packets total="..." null="..."/>
  <ts_bitrate_mbps>20.012</ts_bitrate_mbps>

  <programs>
    <program number="1" pmt_pid="0x0100" pcr_pid="0x0101">
      <es pid="0x0101" stream_type="0x1b" name="H.264/AVC"/>
      <es pid="0x0102" stream_type="0x03" name="MPEG-2 Audio"/>
    </program>
  </programs>

  <tr101290>
    <check id="1.1" name="TS Sync Byte Error" applicable="true" errors="0" result="PASS"/>
    ...
    <check id="2.3" name="PCR Repetition Error"
           applicable="true" errors="0" result="PASS" soft_violations="3"/>
    ...
    <check id="3.4" name="Unreferenced PIDs" applicable="true" count="2" result="INFO"/>
    ...
  </tr101290>

  <si_section_size oversize_total="0" eit_stb_warn_total="12">
    <table name="EIT_actual_pf" max_bytes="1380" std_limit="4096"
           oversize="0" eit_stb_warn="12" result="WARN_STB"/>
    ...
  </si_section_size>

  <iat datagrams="33252" intervals="33251" min_ms="0.002" max_ms="5.009"
       avg_ms="0.150" stddev_ms="0.295" p95_ms="0.872" p99_ms="1.076"
       max_jitter_ms="4.272" gap_threshold_ms="100.0" gaps_over_threshold="0"/>

  <pcr_pids>
    <pcr_pid value="0x0101" sid="1" pcr_count="1500" discontinuities="0"
             estimated_bitrate_mbps="18.750">
      <interval samples="1499" min_ms="19.812" max_ms="20.195"
                avg_ms="20.001" p95_ms="20.102"
                iso_hard_violations="0" tr_soft_violations="0"
                rec_violations="0" result="PASS"/>
      <accuracy samples="1499" min_ns="-148.3" max_ns="201.7" abs_max_ns="201.7"
                avg_ns="2.1" stddev_ns="45.6" p95_ns="102.3"
                violations="0" result="PASS"/>
      <drift measured="true" ppm="0.618" limit_ppm="30"
             verdict_mode="informational" result="PASS"/>
      <tstd overflows="0" underflows="0" max_fill_bytes="34218" result="PASS">
        <es_buffer es_pid="0x0101" stream_type="0x1b"
                   capacity_bytes="3000000" measuring="true"
                   es_bitrate_mbps="15.200" max_fill_bytes="34218"
                   overflows="0" underflows="0"/>
      </tstd>
    </pcr_pid>
  </pcr_pids>

  <unreferenced_pids count="2">
    <pid value="0x01ff"/>
    <pid value="0x0200"/>
  </unreferenced_pids>

  <overall result="PASS"/>
</ts_analyze>

Convenciones clave:

• Todos los PID se formatean como 0xHHHH (hex de 4 dígitos con prefijo 0x).

• El atributo result admite los valores PASS / FAIL / WARN / N/A / INFO / SKIP / ok / WARN_STB.

• Para verificaciones no aplicables (modo archivo, ausencia de scrambling, etc.), el elemento aparece igualmente con applicable="false" y result="N/A" para que los consumidores del esquema vean una forma estable.

• <drift> lleva verdict_mode="informational" para 30 s ≤ T < 300 s y verdict_mode="hard" para T ≥ 300 s; result="SKIP" en ejecuciones de menos de 30 s.

• <iat> está ausente en las ejecuciones en modo de archivo.

• <overall> refleja la misma puerta que la línea OVERALL del informe en texto y coincide con el código de salida del proceso.

La salida es XML bien formado (validable con xmllint --noout); se puede enviar directamente a XSLT, Python lxml, etc., sin ajustar el parsing.

Lectura del informe

Colores de estado

Estado	Color	Valor
PASS / ok	verde	La comprobación cumple el estándar
WARN / WARNING / WARN(STB)	amarillo	Violación leve, no afecta a OVERALL
FAIL / ERROR	rojo	Violación del estándar, afecta a OVERALL
INFO / NOTE / N/A	por defecto	Solo informativo

Use --no-color al redirigir a archivos de log o a terminales no ANSI.

Duración mínima del análisis

Duración	Cobertura	Código de salida
< 2 s	Insuficiente — análisis rechazado	3 (error)
2–10 s	P1 + P2 fiables; algunas comprobaciones P3 pueden carecer de datos	0 + WARN
10–30 s	P1 + P2 + la mayoría de P3; TDT (30 s) puede no tener datos	0 + NOTE
≥ 30 s	Cobertura completa de todas las comprobaciones TR 101 290	0

La duración predeterminada es de 30 segundos — suficiente para cobertura completa del TR 101 290. Use -t <sec> para ampliar (por ejemplo, para pruebas de aceptación de drift PCR) o reducir (verificaciones smoke rápidas).

Durante la ejecución, el analizador actualiza cada segundo un indicador de progreso de una línea en stderr:

Progress: 47.3%  (14.2s / 30.0s, 330614 packets)

La línea usa carriage-return (\r) para quedarse en una sola línea en un terminal; redirija stderr (2>/dev/null) para suprimirla.

Veredicto de drift PCR — ventana de dos niveles

La tolerancia de la frecuencia de reloj PCR según ISO/IEC 13818-1 §2.4.2.1 y ETSI TR 101 290 es de ±30 ppm. El valor de drift en el informe se obtiene por regresión lineal de los segundos PCR acumulativos respecto al tiempo de llegada por reloj de pared; el error estadístico decrece como 1 / T^(3/2), por lo que la ventana de análisis debe ser lo suficientemente larga para que el ruido de medición esté claramente por debajo del límite de ±30 ppm.

Por eso, el analizador condiciona el veredicto de drift a la duración del análisis:

Ventana	Veredicto cuando el drift sale del rango	Impacto en OVERALL
T < 30 s	skipped (el ruido domina sobre el límite de ±30 ppm)	ninguno
30 s ≤ T < 300 s	WARN — solo informativo	ninguno
T ≥ 300 s	FAIL	OVERALL = FAIL, exit 65

300 s es la ventana de pruebas de aceptación del DVB TR 101 297 — lo bastante larga para que incluso una entrega bursty/loopback se promedie por debajo de 1 ppm de ruido de medición; un resultado fuera de especificación reflejaría entonces el reloj del encoder, no la red. El informe completo muestra el nivel actual en la línea Verdict mode del bloque PCR DRIFT.

Para obtener un veredicto PASS/FAIL estricto del drift, ejecute con -t 300 o más.

Recomendaciones sobre la calidad de la fuente (informativo; los niveles de veredicto no cambian):

Fuente	Ventana mínima para ±5 ppm	Para ±2 ppm	Aceptación
Multicast broadcast (red CBR, jitter < 100 µs)	30 s	60 s	5 min
Red IP estable (jitter < 200 µs)	30 s	2 min	5–10 min
Loopback / emisor en ráfagas (UDP unicast en lo)	5 min	15 min	30 min
Calibración / medición de laboratorio	—	30 min	1+ hora

Ejemplos:

# Быстрая проверка дрейфа PCR на реальном вещательном multicast (30 с)
ts_analyze -t 30 -s udp://239.1.1.1:5000

# Надёжная проверка на loopback-источнике (5 мин)
ts_analyze -t 300 -s udp://lo@127.0.0.1:12655

# Лабораторная приёмка (30 мин, полный отчёт в файл)
ts_analyze -t 1800 -f --no-color udp://239.1.1.1:5000 > acceptance.txt

Si se analiza el mismo flujo en varias ventanas cortas y el valor del drift varía más de unos pocos ppm entre ventanas, el cuello de botella es el jitter de entrega (cadencia del emisor o la red) y no el reloj del codificador — amplíe la ventana.

Códigos de salida

Código	Valor
0	Análisis completado, OVERALL = PASS
1	Error de argumento o entrada
2	El flujo no contiene datos PCR
3	Duración del flujo por debajo del mínimo de 2 s
65	Análisis completado, OVERALL = FAIL — incumplimiento de TR 101 290 / ISO 13818-1
130	Interrumpido por SIGINT (Ctrl+C) — análisis abortado, no se genera informe
143	Interrumpido por SIGTERM — análisis abortado, no se genera informe

65 es EX_DATAERR de POSIX <sysexits.h>: «input data was incorrect». Úselo en CI/monitorización como puerta de conformidad del flujo:

ts_analyze -s -t 60 udp://239.1.1.1:5000 || {
    case $? in
        65)  echo "поток не соответствует — см. отчёт" >&2 ;;
        130) echo "прервано пользователем" >&2 ;;
        *)   echo "ошибка инструмента" >&2 ;;
    esac
}

Los códigos 130/143 siguen la convención POSIX shell 128 + signal_number, por lo que $? después de Ctrl+C coincide con lo que devuelve bash para cualquier proceso terminado por SIGINT/SIGTERM. En caso de interrupción, el analizador imprime una sola línea en stderr (Analysis interrupted by signal N — no report produced.) y omite por completo la generación del informe.

Ejemplo de salida

Informe completo (extracto)

========================================================================
  MPEG-TS ANALYZER v2.2 — TR 101 290 FULL REPORT
========================================================================
  Source     : udp://239.1.1.1:5000
  Duration   : 30.00 s
  Packets    : 398936 total, 12045 null
  TS bitrate : 20.012 Mbit/s
------------------------------------------------------------------------

========================================================================
  TR 101 290 — PRIORITY 1 (TS decodability)
========================================================================
  |  1.1   TS Sync Byte Error            :        0 errors  PASS
  |  1.4   Continuity Count Error        :        0 errors  PASS
  |  1.6   PID Error (5s absence)        :        0 errors  PASS
  ...

========================================================================
  TR 101 290 — PRIORITY 2 (recommended monitoring)
========================================================================
  |  2.3   PCR Repetition Error          :        0 errors  PASS
  |  2.5   PCR Accuracy Error            :        0 errors  PASS
  ...

========================================================================
  OVERALL COMPLIANCE: PASS  — stream is TR 101 290 compliant
========================================================================

Informe breve

MPEG-TS Analyzer v2.2
TR 101 290 Summary | udp://239.1.1.1:5000 | 30.0s
----------------------------------------------------------------------------------------------------
  P1: sync=0 CC=0 PAT=0 PMT=0 PID=0  P2: TEI=0 CRC=0 PTS=0  P3: NIT=0 SDT=0 EIT=0 TDT=0 unref=2
  IAT: dgrams=33252 avg=0.150 ms max=5.009 ms p99=1.076 ms gaps>100ms=0
----------------------------------------------------------------------------------------------------
PCR PID       SID     Count     Intv max      Jitter max    Drift     Interval  Accuracy  T-STD
----------------------------------------------------------------------------------------------------
0x0101        1       1500      20.195 ms     76.4 ns       0ppm      PASS      PASS      PASS
----------------------------------------------------------------------------------------------------
OVERALL: PASS

Notas

• Modo fichero: el drift PCR, el modelo de buffers T-STD y el UDP IAT no se miden — requieren una referencia en tiempo real. El resto de comprobaciones funciona en ambos modos.

• Un único flujo de transporte: se analiza un MPTS o SPTS por ejecución.