package module
Version: v0.0.1 Latest Latest

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

Go to latest
Published: Feb 5, 2021 License: MIT Imports: 16 Imported by: 0


GoDoc Build Status


Package thumbnailer provides a more efficient media thumbnailer than available with native Go processing libraries through ffmpeg bindings.

For a comprehensive list of file formats supported by default see main.go:Process().


  • Go >= 1.10
  • C11 compiler
  • make
  • pkg-config
  • pthread
  • ffmpeg >= 4.1 libraries (libavcodec, libavutil, libavformat, libswscale)


  • ffmpeg should be compiled with all the dependency libraries for formats you want to process. On most Linux distributions you should be fine with the packages in the stock repositories.
  • Ubuntu patches to ffmpeg on some Ubuntu versions <19.10 break this library. In this case, please compile from unmodified ffmpeg sources using:
sudo apt build-dep ffmpeg
git clone ffmpeg
cd ffmpeg
git checkout n4.1
make -j`nproc`
sudo make install



Package thumbnailer provides a more efficient media thumbnailer than \ available with native Go processing libraries through ffmpeg bindings.



This section is empty.


View Source
var (
	ErrTooWide             = ErrInvalidImage("image too wide")
	ErrTooTall             = ErrInvalidImage("image too tall")
	ErrThumbnailingUnknown = errors.New("unknown thumbnailing error")

	// ErrCantThumbnail denotes the input file was valid but no thumbnail could
	// be generated for it (example: audio file with no cover art).
	ErrCantThumbnail = errors.New("thumbnail can't be generated")

	// ErrGetFrame denotes an unknown failure to retrieve a video frame
	ErrGetFrame = errors.New("failed to get frame")

	// ErrStreamNotFound denotes no steam of this media type was found
	ErrStreamNotFound = errors.New("no stream of this type found")

Thumbnailing errors


func DetectMIME

func DetectMIME(rs io.ReadSeeker, accepted map[string]bool,
) (
	mime, ext string, err error,

DetectMIME detects the MIME typ of the rs.

accepted: if not nil, specifies MIME types to not reject with ErrUnsupportedMIME

func RegisterMatcher

func RegisterMatcher(m Matcher)

RegisterMatcher adds an extra magic prefix-based MIME type matcher to the default set with an included canonical file extension.

Not safe to use concurrently with file processing.

func RegisterProcessor

func RegisterProcessor(mime string, fn Processor)

RegisterProcessor registers a file processor for a specific MIME type. Can be used to add support for additional MIME types or as an override.

Not safe to use concurrently with file processing.


type AVError

type AVError

AVError converts an FFmpeg error code to a Go error with a human-readable error message

func (AVError) Code

func (f AVError) Code()

Code returns the underlying AVERROR error code

func (AVError) Error

func (f AVError) Error() string

Error formats the FFmpeg error in human-readable format

type Dims

type Dims struct {
	Width, Height uint

Dims store the dimensions of an image

type ErrArchive

type ErrArchive struct {
	Err error

ErrArchive wraps an error that happened during thumbnailing a file in zip archive

func (ErrArchive) Error

func (e ErrArchive) Error() string

type ErrCoverArt

type ErrCoverArt struct {
	Err error

ErrorCovert wraps an error that happened during cover art thumbnailing

func (ErrCoverArt) Error

func (e ErrCoverArt) Error() string

type ErrInvalidImage

type ErrInvalidImage string

Indicates and invalid image has been passed for processing

func (ErrInvalidImage) Error

func (e ErrInvalidImage) Error() string

type ErrUnsupportedMIME

type ErrUnsupportedMIME string

Indicates the MIME type of the file could not be detected as a supported type or was not in the AcceptedMimeTypes list, if defined.

func (ErrUnsupportedMIME) Error

func (e ErrUnsupportedMIME) Error() string

type FFContext

type FFContext struct {
	// contains filtered or unexported fields

FFContext is a wrapper for passing Go I/O interfaces to C

func NewFFContext

func NewFFContext(rs io.ReadSeeker) (*FFContext, error)

NewFFContext constructs a new AVIOContext and AVFormatContext. It is the responsibility of the caller to call Close() after finishing using the context.

func (*FFContext) Close

func (c *FFContext) Close()

Close closes and frees memory allocated for c. c should not be used after this point.

func (*FFContext) CodecName

func (c *FFContext) CodecName(typ FFMediaType) (codec string, err error)

CodecName returns the codec name of the best stream of type typ

func (*FFContext) CoverArt

func (c *FFContext) CoverArt() []byte

CoverArt extracts any attached image

func (*FFContext) Dims

func (c *FFContext) Dims() (dims Dims, err error)

Dims returns dimensions of the best video (or image) stream in the media

func (*FFContext) HasCoverArt

func (c *FFContext) HasCoverArt() bool

HasCoverArt return whether file has cover art in it

func (*FFContext) HasStream

func (c *FFContext) HasStream(typ FFMediaType) (bool, error)

HasStream returns, if the file has a decodeable stream of the passed type

func (*FFContext) Length

func (c *FFContext) Length() time.Duration

Length returns the duration of the input

func (*FFContext) Meta

func (c *FFContext) Meta() (m Meta)

Meta retrieves title and artist for source, if present

func (*FFContext) Thumbnail

func (c *FFContext) Thumbnail(dims Dims) (thumb image.Image, err error)

Thumbnail generates a thumbnail from a representative frame of the media. Images count as one frame media.

type FFMediaType

type FFMediaType int8

FFMediaType correspond to the AVMediaType enum in ffmpeg

const (
	FFUnknown FFMediaType = iota - 1

Correspond to the AVMediaType enum in ffmpeg

type Matcher

type Matcher interface {
	Match([]byte) (mime string, extension string)

Matcher takes up to the first 4 KB of a file and returns the MIME type and canonical extension, that were matched. Empty string indicates no match.

type MatcherFunc

type MatcherFunc func([]byte) (string, string)

MatcherFunc is an adapter that allows using functions as Matcher

func (MatcherFunc) Match

func (fn MatcherFunc) Match(data []byte) (string, string)

Match implements Matcher

type Meta

type Meta struct {
	Title, Artist string

File metadata

type Options

type Options struct {
	// Maximum source image dimensions. Any image exceeding either will be
	// rejected and return with ErrTooTall or ErrTooWide.
	// If not set, all image processing will not be restricted by that
	// dimension.
	MaxSourceDims Dims

	// Target Maximum dimensions for the thumbnail.
	// Default to 150x150, if unset.
	ThumbDims Dims

	// MIME types to accept for thumbnailing.
	// If nil, all MIME types will be processed.
	// To process MIME types that are a subset of archive files, like
	// "application/x-cbz", "application/x-cbr", "application/x-cb7" and
	// "application/x-cbt", you must accept the corresponding archive type
	// such as "application/zip" or leave this nil.
	AcceptedMimeTypes map[string]bool

Options suplied to the Thumbnail function

type Processor

type Processor func(io.ReadSeeker, *Source, Options) (image.Image, error)

Processor is a specialized file processor for a specific file type. Returns thumbnail and error.

io.ReadSeeker is the start position, when passed to Processor.

type Source

type Source struct {
	// Some containers may or may not have either
	HasAudio, HasVideo bool

	// Length of the stream. Applies to audio and video files.
	Length time.Duration

	// Source dimensions, if file is image or video

	// Mime type of the source file
	Mime string

	// Canonical file extension
	Extension string

	// Optional metadata

Source stores information about the source file

func Process

func Process(rs io.ReadSeeker, opts Options) (
	src Source, thumb image.Image, err error,

Process generates a thumbnail from a file of unknown type and performs some basic meta information extraction

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL