The highest tagged major version is
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
- type ErrInvalidImage
- type ErrUnsupportedMIME
- type FFContext
- 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
- 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 ¶
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 ¶
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 ¶
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 ¶
Process generates a thumbnail from a file of unknown type and performs some basic meta information extraction
func ProcessBuffer ¶
ProcessBuffer is like Process, but takes []byte as input. More efficient, if you already have the file buffered into memory.
func ReadFrom ¶
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 ¶
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 ¶
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 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) ExtractMeta ¶
ExtractMeta retrieves title and artist for source, if present
func (*FFContext) HasCoverArt ¶
HasCoverArt return whether file has cover art in it
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 ¶
Image stores an image of known dimensions. To decrease allocations call ReturnBuffer() on Data, after you are done using Image.
type Matcher ¶
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 ¶
MatcherFunc is an adapter that allows using functions as 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 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
Source Files