media

package module
v1.5.1 Latest Latest
Warning

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

 Go to latest Published: Dec 16, 2022 License: Apache-2.0 Imports: 4 Imported by: 6

README

go-media

This module provides an interface for media services, including:

  • Bindings in golang for ffmpeg 5.1;
  • Opening media files, devices and network sockets for reading and writing;
  • Retrieving metadata and artwork from audio and video media;
  • Re-multiplexing media files from one format to another;
  • Fingerprinting audio files to identify music.

Current Status

This module is currently in development and subject to change. If there are any specific features you are interested in, please see below "Contributing & Distribution" below.

Requirements

In order to build the examples, you'll need the library and header files for ffmpeg 5.1 installed. The chromaprint library is also required for fingerprinting audio files.

On Macintosh with homebrew, for example:

brew install ffmpeg chromaprint make

There are some examples in the cmd folder of the main repository on how to use the package. The various make targets are:

  • make all will perform tests, build all examples and the backend API;
  • make test will perform tests;
  • make cmd will build example command-line tools into the build folder;
  • make clean will remove all build artifacts.

For example,

git clone git@github.com:djthorpe/go-media.git
cd go-media
make

Examples

There are two example Command Line applications:

  • extractartwork can be used to walk through a directory and extract artwork from media files and save the artwork into files;
  • transcode can be used to copy, re-mux and re-sample media files from one format to another.

You can compile both applications with make cmdwhich places the binaries into the build folder. Use the -help option on either application to see the options.

Media Transcoding

You can programmatically demultiplex, re-multiplex and re-sample media files using the following packages:

  • sys/ffmpeg51 provides the implementation of the lower-level function calls to ffmpeg. The documentation is here
  • pkg/media provides the higher-level API for opening media files, reading, transcoding, resampling and writing media files. The interfaces and documentation are best read here:

Audio Fingerprinting

You can programmatically fingerprint audio files, compare fingerprints and identify music using the following packages:

  • sys/chromaprint provides the implementation of the lower-level function calls to chromaprint. The documentation is here
  • pkg/chromaprint provides the higher-level API for fingerprinting and identifying music. The documentation is here.

You'll need an API key in order to use the AcoustID service. You can get a key here.

Contributing & Distribution

This module is currently in development and subject to change.

Please do file feature requests and bugs here. The license is Apache 2 so feel free to redistribute. Redistributions in either source code or binary form must reproduce the copyright notice, and please link back to this repository for more information:

Copyright (c) 2021-2023 David Thorpe, All rights reserved.

References

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AudioChannel added in v1.5.1 

type AudioChannel uint

AudioChannel specifies a single audio channel 

const (
	CHANNEL_NONE AudioChannel = iota
	CHANNEL_FRONT_LEFT
	CHANNEL_FRONT_RIGHT
	CHANNEL_FRONT_CENTER
	CHANNEL_LOW_FREQUENCY
	CHANNEL_BACK_LEFT
	CHANNEL_BACK_RIGHT
	CHANNEL_FRONT_LEFT_OF_CENTER
	CHANNEL_FRONT_RIGHT_OF_CENTER
	CHANNEL_BACK_CENTER
	CHANNEL_SIDE_LEFT
	CHANNEL_SIDE_RIGHT
	CHANNEL_TOP_CENTER
	CHANNEL_TOP_FRONT_LEFT
	CHANNEL_TOP_FRONT_CENTER
	CHANNEL_TOP_FRONT_RIGHT
	CHANNEL_TOP_BACK_LEFT
	CHANNEL_TOP_BACK_CENTER
	CHANNEL_TOP_BACK_RIGHT
	CHANNEL_STEREO_LEFT
	CHANNEL_STEREO_RIGHT
	CHANNEL_WIDE_LEFT
	CHANNEL_WIDE_RIGHT
	CHANNEL_SURROUND_DIRECT_LEFT
	CHANNEL_SURROUND_DIRECT_RIGHT
	CHANNEL_LOW_FREQUENCY_2
	CHANNEL_TOP_SIDE_LEFT
	CHANNEL_TOP_SIDE_RIGHT
	CHANNEL_BOTTOM_FRONT_CENTER
	CHANNEL_BOTTOM_FRONT_LEFT
	CHANNEL_BOTTOM_FRONT_RIGHT
	CHANNEL_MAX = CHANNEL_BOTTOM_FRONT_RIGHT
)

func (AudioChannel) String added in v1.5.1 

func (v AudioChannel) String() string

type AudioFormat 

type AudioFormat struct {
	// Sample rate in Hz
	Rate uint

	// Sample format
	Format SampleFormat

	// Channel layout
	Layout ChannelLayout
}

AudioFormat specifies the interface for audio format

func (AudioFormat) String 

func (v AudioFormat) String() string

type AudioFrame added in v1.5.1 

type AudioFrame interface {
	// Returns the audio format, if MEDIA_FLAG_AUDIO is set
	AudioFormat() AudioFormat

	// Number of samples, if MEDIA_FLAG_AUDIO is set
	NumSamples() int

	// Audio channels, if MEDIA_FLAG_AUDIO is set
	Channels() []AudioChannel

	// Duration of the frame, if MEDIA_FLAG_AUDIO is set
	Duration() time.Duration
}

type ChannelLayout added in v1.5.1 

type ChannelLayout uint

ChannelLayout specifies the layout of channels 

const (
	CHANNEL_LAYOUT_NONE ChannelLayout = iota
	CHANNEL_LAYOUT_MONO
	CHANNEL_LAYOUT_STEREO
	CHANNEL_LAYOUT_2POINT1
	CHANNEL_LAYOUT_2_1
	CHANNEL_LAYOUT_SURROUND
	CHANNEL_LAYOUT_3POINT1
	CHANNEL_LAYOUT_4POINT0
	CHANNEL_LAYOUT_4POINT1
	CHANNEL_LAYOUT_2_2
	CHANNEL_LAYOUT_QUAD
	CHANNEL_LAYOUT_5POINT0
	CHANNEL_LAYOUT_5POINT1
	CHANNEL_LAYOUT_5POINT0_BACK
	CHANNEL_LAYOUT_5POINT1_BACK
	CHANNEL_LAYOUT_6POINT0
	CHANNEL_LAYOUT_6POINT0_FRONT
	CHANNEL_LAYOUT_HEXAGONAL
	CHANNEL_LAYOUT_6POINT1
	CHANNEL_LAYOUT_6POINT1_BACK
	CHANNEL_LAYOUT_6POINT1_FRONT
	CHANNEL_LAYOUT_7POINT0
	CHANNEL_LAYOUT_7POINT0_FRONT
	CHANNEL_LAYOUT_7POINT1
	CHANNEL_LAYOUT_7POINT1_WIDE
	CHANNEL_LAYOUT_7POINT1_WIDE_BACK
	CHANNEL_LAYOUT_OCTAGONAL
	CHANNEL_LAYOUT_HEXADECAGONAL
	CHANNEL_LAYOUT_STEREO_DOWNMIX
	CHANNEL_LAYOUT_22POINT2
	CHANNEL_LAYOUT_AMBISONIC_FIRST_ORDER
	CHANNEL_LAYOUT_MAX = CHANNEL_LAYOUT_AMBISONIC_FIRST_ORDER
)

func (ChannelLayout) String added in v1.5.1 

func (v ChannelLayout) String() string

type Codec added in v1.5.1 

type Codec interface {
	// Name returns the unique name for the codec
	Name() string

	// Description returns the long description for the codec
	Description() string

	// Flags for the codec (Audio, Video, Encoder, Decoder)
	Flags() MediaFlag
}

Codec is an encoder or decoder for a specific media type

type DecodeFn added in v1.5.1 

type DecodeFn func(context.Context, Frame) error

DecodeFn is a function which is called for each frame in the media, which is associated with a single stream. The function should return an error if the decode should be terminated.

type DemuxFn added in v1.5.1 

type DemuxFn func(context.Context, Packet) error

Demux is a function which is called for each packet in the media, which is associated with a single stream. The function should return an error if the decode should be terminated.

type Frame added in v1.5.1 

type Frame interface {
	AudioFrame
	VideoFrame

	// Returns MEDIA_FLAG_VIDEO, MEDIA_FLAG_AUDIO
	Flags() MediaFlag
}

Frame is a decoded video or audio frame

type Manager added in v1.5.1 

type Manager interface {
	io.Closer

	// Enumerate formats with MEDIA_FLAG_ENCODER, MEDIA_FLAG_DECODER,
	// MEDIA_FLAG_FILE and MEDIA_FLAG_DEVICE flags to filter.
	// Lookups can be further filtered by name, mimetype and extension
	MediaFormats(MediaFlag, ...string) []MediaFormat

	// Open media file for reading and return it. A format can be specified
	// to "force" a specific format
	OpenFile(string, MediaFormat) (Media, error)

	// Open media URL for reading and return it. A format can be specified
	// to "force" a specific format
	OpenURL(string, MediaFormat) (Media, error)

	// Open media device with a specific name for reading and return it.
	OpenDevice(string) (Media, error)

	// Create file for writing and return it
	CreateFile(string) (Media, error)

	// Create an output device with a specific name for writing and return it
	CreateDevice(string) (Media, error)

	// Create a map of input media. If MediaFlag is MEDIA_FLAG_NONE, then
	// all audio, video and subtitle streams are mapped, or else a
	// combination of MEDIA_FLAG_AUDIO,
	// MEDIA_FLAG_VIDEO, MEDIA_FLAG_SUBTITLE and MEDIA_FLAG_DATA
	// can be used to map specific types of streams.
	Map(Media, MediaFlag) (Map, error)

	// Demux a media file, passing packets to a callback function
	Demux(context.Context, Map, DemuxFn) error

	// Decode a packet into a series of frames, passing decoded frames to
	// a callback function
	Decode(context.Context, Map, Packet, DecodeFn) error

	// Log messages from ffmpeg
	SetDebug(bool)
}

Manager is an interface to the ffmpeg media library for media manipulation

type Map added in v1.5.1 

type Map interface {
	// Return input media
	Input() Media

	// Return streams which are mapped for decoding
	Streams() []Stream

	// Print a summary of the mapping
	PrintMap(w io.Writer)
}

Map is a mapping of input media, potentially to output media

type Media 

type Media interface {
	io.Closer

	// URL for the media
	URL() string

	// Return enumeration of streams
	Streams() []Stream

	// Return media flags for the media
	Flags() MediaFlag

	// Return metadata for the media
	Metadata() Metadata

	// Set metadata value by key, or remove it if the value is nil
	Set(MediaKey, any) error
}

Media is a source or destination of media

type MediaFlag 

type MediaFlag uint

MediaFlag is a bitfield of flags for media, including type of media 

const (
	MEDIA_FLAG_ALBUM             MediaFlag = (1 << iota) // Is part of an album
	MEDIA_FLAG_ALBUM_TRACK                               // Is an album track
	MEDIA_FLAG_ALBUM_COMPILATION                         // Album is a compilation
	MEDIA_FLAG_TVSHOW                                    // Is part of a TV Show
	MEDIA_FLAG_TVSHOW_EPISODE                            // Is a TV Show episode
	MEDIA_FLAG_FILE                                      // Is a file
	MEDIA_FLAG_DEVICE                                    // Is a device
	MEDIA_FLAG_VIDEO                                     // Contains video
	MEDIA_FLAG_AUDIO                                     // Contains audio
	MEDIA_FLAG_SUBTITLE                                  // Contains subtitles
	MEDIA_FLAG_DATA                                      // Contains data stream
	MEDIA_FLAG_ATTACHMENT                                // Contains attachment
	MEDIA_FLAG_ARTWORK                                   // Contains artwork
	MEDIA_FLAG_CAPTIONS                                  // Contains captions
	MEDIA_FLAG_ENCODER                                   // Is an encoder
	MEDIA_FLAG_DECODER                                   // Is an decoder
	MEDIA_FLAG_NONE              MediaFlag = 0
	MEDIA_FLAG_MAX                         = MEDIA_FLAG_DECODER
)

func (MediaFlag) FlagString 

func (f MediaFlag) FlagString() string

func (MediaFlag) Is 

func (f MediaFlag) Is(v MediaFlag) bool

func (MediaFlag) String 

func (f MediaFlag) String() string

type MediaFormat added in v1.5.1 

type MediaFormat interface {
	// Return the names of the media format
	Name() []string

	// Return a longer description of the media format
	Description() string

	// Return MEDIA_FLAG_ENCODER, MEDIA_FLAG_DECODER, MEDIA_FLAG_FILE
	// and MEDIA_FLAG_DEVICE flags
	Flags() MediaFlag

	// Return mimetypes handled
	MimeType() []string

	// Return file extensions handled
	Ext() []string

	// Return the default audio codec for the format
	DefaultAudioCodec() Codec

	// Return the default video codec for the format
	DefaultVideoCodec() Codec

	// Return the default subtitle codec for the format
	DefaultSubtitleCodec() Codec
}

MediaFormat is an input or output format for media items

type MediaKey 

type MediaKey string

MediaKey is a string which is used for media metadata 

const (
	MEDIA_KEY_BRAND_MAJOR      MediaKey = "major_brand"       // string
	MEDIA_KEY_BRAND_COMPATIBLE MediaKey = "compatible_brands" // string
	MEDIA_KEY_CREATED          MediaKey = "creation_time"     // time.Time
	MEDIA_KEY_ENCODER          MediaKey = "encoder"           // string
	MEDIA_KEY_ALBUM            MediaKey = "album"             // string
	MEDIA_KEY_ALBUM_ARTIST     MediaKey = "artist"            // string
	MEDIA_KEY_COMMENT          MediaKey = "comment"           // string
	MEDIA_KEY_COMPOSER         MediaKey = "composer"          // string
	MEDIA_KEY_COPYRIGHT        MediaKey = "copyright"         // string
	MEDIA_KEY_YEAR             MediaKey = "date"              // uint
	MEDIA_KEY_DISC             MediaKey = "disc"              // uint xx or xx/yy
	MEDIA_KEY_ENCODED_BY       MediaKey = "encoded_by"        // string
	MEDIA_KEY_FILENAME         MediaKey = "filename"          // string
	MEDIA_KEY_GENRE            MediaKey = "genre"             // string
	MEDIA_KEY_LANGUAGE         MediaKey = "language"          // string
	MEDIA_KEY_PERFORMER        MediaKey = "performer"         // string
	MEDIA_KEY_PUBLISHER        MediaKey = "publisher"         // string
	MEDIA_KEY_SERVICE_NAME     MediaKey = "service_name"      // string
	MEDIA_KEY_SERVICE_PROVIDER MediaKey = "service_provider"  // string
	MEDIA_KEY_TITLE            MediaKey = "title"             // string
	MEDIA_KEY_TRACK            MediaKey = "track"             // uint xx or xx/yy
	MEDIA_KEY_VERSION_MAJOR    MediaKey = "major_version"     // string
	MEDIA_KEY_VERSION_MINOR    MediaKey = "minor_version"     // string
	MEDIA_KEY_SHOW             MediaKey = "show"              // string
	MEDIA_KEY_SEASON           MediaKey = "season_number"     // uint
	MEDIA_KEY_EPISODE_SORT     MediaKey = "episode_sort"      // string
	MEDIA_KEY_EPISODE_ID       MediaKey = "episode_id"        // uint
	MEDIA_KEY_COMPILATION      MediaKey = "compilation"       // bool
	MEDIA_KEY_GAPLESS_PLAYBACK MediaKey = "gapless_playback"  // bool
	MEDIA_KEY_ACCOUNT_ID       MediaKey = "account_id"        // string
	MEDIA_KEY_DESCRIPTION      MediaKey = "description"       // string
	MEDIA_KEY_MEDIA_TYPE       MediaKey = "media_type"        // string
	MEDIA_KEY_PURCHASED        MediaKey = "purchase_date"     // time.Time
	MEDIA_KEY_ALBUM_SORT       MediaKey = "sort_album"        // string
	MEDIA_KEY_ARTIST_SORT      MediaKey = "sort_artist"       // string
	MEDIA_KEY_TITLE_SORT       MediaKey = "sort_name"         // string
	MEDIA_KEY_SYNOPSIS         MediaKey = "synopsis"          // string
	MEDIA_KEY_GROUPING         MediaKey = "grouping"          // string
)

type Metadata added in v1.5.1 

type Metadata interface {
	// Return enumeration of keys
	Keys() []MediaKey

	// Return value for key
	Value(MediaKey) any
}

Metadata embedded in the media

type Packet added in v1.5.1 

type Packet interface {
	// Flags returns the flags for the packet from the stream
	Flags() MediaFlag

	// Stream returns the stream which the packet belongs to
	Stream() Stream

	// IsKeyFrame returns true if the packet contains a key frame
	IsKeyFrame() bool

	// Pos returns the byte position of the packet in the media
	Pos() int64

	// Duration returns the duration of the packet
	Duration() time.Duration

	// Size of the packet in bytes
	Size() int

	// Bytes returns the raw bytes of the packet
	Bytes() []byte
}

Packet is a single unit of data in the media

type PixelFormat added in v1.5.1 

type PixelFormat int

PixelFormat specifies the encoding of pixel within a frame 

const (
	PIXEL_FORMAT_YUV420P PixelFormat = iota
	PIXEL_FORMAT_NONE    PixelFormat = -1
)

func (PixelFormat) String added in v1.5.1 

func (f PixelFormat) String() string

type SWResample added in v1.5.1 

type SWResample interface {
	io.Closer

	// Create a new empty context object for conversion, with an input frame which
	// will be used to store the data and the target output format.
	Convert(AudioFrame, AudioFormat, SWResampleFn) error
}

SWResample is an interface to the ffmpeg swresample library which resamples audio.

type SWResampleFn added in v1.5.1 

type SWResampleFn func(AudioFrame) error

SWResampleFn is a function that accepts an "output" audio frame, which can be nil if the conversion has not started yet, and should fill the audio frame provided to the Convert function. Should return io.EOF on end of conversion, or any other error to stop the conversion.

type SampleFormat added in v1.5.1 

type SampleFormat uint

SampleFormat specifies the type of a single sample 

const (
	SAMPLE_FORMAT_NONE SampleFormat = iota
	SAMPLE_FORMAT_U8                // Byte
	SAMPLE_FORMAT_S16               // Signed 16-bit
	SAMPLE_FORMAT_S32               // Signed 32-bit
	SAMPLE_FORMAT_S64               // Signed 64-bit
	SAMPLE_FORMAT_FLT               // Float 32-bit
	SAMPLE_FORMAT_DBL               // Float 64-bit
	SAMPLE_FORMAT_U8P               // Planar byte
	SAMPLE_FORMAT_S16P              // Planar signed 16-bit
	SAMPLE_FORMAT_S32P              // Planar signed 32-bit
	SAMPLE_FORMAT_S64P              // Planar signed 64-bit
	SAMPLE_FORMAT_FLTP              // Planar float 32-bit
	SAMPLE_FORMAT_DBLP              // Planar float 64-bit
	SAMPLE_FORMAT_MAX  = SAMPLE_FORMAT_DBLP
)

func (SampleFormat) String added in v1.5.1 

func (v SampleFormat) String() string

type Stream added in v1.5.1 

type Stream interface {
	// Return index of stream in the media
	Index() int

	// Return media flags for the stream
	Flags() MediaFlag

	// Return artwork for the stream - if MEDIA_FLAG_ARTWORK is set
	Artwork() []byte
}

Stream of data multiplexed in the media

type VideoFrame added in v1.5.1 

type VideoFrame interface {
	// Returns the audio format, if MEDIA_FLAG_VIDEO is set
	PixelFormat() PixelFormat

	// Return frame width and height, if MEDIA_FLAG_VIDEO is set
	Size() (int, int)
}

Source Files

View all Source files

Directories

Path Synopsis
Media services for golang, including bindings for ffmpeg, command line application
 Media services for golang, including bindings for ffmpeg, command line application
cmd/_mediatool
cmd/_photosync
hw/mmal
pkg/_old/_googleclient
pkg/_old/_googlephotos
pkg/_old/_media
Package media provides high-level media services for multiplexing, extracting and transcoding audio and video.
 Package media provides high-level media services for multiplexing, extracting and transcoding audio and video.
plugin/_media
sys/_ffmpeg
Package ffmpeg provides low-level ffmpeg for go
 Package ffmpeg provides low-level ffmpeg for go
cmd
extractartwork
An example of extracting artwork from media files.
 An example of extracting artwork from media files.
transcode
An example of extracting frames from a video.
 An example of extracting frames from a video.
pkg
chromaprint
config
file
Package file provides file system support, including file system walking
 Package file provides file system support, including file system walking
media
Package media provides media open, close and conversion support
 Package media provides media open, close and conversion support
sys
chromaprint
This package provides chromaprint audio fingerprinting bindings
 This package provides chromaprint audio fingerprinting bindings
dvb
DVB (Digital Video Broadcasting) bindings for Go
 DVB (Digital Video Broadcasting) bindings for Go
ffmpeg51
Package ffmpeg provides low-level ffmpeg for go
 Package ffmpeg provides low-level ffmpeg for go

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.