Skip to main 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, and checks the loudness of the audio.

Broadcasters, streaming operators, and encoding engineers can use it to validate encodes and tune bitrate ladders.

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-1/2, 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.
  • Video 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.
  • Audio loudness: momentary, short-term and integrated loudness, loudness range and true peak based on ITU-R BS.1770 and EBU R 128.
  • 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.
  • 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, and to decode the audio for the loudness measurement
  • 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.
  • For MPEG-2 and AV1, the toolkit reports bitstream statistics, pixel metrics, and full-reference metrics. P.1204.3 scores are unavailable for these codecs.
  • For audio, there is no quality score for the lack of an accurate bitstream model.

Next steps​

Install the toolkit, then register it with your key. The use cases include examples for validating an encode and checking loudness compliance.