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)
ffmpegwith libvmaf for VMAF, PSNR, SSIM, deinterlacing and frame alignment, and to decode the audio for the loudness measurementffprobefor the stream information
See Basic Usage for the usage options.
- 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.