TS Analyzer

ts_analyze.py parses and analyzes 188-byte MPEG-2 transport stream packets from .ts files captured by tune.py, piped from stdin, or any standard TS source. It covers PID distribution, PAT/PMT parsing, continuity counter verification, scrambling detection, bitrate estimation, and live stream monitoring.

Reference: ISO/IEC 13818-1 (MPEG-2 Systems).

Subcommands

Subcommand	Purpose
`analyze`	Full stream analysis with PID table, CC errors, bitrate (default)
`pids`	Quick PID summary table
`pat`	Parse and display the Program Association Table
`pmt`	Parse and display Program Map Tables
`dump`	Hex dump of individual TS packets
`monitor`	Live stream monitoring with real-time statistics

Passing a filename without a subcommand defaults to analyze.

Global Options

Flag	Description
`-v, --verbose`	Show sync search details and debug info

analyze — Full Stream Analysis

Comprehensive analysis of a TS file or stream: total packets, unique PIDs, TEI errors, scrambling, continuity counter errors, PCR-based bitrate, and a per-PID distribution table.

python3 tools/ts_analyze.py capture.ts

python3 tools/ts_analyze.py analyze capture.ts --max-packets 10000

Flag	Description
`INPUT`	TS file path or `-` for stdin
`--max-packets N`	Limit analysis to N packets (0 = all)

Example output:

MPEG-2 Transport Stream Analysis
============================================================
File: capture.ts (52,428,800 bytes)

Total packets: 278,876
Total bytes:   52,428,688
Unique PIDs:   12
TEI errors:    0
Scrambled:     0
Duration:      5.23s (from PCR)
Bitrate:       80.21 Mbps (PCR-based)

============================================================
PID Distribution
============================================================
     PID       Count        %  CC Err  Name
     ---       -----       --  ------  ----
  0x0000       1,394    0.50%       -  PAT
  0x0001         278    0.10%       -  CAT
  0x0010         556    0.20%       -  NIT/ST
  0x0011         556    0.20%       -  SDT/BAT/ST
  0x0100     139,438   50.00%       -
  0x0101      83,663   29.99%       -
  0x0102       5,576    2.00%       -
  0x1FFF      47,415   17.01%       -  Null

What It Detects

Metric	Description
PID count	Packet count per Program ID
TEI	Transport Error Indicator flag in the TS header
Scrambling	Transport scrambling control bits (even/odd key)
CC errors	Continuity counter discontinuities per PID
Bitrate	Calculated from PCR timestamps when available

pids — Quick PID Table

Faster variant of analyze that only counts packets per PID without CC checking or PCR extraction.

python3 tools/ts_analyze.py pids capture.ts

pat — Program Association Table

Parses PID 0x0000 to extract the PAT, showing the transport stream ID and which PMT PID corresponds to each program number.

python3 tools/ts_analyze.py pat capture.ts

Program Association Table (PAT)
==================================================
  Transport Stream ID: 0x0001 (1)
  Version: 3
  Programs: 2

     Program     PMT PID  Note
     -------     -------  ----
           0  0x0010      NIT
           1  0x0100

pmt — Program Map Tables

Parses the PAT first to discover PMT PIDs, then parses each PMT to show the elementary streams (video, audio, data) in each program.

python3 tools/ts_analyze.py pmt capture.ts

Program Map Tables
============================================================
Transport Stream ID: 0x0001

  Program 1 (PMT PID 0x0100, version 2)
  PCR PID: 0x0101
  Streams:
      Type     PID  Description
      ----     ---  -----------
      0x02    0x0101  MPEG-2 Video (13818-2)
      0x04    0x0102  MPEG-2 Audio (13818-3)
      0x06    0x0103  PES Private Data

Known Stream Types

The tool recognizes these standard stream type identifiers:

Code	Description
0x01	MPEG-1 Video
0x02	MPEG-2 Video
0x03	MPEG-1 Audio
0x04	MPEG-2 Audio
0x06	PES Private Data
0x0F	MPEG-2 AAC Audio
0x1B	H.264/AVC Video
0x24	H.265/HEVC Video
0x81	AC-3 Audio (ATSC)

dump — Hex Dump Packets

Print detailed per-packet information including header fields, adaptation field flags, PCR values, and raw hex dump.

python3 tools/ts_analyze.py dump capture.ts --count 5

python3 tools/ts_analyze.py dump capture.ts --pid 0x0100 --count 3

Flag	Description
`--pid PID`	Filter by PID (hex `0x100` or decimal `256`)
`--count N`	Maximum packets to dump (default: `10`)

Example output:

Packet #1
  PID: 0x0000 (PAT)
  TEI: 0  PUSI: 1  Priority: 0
  Scrambling: none  Adaptation: payload only  CC: 5
  Hex:
    0000: 47 40 00 15 00 00 B0 0D 00 01 C1 00 00 00 00 E0  G@..............
    0010: 10 00 01 E1 00 78 A0 B4 FF FF FF FF FF FF FF FF  .....x..........
    ...

monitor — Live Stream Monitoring

Real-time monitoring of a TS stream, reporting new PIDs as they appear, continuity errors, TEI errors, and bitrate.

sudo python3 tools/tune.py stream --stdout | python3 tools/ts_analyze.py monitor -

python3 tools/ts_analyze.py monitor capture.ts

The monitor prints events as they occur (new PIDs, errors) and updates a status line on stderr every second with running statistics.

MPEG-2 TS Live Monitor
============================================================
Ctrl-C to stop

  [    0.0s] New PID: 0x0000 (PAT)
  [    0.0s] New PID: 0x1FFF (Null)
  [    0.1s] New PID: 0x0100
  [    0.1s] New PID: 0x0101
  [    0.2s] New PID: 0x0102
      278,876 pkts    52,428,688 bytes    80.21 Mbps  PIDs: 12  CCerr:0  TEI:0  (5s)

Monitor Summary
========================================
  Duration:     5.2s
  Packets:      278,876
  Bytes:        52,428,688
  Unique PIDs:  12
  CC errors:    0
  TEI errors:   0
  Avg bitrate:  80.21 Mbps

Capturing a Transport Stream

To capture a TS stream for analysis, first tune to a transponder with tune.py, then capture with the stream subcommand:

sudo python3 tools/tune.py tune 12520 27500 --pol H --band high
sudo python3 tools/tune.py stream -o capture.ts --duration 30

sudo python3 tools/tune.py stream --stdout | python3 tools/ts_analyze.py monitor -

Sync Detection

The analyzer requires at least 3 consecutive sync bytes (0x47) at 188-byte intervals to confirm alignment. If the file starts with non-TS data (e.g., leading garbage from a partial USB transfer), the tool will skip ahead until sync is found.

When using -v (verbose), the sync search offset is reported. A non-zero sync offset may indicate that the capture started mid-packet or contains a non-TS preamble.