thumbnailer

README

thumbnailer

Package thumbnailer provides a more efficient image/video/audio/PDF thumbnailer than available with native Go processing libraries through GraphicsMagic and ffmpeg bindings.

For a comprehensive list of file formats supported by default, check the matchers slice in mime.go.

License

GNU GENERAL PUBLIC LICENSE / MIT License

Depending on how the project is built it can be licensed under either MIT or GPLv3. Thumbnailer links against the GPLv3-licensed libimagequant for lossy PNG thumbnail compression by default and thus also becomes applicable under the GPLv3. To build thumbnailer without this feature under the MIT license, please specify --tags=MIT when building the project. See LICENSE for more details.

Dependencies

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

NB: ffmpeg and GM 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.

Documentation

Overview

Package thumbnailer provides a more efficient image/video/audio/PDF thumbnailer than available with native Go processing libraries through GraphicsMagic and ffmpeg bindings.

Index

• Constants
• Variables
• func DetectMIME(r io.Reader, accepted map[string]bool) (string, string, error)
• func DetectMIMEBuffer(buf []byte, accepted map[string]bool) (string, string, error)
• func GetBuffer() []byte
• func GetBufferCap(capacity int) []byte
• func Process(rs io.ReadSeeker, opts Options) (src Source, thumb Thumbnail, err error)
• func ProcessBuffer(buf []byte, opts Options) (src Source, thumb Thumbnail, err error)
• func ReadFrom(r io.Reader) ([]byte, error)
• func ReadInto(buf []byte, r io.Reader) ([]byte, error)
• func RegisterMatcher(m Matcher)
• func RegisterProcessor(mime string, fn Processor)
• func ReturnBuffer(buf []byte)
• type Dims
• type ErrCorruptImage
  • func (e ErrCorruptImage) Error() string
• type ErrInvalidImage
  • func (e ErrInvalidImage) Error() string
• type ErrUnsupportedMIME
  • func (e ErrUnsupportedMIME) Error() string
• type FFContext
  • func NewFFContext(rs io.ReadSeeker) (*FFContext, error)
  • func (c *FFContext) Close()
  • func (c *FFContext) CodecName(typ FFMediaType) (string, error)
  • func (c *FFContext) CoverArt() []byte
  • func (c *FFContext) Duration() time.Duration
  • func (c *FFContext) ExtractMeta(src *Source)
  • func (c *FFContext) HasCoverArt() bool
  • func (c *FFContext) HasStream(typ FFMediaType) (bool, error)
  • func (c *FFContext) Thumbnail() (thumb Image, err error)
• type FFMediaType
• type Image
• type Matcher
• type MatcherFunc
  • func (fn MatcherFunc) Match(data []byte) (string, string)
• type Options
• type Processor
• type Source
• type Thumbnail
• type UnsupportedMIMEError

Constants

const MinBufSize = 10 << 10

Initial minimum size of pooled buffer

Variables

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

Thumbnailing errors

var (
	// ErrNoStreams denotes no decodeable audio or video streams were found in
	// a media container
	ErrNoStreams = errors.New("no decodeable video or audio streams found")

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

var ErrNoCoverArt = errors.New("no cover art found")

ErrNoCoverArt denotes no cover art has been found in the audio file, or a multipurpose media container file contained only audio and no cover art.

var (

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

Functions

func DetectMIME

func DetectMIME(r io.Reader, accepted map[string]bool) (string, string, error)

DetectMIME detects the MIME typ of the r. r must be at starting position. accepted, if not nil, specifies MIME types to not reject with UnsupportedMIMEError.

func DetectMIMEBuffer

func DetectMIMEBuffer(buf []byte, accepted map[string]bool) (
	string, string, error,
)

DetectMIMEBuffer is like DetectMIME, but accepts a []byte slice already loaded into memory.

func GetBuffer

func GetBuffer() []byte

Retrieve a buffer from the memory pool or allocate a new one. Use this to reduce large allocations in your side of the application.

Return the buffer to the pool using ReturnBuffer() when it is no longer being used.

func GetBufferCap

func GetBufferCap(capacity int) []byte

Like GetBuffer() but the capacity of the returned buffer will be at least `capacity`. This can greatly reduce reallocation, if you already have a hint of the end size of the buffer.

func Process

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

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

func ProcessBuffer

func ProcessBuffer(buf []byte, opts Options) (
	src Source, thumb Thumbnail, err error,
)

ProcessBuffer is like Process, but takes []byte as input. More efficient, if you already have the file buffered into memory.

func ReadFrom

func ReadFrom(r io.Reader) ([]byte, error)

Reads data from r until EOF and appends it to the buffer, growing the buffer as needed. The return value n is the number of bytes read. Any error except io.EOF encountered during the read is also returned. If the buffer becomes too large, ReadFrom will panic with ErrTooLarge.

Unlike similar functions in the standard library this function uses the internal memory pool for reducing reallocations and decreasing heap sizes during heavy thumbnailing workloads.

Return the buffer to the pool using ReturnBuffer() when it is no longer being used.

func ReadInto

func ReadInto(buf []byte, r io.Reader) ([]byte, error)

Like ReadFrom() but the suplied buffer is used for reading. The supplied buffer should not be used after this call.

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.

func ReturnBuffer

func ReturnBuffer(buf []byte)

Return or put a buffer into the pool. It is recommended not to put buffers with capacity smaller than MinBufSize into the pool. The buffer must not be used after this call.

Types

type Dims

type Dims struct {
	Width, Height uint
}

Dims store the dimensions of an image

type ErrCorruptImage

type ErrCorruptImage string

Source image is corrupt and could not be decoded

func (ErrCorruptImage) Error

func (e ErrCorruptImage) 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) (string, 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) Duration

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

Duration returns the duration of the input

func (*FFContext) ExtractMeta

func (c *FFContext) ExtractMeta(src *Source)

ExtractMeta retrieves title and artist for source, if present

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) Thumbnail

func (c *FFContext) Thumbnail() (thumb Image, err error)

Thumbnail extracts the first frame of the video

type FFMediaType

type FFMediaType int8

FFMediaType correspond to the AVMediaType enum in ffmpeg

const (
	FFUnknown FFMediaType = iota - 1
	FFVideo
	FFAudio
)

Correspond to the AVMediaType enum in ffmpeg

type Image

type Image struct {
	Data []byte
	Dims
}

Image stores an image of known dimensions. To decrease allocations call ReturnBuffer() on Data, after you are done using Image.

type Matcher

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

Matcher takes up to the first 512 bytes 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 Options

type Options struct {
	// JPEG thumbnail quality to use. [1,100]. Defaults to 75.
	JPEGQuality uint8

	PNGQuality struct {
		// Minimum and maximum quality for lossy PNG compression with
		// libimagequant. [1,100]. Defaults to 10-100.
		Min, Max uint
	}

	// Maximum source image dimensions. Any image exceeding either will be
	// rejected and return with ErrTooTall or ErrTooWide. If not set, all images
	// are processed.
	MaxSourceDims Dims

	// Target Maximum dimensions for the thumbnail
	ThumbDims Dims

	// MIME types to accept for thumbnailing. If nil, all MIME types will be
	// processed.
	AcceptedMimeTypes map[string]bool
}

Options suplied to the Thumbnail function

type Processor

type Processor func(Source, Options) (Source, Thumbnail, error)

Processor is a specialized file processor for a specific file type

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

	// Mime type of the source file
	Mime string

	// optional metadata
	Title, Artist string

	// Canonical file extension
	Extension string

	Image
}

Source stores the source image, including information about the source file

type Thumbnail

type Thumbnail struct {
	// Thumbnails can be either JPEG or PNG. Only images with transparency will
	// be PNG.
	IsPNG bool

	Image
}

Thumbnail stores a processed thumbnail. Take note, that in case an audio file with no cover art is passed, this struct will be unassigned.

type UnsupportedMIMEError

type UnsupportedMIMEError = ErrUnsupportedMIME

Alias for backwards compatibility