Skip to content

Surfmeter Media Toolkit

The Surfmeter Media Toolkit (surfmeter-media) is a command-line tool that analyzes video files. It shows how a file is structured, how it was encoded, what the decoded pictures look like, and what quality a viewer can expect. It also compares encodes against their source with full-reference metrics such as VMAF.

The toolkit is aimed at broadcasters, streaming operators and encoding engineers who want to validate encodes, tune bitrate ladders, etc.

Features

The toolkit combines several analysis layers on a single timeline:

  • Stream information: container, programs and PIDs of transport streams, codecs, resolution, frame rate, bitrate, interlacing, color properties, audio layout, and whether an SCTE-35 PID is present.
  • Bitstream statistics per frame: QP (average, standard deviation, minimum, maximum), frame types, frame sizes, motion vector statistics, and decoder errors. Supported for MPEG-½, H.264, HEVC, VP9 and AV1.
  • No-reference pixel metrics per frame: blockiness, blurriness, noise, brightness, black frames, freezes, scene changes, spatial and temporal information (SI/TI), jerkiness, and more.
  • Quality model: the ITU-T P.1204.3 score (MOS from 1 to 5) per second, per GOP and for the whole file
  • Full-reference metrics: VMAF, PSNR and SSIM of one or more encodes against a reference, with automatic frame alignment, scaling and deinterlacing.
  • Comparison of several encodes side by side, including the difference of every summary value against the reference.
  • Machine-readable output: NDJSON records, a summary JSON document, and CSV files for spreadsheets, all described by a JSON Schema.
  • A Terminal UI for interactive exploration of the results

How it works

surfmeter-media is a single CLI program that ships with a bundle of analysis components:

  • videoparser-ng, AVEQ's open-source bitstream parser based on a patched FFmpeg, for the bitstream statistics and decoding
  • AVEQ's implementation of ITU-T P.1204.3 for the quality score (see ITU-T P.1204)
  • AVEQ's video analyzer for the no-reference pixel metrics (the same analyzer as in the Video Analyzer SDK)
  • ffmpeg with libvmaf for VMAF, PSNR, SSIM, deinterlacing and frame alignment
  • ffprobe for the stream information

See Basic Usage for the usage options.

Current Limitations

  • Only files are supported. Live streams (HLS, DASH, MPEG-TS over UDP, RTP or SRT) are on our roadmap.
  • P.1204.3 does not cover MPEG-2 and AV1. For those, the toolkit reports bitstream statistics, pixel metrics and full-reference metrics, but no P.1204.3 score. We are working on this!
  • We don't analyze audio yet.

Next steps

Head to Installation to set up the toolkit, then register it with your key. The use cases show complete examples for common tasks.