Documentation
¶
Overview ¶
Package media decodes a media file into what a perceptual hash needs: mono PCM at a chosen sample rate, or video frames resampled to a chosen rate by time.
It is the plumbing, not the policy. Thresholds, verdicts and what counts as a duplicate belong to the caller — this package only turns a path into samples or pictures, and refuses loudly when it cannot.
Why it is a package ¶
Every function here encodes a decision that goes wrong SILENTLY if two copies of it drift apart. A downmix that takes the first channel instead of averaging compares a one-channel recording against silence; PCM read at the wrong sample width is noise that still hashes; a 10-bit frame truncated to 8 gives one film two different fingerprints; frames taken every nth instead of by time put a 25 fps and a 30 fps copy on different indices. None of those crash, and none fail a test. They produce two tools that disagree about whether two files are the same, confidently.
Index ¶
- Constants
- Variables
- func Downmix(a decode.Audio) ([]float64, error)
- func FrameImage(f decode.Frame) (image.Image, error)
- func Frames(path string, fps float64, maxSeconds int, ...) error
- func IsPCM(codec string) bool
- func Mono(path string, rate, maxSeconds int) ([]int16, error)
- func MonoFloat(path string, maxSeconds int) (samples []float64, rate int, err error)
- func PCMValue(codec string, b []byte, width int) (float64, error)
- func Resample(mono []float64, from, to int) ([]int16, error)
- type Kind
Constants ¶
const HeaderBytes = 64 << 10
HeaderBytes is how much of a file Classify reads before deciding.
Enough for every signature container.Sniff looks at, and for the configuration header of a JPEG, PNG or GIF. MPEG-TS is the greediest: its sync byte recurs every 188 bytes and a sniffer wants several packets before believing it, so this is generous rather than minimal.
Variables ¶
var ErrNoFrames = errors.New("media: the video track yielded no frames")
ErrNoFrames means the video track decoded to nothing. Like ErrNoSamples it is a skip rather than a failure.
var ErrNoSamples = errors.New("media: the audio track yielded no samples")
ErrNoSamples means the track decoded to nothing, or to too little to fingerprint. It is a skip, not a failure: a one-frame file is not broken.
Functions ¶
func Downmix ¶
Downmix averages one buffer's channels into samples in [-1, 1].
⛔ AVERAGING, not taking the first channel. A track whose content sits in one channel — an interview, a badly mixed rip, a karaoke version — would otherwise be compared against silence, and silence matches other silence, so such files would all group together as "the same recording".
func FrameImage ¶
FrameImage wraps a decoded frame's planes as an image WITHOUT copying them.
⛔ It refuses what it cannot represent honestly rather than approximating. A 10-bit frame shifted down to 8 bits would hash perfectly well — and would hash DIFFERENTLY from the same film delivered as 8-bit, so one film would carry two fingerprints. For a tool whose whole purpose is deciding whether two files are the same thing, that is the one failure that must never be silent.
func Frames ¶
func Frames(path string, fps float64, maxSeconds int, fn func(index int, img image.Image) error) error
Frames decodes a file's first video track, resampled to fps, and hands each frame to fn as an image.
maxSeconds bounds how much is read (0 reads all of it). If fn returns an error, decoding stops and that error is returned.
⛔ Frames are resampled BY TIME, not by taking every nth frame. A video hash compares phases at integer frame indices, so a 30 fps and a 25 fps copy of one film must land on the SAME indices — which happens only if each index is filled by the frame showing at that instant. Taking every other frame of the 30 fps file and every frame of a 15 fps one produces two valid-looking hashes that cannot be compared, and nothing says so.
⛔ A callback rather than a returned slice, because a decoded video does not fit in memory and no caller wants it there: they hash frame by frame.
func IsPCM ¶
IsPCM says whether a track's samples are already PCM and need no decoder.
⛔ These are the codecs a container reports for a WAV: `ipcm` signed integer, `fpcm` float, `raw ` unsigned 8-bit. go-avkit's decoder REFUSES all three — correctly, since the samples already ARE PCM and there is nothing to decode — so a consumer that only knows how to call a decoder cannot read a WAV at all, which is the simplest format in the list.
Reported upstream (go-avkit/decode, 2026-11-15, with a working implementation offered). This package carries the passthrough meanwhile, in one place, so the workaround does not get copied into every consumer.
func Mono ¶
Mono decodes a file's first audio track to mono samples at rate, reading at most maxSeconds of it (0 reads all of it).
The chain is demux, decode to PCM, downmix to mono, resample. Each step is somebody else's job done properly — the container and decoder are go-avkit's, the resampler is go-dsp's — and this is the plumbing between them.
⛔ The RATE is part of a fingerprint, not a preference. A feature's frame geometry and frequency bounds are expressed in samples at a particular rate, so audio fed at another rate produces a perfectly plausible fingerprint that matches nothing. Callers pass the rate their feature is defined at and do not treat it as a tuning knob.
func MonoFloat ¶
MonoFloat is Mono without the resampling or the conversion to int16: the track's own samples, downmixed, in [-1, 1], with the rate they are at.
It exists for a caller whose feature wants float input or another rate.
func PCMValue ¶
PCMValue turns one PCM sample's bytes into a value in [-1, 1].
It is exported because the sample width cannot be read from the track configuration, so a caller doing its own PCM reading needs the same conversion rather than a second guess at it.
func Resample ¶
Resample brings mono samples from one rate to another and converts them to int16.
⛔ It CLAMPS. A polyphase resampler rings, and its ringing overshoots a full-scale signal; converting an overshoot to int16 without clamping wraps it to the opposite sign, which puts a click into the feature — content that is not in the recording.
Types ¶
type Kind ¶
type Kind string
Kind is what a file turned out to hold.
func Classify ¶
Classify says what a file holds, by READING it.
⛔ Not by its extension. An extension is a claim by whoever named the file, and a download folder is full of wrong ones: a .jpg holding a PNG, an .mp4 holding only audio, a film saved with no extension at all. Code that believes the name returns a confident wrong answer — and for a tool that looks for copies, a file it cannot see reads as "nothing found", which is indistinguishable from a clean tree.
It works in two stages, because a tree scan cannot afford to read every file whole. The header alone settles images and the audio-only containers. Only a container that could hold either gets opened properly, and that open STREAMS rather than slurping the file, which matters when the candidate is a 4 GB film.
A file holding BOTH audio and video is KindVideo. Its pictures are the stronger evidence: two different films can share a soundtrack, while one film in two languages shares its pictures.