filetype

filetype is a small, dependency-free Go package that identifies a file’s true type by inspecting its magic number header signature rather than trusting its extension. It recognizes a wide range of image, video, audio, archive, document, font, and application formats, and exposes both single-type checks (filetype.Is, filetype.IsMIME) and class-level helpers (filetype.IsImage, filetype.IsArchive) for quick classification.

Because it only needs the first 262 bytes of a file, filetype works efficiently on large files, streams, and byte slices alike, and it accepts os.File, io.Reader, or raw []byte inputs through MatchFile, MatchReader, and Match. Its matcher registry is pluggable, so applications can register additional custom types and matching functions alongside the built-in set without forking the library.

What You Get

• Type detection via magic-number matching for images, video, audio, archives, documents, fonts, and application formats
• Class-level helpers (IsImage, IsAudio, IsVideo, IsArchive, IsDocument, IsFont, IsApplication) for quick categorization
• File, reader, and byte-slice APIs (MatchFile, MatchReader, Match) covering common input sources
• A pluggable matcher registry (AddMatcher, AddType) for registering custom file types alongside the built-ins
• MIME type resolution alongside file extension for every detected type

Common Use Cases

• Validating uploaded files server-side before accepting or storing them
• Sniffing the real type of a file when its extension or declared Content-Type can’t be trusted
• Filtering or routing files in a processing pipeline by class (image, video, document, etc.)
• Building custom file-type registries for domain-specific binary formats

Under The Hood

Architecture filetype separates concerns across three packages: the root package (filetype.go, match.go, kind.go) exposes the public API, matchers/ owns per-category type registries (image.go, video.go, audio.go, archive.go, document.go, font.go, application.go) plus a matchers.go registry that stores a global map[types.Type]TypeMatcher and an ordered MatcherKeys slice, and types/ defines the Type struct with a sync.Map-backed registry for extension/MIME lookups. Matching flows from filetype.Match through matchers.MatcherKeys — populated at init() time via register(Archive, Document, Font, Audio, Video, Image, Application), with the ordering intentional since NewMatcher prepends each new registration so Archive types are tried last — down to individual matcher closures in matchers/*.go that inspect a small byte-slice header. Extending the built-in set means editing matchers.go’s init() list, while user-defined types only require calling AddType/AddMatcher, since the registry is designed to be extended at runtime rather than requiring a fork.

Tech Stack The module (go.mod, module github.com/h2non/filetype, go 1.13) has zero third-party dependencies — the entire implementation uses only the Go standard library (os, io, errors, sync). There is no build tooling beyond go build/go test; CI (.github/workflows/ci.yml) runs go test ./… across a Go 1.19-1.21 version matrix and separately enforces gofmt -s and go vet as a lint job. The matchers/isobmff subpackage implements a small hand-rolled parser for ISO base media file format boxes (used for heif/avif/mp4-family detection) rather than depending on an external container-format library.

Code Quality Testing is table-driven and colocated with the code under test (filetype_test.go, match_test.go, kind_test.go, matchers/split_test.go), covering the public Match/Is*/MatchFile/MatchReader surface, plus a fixtures/ directory of real sample files per format used in benchmarks. Error handling is minimal but explicit — Match returns a typed types.Unknown plus a small set of sentinel errors (ErrEmptyBuffer, ErrUnknownBuffer) rather than panicking or silently swallowing failures. Naming is consistent, idiomatic Go with doc comments on every exported symbol, and CI enforces gofmt and go vet on every push and pull request, though there is no golangci-lint or deeper static-analysis step beyond vet.

API Design The public surface is intentionally layered for progressive disclosure: a single filetype.Match(buf) covers the common case, class helpers (IsImage, IsVideo, IsArchive, etc.) cover categorical checks, and MatchFile/MatchReader remove the boilerplate of opening a file or pre-reading a header slice. Getting started requires only a go get plus one import and one function call, with no configuration objects or interfaces to implement — the tradeoff is a package-level global matcher registry instead of an injectable instance, which favors simplicity over isolation in multi-tenant scenarios.