ffmpeg

package
v1.8.3 Latest Latest
Warning

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

 Go to latest Published: Jan 7, 2026 License: Apache-2.0 Imports: 21 Imported by: 1

Documentation

Index

Constants

View Source 
const (
	PTS_UNDEFINED = ff.AV_NOPTS_VALUE
	TS_UNDEFINED  = -1.0
)
View Source 
const (
	MetaArtwork = "artwork" // Metadata key for artwork, set the value as []byte
)

Variables

View Source 
var ErrCodecNotFound = errors.New("codec decoder not found")

ErrCodecNotFound is returned when a decoder cannot be found for a codec

Functions

func SetLogging added in v1.6.10 

func SetLogging(verbose bool, fn LogFn)

Set logging options, including a callback function

Types

type DecoderFrameFn added in v1.6.7 

type DecoderFrameFn func(int, *Frame) error

DecoderFrameFn is a function which is called to send a frame after decoding. It should return nil to continue decoding or io.EOF to stop.

type DecoderMapFunc added in v1.6.7 

type DecoderMapFunc func(int, *Par) (*Par, error)

Return parameters if a stream should be decoded and either resampled or resized. Return nil if you want to ignore the stream, or pass back the stream parameters if you want to copy the stream without any changes.

type DecoderPacketFn added in v1.8.0 

type DecoderPacketFn func(int, *Packet) error

DecoderPacketFn is a function which is called to send a packet after demuxing. It should return nil to continue reading packets or io.EOF to stop. Use this for stream copying without decode/encode overhead.

type DecoderSubtitleFn added in v1.8.0 

type DecoderSubtitleFn func(int, *ff.AVSubtitle) error

DecoderSubtitleFn is a function which is called to send a decoded subtitle. It should return nil to continue decoding or io.EOF to stop.

type EncoderFrameFn 

type EncoderFrameFn func(int) (*Frame, error)

EncoderFrameFn is a function which is called to receive a frame to encode. It should return nil to continue encoding or io.EOF to stop encoding.

type EncoderPacketFn 

type EncoderPacketFn func(*Packet) error

EncoderPacketFn is a function which is called for each packet encoded, with the stream timebase.

type Filter added in v1.8.0 

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

Filter applies a filter graph to frames for a single stream. Supports single input → filter chain → single output.

func NewFilter added in v1.8.0 

func NewFilter(filterSpec string, srcPar, destPar *Par) (*Filter, error)

Create a new filter which will apply the given filter specification to frames. filterSpec is an FFmpeg filter string (e.g., "scale=1280:720", "volume=0.5"). srcPar defines the input frame format, destPar defines the desired output format.

func (*Filter) Close added in v1.8.0 

func (f *Filter) Close() error

Release resources

func (*Filter) Process added in v1.8.0 

func (f *Filter) Process(src *Frame, fn func(*Frame) error) error

Process applies the filter to one frame and emits zero or more frames via fn. Pass src==nil to flush. fn may receive nil to signal end-of-batch.

IMPORTANT: The frame pointer passed to fn is only valid during the callback execution. The frame is freed immediately after fn returns. If you need to retain the frame data, you must clone it within the callback using AVUtil_frame_clone or copy its data. Do not store the frame pointer for later use.

type Frame 

type Frame ff.AVFrame

func NewFrame 

func NewFrame(par *Par) (*Frame, error)

Create a new frame and optionally set audio or video parameters

func (*Frame) AllocateBuffers added in v1.6.7 

func (frame *Frame) AllocateBuffers() error

Allocate buffers for the frame

func (*Frame) Bytes 

func (frame *Frame) Bytes(plane int) []byte

Return plane data as a byte slice

func (*Frame) ChannelLayout 

func (frame *Frame) ChannelLayout() ff.AVChannelLayout

func (*Frame) Close added in v1.6.7 

func (frame *Frame) Close() error

Release frame resources

func (*Frame) Copy added in v1.6.7 

func (frame *Frame) Copy() (*Frame, error)

Make a copy of the frame, which should be released by the caller

func (*Frame) CopyPropsFromFrame added in v1.6.7 

func (frame *Frame) CopyPropsFromFrame(other *Frame) error

Copy properties from another frame

func (*Frame) Float32 added in v1.6.7 

func (frame *Frame) Float32(plane int) []float32

Return plane data as a float32 slice

func (*Frame) FrameRate added in v1.6.7 

func (frame *Frame) FrameRate() ff.AVRational

func (*Frame) Height 

func (frame *Frame) Height() int

func (*Frame) IncPts added in v1.6.7 

func (frame *Frame) IncPts(v int64)

Increment presentation timestamp

func (*Frame) Int16 

func (frame *Frame) Int16(plane int) []int16

Return plane data as a int16 slice

func (*Frame) IsAllocated added in v1.6.7 

func (frame *Frame) IsAllocated() bool

Return true if the frame has allocated buffers

func (*Frame) MakeWritable added in v1.6.7 

func (frame *Frame) MakeWritable() error

Make the frame writable

func (*Frame) MarshalJSON 

func (frame *Frame) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler by delegating to the underlying AVFrame

func (*Frame) MatchesFormat added in v1.8.0 

func (frame *Frame) MatchesFormat(other *Frame) bool

Returns true if this frame can be resampled/resized to match the other frame. Checks format compatibility (sample format, pixel format, channel layout, sample rate) but ignores sample count and framerate.

func (*Frame) NumSamples 

func (frame *Frame) NumSamples() int

func (*Frame) PixelFormat 

func (frame *Frame) PixelFormat() ff.AVPixelFormat

func (*Frame) Pts added in v1.6.7 

func (frame *Frame) Pts() int64

Return the presentation timestamp in int64

func (*Frame) SampleAspectRatio added in v1.6.7 

func (frame *Frame) SampleAspectRatio() ff.AVRational

func (*Frame) SampleFormat 

func (frame *Frame) SampleFormat() ff.AVSampleFormat

func (*Frame) SampleRate added in v1.6.7 

func (frame *Frame) SampleRate() int

func (*Frame) SetFloat32 added in v1.6.13 

func (frame *Frame) SetFloat32(plane int, data []float32) error

Set plane data from float32 slice

func (*Frame) SetPts added in v1.6.7 

func (frame *Frame) SetPts(v int64)

Set the presentation timestamp in int64

func (*Frame) SetTs added in v1.6.13 

func (frame *Frame) SetTs(secs float64)

Set timestamp in seconds

func (*Frame) Stride 

func (frame *Frame) Stride(plane int) int

Return the stride for a plane (number of bytes in a row)

func (*Frame) String 

func (frame *Frame) String() string

func (*Frame) TimeBase added in v1.6.7 

func (frame *Frame) TimeBase() ff.AVRational

func (*Frame) Ts added in v1.6.7 

func (frame *Frame) Ts() float64

Return the timestamp in seconds, or TS_UNDEFINED if the timestamp is undefined or timebase is not set

func (*Frame) Type 

func (frame *Frame) Type() media.Type

Return frame type - AUDIO or VIDEO. Other types are not yet identified and returned as UNKNOWN

func (*Frame) Unref added in v1.6.7 

func (frame *Frame) Unref()

Unreference frame buffers

func (*Frame) Width 

func (frame *Frame) Width() int

type LogFn added in v1.6.10 

type LogFn func(text string)

Logging function

type LogFunc added in v1.6.7 

type LogFunc func(string)

Logging function which is used to log messages

type Metadata 

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

func NewMetadata 

func NewMetadata(key string, value any) *Metadata

Metadata implementation

func (*Metadata) Any added in v1.6.7 

func (m *Metadata) Any() any

Returns the value as an interface

func (*Metadata) Bytes added in v1.6.7 

func (m *Metadata) Bytes() []byte

Returns the value as a byte slice

func (*Metadata) Image added in v1.6.7 

func (m *Metadata) Image() image.Image

Returns the value as an image

func (*Metadata) Key 

func (m *Metadata) Key() string

func (*Metadata) MarshalJSON added in v1.8.0 

func (m *Metadata) MarshalJSON() ([]byte, error)

func (*Metadata) String 

func (m *Metadata) String() string

func (*Metadata) Value 

func (m *Metadata) Value() string

Value returns the value as a string. If the value is a byte slice, it will return the mimetype of the byte slice.

type Opt 

type Opt func(*opts) error

Option which can affect the behaviour of ffmpeg

func OptCopy added in v1.8.0 

func OptCopy() Opt

Enable stream copying mode (remuxing without encoding)

func OptForce 

func OptForce() Opt

Force resampling and resizing on decode, even if the input and output parameters are the same

func OptLog added in v1.6.7 

func OptLog(verbose bool, fn LogFunc) Opt

Set a logging function

func OptMetadata 

func OptMetadata(entry ...*Metadata) Opt

Append metadata to the output file, including artwork

func OptOutputFormat 

func OptOutputFormat(name string) Opt

Output format from name or url

func OptStream 

func OptStream(stream int, par *Par) Opt

New stream with parameters

func WithInput added in v1.8.0 

func WithInput(format string, options ...string) Opt

WithInput sets the input format and format options for reading. The format parameter specifies the input format name (e.g., "s16le", "mp3"). If format is empty, only the options are set without changing the format. Additional options are key=value pairs (e.g., "sample_rate=22050", "channels=1").

Example: 

WithInput("s16le", "sample_rate=22050", "channels=1", "sample_fmt=s16")
WithInput("", "analyzeduration=1000000") // Only set options

func WithInputFormat added in v1.8.1 

func WithInputFormat(iformat *ffmpeg.AVInputFormat, options ...string) Opt

WithInputFormat sets the input format directly using an AVInputFormat pointer. This is useful for device formats that may not be found via AVFormat_find_input_format. Additional options are key=value pairs (e.g., "sample_rate=22050", "channels=1").

type Packet added in v1.6.7 

type Packet = schema.Packet

Packet is an alias for schema.Packet for backwards compatibility

type Par 

type Par struct {
	ff.AVCodecParameters
	// contains filtered or unexported fields
}

func AudioPar 

func AudioPar(samplefmt string, channellayout string, samplerate int, opts ...media.Metadata) *Par

Create audio parameters. If there is an error, then this function will panic

func NewAudioPar 

func NewAudioPar(samplefmt string, channellayout string, samplerate int, opts ...media.Metadata) (*Par, error)

Create new audio parameters with sample format, channel layout and sample rate plus any additional options which is used for creating a stream

func NewVideoPar 

func NewVideoPar(pixfmt string, size string, framerate float64, opts ...media.Metadata) (*Par, error)

Create new video parameters with pixel format, frame size, framerate plus any additional options which is used for creating a stream

func VideoPar 

func VideoPar(pixfmt string, size string, framerate float64, opts ...media.Metadata) *Par

Create video parameters. If there is an error, then this function will panic

func (*Par) CopyToCodecContext added in v1.6.7 

func (par *Par) CopyToCodecContext(codec *ff.AVCodecContext) error

func (*Par) FrameRate added in v1.6.7 

func (par *Par) FrameRate() float64

func (*Par) MarshalJSON 

func (par *Par) MarshalJSON() ([]byte, error)

func (*Par) String 

func (par *Par) String() string

func (*Par) Type added in v1.6.7 

func (par *Par) Type() media.Type

func (*Par) ValidateFromCodec 

func (par *Par) ValidateFromCodec(codec *ff.AVCodec) error

func (*Par) WidthHeight added in v1.6.7 

func (par *Par) WidthHeight() string

type Reader added in v1.6.7 

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

Media reader which reads from a URL, file path or device

func NewReader added in v1.6.7 

func NewReader(r io.Reader, opt ...Opt) (*Reader, error)

Create a new reader from an io.Reader

func Open added in v1.6.7 

func Open(url string, opt ...Opt) (*Reader, error)

Open media from a url, file path or device

func (*Reader) AVStreams added in v1.8.0 

func (r *Reader) AVStreams() []*ff.AVStream

Return the raw AVStream objects for direct access

func (*Reader) BestStream added in v1.6.7 

func (r *Reader) BestStream(t media.Type) int

Return the "best stream" for a specific media type, or -1 if there is no "best stream" for that type.

func (*Reader) Close added in v1.6.7 

func (r *Reader) Close() error

Close the reader

func (*Reader) Decode added in v1.6.7 

func (r *Reader) Decode(ctx context.Context, packetfn DecoderPacketFn) error

Decode packets from the media stream without decoding to frames. The packetfn is called for each packet read from any stream. Use this for stream copying or remuxing without transcoding.

The reading can be interrupted by cancelling the context, or by the packetfn returning an error or io.EOF. The latter will end the reading process early but will not return an error.

func (*Reader) Demux added in v1.8.0 

func (r *Reader) Demux(ctx context.Context, mapfn DecoderMapFunc, framefn DecoderFrameFn, subtitlefn DecoderSubtitleFn) error

Demux and decode the media stream into frames and subtitles. The map function determines which streams to decode and what output parameters to use. The framefn is called for each decoded frame from any mapped stream. The optional subtitlefn is called for each decoded subtitle.

The decoding can be interrupted by cancelling the context, or by the framefn/subtitlefn returning an error or io.EOF. The latter will end the decoding process early but will not return an error.

func (*Reader) Duration added in v1.6.7 

func (r *Reader) Duration() time.Duration

Return the duration of the media stream, returns zero if unknown

func (*Reader) InputFormat added in v1.8.0 

func (r *Reader) InputFormat() *ff.AVInputFormat

Return the input format (for probing format info)

func (*Reader) MarshalJSON added in v1.6.7 

func (r *Reader) MarshalJSON() ([]byte, error)

Display the reader as a string

func (*Reader) Metadata added in v1.6.7 

func (r *Reader) Metadata(keys ...string) []*Metadata

Return the metadata for the media stream, filtering by the specified keys if there are any. Artwork is returned with the "artwork" key.

func (*Reader) Seek added in v1.7.3 

func (r *Reader) Seek(stream int, secs float64) error

Seek to a specific time in the media stream, in seconds

func (*Reader) Streams added in v1.7.3 

func (r *Reader) Streams(t media.Type) []*schema.Stream

Return all streams of a specific type (video, audio, subtitle, data) Use media.ANY to return all streams regardless of type

func (*Reader) String added in v1.6.7 

func (r *Reader) String() string

Display the reader as a string

func (*Reader) Type added in v1.6.7 

func (r *Reader) Type() media.Type

Return the media type

type Resampler added in v1.8.0 

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

Resampler handles audio resampling or video rescaling for a single stream.

func NewResampler 

func NewResampler(par *Par, force bool) (*Resampler, error)

Create a new resampler which will resample or rescale frames to the specified parameters

func (*Resampler) Close added in v1.8.0 

func (r *Resampler) Close() error

Release resources

func (*Resampler) Resample added in v1.8.0 

func (r *Resampler) Resample(src *Frame, fn func(*Frame) error) error

Resample converts one frame and emits zero or more frames via fn. Pass src==nil to flush. fn may receive nil to signal end-of-batch.

type Writer 

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

Writer creates media files with multiple streams. Supports encoding frames or writing pre-encoded packets. For multiple streams, frames/packets are automatically interleaved by the muxer (AVFormat_interleaved_write_frame), but best results are achieved by sending frames in roughly temporal order to minimize buffering.

Multi-stream Encoding Best Practices

When encoding multiple streams (e.g., video + audio), you have two options:

  1. Temporal Interleaving (Recommended for streaming): Compare timestamps across streams and encode the frame with the earliest timestamp. This minimizes muxer buffering and is ideal for live streaming scenarios. See Test_encode_multiple_streams_interleaved_mp4 for an example.

  2. Batch by Stream (Simpler, works for files): Encode all frames for one stream, then the next. The muxer will buffer and reorder. This is simpler but uses more memory and adds latency. See Test_encode_multiple_streams_mp4 for an example.

Both approaches work correctly - the muxer handles interleaving automatically. Choose based on your use case (streaming vs file output, memory constraints, etc).

func Create 

func Create(url string, opt ...Opt) (*Writer, error)

Create a new writer with a URL and options

func NewWriter 

func NewWriter(w io.Writer, opt ...Opt) (*Writer, error)

Create a new writer with an io.Writer and options

func (*Writer) Close 

func (w *Writer) Close() error

Close a writer and release resources

func (*Writer) EncodeFrame added in v1.8.0 

func (w *Writer) EncodeFrame(stream int, frame *Frame) error

EncodeFrame encodes a single frame and writes the resulting packet(s) to the output (synchronous). The frame should have the correct format for the stream's encoder. Pass nil to flush the encoder. Returns nil on success or error. Automatically writes artwork on first frame if available.

func (*Writer) EncodeFrames added in v1.8.0 

func (w *Writer) EncodeFrames(stream int, frames <-chan *Frame) error

EncodeFrames encodes frames from a channel and writes the resulting packets to the output (asynchronous). This method blocks until the channel is closed or an error occurs. Returns nil when the channel is closed normally, or an error if encoding/writing fails. When the channel closes, the encoder is automatically flushed. Automatically writes artwork before first frame if available.

Ownership: EncodeFrames assumes ownership of frames received from the channel and will Close() each frame after it has been sent to the encoder.

func (*Writer) MarshalJSON added in v1.6.7 

func (w *Writer) MarshalJSON() ([]byte, error)

Display the writer as a string

func (*Writer) Stream 

func (w *Writer) Stream(stream int) *encoder

Return encoder for a given stream index

func (*Writer) String added in v1.6.7 

func (w *Writer) String() string

Display the writer as a string

func (*Writer) Type added in v1.7.3 

func (w *Writer) Type() media.Type

Return a "stream" for encoding

func (*Writer) Write 

func (w *Writer) Write(packet *Packet) error

Write a packet to the output (synchronous). The packet should have the stream index, PTS, DTS, duration, and timebase set correctly. Returns nil on success or error. Packets are automatically interleaved for proper ordering.

func (*Writer) WritePackets added in v1.8.0 

func (w *Writer) WritePackets(packets <-chan *Packet) error

WritePackets reads packets from a channel and writes them to the output (asynchronous). This method blocks until the channel is closed or an error occurs. Returns nil when the channel is closed normally, or an error if writing fails. Packets are automatically interleaved for proper ordering.

Source Files

View all Source files

Directories

Path Synopsis

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.