Skip to 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)

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.

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

surfmeter-media analyze --tui input.ts

You can combine --tui with -o, so the results are also saved. 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.