metadata

README

go-metadata

Files carry a lot of information about themselves, in a different format for every kind of file: EXIF tags in a photo, ID3 tags in an MP3, document properties in a Word document, a Subject: header in an email. go-metadata reads them all into one set of metadata, so a photo, a song, a PDF and an email can be indexed and searched the same way. Common properties, such as a file's title, creator, date and kind, use the same keys whatever the format, mostly from Dublin Core, alongside the format's own properties in a namespace of their own, such as exif:, pdf: or email:. Beyond metadata, it extracts the content of documents as Markdown, a page at a time, and artwork, such as album covers, the thumbnails of photos, video frames, and images of the pages of documents. It can also look up the movie or TV episode a video is on The Movie Database.

It reads images (JPEG, PNG, GIF, WebP, TIFF, HEIF/AVIF, camera RAW, SVG, Photoshop), audio and video (anything FFmpeg can read, and playlists), documents (PDF, Word, Excel and PowerPoint, old and new, OpenDocument, Pages and Keynote, RTF, PostScript, EPUB and Kindle books), text (Markdown, HTML, XML, CSV, source code, vCards and iCalendars), email messages and mailboxes, and archives.

Requirements

go-metadata needs Go 1.27 or later. Most of it is pure Go, but a few of its handlers use C libraries, through cgo:

Handler	C library
Audio and video (audio/ffmpeg, video/ffmpeg)	FFmpeg 8
EXIF metadata of photos (image/exif)	libexif
HEIF and AVIF images (image/heif)	libheif
Camera RAW images (image/raw)	LibRaw
Classes of audio: speech, music or silence (audio/classify)	libfvad, which is optional
Fingerprints of audio, to look it up on AcoustID (pkg/chromaprint)	Chromaprint and libfvad, which are optional

FFmpeg needs to be FFmpeg 8, which go-media's bindings are for: FFmpeg 9 removed parts of its API which they use. These are only built with cgo. Without it, which is CGO_ENABLED=0, or when there's no C compiler, go-metadata builds without them. It still reads everything else, but returns no metadata or artwork from audio and video files, no EXIF metadata from photos, and nothing from HEIF and RAW images other than their type and kind.

libfvad, the WebRTC voice activity detector, which go-media's segmenter classifies and decodes audio with, is only built with the libfvad build tag, which the Makefile sets when it finds it. Without it, audio isn't classified. Chromaprint is only built with the chromaprint build tag, which the Makefile sets when it finds it and libfvad. Without it, audio is only looked up on AcoustID by the AcoustID identifier in its tags. Neither Homebrew nor Debian has libfvad, and Homebrew's chromaprint is built with FFmpeg 9, so to classify or fingerprint audio, build go-media's libraries, and set GO_MEDIA_PREFIX (see below).

The C libraries are found with pkg-config, so to build with cgo, install them, their development headers and pkg-config:

macOS (with Homebrew):

brew install pkg-config ffmpeg@8 libexif libheif libraw

Homebrew's ffmpeg@8 is installed alongside its ffmpeg, which is FFmpeg 9, so it isn't found unless it's on PKG_CONFIG_PATH. The Makefile (see below) does that for you; to build with go itself, set:

export PKG_CONFIG_PATH="$(brew --prefix ffmpeg@8)/lib/pkgconfig"
export CGO_CFLAGS_ALLOW="-Xpreprocessor" CGO_LDFLAGS_ALLOW="-Xpreprocessor"

as Homebrew's LibRaw is built with OpenMP, whose -Xpreprocessor flag cgo doesn't allow by default.

Linux (Debian and Ubuntu):

apt install build-essential pkg-config libexif-dev libheif-dev libraw-dev \
  libavcodec-dev libavformat-dev libavutil-dev libavdevice-dev libavfilter-dev \
  libswscale-dev libswresample-dev

and on Fedora:

dnf install gcc pkg-config libexif-devel libheif-devel LibRaw-devel ffmpeg-free-devel

Many Linux distributions ship a version of FFmpeg other than 8. If yours does, go-media, which go-metadata uses for its C bindings, can build FFmpeg 8 and the other libraries from source, as static libraries: run make in a clone of it, and then build go-metadata with make GO_MEDIA_PREFIX=<go-media>/build/install, or with go itself, with PKG_CONFIG_PATH set to its build/install/lib/pkgconfig folder, CGO_LDFLAGS_ALLOW="-(W|D).*" and CGO_LDFLAGS="-lstdc++", and -tags libfvad,chromaprint to classify and fingerprint audio. make ffmpeg chromaprint libexif libraw libheif libfvad in go-media builds the libraries which go-metadata uses.

Each go-media release also has these libraries built already: as Docker images to build in, such as ghcr.io/mutablelogic/go-media:v1.11.4-lgpl-dev, which go-metadata's CI tests in, and as archives for Linux and Windows, to unpack and set GO_MEDIA_PREFIX to. Use the release of the go-media version in go.mod, as its bindings are for its versions of the libraries. The image doesn't have the types of files by their extensions, which content types are detected with, so install media-types and shared-mime-info in it.

Windows (with MSYS2, in its UCRT64 environment, which provides the C compiler too):

pacman -S mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-pkgconf \
  mingw-w64-ucrt-x86_64-ffmpeg mingw-w64-ucrt-x86_64-libexif \
  mingw-w64-ucrt-x86_64-libheif mingw-w64-ucrt-x86_64-libraw

and build from the UCRT64 shell, with its bin folder on your PATH, when its FFmpeg is FFmpeg 8. go-metadata is built and tested on macOS; on Windows, it's expected to work this way, but isn't tested.

Building with make

In a clone of go-metadata, the Makefile checks for the C libraries with pkg-config, and builds with cgo when they're all found, and FFmpeg is FFmpeg 8, or else without it:

make deps             # Report the C libraries, and whether the build uses cgo
make                  # Build the metadata command in build/
make install          # Install the metadata command
make test             # Test everything
make test-race        # Test everything with the race detector
make test-coverage    # Test everything, and report the coverage, in build/coverage.html
make test-nocgo       # Test everything without cgo
make test-image       # Test one package, such as image, audio, video, text, pkg, ...
make help             # List the targets, and the variables which change them

CGO_ENABLED=0 or 1 builds without or with cgo, whatever is found, GO_MEDIA_PREFIX uses go-media's static libraries, and ARGS are arguments to go test, such as ARGS=-v.

The metadata command

Install the metadata command with:

go install github.com/mutablelogic/go-metadata/cmd/metadata@latest

which builds with cgo when there's a C compiler, with the C libraries found as above, or without it with:

CGO_ENABLED=0 go install github.com/mutablelogic/go-metadata/cmd/metadata@latest

metadata prints the content type and metadata of a file, of every file in a folder, or of the files which match a glob pattern, which is quoted so the shell doesn't expand it:

metadata photo.jpg                      # A table of the metadata of a file
metadata ~/Documents                    # Of every file in a folder, and its folders
metadata 'Music/**/*.mp3'               # Of the files which match a pattern
metadata --ns dc,exif photo.jpg         # Only the metadata in these namespaces
metadata --json report.pdf              # As JSON
metadata --type ~/Downloads             # Only the content types
metadata --xmp photo.jpg > photo.xmp    # As an XMP sidecar

It prints the content of a document as Markdown, all of it, or a range of bytes of it, a page at a time:

metadata --markdown report.pdf
metadata --markdown --range 0:4096 report.pdf

and saves the artwork of files as images in the current folder, such as the images of a PDF document's pages, or an album's cover, at a resolution you choose for the images of pages:

metadata --artwork --dpi 300 scan.pdf

The password of an encrypted document is --password, or the METADATA_PASSWORD environment variable. To look up the movie or TV episode which a video is on TMDB, set --tmdb-key, or the TMDB_TOKEN environment variable, to your TMDB API Read Access Token. To look up the MusicBrainz recording and artists of audio on AcoustID, set --acoustid-key, or the CHROMAPRINT_KEY environment variable, to the API key of an application which is registered with AcoustID. Audio is classified as speech, music, silence or other sound, as audio:class, with the fractions which are speech, music and silence, as audio:speech, audio:music and audio:silence, from up to its first 10 minutes, when it's built with libfvad, unless it has a MusicBrainz release type, as it's a known release. That decodes it, which takes about a second for each 8 minutes of audio. metadata --help lists every flag.

Using the library

The API reference is on pkg.go.dev.

Import the go-metadata package, and the packages of the handlers of the files you want to read, which register themselves when they're imported:

import (
    "context"
    "fmt"
    "os"

    metadata "github.com/mutablelogic/go-metadata"

    // Handlers
    _ "github.com/mutablelogic/go-metadata/application" // PDF, office documents, books, archives
    _ "github.com/mutablelogic/go-metadata/audio"       // Audio and playlists
    _ "github.com/mutablelogic/go-metadata/image"       // Images
    _ "github.com/mutablelogic/go-metadata/message"     // Email messages and mailboxes
    _ "github.com/mutablelogic/go-metadata/text"        // Text, HTML, Markdown, CSV, XML, ...
    _ "github.com/mutablelogic/go-metadata/video"       // Video and subtitles
)

func main() {
    f, err := os.Open("report.pdf")
    if err != nil {
        panic(err)
    }
    defer f.Close()

    contentType, meta, err := metadata.Extract(context.Background(), f)
    if err != nil {
        panic(err)
    }
    fmt.Println(contentType)
    for _, m := range meta {
        fmt.Printf("%s:%s = %s\n", m.NS(), m.Key(), m.Value())
    }
}

Extract detects the content type of the reader from its content, and from its name when it has one, as an *os.File does, and runs every handler of that type concurrently. Each piece of metadata has a namespace and a key, such as dc and title, and a value, which is text, a typed value, such as a time or a number, or an image. When a handler fails, Extract returns the metadata which was extracted along with the error, and ErrNotImplemented when there's no handler for the content type, with a title from the file's name, a metadata:kind of unknown, and an empty metadata:hint, as there's nothing more to read of it.

The metadata namespace describes the file itself: metadata:kind is what it is, such as a book or a conversation, and metadata:hint is a list of hints of what to read of it next, as the handlers which read it found, so an indexer knows what's worth the work:

Hint
markdown	It has content which can be read as Markdown, such as a document's text, to index
artwork	It has artwork which can be extracted, such as a cover, a thumbnail, or a video's frames
ocr	It has pages which are images, such as a scanned PDF, whose text can be recognised
transcription	It's audio which is tagged as spoken word (an audiobook or spoken word MusicBrainz release type, or a spoken word, podcast or audiobook genre), or is speech, when it's classified, or else has no MusicBrainz or AcoustID tags, so may be speech, and not when it's protected with DRM
album, single, ep, broadcast, other	It's a track of a release, by the primary type of its MusicBrainz release type, or of an album, when it has an album's name and no release type
tv	It's an episode of a TV show, by its tags, its name, such as Show.S01E02.mkv, or TMDB
event	It has events, such as a calendar's, a contact's birthday, or an invitation
geo	It has places, such as where a photo was taken, a contact's address, or GeoJSON

metadata:tag is a list of tags, which are identifiers in lower case, of what a file is or has, from all the handlers which read it, so an indexer can select files by them, and search for them: a calendar of events is tagged event, and with what its events are, such as birthday, all-day, recurring, task or out-of-office, and an email with a calendar attached to it, such as an invitation, and a mailbox with one, are tagged event. A handler returns them with TagMetadata, which leaves out those which aren't identifiers.

metadata:note is a list of notes about reading a file: for each handler which found it invalid, and returned ErrBadParameter, such as for a PDF which is cut short, that it couldn't be read and why, such as It can't be read, so it may be damaged or incomplete: not a pdf document: …. It's returned with the error, so an indexer can store the file with what was read of it, and show why the rest wasn't.

Options change what's extracted:

Option
WithNamespace(ns...)	Only the metadata in these namespaces, and only the handlers which return them
WithNamespace(metadata.MarkdownNamespace)	The content of a document, as Markdown, as markdown:body
WithRange("0:4096")	The range of bytes of the Markdown, which is the first kilobyte when it isn't set, with markdown:next when there's more
WithNamespace(metadata.ArtworkNamespace)	Artwork, whose images are Image() and Bytes()
WithMaxImageDimension(pixels), WithImageDPI(dpi)	The size of artwork, and of the images of pages
WithMinImageDimension(pixels)	The smallest thumbnail embedded in an image, such as a photo's EXIF thumbnail, which is its artwork, or else the image itself is (256 pixels by default)
WithPassword(password)	The password of an encrypted document
WithContentType(type)	The content type, rather than detecting it
WithMaxSize(bytes)	The largest input which is read
WithTMDB(client)	Look up videos on TMDB, with a client from pkg/tmdb
WithAcoustID(client)	Look up audio on AcoustID, with a client from pkg/acoustid
WithTracer(tracer)	Trace extraction with OpenTelemetry

A handler of another type of file is a function which is registered with AddHandler, for a regular expression of content types, and the namespaces of the metadata it returns. AddHandlerAfter registers a handler which uses the metadata of other handlers, such as a video's duration, which it gets with Opts.Get. AddSignature and AddTextExtensionType register how a type of file is detected, from the bytes it starts with, or the extension of text.

The formats which go-metadata reads are also packages of their own, in pkg/, which can be used without it, such as pkg/eml for email messages, pkg/mbox for mailboxes, pkg/ical and pkg/vcard for calendars and contacts, pkg/rtf, pkg/postscript, pkg/iwork, pkg/exif, pkg/xmp, pkg/tmdb, pkg/acoustid and pkg/chromaprint.

License & Distribution

go-metadata is licensed under the Apache License 2.0.

go-metadata
https://github.com/mutablelogic/go-metadata/
Copyright (c) 2026 The go-metadata authors, All rights reserved.

Under the Apache License 2.0, you are free to use, modify, and distribute this software for any purpose, including commercial applications. Attribution requirement: When redistributing this software or derivative works (in source or binary form), you must include the copyright notice above, and a copy of the LICENSE and NOTICE files. If you modify the code, you must state your changes. See the Apache License 2.0 for complete terms.

Important: When distributing binaries built with cgo, you must also comply with the licenses of the C libraries they link to:

Library	Used for	License
FFmpeg	Audio and video	LGPL 2.1 or later by default; GPL as Homebrew and go-media build it (see below)
libexif	The EXIF metadata of photos	LGPL 2.1 or later
libheif	HEIF and AVIF images	LGPL 3.0
LibRaw	Camera RAW images	LGPL 2.1 or CDDL 1.0, with bundled code under BSD and MIT licenses
Chromaprint	Fingerprints of audio, with the chromaprint tag	LGPL 2.1, as it includes parts of FFmpeg; its own code is MIT
libfvad	Classifying audio, with the libfvad tag, and decoding it to fingerprint it	BSD 3-clause, with a grant of patent rights

Requirements when distributing binaries which include the LGPL libraries:

1. Include their notices and licenses, which the NOTICE file has, and a copy of the GNU GPL v3, which LGPL v3 (libheif) requires alongside it
2. Provide access to the source code of the versions you used
3. Allow users to relink the application with modified versions of the libraries. A binary which links to them dynamically, such as one built with the libraries from Homebrew or a Linux distribution, meets this; one which links to them statically, such as one built with go-media's libraries (GO_MEDIA_PREFIX), must also provide its object files, or its source

A binary has the license of the FFmpeg it includes, and FFmpeg's license depends on how it's built:

• Homebrew's FFmpeg includes x264 and x265, so it's GPL.
• go-media's libraries (GO_MEDIA_PREFIX, from go-media v1.11.0) build FFmpeg as "GPL version 3 or later".
• FFMPEG_NONFREE=1 in go-media builds it as "nonfree and unredistributable", so a binary built with it is for your own use only.

A binary which includes a GPL build of FFmpeg must be distributed under the GPL, with its complete source code. A binary built without cgo (CGO_ENABLED=0) includes none of these libraries.

Dependencies

These are the modules which go-metadata imports directly, which are all under permissive licences. go.mod lists the modules they depend on in turn, and go list -m all lists every module with its version.

Module	Used for	Licence
github.com/mutablelogic/go-media	The C bindings of FFmpeg, libexif, libheif, LibRaw, Chromaprint and libfvad, and the segmenter which classifies audio and decodes it to fingerprint it	Apache 2.0
github.com/mutablelogic/go-client	The TMDB and AcoustID clients	Apache 2.0
github.com/mutablelogic/go-server	Errors and types	Apache 2.0
github.com/mutablelogic/go-tokenizer	Markdown documents	Apache 2.0
github.com/pdfcpu/pdfcpu	The properties of PDF documents, and the thumbnails stored in them	Apache 2.0
github.com/giraffesyo/pdf	The text of PDF documents, and the images of scanned pages	Apache 2.0
github.com/JohannesKaufmann/html-to-markdown/v2	HTML documents and email messages as Markdown	MIT
github.com/richardlehane/mscfb, msoleps	Word, Excel, PowerPoint, Visio, Project and Works documents before Office 2007	Apache 2.0
github.com/oov/psd	Photoshop documents	MIT
go.yaml.in/yaml/v3	The front matter of Markdown documents	MIT and Apache 2.0
golang.org/x/image, x/net, x/text	Images, HTML, and character sets	BSD 3-Clause
go.opentelemetry.io/otel	Tracing	Apache 2.0
github.com/alecthomas/kong	The metadata command's flags	MIT
github.com/bmatcuk/doublestar/v4	The metadata command's glob patterns	MIT
github.com/charmbracelet/glamour, lipgloss, x/ansi, x/term	The metadata command's tables and Markdown in a terminal	MIT

Contributing

Please file feature requests and bugs at github.com/mutablelogic/go-metadata/issues. Pull Requests are welcome, after discussion of the proposed changes.

Documentation

Index

• Constants
• func AddHandler(re *regexp.Regexp, name string, fn HandlerFunc, namespaces ...string)
• func AddHandlerAfter(re *regexp.Regexp, name string, after []string, fn HandlerFunc, ...)
• func AddHandlerAfterWithPriority(re *regexp.Regexp, name string, priority int, after []string, fn HandlerFunc, ...)
• func AddHandlerWithPriority(re *regexp.Regexp, name string, priority int, fn HandlerFunc, ...)
• func AddSignature(prefix []byte, contentType string) error
• func AddTextExtensionType(ext, contentType string) error
• func ContentType(r io.Reader) (string, map[string]string, error)
• func ExtensionByType(contentType string) string
• func HTTPErr(err error) error
• type Err
  • func (code Err) Code() uint
  • func (code Err) Error() string
  • func (e Err) HTTP() httpresponse.Err
  • func (code Err) With(args ...any) error
  • func (code Err) Withf(format string, args ...any) error
• type HandlerFunc
  • func GetHandlers(contentType string) []HandlerFunc
• type Metadata
  • func Extract(parent context.Context, r io.Reader, opts ...Option) (_ string, _ []Metadata, err error)
  • func HintMetadata(hints ...string) []Metadata
  • func KindMetadata(kind string) []Metadata
  • func TagMetadata(tags ...string) []Metadata
• type NamedReader
• type Option
  • func WithAcoustID(client *acoustid.Client) Option
  • func WithContentType(contentType string) Option
  • func WithImageDPI(dpi int) Option
  • func WithMaxImageDimension(pixels int) Option
  • func WithMaxSize(size int64) Option
  • func WithMinImageDimension(pixels int) Option
  • func WithNamespace(ns ...string) Option
  • func WithPassword(password string) Option
  • func WithRange(r string) Option
  • func WithTMDB(client *tmdb.Client) Option
  • func WithTMDBEpisode(show, season, episode uint64) Option
  • func WithTMDBMovie(id uint64) Option
  • func WithTracer(tracer trace.Tracer) Option
• type Opts
  • func (o *Opts) AcoustID() *acoustid.Client
  • func (o *Opts) ContentType() string
  • func (o *Opts) Get(ns, key string) Metadata
  • func (o *Opts) HasImageDPI() bool
  • func (o *Opts) HasNamespace(ns string) bool
  • func (o *Opts) ImageDPI() int
  • func (o *Opts) MaxImageDimension() int
  • func (o *Opts) MinImageDimension() int
  • func (o *Opts) Password() string
  • func (o *Opts) Range() (offset, limit uint64)
  • func (o *Opts) TMDB() *tmdb.Client
  • func (o *Opts) TMDBEpisode() (show, season, episode uint64)
  • func (o *Opts) TMDBMovie() uint64

Constants

const (
	// HintMarkdown is a hint that the input's content can be read as
	// Markdown, such as a document's text, to index it
	HintMarkdown = "markdown"

	// HintArtwork is a hint that the input has artwork, such as a cover, or
	// a thumbnail, which can be extracted
	HintArtwork = "artwork"

	// HintOCR is a hint that the input has pages which are images, such as
	// a scanned PDF, whose text can be recognised
	HintOCR = "ocr"

	// HintTranscription is a hint that the input is audio which isn't known
	// to be music, which may be speech, which can be transcribed
	HintTranscription = "transcription"

	// The hints that the input is a track of a release, such as a song, by
	// the primary type of the release, as MusicBrainz defines it, which can
	// be grouped with the release's other tracks. A track with an album's
	// name, and no release type, is a track of an album
	HintAlbum     = "album"
	HintSingle    = "single"
	HintEP        = "ep"
	HintBroadcast = "broadcast"
	HintOther     = "other"

	// HintTV is a hint that the input is an episode of a TV show, which can
	// be grouped with the show's other episodes
	HintTV = "tv"

	// HintEvent is a hint that the input has events, such as a calendar's,
	// with when they are, which can be indexed by time
	HintEvent = "event"

	// HintGeo is a hint that the input has places, such as where a photo
	// was taken, or a contact's address, which can be indexed by location
	HintGeo = "geo"
)

The hints of what to read of an input next (see HintMetadata), which a handler returns when it reads an input which has them

const (
	// Separator is between the namespace and key of metadata, such as
	// dc:title
	Separator = ':'

	// DefaultPriority is the priority of a handler which is added with
	// AddHandler. A handler with a higher priority has its metadata first,
	// and in place of the metadata with the same namespace and key from a
	// handler with a lower priority (see AddHandlerWithPriority).
	DefaultPriority = 0

	// MetadataNamespace is the namespace of the metadata about the input
	// itself, such as its kind, as metadata:kind
	MetadataNamespace = "metadata"

	// MarkdownNamespace is the namespace of a document's content as
	// Markdown, which a handler returns only when it's requested
	MarkdownNamespace = "markdown"

	// KindKey is the key of the kind of the input, such as a book, in the
	// metadata namespace (see the kinds in the dublincore package)
	KindKey = "kind"

	// HintKey is the key of the hints of what to read of the input next, in
	// the metadata namespace, such as its Markdown, which are a list of the
	// hints of all the handlers which read it (see HintMetadata), or an empty
	// list when no handler can read it, as there's nothing more to read of it
	HintKey = "hint"

	// TagKey is the key of the tags of the input, in the metadata namespace,
	// such as event or birthday, which are a list of identifiers, of all the
	// handlers which read it (see TagMetadata)
	TagKey = "tag"

	// NoteKey is the key of the notes about reading the input, in the
	// metadata namespace, which are a list of strings: for each handler which
	// found the input invalid, such as a PDF which is cut short, that it
	// couldn't be read, and why. Extract returns them with the error.
	NoteKey = "note"

	// ArtworkNamespace is the namespace of images which represent a
	// document, such as the thumbnails of its pages, which a handler
	// returns only when it's requested, as extracting them is expensive
	ArtworkNamespace = "artwork"

	// Namespace for artwork
	NamespaceArtwork = "artwork"

	// Namespace for markdown text
	NamespaceMarkdown = "markdown"
)

const (
	ContentTypeTextPlain = "text/plain"
	ContentTypeTextHTML  = "text/html"
	ContentTypeTextXML   = "text/xml"
)

Functions

func AddHandler

func AddHandler(re *regexp.Regexp, name string, fn HandlerFunc, namespaces ...string)

Add a metadata handler for a given regular expression, along with a short name identifying it (e.g. "ffmpeg", "tmdb", "artwork" - used to name its span, "metadata.Handler.<name>", so it's distinguishable from other handlers in a trace) and the namespaces (e.g. "exif", "tiff") of metadata it can produce. A caller that requests specific namespaces via WithNamespace will only run handlers registered for one of those namespaces. The handler has the default priority, DefaultPriority.

func AddHandlerAfter

func AddHandlerAfter(re *regexp.Regexp, name string, after []string, fn HandlerFunc, namespaces ...string)

AddHandlerAfter adds a metadata handler, as AddHandler does, which uses the metadata of other handlers, in the namespaces after, such as a video's duration in the video namespace. It runs once the handlers which can produce them have finished, and gets their metadata from Opts.Get. Those handlers run even when their namespaces weren't requested, though their metadata isn't returned. A handler doesn't get the metadata of other handlers added with AddHandlerAfter, which run alongside it. The handler has the default priority, DefaultPriority.

func AddHandlerAfterWithPriority

func AddHandlerAfterWithPriority(re *regexp.Regexp, name string, priority int, after []string, fn HandlerFunc, namespaces ...string)

AddHandlerAfterWithPriority adds a metadata handler which uses the metadata of other handlers, as AddHandlerAfter does, with a priority, as AddHandlerWithPriority does, such as a handler whose title is better than the title of the handlers which ran first.

func AddHandlerWithPriority

func AddHandlerWithPriority(re *regexp.Regexp, name string, priority int, fn HandlerFunc, namespaces ...string)

AddHandlerWithPriority adds a metadata handler, as AddHandler does, with a priority, which is DefaultPriority, zero, or higher for a handler whose metadata is better than others', such as the thumbnail embedded in a photo, rather than the photo itself. Extract returns the metadata of the handlers with the highest priority first, and of those with the same priority in the order they were added. Metadata with the same namespace and key as metadata from a handler with a higher priority isn't returned, but handlers with the same priority can each return it, such as more than one dc:creator.

func AddSignature

func AddSignature(prefix []byte, contentType string) error

AddSignature registers the type of content which starts with the prefix, such as image/vnd.adobe.photoshop for 8BPS, or application/rtf for {\rtf, which content which http.DetectContentType detects as binary, or as plain text, has, rather than the type of its extension, so it's detected without its extension, or with the wrong one. The prefix is at most 512 bytes, and the longest prefix which content starts with is its type.

func AddTextExtensionType

func AddTextExtensionType(ext, contentType string) error

AddTextExtensionType registers the type of text with the extension, such as text/x-typescript for .ts, which refines content sniffed as plain text, as mime.AddExtensionType's does, but is never the type of content by its extension alone, so content which isn't text, such as an MPEG transport stream, has the type it otherwise has. The extension starts with a dot, and is matched without case.

func ContentType

func ContentType(r io.Reader) (string, map[string]string, error)

Type returns the MIME type of the given file, along with a map of any additional metadata that was extracted from the file. If the MIME type cannot be determined, an error is returned.

func ExtensionByType

func ExtensionByType(contentType string) string

ExtensionByType returns the usual extension of a content type, with its dot, such as .jpg for image/jpeg, or an empty string when it has none. It's the type's preferred extension, when it has one, or else the usual extension of a common type, or else the first of its extensions which the mime package knows, or else the first extension of a type of text (see AddTextExtensionType). The type's parameters, such as a charset, are ignored.

func HTTPErr

func HTTPErr(err error) error

Types

type Err

type Err uint

const (
	ErrBadParameter   Err = http.StatusBadRequest
	ErrNotFound       Err = http.StatusNotFound
	ErrInternalError  Err = http.StatusInternalServerError
	ErrNotImplemented Err = http.StatusNotImplemented
)

func (Err) Code

func (code Err) Code() uint

func (Err) Error

func (code Err) Error() string

func (Err) HTTP

func (e Err) HTTP() httpresponse.Err

func (Err) With

func (code Err) With(args ...any) error

func (Err) Withf

func (code Err) Withf(format string, args ...any) error

type HandlerFunc

type HandlerFunc func(context.Context, io.Reader, *Opts) ([]Metadata, error)

HandlerFunc is a function that can be used to extract metadata from a given reader. The context can be used to cancel or time out long-running extraction. Opts carries the options passed to Extract; in particular Opts.HasNamespace can be used to check whether a specific namespace (e.g. "artwork") was requested via WithNamespace, which handlers that do expensive work for a single namespace should use to opt in only when that namespace was explicitly requested. A handler can return metadata in any of its namespaces, as Extract returns only the metadata in the namespaces which were requested.

func GetHandlers

func GetHandlers(contentType string) []HandlerFunc

GetHandlers returns all handlers registered for a given content type, or nil if no handler is registered for that content type.

type Metadata

type Metadata interface {
	// Return the namespace of the metadata, such as "exif"
	NS() string

	// Return the metadata key within its namespace, such as
	// "DateTimeOriginal"
	Key() string

	// Return the value as a string. Returns the mimetype if the value is a
	// byte slice, and the mimetype can be detected.
	Value() string

	// Returns the value as a byte slice
	Bytes() []byte

	// Returns the value as an image, or nil if it isn't one
	Image() image.Image

	// Returns the value as an interface
	Any() any
}

Metadata is an entry of metadata, with a key and a value. The value can be retrieved as a string, as bytes, as an image (for artwork), or as is.

func Extract

func Extract(parent context.Context, r io.Reader, opts ...Option) (_ string, _ []Metadata, err error)

Extract runs every handler registered for the content type of r against it, concurrently, and returns the content type, with its parameters, such as "text/html; charset=utf-8", and the combined metadata from all of them. The content type is set with WithContentType, or else detected from r. When r has a name, and no handler returned a title, its title is from its name, which is returned even when there is no handler for the content type, along with ErrNotImplemented. The metadata which was extracted is returned even when a handler fails.

r is read from its current position, and each handler reads, and can seek in, its own section of it. When r can't be read at an offset and seeked, such as a pipe, it's copied to a temporary file first, which is removed when Extract returns. Use WithMaxSize to limit the size of r.

func HintMetadata

func HintMetadata(hints ...string) []Metadata

HintMetadata returns the metadata of the hints of what to read of an input next, which a handler returns for an input it reads, such as HintMarkdown when it has content which can be read as Markdown, as metadata:hint, or nil when there are none. Extract returns the hints of all the handlers which read an input as one list, in order, whatever their priorities. A handler which returns it registers the metadata namespace.

func KindMetadata

func KindMetadata(kind string) []Metadata

KindMetadata returns the metadata of the kind of an input, such as a book (see the kinds in the dublincore package), which a handler returns for the inputs it handles: the kind, as metadata:kind, and its DCMI type, such as Text, as dc:type. It returns nil when the kind is empty. A handler which returns it registers the metadata and dc namespaces.

func TagMetadata

func TagMetadata(tags ...string) []Metadata

TagMetadata returns the metadata of the tags of an input, which a handler returns for an input it reads, such as event for a calendar of events, as metadata:tag, or nil when there are none. A tag is an identifier: it's in lower case, and one which isn't an identifier, which starts with a letter, followed by letters, digits, underscores and hyphens, is left out. Extract returns the tags of all the handlers which read an input as one sorted list, without duplicates, whatever their priorities. A handler which returns it registers the metadata namespace.

type NamedReader

type NamedReader interface {
	io.Reader
	Name() string
}

NamedReader is a reader with a name, such as a file. The extension of the name is used to detect the content type, and a handler may use the name itself (e.g. to look up TMDB metadata).

type Option

type Option func(*Opts) error

func WithAcoustID

func WithAcoustID(client *acoustid.Client) Option

Set the client of AcoustID, which a handler of audio uses to look up the AcoustID identifier of a recording which doesn't have one in its tags, from its fingerprint, which is from its tags, or else from its audio, when it's built with Chromaprint. When not set, audio isn't looked up.

func WithContentType

func WithContentType(contentType string) Option

Set the content type of the reader, which selects the handlers to run. When not set, the content type is detected from the reader.

func WithImageDPI

func WithImageDPI(dpi int) Option

Set the resolution of an image of a page, in dots per inch, such as the artwork of a scanned page, which a handler downscales an image to, from the size of its page, keeping its aspect ratio, so an A4 page at 300 dpi, as for OCR, is 2480 by 3508 pixels. An image is never upscaled. When it's set, an image of a page is at its resolution, however large, and when it isn't, it's 150 dpi, and at most the largest dimension (see WithMaxImageDimension).

func WithMaxImageDimension

func WithMaxImageDimension(pixels int) Option

Set the largest width or height of an image, in pixels, which a handler downscales an image to fit, keeping its aspect ratio. It's the size of an image without a size of its own, such as a photo, and the most an image of a page can be, such as a poster, unless its resolution is set (see WithImageDPI). When not set, it's 1024 pixels.

func WithMaxSize

func WithMaxSize(size int64) Option

Set the maximum size of the input, in bytes. A larger input is a bad parameter, and a stream is copied to a temporary file only up to this size. When not set, or zero, there is no limit.

func WithMinImageDimension

func WithMinImageDimension(pixels int) Option

Set the smallest size, in pixels, of the longer side of a thumbnail which is embedded in an image, such as a photo's EXIF thumbnail, which is used as its artwork. A thumbnail which is smaller isn't used, and the image itself, downscaled (see WithMaxImageDimension), is its artwork instead, as a thumbnail which is too small shows too little, such as a camera's 160 by 120 pixels. Zero uses any thumbnail. When not set, it's 256 pixels.

func WithNamespace

func WithNamespace(ns ...string) Option

Return only the metadata from the given namespaces.

func WithPassword

func WithPassword(password string) Option

Set the password of a document which is encrypted, such as a PDF document which needs a password to be opened, which a handler uses to read it

func WithRange

func WithRange(r string) Option

WithRange sets the part of a document's Markdown which a handler of the markdown namespace returns, as a range of bytes, so a long document is read a part at a time: from:to, from:, :to, or : for all of it. When not set, or empty, it's the first kilobyte. A range which ends holds at least a whole character.

func WithTMDB

func WithTMDB(client *tmdb.Client) Option

Set the client of TMDB, which a handler of videos uses to look up the movie or TV episode which a video is, from its name. When not set, videos aren't looked up.

func WithTMDBEpisode

func WithTMDBEpisode(show, season, episode uint64) Option

Set the episode of a TV show on TMDB which a video is, by its show's identifier, such as 1396 for Breaking Bad, and its season and episode numbers, which is got rather than looked up from the video's name, when a TMDB client is set (see WithTMDB). An episode has an identifier of its own, but TMDB gets an episode only by its show, season and episode. The season is zero for a show's specials. It replaces a movie set with WithTMDBMovie.

func WithTMDBMovie

func WithTMDBMovie(id uint64) Option

Set the movie on TMDB which a video is, by its identifier, such as 603 for The Matrix, which is got rather than looked up from the video's name, when a TMDB client is set (see WithTMDB). It replaces an episode set with WithTMDBEpisode.

func WithTracer

func WithTracer(tracer trace.Tracer) Option

Set the otel tracer to use for metadata operations.

type Opts

type Opts struct {
	// contains filtered or unexported fields
}

func (*Opts) AcoustID

func (o *Opts) AcoustID() *acoustid.Client

AcoustID returns the client of AcoustID set via WithAcoustID, or nil when it wasn't set, when audio isn't looked up

func (*Opts) ContentType

func (o *Opts) ContentType() string

ContentType returns the content type that was set via WithContentType, or detected from the reader when it wasn't set.

func (*Opts) Get

func (o *Opts) Get(ns, key string) Metadata

Get returns the first metadata with the namespace and key from the handlers which ran before this one, or nil when there's none. Only a handler added with AddHandlerAfter gets it, of the namespaces it uses.

func (*Opts) HasImageDPI

func (o *Opts) HasImageDPI() bool

HasImageDPI reports whether the resolution of an image of a page was set via WithImageDPI, when an image of a page is at its resolution, rather than at most the largest dimension

func (*Opts) HasNamespace

func (o *Opts) HasNamespace(ns string) bool

HasNamespace reports whether ns was requested via WithNamespace,

func (*Opts) ImageDPI

func (o *Opts) ImageDPI() int

ImageDPI returns the resolution of an image of a page, in dots per inch, which a handler downscales an image to, set via WithImageDPI, or 150 dpi when it wasn't set

func (*Opts) MaxImageDimension

func (o *Opts) MaxImageDimension() int

MaxImageDimension returns the largest width or height of an image, in pixels, which a handler downscales an image to fit, set via WithMaxImageDimension, or 1024 pixels when it wasn't set

func (*Opts) MinImageDimension

func (o *Opts) MinImageDimension() int

MinImageDimension returns the smallest size, in pixels, of the longer side of a thumbnail which is embedded in an image, which is used as its artwork, set via WithMinImageDimension, or 256 pixels when it wasn't set

func (*Opts) Password

func (o *Opts) Password() string

Password returns the password of a document which is encrypted, set via WithPassword, or an empty string when it wasn't set

func (*Opts) Range

func (o *Opts) Range() (offset, limit uint64)

Range returns the byte offset and limit of the part of the Markdown which a handler returns, set via WithRange, or the first kilobyte when it wasn't set. A limit of zero is to the end.

func (*Opts) TMDB

func (o *Opts) TMDB() *tmdb.Client

TMDB returns the client of TMDB set via WithTMDB, or nil when it wasn't set, when videos aren't looked up

func (*Opts) TMDBEpisode

func (o *Opts) TMDBEpisode() (show, season, episode uint64)

TMDBEpisode returns the identifier of the show on TMDB, and the season and episode numbers, set via WithTMDBEpisode, or zeros when they weren't set

func (*Opts) TMDBMovie

func (o *Opts) TMDBMovie() uint64

TMDBMovie returns the identifier of the movie on TMDB set via WithTMDBMovie, or zero when it wasn't set