Class AVFrame

Represents a decoded audio or video frame in memory. This structure holds raw data for video frames or audio samples.
It provides methods and properties to access and manipulate this data, as well as to manage the associated resources.

Inheritance

object

AVFrame

Implements

IDisposable

IAVPointer<_AVFrame>

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Namespace: FFmpeg.Utils

Assembly: FFmpeg.dll

Syntax

public sealed class AVFrame : IDisposable, IAVPointer<_AVFrame>

Properties

BestEffortTimestamp

Gets or sets the timestamp of the frame, estimated using various heuristics, in the stream's time base.

• Encoding: Unused.
• Decoding: Notify by libavcodec, read by the user.

Declaration

public long BestEffortTimestamp { get; set; }

Property Value

Type	Description
long

ChannelLayout

Gets the channel layout of the audio data in the frame. The channel layout defines the spatial positioning of audio channels (e.g., mono, stereo).

Declaration

public ChannelLayout_ref ChannelLayout { get; }

Property Value

Type	Description
ChannelLayout_ref

ChromaLocation

Gets or sets the chroma subsampling location, which defines the position of chroma samples in relation to the luma samples.

Declaration

public ChromaLocation ChromaLocation { get; set; }

Property Value

Type	Description
ChromaLocation

ColorPrimaries

Gets or sets the color primaries for the frame, describing the chromaticity coordinates of the source's red, green, and blue components.

Declaration

public ColorPrimaries ColorPrimaries { get; set; }

Property Value

Type	Description
ColorPrimaries

ColorRange

Gets or sets the YUV range (color range) for the frame. This specifies the range of color values used in YUV encoding. For video frames, this can differentiate between MPEG (full range) and JPEG (limited range) YUV encoding.

• Encoding: Notify by user.
• Decoding: Notify by FFmpeg.AutoGen.ffmpeg.

Declaration

public ColorRange ColorRange { get; set; }

Property Value

Type	Description
ColorRange

ColorSpace

Gets or sets the YUV colorspace type of the frame. The colorspace determines how the YUV color model is applied to the frame.

• Encoding: Notify by user.
• Decoding: Notify by FFmpeg.AutoGen.ffmpeg.

Declaration

public ColorSpace ColorSpace { get; set; }

Property Value

Type	Description
ColorSpace

ColorTransferCharacteristic

Gets or sets the transfer characteristic of the frame, which describes the non-linear transfer function used to encode and decode color values. This can affect how brightness and contrast are handled in the frame.

Declaration

public ColorTransferCharacteristic ColorTransferCharacteristic { get; set; }

Property Value

Type	Description
ColorTransferCharacteristic

CropBottom

Gets or sets the number of pixels to crop from the bottom border of the video frame. This is used to discard pixels from the frame and obtain a sub-rectangle intended for presentation.

Declaration

public ulong CropBottom { get; set; }

Property Value

Type	Description
ulong

CropLeft

Gets or sets the number of pixels to crop from the left border of the video frame. This is used to discard pixels from the frame and obtain a sub-rectangle intended for presentation.

Declaration

public ulong CropLeft { get; set; }

Property Value

Type	Description
ulong

CropRight

Gets or sets the number of pixels to crop from the right border of the video frame. This is used to discard pixels from the frame and obtain a sub-rectangle intended for presentation.

Declaration

public ulong CropRight { get; set; }

Property Value

Type	Description
ulong

CropTop

Gets or sets the number of pixels to crop from the top border of the video frame. This is used to discard pixels from the frame and obtain a sub-rectangle intended for presentation.

Declaration

public ulong CropTop { get; set; }

Property Value

Type	Description
ulong

CroppedHeight

Gets the height of the video frame after applying the top and bottom cropping offsets.

Declaration

public int CroppedHeight { get; }

Property Value

Type	Description
int

Remarks

The cropped height is calculated by subtracting the top and bottom crop offsets from the original frame height.

CroppedWidth

Gets the width of the cropped frame in pixels.

Declaration

public int CroppedWidth { get; }

Property Value

Type	Description
int

Remarks

The cropped width is calculated by subtracting the left and right crop offsets from the original frame width.

Data

Gets the data pointers for the frame.

Declaration

public ReadOnlySpan<nint> Data { get; }

Property Value

Type	Description
ReadOnlySpan<nint>

Remarks

For video frames, the span contains one pointer for each image plane. For audio frames, it contains one pointer for packed audio or one pointer per channel for planar audio.

DecodeErrorFlags

Gets or sets the decode error flags for the frame, indicating errors that occurred during decoding. This is set to a combination of FF_DECODE_ERROR_xxx flags if the decoder produced a frame but encountered errors.

• Encoding: Unused.
• Decoding: Notify by libavcodec, read by the user.

Declaration

public DecodeErrorFlags DecodeErrorFlags { get; set; }

Property Value

Type	Description
DecodeErrorFlags

Duration

Gets or sets the duration of the frame, in the same units as PresentationTimestamp. A value of 0 indicates an unknown duration.

Declaration

public long Duration { get; set; }

Property Value

Type	Description
long

Flags

Gets or sets the flags associated with this frame, represented as a combination of FrameFlags values. These flags provide additional metadata for the frame.

Declaration

public FrameFlags Flags { get; set; }

Property Value

Type	Description
FrameFlags

Format

Gets or sets the format of the frame.
Values correspond to FFmpeg.AutoGen._AVPixelFormat for video frames or FFmpeg.AutoGen._AVSampleFormat for audio frames.

Declaration

public int Format { get; set; }

Property Value

Type	Description
int

FramesContext

Gets a reference to the FramesContext for hardware-accelerated frames. This context describes the frame when using hardware acceleration.

Declaration

public FramesContext_ref FramesContext { get; }

Property Value

Type	Description
FramesContext_ref

HasBuffer

Gets a value indicating whether the frame owns an allocated data buffer.

Declaration

public bool HasBuffer { get; }

Property Value

Type	Description
bool

Remarks

A frame without a buffer may still contain metadata and format information, but cannot store image or audio data until CreateBuffer(int) is called.

Height

Gets or sets the coded height (in pixels) of the video frame.
This represents the height of the rectangle that contains meaningful pixel data.

Declaration

public int Height { get; set; }

Property Value

Type	Description
int

IsAudio

Gets a value indicating whether this frame represents audio data.

Declaration

public bool IsAudio { get; }

Property Value

Type	Description
bool

IsReadOnly

Gets a value indicating whether the frame is read-only. If true, the frame cannot be modified.

Declaration

public bool IsReadOnly { get; }

Property Value

Type	Description
bool

IsVideo

Gets a value indicating whether this frame represents video data.

Declaration

public bool IsVideo { get; }

Property Value

Type	Description
bool

LineSize

Gets a reference to the array of line sizes for each data buffer in the frame.
For video frames, this usually indicates the size in bytes of each picture line (stride).
For audio frames, this may indicate the size of each channel buffer.

Declaration

public ref int_array8 LineSize { get; }

Property Value

Type	Description
int_array8

MediaType

Gets the inferred media type represented by this frame.

Declaration

public MediaType MediaType { get; }

Property Value

Type	Description
MediaType

Remarks

The media type is determined from the frame dimensions and sample count. If the frame does not clearly represent either audio or video, Unknown is returned.

Metadata

Gets the metadata associated with the frame.

• Encoding: Notify by the user.
• Decoding: Notify by libavcodec.

Declaration

public AVDictionary_ref Metadata { get; }

Property Value

Type	Description
AVDictionary_ref

PacketDecoderTimestamp

Gets or sets the decoding timestamp (DTS) of the packet that triggered the return of this frame. The DTS is used to order frames before they are presented.

Declaration

public long PacketDecoderTimestamp { get; set; }

Property Value

Type	Description
long

PictureType

Gets or sets the type of the picture in the video frame, such as I-frame, P-frame, or B-frame.

Declaration

public PictureType PictureType { get; set; }

Property Value

Type	Description
PictureType

PixelAspectRatio

Gets or sets the sample aspect ratio for the video frame. A value of 0/1 indicates an unspecified aspect ratio.

Declaration

public Rational PixelAspectRatio { get; set; }

Property Value

Type	Description
Rational

PixelFormat

Gets or sets the pixel format of the video frame.
This is a strongly-typed version of Format when working with video frames.

Declaration

public PixelFormat PixelFormat { get; set; }

Property Value

Type	Description
PixelFormat

PresentationTimestamp

Gets or sets the presentation timestamp (PTS) of the frame, in time base units. This timestamp indicates when the frame should be displayed to the user.

Declaration

public long PresentationTimestamp { get; set; }

Property Value

Type	Description
long

Quality

Gets or sets the quality of the frame. Valid values range from 1 (high quality) to FF_LAMBDA_MAX (low quality).

Declaration

public Quality Quality { get; set; }

Property Value

Type	Description
Quality

RepeatPicture

Gets or sets the number of fields in this frame that should be repeated. The total duration of the frame should be the normal duration plus the number of repeated fields.

Declaration

public int RepeatPicture { get; set; }

Property Value

Type	Description
int

SampleCount

Gets or sets the number of audio samples per channel described by this frame.

Declaration

public int SampleCount { get; set; }

Property Value

Type	Description
int

SampleFormat

Gets or sets the sample format of the audio frame.
This is a strongly-typed version of Format when working with audio frames.

Declaration

public SampleFormat SampleFormat { get; set; }

Property Value

Type	Description
SampleFormat

SampleRate

Gets or sets the sample rate of the audio data in this frame, in Hz.

Declaration

public int SampleRate { get; set; }

Property Value

Type	Description
int

Size

Gets the total size of the data in bytes across all planes.

Declaration

public long Size { get; }

Property Value

Type	Description
long

TimeBase

Gets or sets the time base for the timestamps in this frame. The time base defines the unit of time for PresentationTimestamp and PacketDecoderTimestamp and is typically set by decoders or filters.

Declaration

public Rational TimeBase { get; set; }

Property Value

Type	Description
Rational

Width

Gets or sets the coded width (in pixels) of the video frame.
This represents the width of the rectangle that contains meaningful pixel data.

Declaration

public int Width { get; set; }

Property Value

Type	Description
int

Methods

Allocate()

Allocates a new AVFrame.
This method only allocates the AVFrame structure itself and does not allocate any underlying image or audio buffer.

Declaration

public static AVFrame Allocate()

Returns

Type	Description
AVFrame	A newly allocated AVFrame instance.

Exceptions

Type	Condition
OutOfMemoryException	Thrown if the frame allocation fails.

Allocate(SampleFormat, ChannelLayout, int, int?)

Allocates a new AVFrame for audio with an allocated sample buffer.
This is a shortcut for creating a frame that can be written to manually.

Declaration

public static AVFrame Allocate(SampleFormat format, ChannelLayout layout, int samples, int? sampleRate = null)

Parameters

Type	Name	Description
SampleFormat	format	The sample format of the audio frame.
ChannelLayout	layout	The channel layout of the audio frame.
int	samples	The number of samples per channel.
int?	sampleRate	The sample rate (optional). If null, the frame will not set a sample rate.

Returns

Type	Description
AVFrame	A newly allocated AVFrame with its audio buffer initialized.

Exceptions

Type	Condition
OutOfMemoryException	Thrown if the frame structure allocation fails.
FFmpegException	Thrown if buffer allocation fails.

Allocate(SampleFormat, int, int, int?)

Allocates a new AVFrame for audio with an allocated sample buffer.
This overload allows specifying the number of channels directly; a default channel layout will be created.

Declaration

public static AVFrame Allocate(SampleFormat format, int channels, int samples, int? sampleRate = null)

Parameters

Type	Name	Description
SampleFormat	format	The sample format of the audio frame.
int	channels	The number of audio channels.
int	samples	The number of samples per channel.
int?	sampleRate	The sample rate (optional). If null, the frame will not set a sample rate.

Returns

Type	Description
AVFrame	A newly allocated AVFrame with its audio buffer initialized.

Exceptions

Type	Condition
OutOfMemoryException	Thrown if the frame structure allocation fails.
FFmpegException	Thrown if buffer allocation fails.

Allocate(PixelFormat, int, int)

Allocates a new AVFrame for video with an allocated image buffer.
This is a shortcut for creating a frame that can be written to manually.

Declaration

public static AVFrame Allocate(PixelFormat format, int width, int height)

Parameters

Type	Name	Description
PixelFormat	format	The pixel format of the frame.
int	width	The width of the frame in pixels.
int	height	The height of the frame in pixels.

Returns

Type	Description
AVFrame	A newly allocated AVFrame with its buffer initialized.

Exceptions

Type	Condition
OutOfMemoryException	Thrown if the frame structure allocation fails.
FFmpegException	Thrown if buffer allocation fails.

Clone()

Creates a clone of the current frame. The cloned frame is an exact duplicate but with separate memory allocation.

Declaration

public AVFrame Clone()

Returns

Type	Description
AVFrame	A new AVFrame that is a clone of the current frame.

Copy()

Copies the current frame's data and properties to a new frame. This includes copying the frame's format, dimensions, and any other associated properties.

Declaration

public AVFrame Copy()

Returns

Type	Description
AVFrame	A new AVFrame with the same properties and data as the current frame.

Exceptions

Type	Condition
InvalidOperationException	Thrown if an error occurs during the copy process.

CopyPropertiesTo(AVFrame)

Copies all frame properties to another frame without copying the underlying image or audio data.

Declaration

public void CopyPropertiesTo(AVFrame dst)

Parameters

Type	Name	Description
AVFrame	dst	The destination frame that receives the frame properties.

Remarks

This copies metadata such as timestamps, color information, sample aspect ratio, and other frame properties. The frame buffers themselves are not copied.

CreateBuffer(int)

Allocates new buffers for the frame. This method is required before encoding or decoding if the frame does not have any buffer. If the frame already has a buffer, an exception will be thrown to prevent memory leakage. Please set SampleFormat, ChannelLayout and SampleCount or PixelFormat, Width and Height before calling.

Declaration

public AVResult32 CreateBuffer(int align = 1)

Parameters

Type	Name	Description
int	align	Specifies the alignment requirement for the buffer. Defaults to 1.

Returns

Type	Description
AVResult32	An AVResult32 indicating the success or failure of the buffer allocation.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the frame already has a buffer.

Dispose()

Releases the resources associated with the frame. This method should be called when the frame is no longer needed to prevent memory leaks.

Declaration

public void Dispose()

~AVFrame()

Finalizer for the frame, ensures that unmanaged resources are cleaned up if Dispose() was not called.

Declaration

protected ~AVFrame()

Free()

Frees the frame by disposing of any allocated resources.

Declaration

public void Free()

FreeSideData()

Frees any side data associated with the frame, releasing the allocated memory.

Declaration

public void FreeSideData()

GetBuffer(int)

Allocates new buffers for the frame. This method is required before encoding or decoding if the frame does not have any buffer. If the frame already has a buffer, an exception will be thrown to prevent memory leakage.

Declaration

[Obsolete("This function got renamed into CreateBuffer, as it actually create the underlying buffer based on the specified parameters.")]
public AVResult32 GetBuffer(int align = 1)

Parameters

Type	Name	Description
int	align	Specifies the alignment requirement for the buffer. Defaults to 1.

Returns

Type	Description
AVResult32	An AVResult32 indicating the success or failure of the buffer allocation.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the frame already has a buffer.

GetBufferCapacity(int)

Gets the capacity (in bytes) of the specified buffer index in the frame.
Returns 0 if the buffer is not set or the index is out of range.

Declaration

public int GetBufferCapacity(int index)

Parameters

Type	Name	Description
int	index	The index of the buffer to retrieve. Indices 0–7 refer to buf, and indices 8 and above refer to extended_buf.

Returns

Type	Description
int	The size of the buffer in bytes, or 0 if not available.

GetBufferSpan(int)

Gets a span over one of the underlying frame buffers.

Declaration

public Span<byte> GetBufferSpan(int bufferIndex)

Parameters

Type	Name	Description
int	bufferIndex	The zero-based buffer index. Indices 0-7 refer to the primary buf array, while higher indices refer to extended_buf.

Returns

Type	Description
Span<byte>	A Span<T> representing the requested buffer, or an empty span if the buffer does not exist.

GetData(int)

Gets the frame data for the specified plane or channel.

Declaration

public Span<byte> GetData(int index)

Parameters

Type	Name	Description
int	index	The zero-based plane index for video frames or channel index for planar audio frames. For packed audio, only index 0 is valid.

Returns

Type	Description
Span<byte>	A Span<T> over the requested frame data. Returns an empty span if the specified plane or channel does not exist.

Remarks

For video frames, the returned span covers the complete image plane. For audio frames, the returned span contains the sample data for the requested channel (or the single packed buffer).

Exceptions

Type	Condition
NotSupportedException	Thrown if the frame is neither an audio nor a video frame.

GetPresentationTimestamp()

Gets the presentation timestamp (PTS) of the frame, if available. If the PTS is unavailable, returns the best-effort timestamp as a fallback.

Declaration

public long GetPresentationTimestamp()

Returns

Type	Description
long	A timestamp (in stream time base units) representing when the frame should be presented. This is typically the PTS; if the PTS is not set, the best-effort timestamp is returned instead.

MakeWriteable()

Makes the frame writeable, ensuring that it can be modified. If the frame is shared, this will create a writable copy of the frame.

Declaration

public AVResult32 MakeWriteable()

Returns

Type	Description
AVResult32	An AVResult32 indicating success or failure of the operation.

Reference(AVFrame)

Makes this frame reference the same underlying data as another frame. Any data currently referenced by this frame is released first.

Declaration

public void Reference(AVFrame src)

Parameters

Type	Name	Description
AVFrame	src	The source frame to reference.

Exceptions

Type	Condition
FFmpegException	Thrown if the reference operation fails.

Unreference()

Unreferences the frame, releasing any associated resources but keeping the frame structure allocated. This effectively resets the frame for reuse.

Declaration

public void Unreference()

Implements

IDisposable

IAVPointer<T>