Buffer

class Buffer(**kwargs)

Buffers are the basic unit of data transfer in GStreamer. They contain the timing and offset along with other arbitrary metadata that is associated with the Memory blocks that the buffer contains.

Buffers are usually created with new(). After a buffer has been created one will typically allocate memory for it and add it to the buffer. The following example creates a buffer that can hold a given video frame with a given width, height and bits per plane.

GstBuffer *buffer;
GstMemory *memory;
gint size, width, height, bpp;
...
size = width * height * bpp;
buffer = gst_buffer_new ();
memory = gst_allocator_alloc (NULL, size, NULL);
gst_buffer_insert_memory (buffer, -1, memory);
...

Alternatively, use new_allocate() to create a buffer with preallocated data of a given size.

Buffers can contain a list of Memory objects. You can retrieve how many memory objects with n_memory() and you can get a pointer to memory with peek_memory()

A buffer will usually have timestamps, and a duration, but neither of these are guaranteed (they may be set to GST_CLOCK_TIME_NONE). Whenever a meaningful value can be given for these, they should be set. The timestamps and duration are measured in nanoseconds (they are ClockTime values).

The buffer DTS refers to the timestamp when the buffer should be decoded and is usually monotonically increasing. The buffer PTS refers to the timestamp when the buffer content should be presented to the user and is not always monotonically increasing.

A buffer can also have one or both of a start and an end offset. These are media-type specific. For video buffers, the start offset will generally be the frame number. For audio buffers, it will be the number of samples produced so far. For compressed data, it could be the byte offset in a source or destination file. Likewise, the end offset will be the offset of the end of the buffer. These can only be meaningfully interpreted if you know the media type of the buffer (the preceding CAPS event). Either or both can be set to GST_BUFFER_OFFSET_NONE.

gst_buffer_ref() is used to increase the refcount of a buffer. This must be done when you want to keep a handle to the buffer after pushing it to the next element. The buffer refcount determines the writability of the buffer, a buffer is only writable when the refcount is exactly 1, i.e. when the caller has the only reference to the buffer.

To efficiently create a smaller buffer out of an existing one, you can use copy_region(). This method tries to share the memory objects between the two buffers.

If a plug-in wants to modify the buffer data or metadata in-place, it should first obtain a buffer that is safe to modify by using buffer_make_writable(). This function is optimized so that a copy will only be made when it is necessary.

Several flags of the buffer can be set and unset with the BUFFER_FLAG_SET() and BUFFER_FLAG_UNSET() macros. Use BUFFER_FLAG_IS_SET() to test if a certain BufferFlags flag is set.

Buffers can be efficiently merged into a larger buffer with append(). Copying of memory will only be done when absolutely needed.

Arbitrary extra metadata can be set on a buffer with add_meta(). Metadata can be retrieved with get_meta(). See also Meta.

An element should either unref the buffer or push it out on a src pad using push() (see Pad).

Buffers are usually freed by unreffing them with gst_buffer_unref(). When the refcount drops to 0, any memory and metadata pointed to by the buffer is unreffed as well. Buffers allocated from a BufferPool will be returned to the pool when the refcount drops to 0.

The ParentBufferMeta is a meta which can be attached to a Buffer to hold a reference to another buffer that is only released when the child Buffer is released.

Typically, ParentBufferMeta is used when the child buffer is directly using the Memory of the parent buffer, and wants to prevent the parent buffer from being returned to a buffer pool until the Memory is available for re-use. (Since: 1.6)

Constructors

class Buffer
classmethod new() → Buffer

Creates a newly allocated buffer without any data.

classmethod new_allocate(allocator: Allocator | None, size: int, params: AllocationParams | None = None) → Buffer | None

Tries to create a newly allocated buffer with data of the given size and extra parameters from allocator. If the requested amount of memory can’t be allocated, None will be returned. The allocated buffer memory is not cleared.

When allocator is None, the default memory allocator will be used.

Note that when size == 0, the buffer will not have memory associated with it.

Parameters:

  • allocator – the Allocator to use, or None to use the default allocator

  • size – the size in bytes of the new buffer’s data.

  • params – optional parameters

classmethod new_memdup(data: Sequence[int]) → Buffer

Creates a new buffer of size size and fills it with a copy of data.

Added in version 1.20.

Parameters:

data – data to copy into new buffer

classmethod new_wrapped(data: Sequence[int]) → Buffer

Creates a new buffer that wraps the given data. The memory will be freed with free() and will be marked writable.

Parameters:

data – data to wrap

classmethod new_wrapped_bytes(bytes: Bytes) → Buffer

Creates a new Buffer that wraps the given bytes. The data inside bytes cannot be None and the resulting buffer will be marked as read only.

Added in version 1.16.

Parameters:

bytes – a Bytes to wrap

classmethod new_wrapped_full(flags: MemoryFlags, data: Sequence[int], maxsize: int, offset: int, user_data: None, notify: Callable[[...], None] | None = None) → Buffer

Allocates a new buffer that wraps the given memory. data must point to maxsize of memory, the wrapped buffer will have the region from offset and size visible.

When the buffer is destroyed, notify will be called with user_data.

The prefix/padding must be filled with 0 if flags contains GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED respectively.

Parameters:

  • flags – MemoryFlags

  • data – data to wrap

  • maxsize – allocated size of data

  • offset – offset in data

  • user_data – user_data

  • notify – called with user_data when the memory is freed

Methods

class Buffer
add_custom_meta(name: str) → CustomMeta | None

Creates and adds a CustomMeta for the desired name. name must have been successfully registered with register_custom().

Added in version 1.20.

Parameters:

name – the registered name of the desired custom meta

add_meta(info: MetaInfo, params: None) → Meta | None

Adds metadata for info to buffer using the parameters in params.

Parameters:

  • info – a MetaInfo

  • params – params for info

add_parent_buffer_meta(ref: Buffer) → ParentBufferMeta | None

Adds a ParentBufferMeta to buffer that holds a reference on ref until the buffer is freed.

Added in version 1.6.

Parameters:

ref – a Buffer to ref

add_protection_meta(info: Structure) → ProtectionMeta

Attaches protection metadata to a Buffer.

Added in version 1.6.

Parameters:

info – a Structure holding cryptographic information relating to the sample contained in buffer. This function takes ownership of info.

add_reference_timestamp_meta(reference: Caps, timestamp: int, duration: int) → ReferenceTimestampMeta | None

Adds a ReferenceTimestampMeta to buffer that holds a timestamp and optionally duration based on a specific timestamp reference. See the documentation of ReferenceTimestampMeta for details.

Added in version 1.14.

Parameters:

  • reference – identifier for the timestamp reference.

  • timestamp – timestamp

  • duration – duration, or CLOCK_TIME_NONE

append(buf2: Buffer) → Buffer

Appends all the memory from buf2 to buf1. The result buffer will contain a concatenation of the memory of buf1 and buf2.

Parameters:

buf2 – the second source Buffer to append.

append_memory(mem: Memory) → None

Appends the memory block mem to buffer. This function takes ownership of mem and thus doesn’t increase its refcount.

This function is identical to insert_memory() with an index of -1. See insert_memory() for more details.

Parameters:

mem – a Memory.

append_region(buf2: Buffer, offset: int, size: int) → Buffer

Appends size bytes at offset from buf2 to buf1. The result buffer will contain a concatenation of the memory of buf1 and the requested region of buf2.

Parameters:

  • buf2 – the second source Buffer to append.

  • offset – the offset in buf2

  • size – the size or -1 of buf2

extract(offset: int) → tuple[int, bytes]

Copies size bytes starting from offset in buffer to dest.

Parameters:

offset – the offset to extract

extract_dup(offset: int, size: int) → bytes

Extracts a copy of at most size bytes the data at offset into newly-allocated memory. dest must be freed using free() when done.

Added in version 1.0.10.

Parameters:

  • offset – the offset to extract

  • size – the size to extract

fill(offset: int, src: Sequence[int]) → int

Copies size bytes from src to buffer at offset.

Parameters:

  • offset – the offset to fill

  • src – the source address

find_memory(offset: int, size: int) → tuple[bool, int, int, int]

Finds the memory blocks that span size bytes starting from offset in buffer.

When this function returns True, idx will contain the index of the first memory block where the byte for offset can be found and length contains the number of memory blocks containing the size remaining bytes. skip contains the number of bytes to skip in the memory block at idx to get to the byte for offset.

size can be -1 to get all the memory blocks after idx.

Parameters:

  • offset – an offset

  • size – a size

foreach_meta(func: Callable[[...], tuple[bool, Meta]], *user_data: Any) → bool

Calls func with user_data for each meta in buffer.

func can modify the passed meta pointer or its contents. The return value of func defines if this function returns or if the remaining metadata items in the buffer should be skipped.

Parameters:

  • func – a BufferForeachMetaFunc to call

  • user_data – user data passed to func

get_all_memory() → Memory | None

Gets all the memory blocks in buffer. The memory blocks will be merged into one large Memory.

get_custom_meta(name: str) → CustomMeta | None

Finds the first CustomMeta on buffer for the desired name.

Added in version 1.20.

Parameters:

name – the registered name of the custom meta to retrieve.

get_flags() → BufferFlags

Gets the BufferFlags flags set on this buffer.

Added in version 1.10.

get_max_memory() → int

Gets the maximum amount of memory blocks that a buffer can hold. This is a compile time constant that can be queried with the function.

When more memory blocks are added, existing memory blocks will be merged together to make room for the new block.

Added in version 1.2.

get_memory(idx: int) → Memory | None

Gets the memory block at index idx in buffer.

Parameters:

idx – an index

get_memory_range(idx: int, length: int) → Memory | None

Gets length memory blocks in buffer starting at idx. The memory blocks will be merged into one large Memory.

If length is -1, all memory starting from idx is merged.

Parameters:

  • idx – an index

  • length – a length

get_meta(api: type) → Meta | None

Gets the metadata for api on buffer. When there is no such metadata, None is returned. If multiple metadata with the given api are attached to this buffer only the first one is returned. To handle multiple metadata with a given API use iterate_meta() or foreach_meta() instead and check the meta->info.api member for the API type.

Parameters:

api – the Type of an API

get_n_meta(api_type: type) → int

Added in version 1.14.

Parameters:

api_type – the Type of an API

get_reference_timestamp_meta(reference: Caps | None = None) → ReferenceTimestampMeta | None

Finds the first ReferenceTimestampMeta on buffer that conforms to reference. Conformance is tested by checking if the meta’s reference is a subset of reference.

Buffers can contain multiple ReferenceTimestampMeta metadata items.

Added in version 1.14.

Parameters:

reference – a reference Caps

get_size() → int

Gets the total size of the memory blocks in buffer.

get_sizes() → tuple[int, int, int]

Gets the total size of the memory blocks in buffer.

When not None, offset will contain the offset of the data in the first memory block in buffer and maxsize will contain the sum of the size and offset and the amount of extra padding on the last memory block. offset and maxsize can be used to resize the buffer memory blocks with resize().

get_sizes_range(idx: int, length: int) → tuple[int, int, int]

Gets the total size of length memory blocks stating from idx in buffer.

When not None, offset will contain the offset of the data in the memory block in buffer at idx and maxsize will contain the sum of the size and offset and the amount of extra padding on the memory block at idx + length -1. offset and maxsize can be used to resize the buffer memory blocks with resize_range().

Parameters:

  • idx – an index

  • length – a length

has_flags(flags: BufferFlags) → bool

Gives the status of a specific flag on a buffer.

Added in version 1.10.

Parameters:

flags – the BufferFlags flag to check.

insert_memory(idx: int, mem: Memory) → None

Inserts the memory block mem into buffer at idx. This function takes ownership of mem and thus doesn’t increase its refcount.

Only get_max_memory() can be added to a buffer. If more memory is added, existing memory blocks will automatically be merged to make room for the new memory.

Parameters:

  • idx – the index to add the memory at, or -1 to append it to the end

  • mem – a Memory.

is_all_memory_writable() → bool

Checks if all memory blocks in buffer are writable.

Note that this function does not check if buffer is writable, use buffer_is_writable() to check that if needed.

Added in version 1.4.

is_memory_range_writable(idx: int, length: int) → bool

Checks if length memory blocks in buffer starting from idx are writable.

length can be -1 to check all the memory blocks after idx.

Note that this function does not check if buffer is writable, use buffer_is_writable() to check that if needed.

Added in version 1.4.

Parameters:

  • idx – an index

  • length – a length, should not be 0

map(flags: MapFlags) → tuple[bool, MapInfo]

Fills info with the MapInfo of all merged memory blocks in buffer.

flags describe the desired access of the memory. When flags is GST_MAP_WRITE, buffer should be writable (as returned from buffer_is_writable()).

When buffer is writable but the memory isn’t, a writable copy will automatically be created and returned. The readonly copy of the buffer memory will then also be replaced with this writable copy.

The memory in info should be unmapped with unmap() after usage.

Parameters:

flags – flags for the mapping

map_range(idx: int, length: int, flags: MapFlags) → tuple[bool, MapInfo]

Fills info with the MapInfo of length merged memory blocks starting at idx in buffer. When length is -1, all memory blocks starting from idx are merged and mapped.

flags describe the desired access of the memory. When flags is GST_MAP_WRITE, buffer should be writable (as returned from buffer_is_writable()).

When buffer is writable but the memory isn’t, a writable copy will automatically be created and returned. The readonly copy of the buffer memory will then also be replaced with this writable copy.

The memory in info should be unmapped with unmap() after usage.

Parameters:

  • idx – an index

  • length – a length

  • flags – flags for the mapping

memcmp(offset: int, mem: Sequence[int]) → int

Compares size bytes starting from offset in buffer with the memory in mem.

Parameters:

  • offset – the offset in buffer

  • mem – the memory to compare

memset(offset: int, val: int, size: int) → int

Fills buf with size bytes with val starting from offset.

Parameters:

  • offset – the offset in buffer

  • val – the value to set

  • size – the size to set

n_memory() → int

Gets the amount of memory blocks that this buffer has. This amount is never larger than what get_max_memory() returns.

peek_memory(idx: int) → Memory | None

Gets the memory block at idx in buffer. The memory block stays valid until the memory block in buffer is removed, replaced or merged, typically with any call that modifies the memory in buffer.

Parameters:

idx – an index

prepend_memory(mem: Memory) → None

Prepends the memory block mem to buffer. This function takes ownership of mem and thus doesn’t increase its refcount.

This function is identical to insert_memory() with an index of 0. See insert_memory() for more details.

Parameters:

mem – a Memory.

remove_all_memory() → None

Removes all the memory blocks in buffer.

remove_memory(idx: int) → None

Removes the memory block in b at index i.

Parameters:

idx – an index

remove_memory_range(idx: int, length: int) → None

Removes length memory blocks in buffer starting from idx.

length can be -1, in which case all memory starting from idx is removed.

Parameters:

  • idx – an index

  • length – a length

remove_meta(meta: Meta) → bool

Removes the metadata for meta on buffer.

Parameters:

meta – a Meta

replace_all_memory(mem: Memory) → None

Replaces all memory in buffer with mem.

Parameters:

mem – a Memory

replace_memory(idx: int, mem: Memory) → None

Replaces the memory block at index idx in buffer with mem.

Parameters:

  • idx – an index

  • mem – a Memory

replace_memory_range(idx: int, length: int, mem: Memory) → None

Replaces length memory blocks in buffer starting at idx with mem.

If length is -1, all memory starting from idx will be removed and replaced with mem.

buffer should be writable.

Parameters:

  • idx – an index

  • length – a length, should not be 0

  • mem – a Memory

resize(offset: int, size: int) → None

Sets the offset and total size of the memory blocks in buffer.

Parameters:

  • offset – the offset adjustment

  • size – the new size or -1 to just adjust the offset

resize_range(idx: int, length: int, offset: int, size: int) → bool

Sets the total size of the length memory blocks starting at idx in buffer

Parameters:

  • idx – an index

  • length – a length

  • offset – the offset adjustment

  • size – the new size or -1 to just adjust the offset

set_flags(flags: BufferFlags) → bool

Sets one or more buffer flags on a buffer.

Added in version 1.10.

Parameters:

flags – the BufferFlags to set.

set_size(size: int) → None

Sets the total size of the memory blocks in buffer.

Parameters:

size – the new size

unmap(info: MapInfo) → None

Releases the memory previously mapped with map().

Parameters:

info – a MapInfo

unset_flags(flags: BufferFlags) → bool

Clears one or more buffer flags.

Added in version 1.10.

Parameters:

flags – the BufferFlags to clear

Fields

class Buffer
dts

Decoding timestamp of the buffer, can be GST_CLOCK_TIME_NONE when the dts is not known or relevant. The dts contains the timestamp when the media should be processed.

duration

Duration in time of the buffer data, can be GST_CLOCK_TIME_NONE when the duration is not known or relevant.

mini_object

The parent structure

offset

A media specific offset for the buffer data. For video frames, this is the frame number of this buffer. For audio samples, this is the offset of the first sample in this buffer. For file data or compressed data this is the byte offset of the first

byte in this buffer.

offset_end

The last offset contained in this buffer. It has the same format as offset.

pool

Pointer to the pool owner of the buffer

pts

Presentation timestamp of the buffer, can be GST_CLOCK_TIME_NONE when the pts is not known or relevant. The pts contains the timestamp when the media should be presented to the user.