Skip to main content

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 .ac3 and .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

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 line
  • summary.json: one JSON document with the stream information, overall scores and statistics per input
  • one CSV file per record type, for example frame_bitstream.csv and summary.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 frame
  • pixels: no-reference pixel metrics per frame
  • p1204: the quality score from the bitstream
  • audio: loudness, levels and dialnorm of the audio streams
  • none: no layer (in compare, 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 is ebu-r128 and atsc-a85.
  • --audio-streams <list>: the audio streams to measure, as a comma-separated list of stream indexes as probe shows them, for example --audio-streams 1,3. The default is all.
  • --duration <seconds>: limits the audio in the same way as the video.

The targets:

TargetIntegrated loudnessToleranceMaximum true peakChecks dialnorm
ebu-r128-23 LUFS±0.2 LU-1 dBTPno
ebu-r128-live-23 LUFS±1 LU-1 dBTPno
atsc-a85-24 LKFS±2 dB-2 dBTPyes
arib-tr-b32-24 LKFS±1 dB-1 dBTPno
op59-24 LKFS±1 LU-2 dBTPno
LEVEL:TOLERANCE:MAX_TRUE_PEAK, for example -16:1:-1as givenas givenas givenno

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).

surfmeter-media 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.

Using the mouse

Click to select an input, panel or row, or to move the cursor; use the scroll wheel to zoom the timeline.

Computing metrics on demand

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.

  • status is completed, completed_with_errors (the run finished, but some analysis layers failed for some inputs), failed, or interrupted.
  • errors lists each error with the component and input it belongs to.

In scripts, check the status field in addition to the exit code.