Skip to content

Inspecting Stream Information

Use probe to quickly check what a file contains before you analyze it: container, programs and PIDs, codecs, resolution, frame rate, interlacing, bitrate, audio layout, and whether an SCTE-35 PID is present. probe does not decode the video, so it finishes in a fraction of a second, even for large files. It does not need a registration.

Showing the stream information

surfmeter-media probe channel1.ts

The output is a sequence of NDJSON records on standard output: a run_info record at the start, one stream_info record per input, and a final run_info record with the status of the run.

The stream_info record has three parts:

  • container: format, duration, start time, size and overall bitrate
  • programs: for transport streams, the program number, PMT PID, PCR PID, and service and provider name of each program
  • streams: one entry per elementary stream, with its PID, stream type, codec, profile and level, and video or audio properties

In addition, has_scte35 and scte35_pids tell you whether the transport stream carries SCTE-35 cue messages.

Extracting the key facts with jq

The records are easier to read when you filter them with jq. For example, to list the streams of an interlaced MPEG-2 broadcast recording:

surfmeter-media probe channel1.ts | jq -c '
  select(.type == "stream_info") | .streams[] |
  {pid, kind, codec, width: .video.width, height: .video.height,
   frame_rate: .video.frame_rate, field_order: .video.field_order,
   channels: .audio.channels}'

{"pid":256,"kind":"video","codec":"mpeg2video","width":1920,"height":1080,"frame_rate":25.0,"field_order":"tt","channels":null}
{"pid":257,"kind":"audio","codec":"mp2","width":null,"height":null,"frame_rate":null,"field_order":null,"channels":2}

field_order is progressive for progressive video, and tt (top field first) or bb (bottom field first) for interlaced video. The interlaced field gives the same information as a boolean.

To check a batch of files for SCTE-35 PIDs:

for f in recordings/*.ts; do
  surfmeter-media probe -q "$f" | jq -r --arg f "$f" '
    select(.type == "stream_info") | "\($f): scte35=\(.has_scte35) \(.scte35_pids)"'
done

Probing several files at once

probe accepts several inputs. Each input gets an ID ("0", "1", …), which the input field of each stream_info record refers to. The run_info record lists the inputs with their IDs and file names.

surfmeter-media probe -o probe-results ladder/*.mp4

With -o, the toolkit also writes a summary.json that groups the stream information by input. This is convenient for an overview of a whole bitrate ladder:

jq -r '.inputs[] | .label as $l | .stream_info[] | .streams[] | select(.kind == "video") |
  "\($l)\t\(.codec)\t\(.video.width)x\(.video.height)\t\(.bitrate // "-")"' \
  probe-results/summary.json

Next steps

Once you know what the file contains, analyze the encode for bitstream statistics, pixel metrics and the P.1204.3 score.