Gst.Buffer

Fields

Name

Type

Access

Description

dts

int

r/w

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

int

r/w

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

mini_object

Gst.MiniObject

r/w

the parent structure

offset

int

r/w

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

int

r/w

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

pool

Gst.BufferPool

r/w

pointer to the pool owner of the buffer

pts

int

r/w

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.

Methods

class

get_max_memory ()

class

new ()

class

new_allocate (allocator, size, params)

class

new_memdup (data)

class

new_wrapped (data)

class

new_wrapped_bytes (bytes)

class

new_wrapped_full (flags, data, maxsize, offset, user_data, notify)

add_custom_meta (name)

add_meta (info, params)

add_parent_buffer_meta (ref)

add_protection_meta (info)

add_reference_timestamp_meta (reference, timestamp, duration)

append (buf2)

append_memory (mem)

append_region (buf2, offset, size)

copy_deep ()

copy_into (src, flags, offset, size)

copy_region (flags, offset, size)

extract (offset)

extract_dup (offset, size)

fill (offset, src)

find_memory (offset, size)

foreach_meta (func, *user_data)

get_all_memory ()

get_custom_meta (name)

get_flags ()

get_memory (idx)

get_memory_range (idx, length)

get_meta (api)

get_n_meta (api_type)

get_reference_timestamp_meta (reference)

get_size ()

get_sizes ()

get_sizes_range (idx, length)

has_flags (flags)

insert_memory (idx, mem)

is_all_memory_writable ()

is_memory_range_writable (idx, length)

map (flags)

map_range (idx, length, flags)

memcmp (offset, mem)

memset (offset, val, size)

n_memory ()

peek_memory (idx)

prepend_memory (mem)

remove_all_memory ()

remove_memory (idx)

remove_memory_range (idx, length)

remove_meta (meta)

replace_all_memory (mem)

replace_memory (idx, mem)

replace_memory_range (idx, length, mem)

resize (offset, size)

resize_range (idx, length, offset, size)

set_flags (flags)

set_size (size)

unmap (info)

unset_flags (flags)

Details

class Gst.Buffer

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 Gst.Memory blocks that the buffer contains.

Buffers are usually created with Gst.Buffer.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.

`` C

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 Gst.Buffer.new_allocate() to create a buffer with preallocated data of a given size.

Buffers can contain a list of Gst.Memory objects. You can retrieve how many memory objects with Gst.Buffer.n_memory() and you can get a pointer to memory with Gst.Buffer.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 #GstClockTime 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 Gst.Buffer.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 gst_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 GST_BUFFER_FLAG_SET() and GST_BUFFER_FLAG_UNSET() macros. Use GST_BUFFER_FLAG_IS_SET() to test if a certain Gst.BufferFlags flag is set.

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

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

An element should either unref the buffer or push it out on a src pad using Gst.Pad.push() (see Gst.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 Gst.BufferPool will be returned to the pool when the refcount drops to 0.

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

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

New in version 1.6.

classmethod get_max_memory()[source]
Returns:

the maximum amount of memory blocks that a buffer can hold.

Return type:

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.

New in version 1.2.

classmethod new()[source]
Returns:

the new Gst.Buffer.

Return type:

Gst.Buffer

Creates a newly allocated buffer without any data.

classmethod new_allocate(allocator, size, params)[source]
Parameters:
Returns:

a new Gst.Buffer

Return type:

Gst.Buffer or 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.

classmethod new_memdup(data)[source]
Parameters:

data (bytes) – data to copy into new buffer

Returns:

a new Gst.Buffer

Return type:

Gst.Buffer

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

New in version 1.20.

classmethod new_wrapped(data)[source]
Parameters:

data (bytes) – data to wrap

Returns:

a new Gst.Buffer

Return type:

Gst.Buffer

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

classmethod new_wrapped_bytes(bytes)[source]
Parameters:

bytes (GLib.Bytes) – a GLib.Bytes to wrap

Returns:

a new Gst.Buffer wrapping bytes

Return type:

Gst.Buffer

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

New in version 1.16.

classmethod new_wrapped_full(flags, data, maxsize, offset, user_data, notify)[source]
Parameters:
Returns:

a new Gst.Buffer

Return type:

Gst.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.MemoryFlags.ZERO_PREFIXED and Gst.MemoryFlags.ZERO_PADDED respectively.

add_custom_meta(name)[source]
Parameters:

name (str) – the registered name of the desired custom meta

Returns:

The Gst.CustomMeta that was added to the buffer

Return type:

Gst.CustomMeta or None

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

New in version 1.20.

add_meta(info, params)[source]
Parameters:
Returns:

the metadata for the api in info on self.

Return type:

Gst.Meta or None

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

add_parent_buffer_meta(ref)[source]
Parameters:

ref (Gst.Buffer) – a Gst.Buffer to ref

Returns:

The Gst.ParentBufferMeta that was added to the buffer

Return type:

Gst.ParentBufferMeta or None

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

New in version 1.6.

add_protection_meta(info)[source]
Parameters:

info (Gst.Structure) – a Gst.Structure holding cryptographic information relating to the sample contained in self. This function takes ownership of info.

Returns:

a pointer to the added Gst.ProtectionMeta if successful

Return type:

Gst.ProtectionMeta

Attaches protection metadata to a Gst.Buffer.

New in version 1.6.

add_reference_timestamp_meta(reference, timestamp, duration)[source]
Parameters:
Returns:

The Gst.ReferenceTimestampMeta that was added to the buffer

Return type:

Gst.ReferenceTimestampMeta or None

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

New in version 1.14.

append(buf2)[source]
Parameters:

buf2 (Gst.Buffer) – the second source Gst.Buffer to append.

Returns:

the new Gst.Buffer that contains the memory of the two source buffers.

Return type:

Gst.Buffer

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

append_memory(mem)[source]
Parameters:

mem (Gst.Memory) – a Gst.Memory.

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

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

append_region(buf2, offset, size)[source]
Parameters:
  • buf2 (Gst.Buffer) – the second source Gst.Buffer to append.

  • offset (int) – the offset in buf2

  • size (int) – the size or -1 of buf2

Returns:

the new Gst.Buffer that contains the memory of the two source buffers.

Return type:

Gst.Buffer

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

copy_deep()[source]
Returns:

a new copy of self if the copy succeeded, None otherwise.

Return type:

Gst.Buffer or None

Creates a copy of the given buffer. This will make a newly allocated copy of the data the source buffer contains.

New in version 1.6.

copy_into(src, flags, offset, size)[source]
Parameters:
  • src (Gst.Buffer) – a source Gst.Buffer

  • flags (Gst.BufferCopyFlags) – flags indicating what metadata fields should be copied.

  • offset (int) – offset to copy from

  • size (int) – total size to copy. If -1, all data is copied.

Returns:

True if the copying succeeded, False otherwise.

Return type:

bool

Copies the information from src into self.

If self already contains memory and flags contains Gst.BufferCopyFlags.MEMORY, the memory from src will be appended to self.

flags indicate which fields will be copied.

copy_region(flags, offset, size)[source]
Parameters:
Returns:

the new Gst.Buffer or None if copying failed.

Return type:

Gst.Buffer or None

Creates a sub-buffer from self at offset and size. This sub-buffer uses the actual memory space of the parent buffer. This function will copy the offset and timestamp fields when the offset is 0. If not, they will be set to Gst.CLOCK_TIME_NONE and Gst.BUFFER_OFFSET_NONE. If offset equals 0 and size equals the total size of buffer, the duration and offset end fields are also copied. If not they will be set to Gst.CLOCK_TIME_NONE and Gst.BUFFER_OFFSET_NONE.

extract(offset)[source]
Parameters:

offset (int) – the offset to extract

Returns:

The amount of bytes extracted. This value can be lower than size when self did not contain enough data.

dest:

the destination address

Return type:

(int, dest: bytes)

Copies size bytes starting from offset in self to dest.

extract_dup(offset, size)[source]
Parameters:
  • offset (int) – the offset to extract

  • size (int) – the size to extract

Returns:

A pointer where the destination array will be written. Might be None if the size is 0.

Return type:

dest: bytes

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

New in version 1.0.10.

fill(offset, src)[source]
Parameters:
  • offset (int) – the offset to fill

  • src (bytes) – the source address

Returns:

The amount of bytes copied. This value can be lower than size when self did not contain enough data.

Return type:

int

Copies size bytes from src to self at offset.

find_memory(offset, size)[source]
Parameters:
  • offset (int) – an offset

  • size (int) – a size

Returns:

True when size bytes starting from offset could be found in self and idx, length and skip will be filled.

idx:

pointer to index

length:

pointer to length

skip:

pointer to skip

Return type:

(bool, idx: int, length: int, skip: int)

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

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.

foreach_meta(func, *user_data)[source]
Parameters:
Returns:

False when func returned False for one of the metadata.

Return type:

bool

Calls func with user_data for each meta in self.

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.

get_all_memory()[source]
Returns:

a Gst.Memory that contains the merged memory.

Return type:

Gst.Memory or None

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

get_custom_meta(name)[source]
Parameters:

name (str) – the registered name of the custom meta to retrieve.

Returns:

the Gst.CustomMeta

Return type:

Gst.CustomMeta or None

Finds the first Gst.CustomMeta on self for the desired name.

New in version 1.20.

get_flags()[source]
Returns:

the flags set on this buffer.

Return type:

Gst.BufferFlags

Gets the Gst.BufferFlags flags set on this buffer.

New in version 1.10.

get_memory(idx)[source]
Parameters:

idx (int) – an index

Returns:

a Gst.Memory that contains the data of the memory block at idx.

Return type:

Gst.Memory or None

Gets the memory block at index idx in self.

get_memory_range(idx, length)[source]
Parameters:
  • idx (int) – an index

  • length (int) – a length

Returns:

a Gst.Memory that contains the merged data of length blocks starting at idx.

Return type:

Gst.Memory or None

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

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

get_meta(api)[source]
Parameters:

api (GObject.GType) – the GObject.GType of an API

Returns:

the metadata for api on self.

Return type:

Gst.Meta or 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 gst_buffer_iterate_meta() or Gst.Buffer.foreach_meta() instead and check the meta->info.api member for the API type.

get_n_meta(api_type)[source]
Parameters:

api_type (GObject.GType) – the GObject.GType of an API

Returns:

number of metas of type api_type on self.

Return type:

int

New in version 1.14.

get_reference_timestamp_meta(reference)[source]
Parameters:

reference (Gst.Caps or None) – a reference Gst.Caps

Returns:

the Gst.ReferenceTimestampMeta or None when there is no such metadata on self.

Return type:

Gst.ReferenceTimestampMeta or None

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

Buffers can contain multiple Gst.ReferenceTimestampMeta metadata items.

New in version 1.14.

get_size()[source]
Returns:

total size of the memory blocks in self.

Return type:

int

Gets the total size of the memory blocks in self.

get_sizes()[source]
Returns:

total size of the memory blocks in self.

offset:

a pointer to the offset

maxsize:

a pointer to the maxsize

Return type:

(int, offset: int, maxsize: int)

Gets the total size of the memory blocks in self.

When not None, offset will contain the offset of the data in the first memory block in self 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 Gst.Buffer.resize().

get_sizes_range(idx, length)[source]
Parameters:
  • idx (int) – an index

  • length (int) – a length

Returns:

total size of length memory blocks starting at idx in self.

offset:

a pointer to the offset

maxsize:

a pointer to the maxsize

Return type:

(int, offset: int, maxsize: int)

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

When not None, offset will contain the offset of the data in the memory block in self 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 Gst.Buffer.resize_range().

has_flags(flags)[source]
Parameters:

flags (Gst.BufferFlags) – the Gst.BufferFlags flag to check.

Returns:

True if all flags in flags are found on self.

Return type:

bool

Gives the status of a specific flag on a buffer.

New in version 1.10.

insert_memory(idx, mem)[source]
Parameters:

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

Only Gst.Buffer.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.

is_all_memory_writable()[source]
Returns:

True if all memory blocks in self are writable

Return type:

bool

Checks if all memory blocks in self are writable.

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

New in version 1.4.

is_memory_range_writable(idx, length)[source]
Parameters:
  • idx (int) – an index

  • length (int) – a length, should not be 0

Returns:

True if the memory range is writable

Return type:

bool

Checks if length memory blocks in self 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 self is writable, use gst_buffer_is_writable() to check that if needed.

New in version 1.4.

map(flags)[source]
Parameters:

flags (Gst.MapFlags) – flags for the mapping

Returns:

True if the map succeeded and info contains valid data.

info:

info about the mapping

Return type:

(bool, info: Gst.MapInfo)

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

flags describe the desired access of the memory. When flags is Gst.MapFlags.WRITE, self should be writable (as returned from gst_buffer_is_writable()).

When self 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 Gst.Buffer.unmap() after usage.

map_range(idx, length, flags)[source]
Parameters:
  • idx (int) – an index

  • length (int) – a length

  • flags (Gst.MapFlags) – flags for the mapping

Returns:

True if the map succeeded and info contains valid data.

info:

info about the mapping

Return type:

(bool, info: Gst.MapInfo)

Fills info with the Gst.MapInfo of length merged memory blocks starting at idx in self. 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.MapFlags.WRITE, self should be writable (as returned from gst_buffer_is_writable()).

When self 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 Gst.Buffer.unmap() after usage.

memcmp(offset, mem)[source]
Parameters:
  • offset (int) – the offset in self

  • mem (bytes) – the memory to compare

Returns:

0 if the memory is equal.

Return type:

int

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

memset(offset, val, size)[source]
Parameters:
  • offset (int) – the offset in self

  • val (int) – the value to set

  • size (int) – the size to set

Returns:

The amount of bytes filled. This value can be lower than size when self did not contain enough data.

Return type:

int

Fills buf with size bytes with val starting from offset.

n_memory()[source]
Returns:

the number of memory blocks this buffer is made of.

Return type:

int

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

peek_memory(idx)[source]
Parameters:

idx (int) – an index

Returns:

the Gst.Memory at idx.

Return type:

Gst.Memory or None

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

prepend_memory(mem)[source]
Parameters:

mem (Gst.Memory) – a Gst.Memory.

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

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

remove_all_memory()[source]

Removes all the memory blocks in self.

remove_memory(idx)[source]
Parameters:

idx (int) – an index

Removes the memory block in b at index i.

remove_memory_range(idx, length)[source]
Parameters:
  • idx (int) – an index

  • length (int) – a length

Removes length memory blocks in self starting from idx.

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

remove_meta(meta)[source]
Parameters:

meta (Gst.Meta) – a Gst.Meta

Returns:

True if the metadata existed and was removed, False if no such metadata was on self.

Return type:

bool

Removes the metadata for meta on self.

replace_all_memory(mem)[source]
Parameters:

mem (Gst.Memory) – a Gst.Memory

Replaces all memory in self with mem.

replace_memory(idx, mem)[source]
Parameters:

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

replace_memory_range(idx, length, mem)[source]
Parameters:

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

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

self should be writable.

resize(offset, size)[source]
Parameters:
  • offset (int) – the offset adjustment

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

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

resize_range(idx, length, offset, size)[source]
Parameters:
  • idx (int) – an index

  • length (int) – a length

  • offset (int) – the offset adjustment

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

Returns:

True if resizing succeeded, False otherwise.

Return type:

bool

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

set_flags(flags)[source]
Parameters:

flags (Gst.BufferFlags) – the Gst.BufferFlags to set.

Returns:

True if flags were successfully set on buffer.

Return type:

bool

Sets one or more buffer flags on a buffer.

New in version 1.10.

set_size(size)[source]
Parameters:

size (int) – the new size

Sets the total size of the memory blocks in self.

unmap(info)[source]
Parameters:

info (Gst.MapInfo) – a Gst.MapInfo

Releases the memory previously mapped with Gst.Buffer.map().

unset_flags(flags)[source]
Parameters:

flags (Gst.BufferFlags) – the Gst.BufferFlags to clear

Returns:

true if flags is successfully cleared from buffer.

Return type:

bool

Clears one or more buffer flags.

New in version 1.10.