Basic Usage
This page describes the options and behavior shared by all commands. For complete examples, see the use cases in the sidebar.
Run surfmeter-media --help for an overview, and surfmeter-media <command> --help for all options of a command.
Supported inputs
The toolkit reads local files in these containers:
- MPEG transport streams (
.ts,.m2ts) and program streams (.mpg) - MP4 and MOV, including fragmented MP4
- Matroska and WebM
- AVI
- Raw elementary streams (for example
.h264,.hevc,.m2v) - Audio-only files, for example WAV, raw
.ac3and.eac3, and MP4 or Matroska files with only audio. For these files, only the audio loudness is measured.
The bitstream statistics are available for MPEG-1 and MPEG-2 video, H.264, HEVC, VP9 and AV1. The P.1204.3 score is available for H.264, HEVC and VP9, as of October 2026.
Pixel metrics and full-reference metrics work for every codec that FFmpeg can decode, including intermediate formats such as FFV1 or ProRes, which are useful as references.
Interlaced video is detected and deinterlaced automatically with FFmpeg's bwdif filter before pixel analysis and comparison. Use --deinterlace bwdif|yadif|off to change this.
Output
By default, analyze and compare write their records as NDJSON (one JSON object per line) to standard output, and progress messages to standard error. This lets you pipe the results into other tools:
surfmeter-media analyze input.ts > records.ndjson
With -o <directory> (or --output), the toolkit writes files into that directory instead:
records.ndjson: all records, one JSON object per linesummary.json: one JSON document with the stream information, overall scores and statistics per input- one CSV file per record type, for example
frame_bitstream.csvandsummary.csv, if CSV output is enabled
--format selects the files. The default is ndjson,json. To also write CSV files, list all formats you want:
surfmeter-media analyze -o results --format ndjson,json,csv input.ts
See Output Format for a description of the records and files.
Analysis layers
analyze and compare run their no-reference analysis in layers. Select them with --layers, as a comma-separated list:
bitstream: bitstream statistics per framepixels: no-reference pixel metrics per framep1204: the quality score from the bitstreamaudio: loudness, levels and dialnorm of the audio streamsnone: no layer (incompare, only the full-reference metrics)
analyze runs all layers by default. compare runs bitstream,p1204,audio by default.
Audio loudness
The audio layer measures the loudness and levels of every audio stream. It follows ITU-R BS.1770, EBU R 128 (with EBU Tech 3341 and 3342) and ATSC A/85. For AC-3 and E-AC-3 streams, it also reads the dialnorm and other metadata. The layer is on by default. --layers audio measures only the audio, which is much faster than the video layers.
These options control the layer:
--loudness-target <target>: the target that each audio stream is checked against. Give the option several times for several targets. The default isebu-r128andatsc-a85.--audio-streams <list>: the audio streams to measure, as a comma-separated list of stream indexes asprobeshows them, for example--audio-streams 1,3. The default isall.--duration <seconds>: limits the audio in the same way as the video.
The targets:
| Target | Integrated loudness | Tolerance | Maximum true peak | Checks dialnorm |
|---|---|---|---|---|
ebu-r128 | -23 LUFS | ±0.2 LU | -1 dBTP | no |
ebu-r128-live | -23 LUFS | ±1 LU | -1 dBTP | no |
atsc-a85 | -24 LKFS | ±2 dB | -2 dBTP | yes |
arib-tr-b32 | -24 LKFS | ±1 dB | -1 dBTP | no |
op59 | -24 LKFS | ±1 LU | -2 dBTP | no |
LEVEL:TOLERANCE:MAX_TRUE_PEAK, for example -16:1:-1 | as given | as given | as given | no |
ebu-r128 uses the ±0.2 LU that EBU R 128 allows for measurement errors in the quality control of finished programmes. ebu-r128-live uses the ±1 LU that EBU R 128 allows for live programmes. It suits linear channels with mixed content.
The integrated loudness and the true peak are rounded to 0.1 before the check, as loudness meters show them. For example, -23.24 LUFS passes ebu-r128.
See Checking Loudness Compliance for examples, and Metrics for the values.
Terminal view
This is the mode you want when you sit in front of the computer and want to see the analysis as it runs.
Add --tui to analyze or compare to open the interactive terminal view. It fills in while the analysis runs and stays open when it is done. The view shows a timeline with one track per metric, a summary table, and a list of events (for example scene changes, freezes, decoder errors or PTS discontinuities). For files with audio, it also shows a loudness track and an audio panel (see Reviewing Saved Results).
- Native Execution
- Docker on Linux and macOS
- Docker on Windows (PowerShell)
surfmeter-media analyze --tui input.ts
docker run --rm -it --user "$(id -u):$(id -g)" \
-v surfmeter-media-config:/config -v "$PWD:/data" \
europe-west3-docker.pkg.dev/aveq-storage/surfmeter/surfmeter-media:latest \
analyze --tui input.ts
docker run --rm -it `
-v surfmeter-media-config:/config -v "${PWD}:/data" `
europe-west3-docker.pkg.dev/aveq-storage/surfmeter/surfmeter-media:latest `
analyze --tui input.ts
In Docker, -it is required for the terminal view. The examples use the registration volume from Registration.
To also save the results, combine --tui with -o. Saved results can be opened again later with surfmeter-media view (see Reviewing Saved Results).
Press ? in the view to list all keys. Press q to quit.
Click to select an input, panel or row, or to move the cursor; use the scroll wheel to zoom the timeline.
In the metric list (m), you can tick metrics that were not computed in the run, for example the pixel metrics in compare, or PSNR after --no-psnr. The toolkit then computes them in the background and fills in their tracks. r shows the state of these jobs. If you saved the run with -o, the new records are added to the output files.
Errors and interruptions
Errors are printed on standard error. They are also recorded in the final run_info record.
statusiscompleted,completed_with_errors(the run finished, but some analysis layers failed for some inputs),failed, orinterrupted.errorslists each error with the component and input it belongs to.
In scripts, check the status field in addition to the exit code.