Loading...
Searching...
No Matches
Bitstream filters
libavcodec

Bitstream filters transform encoded media data without decoding it. More...

## Data Structures

struct | AVBSFContext
| The bitstream filter state. More...
struct | AVBitStreamFilter

## Typedefs

typedef struct AVBSFList | AVBSFList
| Structure for chain/list of bitstream filters.

## Functions

const AVBitStreamFilter * | av_bsf_get_by_name (const char *name)
const AVBitStreamFilter * | av_bsf_iterate (void **opaque)
| Iterate over all registered bitstream filters.
int | av_bsf_alloc (const AVBitStreamFilter *filter, AVBSFContext **ctx)
| Allocate a context for a given bitstream filter.
int | av_bsf_init (AVBSFContext *ctx)
| Prepare the filter for use, after all the parameters and options have been set.
int | av_bsf_send_packet (AVBSFContext *ctx, AVPacket *pkt)
| Submit a packet for filtering.
int | av_bsf_receive_packet (AVBSFContext *ctx, AVPacket *pkt)
| Retrieve a filtered packet.
void | av_bsf_flush (AVBSFContext *ctx)
| Reset the internal bitstream filter state.
void | av_bsf_free (AVBSFContext **ctx)
| Free a bitstream filter context and everything associated with it; write NULL into the supplied pointer.
const AVClass * | av_bsf_get_class (void)
| Get the AVClass for AVBSFContext.
AVBSFList * | av_bsf_list_alloc (void)
| Allocate empty list of bitstream filters.
void | av_bsf_list_free (AVBSFList **lst)
| Free list of bitstream filters.
int | av_bsf_list_append (AVBSFList *lst, AVBSFContext *bsf)
| Append bitstream filter to the list of bitstream filters.
int | av_bsf_list_append2 (AVBSFList *lst, const char *bsf_name, AVDictionary **options)
| Construct new bitstream filter context given it's name and options and append it to the list of bitstream filters.
int | av_bsf_list_finalize (AVBSFList **lst, AVBSFContext **bsf)
| Finalize list of bitstream filters.
int | av_bsf_list_parse_str (const char *str, AVBSFContext **bsf)
| Parse string describing list of bitstream filters and create single AVBSFContext describing the whole chain of bitstream filters.
int | av_bsf_get_null_filter (AVBSFContext **bsf)
| Get null/pass-through bitstream filter.

## Detailed Description

Bitstream filters transform encoded media data without decoding it.

This allows e.g. manipulating various header values. Bitstream filters operate on AVPackets.

The bitstream filtering API is centered around two structures: AVBitStreamFilter and AVBSFContext. The former represents a bitstream filter in abstract, the latter a specific filtering process. Obtain an AVBitStreamFilter using av_bsf_get_by_name() or av_bsf_iterate(), then pass it to av_bsf_alloc() to create an AVBSFContext. Fill in the user-settable AVBSFContext fields, as described in its documentation, then call av_bsf_init() to prepare the filter context for use.

Submit packets for filtering using av_bsf_send_packet(), obtain filtered results with av_bsf_receive_packet(). When no more input packets will be sent, submit a NULL AVPacket to signal the end of the stream to the filter. av_bsf_receive_packet() will then return trailing packets, if any are produced by the filter.

Finally, free the filter context with av_bsf_free().

## Typedef Documentation

## AVBSFList

typedef struct AVBSFList AVBSFList

Structure for chain/list of bitstream filters.

Empty list can be allocated by av_bsf_list_alloc().

Definition at line 247 of file bsf.h.

## Function Documentation

## av_bsf_get_by_name()

const AVBitStreamFilter * av_bsf_get_by_name | ( | const char * | name | ) |

Returns
  a bitstream filter with the specified name or NULL if no such bitstream filter exists.

## av_bsf_iterate()

const AVBitStreamFilter * av_bsf_iterate | ( | void ** | opaque | ) |

Iterate over all registered bitstream filters.

Parameters

  opaque | a pointer where libavcodec will store the iteration state. Must point to NULL to start the iteration.

Returns
  the next registered bitstream filter or NULL when the iteration is finished

## av_bsf_alloc()

int av_bsf_alloc | ( | const AVBitStreamFilter * | filter,
|  | AVBSFContext ** | ctx )

Allocate a context for a given bitstream filter.

The caller must fill in the context parameters as described in the documentation and then call av_bsf_init() before sending any data to the filter.

Parameters

  | filter | the filter for which to allocate an instance.
  [out] | ctx | a pointer into which the pointer to the newly-allocated context will be written. It must be freed with av_bsf_free() after the filtering is done.

Returns
  0 on success, a negative AVERROR code on failure

## av_bsf_init()

int av_bsf_init | ( | AVBSFContext * | ctx | ) |

Prepare the filter for use, after all the parameters and options have been set.

Parameters

  ctx | a AVBSFContext previously allocated with av_bsf_alloc()

## av_bsf_send_packet()

int av_bsf_send_packet | ( | AVBSFContext * | ctx,
|  | AVPacket * | pkt )

Submit a packet for filtering.

After sending each packet, the filter must be completely drained by calling av_bsf_receive_packet() repeatedly until it returns AVERROR(EAGAIN) or AVERROR_EOF.

Parameters

  ctx | an initialized AVBSFContext

  pkt

  the packet to filter. The bitstream filter will take ownership of the packet and reset the contents of pkt. pkt is not touched if an error occurs. If pkt is empty (i.e. NULL, or pkt->data is NULL and pkt->side_data_elems zero), it signals the end of the stream (i.e. no more non-empty packets will be sent; sending more empty packets does nothing) and will cause the filter to output any packets it may have buffered internally.

Returns
  - 0 on success.
  - AVERROR(EAGAIN) if packets need to be retrieved from the filter (using av_bsf_receive_packet()) before new input can be consumed.
  - Another negative AVERROR value if an error occurs.

## av_bsf_receive_packet()

int av_bsf_receive_packet | ( | AVBSFContext * | ctx,
|  | AVPacket * | pkt )

Retrieve a filtered packet.

Parameters

  | ctx | an initialized AVBSFContext

  [out]

  pkt

  this struct will be filled with the contents of the filtered packet. It is owned by the caller and must be freed using av_packet_unref() when it is no longer needed. This parameter should be "clean" (i.e. freshly allocated with av_packet_alloc() or unreffed with av_packet_unref()) when this function is called. If this function returns successfully, the contents of pkt will be completely overwritten by the returned data. On failure, pkt is not touched.

Returns
  - 0 on success.
  - AVERROR(EAGAIN) if more packets need to be sent to the filter (using av_bsf_send_packet()) to get more output.
  - AVERROR_EOF if there will be no further output from the filter.
  - Another negative AVERROR value if an error occurs.

Note
  one input packet may result in several output packets, so after sending a packet with av_bsf_send_packet(), this function needs to be called repeatedly until it stops returning 0. It is also possible for a filter to output fewer packets than were sent to it, so this function may return AVERROR(EAGAIN) immediately after a successful av_bsf_send_packet() call.

## av_bsf_flush()

void av_bsf_flush | ( | AVBSFContext * | ctx | ) |

Reset the internal bitstream filter state.

Should be called e.g. when seeking.

## av_bsf_free()

void av_bsf_free | ( | AVBSFContext ** | ctx | ) |

Free a bitstream filter context and everything associated with it; write NULL into the supplied pointer.

## av_bsf_get_class()

const AVClass * av_bsf_get_class | ( | void |  | ) |

Get the AVClass for AVBSFContext.

It can be used in combination with AV_OPT_SEARCH_FAKE_OBJ for examining options.

See also
  av_opt_find().

## av_bsf_list_alloc()

AVBSFList * av_bsf_list_alloc | ( | void |  | ) |

Allocate empty list of bitstream filters.

The list must be later freed by av_bsf_list_free() or finalized by av_bsf_list_finalize().

Returns
  Pointer to AVBSFList on success, NULL in case of failure

## av_bsf_list_free()

void av_bsf_list_free | ( | AVBSFList ** | lst | ) |

Free list of bitstream filters.

Parameters

  lst | Pointer to pointer returned by av_bsf_list_alloc()

## av_bsf_list_append()

int av_bsf_list_append | ( | AVBSFList * | lst,
|  | AVBSFContext * | bsf )

Append bitstream filter to the list of bitstream filters.

Parameters

  lst | List to append to
  bsf | Filter context to be appended

Returns
  >=0 on success, negative AVERROR in case of failure

## av_bsf_list_append2()

int av_bsf_list_append2 | ( | AVBSFList * | lst,
|  | const char * | bsf_name,
|  | AVDictionary ** | options )

Construct new bitstream filter context given it's name and options and append it to the list of bitstream filters.

Parameters

  lst | List to append to
  bsf_name | Name of the bitstream filter
  options | Options for the bitstream filter, can be set to NULL

Returns
  >=0 on success, negative AVERROR in case of failure

## av_bsf_list_finalize()

int av_bsf_list_finalize | ( | AVBSFList ** | lst,
|  | AVBSFContext ** | bsf )

Finalize list of bitstream filters.

This function will transform AVBSFList to single AVBSFContext, so the whole chain of bitstream filters can be treated as single filter freshly allocated by av_bsf_alloc(). If the call is successful, AVBSFList structure is freed and lst will be set to NULL. In case of failure, caller is responsible for freeing the structure by av_bsf_list_free()

Parameters

  | lst | Filter list structure to be transformed
  [out] | bsf | Pointer to be set to newly created AVBSFContext structure representing the chain of bitstream filters

Returns
  >=0 on success, negative AVERROR in case of failure

## av_bsf_list_parse_str()

int av_bsf_list_parse_str | ( | const char * | str,
|  | AVBSFContext ** | bsf )

Parse string describing list of bitstream filters and create single AVBSFContext describing the whole chain of bitstream filters.

Resulting AVBSFContext can be treated as any other AVBSFContext freshly allocated by av_bsf_alloc().

Parameters

  | str | String describing chain of bitstream filters in format bsf1[=opt1=val1:opt2=val2][,bsf2]
  [out] | bsf | Pointer to be set to newly created AVBSFContext structure representing the chain of bitstream filters

Returns
  >=0 on success, negative AVERROR in case of failure

## av_bsf_get_null_filter()

int av_bsf_get_null_filter | ( | AVBSFContext ** | bsf | ) |

Get null/pass-through bitstream filter.

Parameters

  [out] | bsf | Pointer to be set to new instance of pass-through bitstream filter

Returns