go-media

command module
v1.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 7 Imported by: 0

README

go-media

A pure-Go media library API that supports thumbnail generation, probing, metadata, and subtitles. (no ffmpeg or ffprobe subprocess.)

CI Go Reference

📊 Live comparison report · Examples · Capabilities · Docs


Built for go programs that value speed and efficiency as the primary concern (e.g. FileBrowser Quantum). The library is designed so anything thats unsupported will return typed errors so the app can fall back to ffmpeg without additional delay.

Measured against ffmpeg on every commit

[!TIP] 📊 View the live comparison report → Interactive charts, side-by-side thumbnails and per-format timing, regenerated from the latest main.

Report section Shows
🖼️ Side-by-side thumbnails go-media and ffmpeg output for every format, with PSNR and SSIM
⏱️ Timing per build tier pure Go, pure Go + PGO (production), and PGO + SIMD
✅ Correctness gate Supported results must match ffmpeg or ffprobe, and unsupported cases must return a typed error, or the build fails

To build the same report locally, run make compare (see test/compare/README.md).

Features

Capability Highlights
🔎 Probe Container, streams, codecs, dimensions, rotation, frame rate, sample rate
⏱️ Duration From headers, with a Source (header, estimate, scan) for cache provenance
🏷️ Tags & artwork ID3, MP4 ilst, Vorbis comments; APIC, covr and FLAC PICTURE cover art
💬 Subtitles SRT, VTT, ASS/SSA sidecars plus embedded MKV and MP4 text tracks, converted to WebVTT byte-identical to ffmpeg -f webvtt
🖼️ Thumbnails Video: one keyframe decoded in pure Go. Photos and RAW: the embedded JPEG preview. Audio: cover art. Output as JPEG, PNG or lossless WebP
🎵 Lyrics Embedded lyrics and .lrc / .elrc sidecars
🎞️ Keyframe times MP4/MOV/MKV/WebM keyframe timeline for HLS planning, read from the container index. Matches ffprobe's key packets when the index flags every keyframe; it can list fewer when ffprobe also flags keyframes it finds in the bitstream, or when Matroska Cues skip some
Thumbnail codecs
Codec Containers Decoder
H.264 Baseline, Main, High, High 10 MP4, MOV, M4V, AVI, MPEG-TS Clean-room intra decoder (details)
VP9 profile 0 WebM, MKV govpx, bit-exact with libvpx
VP8 WebM, MKV Pure Go
MPEG-4 Part 2 (DivX, XviD) MP4, MOV, MKV, AVI Clean-room I-VOP decoder, bit-exact with ffmpeg (details)
MPEG-2 MP4, MOV, MPEG-PS, MPEG-TS I-picture decoder
WMV3 (VC-1 Simple & Main) ASF, WMV Intra decoder, bit-exact with ffmpeg
MJPEG MP4, MOV, MKV, AVI Direct frame extract
HEVC Main, MP4/MKV/HEIC MP4, MKV, HEIC gen2brain/h265, IRAP keyframe thumbs
HEIC / HEIF, camera RAW HEIC, HEIF, AVIF, CR2, CR3, NEF, DNG… Embedded JPEG preview; HEIC without JPEG uses HEVC decode, AVIF uses AV1 decode; irot/imir and color tags applied like ffmpeg

[!NOTE] Per-format detail, partial support and ffmpeg equivalents are in Supported capabilities.

Quick start

go get github.com/gtsteffaniak/go-media
package main

import (
	"errors"
	"fmt"
	"log"
	"os"

	"github.com/gtsteffaniak/go-media/pkg/media"
)

func main() {
	f, err := os.Open("clip.mp4")
	if err != nil {
		log.Fatal(err)
	}
	defer f.Close()
	st, err := f.Stat()
	if err != nil {
		log.Fatal(err)
	}

	info, err := media.Probe(f, st.Size()) // format, streams, tags
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(info.FormatName, info.Duration)

	thumb, err := media.ThumbnailLarge(f, st.Size(), 10) // JPEG ~10% into the video
	if errors.Is(err, media.ErrUnsupported) || errors.Is(err, media.ErrUnsupportedProfile) {
		return // hand the file to ffmpeg instead
	} else if err != nil {
		log.Fatal(err)
	}
	if err := os.WriteFile("thumb.jpg", thumb.Data, 0o644); err != nil {
		log.Fatal(err)
	}
}

More recipes, including subtitles, tags, artwork, custom thumbnail sizes, caching and ffmpeg fallback, are in docs/examples.md.

Try it from the command line:

go run . probe    clip.mp4
go run . duration song.flac
go run . thumb clip.mkv --large thumb.jpg

[!IMPORTANT] Build releases with the checked-in PGO profile, the fastest supported configuration:

CGO_ENABLED=0 go build -pgo=default.pgo ./...

GOEXPERIMENT=simd kernels are experimental and off by default. See Profiling and SIMD.

Design principles

  • Pure Go. CGO_ENABLED=0, no WASM and no bundled binaries, so it cross-compiles anywhere.
  • Bounded work. For most formats it reads headers and sync samples and decodes one keyframe. MPEG-TS and MPEG-PS may scan packets across the file.
  • Fast or honest. A format that can't stay close to ffmpeg's speed returns ErrUnsupported or ErrUnsupportedProfile rather than being slow.
  • Provenance. DurationResult.Source, ProbeInfo.DurationSrc and ThumbnailResult.Source say how a value was found, so it can be cached next to ffprobe output.

[!NOTE] Not in scope: transcoding, streaming, playback and full random-access decode. Use go-ffmpeg for those; go-media is the fast path in front of it.

Documentation

Doc What's inside
Examples Copy-paste recipes for every API
Supported capabilities Full format and feature matrix with ffmpeg equivalents
Quality & CI Test matrix, the ffmpeg comparison gate and fuzzing
Comparison harness How the report is generated and how to run it locally
Profiling & PGO Build tiers, benchmarks and refreshing default.pgo
SIMD The GOEXPERIMENT=simd experiment and when it's enabled
H.264 · MPEG-4 Decoder internals, colour handling and accuracy
Third-party notices Dependencies and licenses

License

MIT. Third-party components are listed in THIRD_PARTY.md.

Documentation

Overview

Demo CLI for go-media. Library import: github.com/gtsteffaniak/go-media/pkg/media

Directories

Path Synopsis
bench
manifest
Package manifest describes the benchmark fixture corpus.
Package manifest describes the benchmark fixture corpus.
cmd
gomedia-bench command
Command gomedia-bench is the developer tool for the go-media benchmark framework (see bench/README.md).
Command gomedia-bench is the developer tool for the go-media benchmark framework (see bench/README.md).
gomedia-compare command
Command gomedia-compare fetches seed media, generates ffmpeg fixtures, runs go-media vs ffprobe/ffmpeg checks, and writes a static HTML report.
Command gomedia-compare fetches seed media, generates ffmpeg fixtures, runs go-media vs ffprobe/ffmpeg checks, and writes a static HTML report.
gomedia-thumbmode command
Command thumbmode benchmarks media.Thumbnail for one asset/preset (stdout: median write ms).
Command thumbmode benchmarks media.Thumbnail for one asset/preset (stdout: median write ms).
internal
asf
Package asf reads Advanced Systems Format (ASF/WMV/WMA) containers for probe, duration, and WMV3 video payload extraction.
Package asf reads Advanced Systems Format (ASF/WMV/WMA) containers for probe, duration, and WMV3 video payload extraction.
av1decode
Package av1decode decodes AV1 thumbnails with github.com/gen2brain/gav1d, a pure-Go, bit-exact port of dav1d.
Package av1decode decodes AV1 thumbnails with github.com/gen2brain/gav1d, a pure-Go, bit-exact port of dav1d.
avi
Package avi reads RIFF AVI containers (including OpenDML indexes) for probe, duration, and thumbnail keyframe lookup.
Package avi reads RIFF AVI containers (including OpenDML indexes) for probe, duration, and thumbnail keyframe lookup.
ffmpegtest
Package ffmpegtest holds helpers shared by the subtitle golden tests in internal/subtitle, internal/matroska and internal/isobmff.
Package ffmpegtest holds helpers shared by the subtitle golden tests in internal/subtitle, internal/matroska and internal/isobmff.
h264
Package h264 implements intra-only H.264/AVC keyframe decode for thumbnails.
Package h264 implements intra-only H.264/AVC keyframe decode for thumbnails.
h264/cleanroom
Package cleanroom implements decode-only H.264 intra for thumbnails.
Package cleanroom implements decode-only H.264 intra for thumbnails.
h264/cleanroom/bitstream
Package bitstream — reads H.264 fields from RBSP (bytes already without emulation-prevention).
Package bitstream — reads H.264 fields from RBSP (bytes already without emulation-prevention).
h264/cleanroom/decode
Package h264 parses H.264 syntax on top of bitstream/nal.
Package h264 parses H.264 syntax on top of bitstream/nal.
h264/cleanroom/nal
Package nal — parses the H.264 NAL (Network Abstraction Layer): splitting an Annex-B bytestream into NAL units, removing emulation-prevention (EBSP→RBSP) and parsing the NAL header.
Package nal — parses the H.264 NAL (Network Abstraction Layer): splitting an Annex-B bytestream into NAL units, removing emulation-prevention (EBSP→RBSP) and parsing the NAL header.
h264/frame
Package frame implements the frame buffer for H.264/AVC decoded pictures.
Package frame implements the frame buffer for H.264/AVC decoded pictures.
heifthumb
Package heifthumb reads embedded JPEG thumbnails from HEIF/HEIC/AVIF ISOBMFF files.
Package heifthumb reads embedded JPEG thumbnails from HEIF/HEIC/AVIF ISOBMFF files.
hevcdecode
Package hevcdecode decodes HEVC (H.265) IRAP/IDR keyframes for thumbnails.
Package hevcdecode decodes HEVC (H.265) IRAP/IDR keyframes for thumbnails.
isobmff
Package isobmff supports go-media parsers.
Package isobmff supports go-media parsers.
jpegfast
Package jpeg implements a JPEG image decoder and encoder.
Package jpeg implements a JPEG image decoder and encoder.
jxldecode
Package jxldecode decodes JPEG XL still images with github.com/gen2brain/jxl.
Package jxldecode decodes JPEG XL still images with github.com/gen2brain/jxl.
kernels
Package kernels provides hot numeric paths for thumbnail decode/scale/color.
Package kernels provides hot numeric paths for thumbnail decode/scale/color.
kernels/h264
Package h264 provides SIMD-oriented H.264 decode kernels: 4×4 IDCT residual, 4×4 prediction+residual write, and future intra/8×8 helpers.
Package h264 provides SIMD-oriented H.264 decode kernels: 4×4 IDCT residual, 4×4 prediction+residual write, and future intra/8×8 helpers.
mp3
mpeg2video
Package mpeg2video decodes MPEG-2 Video (ISO/IEC 13818-2) I-pictures for thumbnails.
Package mpeg2video decodes MPEG-2 Video (ISO/IEC 13818-2) I-pictures for thumbnails.
mpeg2video/bitreader
Package bitreader provides basic interfaces to read and traverse an io.Reader as a stream of bits, rather than a stream of bytes.
Package bitreader provides basic interfaces to read and traverse an io.Reader as a stream of bits, rather than a stream of bytes.
mpeg2video/huffman
Package huffman implements a naïve Huffman decoder.
Package huffman implements a naïve Huffman decoder.
mpeg4
Package mpeg4 decodes MPEG-4 Part 2 (ISO/IEC 14496-2) Simple and Advanced Simple Profile I-VOPs for thumbnails.
Package mpeg4 decodes MPEG-4 Part 2 (ISO/IEC 14496-2) Simple and Advanced Simple Profile I-VOPs for thumbnails.
mpegpes
Package pes implements an MPEG-2 packetized elementary stream parser as defined in ISO/IEC 13818-1.
Package pes implements an MPEG-2 packetized elementary stream parser as defined in ISO/IEC 13818-1.
mpegts
Package ts implements an MPEG-2 transport stream parser as defined in ISO/IEC 13818-1.
Package ts implements an MPEG-2 transport stream parser as defined in ISO/IEC 13818-1.
ogg
rawpreview
Package rawpreview extracts embedded JPEG previews from camera RAW files.
Package rawpreview extracts embedded JPEG previews from camera RAW files.
thumb
Package thumb renders scaled keyframe thumbnails (JPEG, PNG, WebP).
Package thumb renders scaled keyframe thumbnails (JPEG, PNG, WebP).
vc1
Code generated from SMPTE 421 / ffmpeg vc1_vlc_data.h factual tables.
Code generated from SMPTE 421 / ffmpeg vc1_vlc_data.h factual tables.
vp8decode
Package vp8decode decodes VP8 video frames (key and inter) for thumbnails.
Package vp8decode decodes VP8 video frames (key and inter) for thumbnails.
vp9decode
Package vp9decode decodes VP9 profile 0 key and inter frames for thumbnails.
Package vp9decode decodes VP9 profile 0 key and inter frames for thumbnails.
wav
pkg
media
Package media provides pure-Go fast paths for probing, metadata, subtitles, and thumbnails used by file browsing applications.
Package media provides pure-Go fast paths for probing, metadata, subtitles, and thumbnails used by file browsing applications.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL