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: list[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: list[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: list[int], maxsize: int, offset: int, user_data: Any = None, notify: Callable[[Any], 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: Any = 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, list[int]]#

Copies size bytes starting from offset in buffer to dest.

Parameters:

offset – the offset to extract

extract_dup(offset: int, size: int) → list[int]#

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: list[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[[Buffer, Any], Tuple[bool, Meta | None]], user_data: Any = None) → 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.

classmethod 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: GType) → 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: GType) → 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: list[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.