FFmpeg
Data Structures | Functions
Bitstream filters

Data Structures

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

Functions

const AVBitStreamFilterav_bsf_get_by_name (const char *name)
 
const AVBitStreamFilterav_bsf_iterate (void **opaque)
 Iterate over all registered bitstream filters. More...
 
int av_bsf_alloc (const AVBitStreamFilter *filter, AVBSFContext **ctx)
 Allocate a context for a given bitstream filter. More...
 
int av_bsf_init (AVBSFContext *ctx)
 Prepare the filter for use, after all the parameters and options have been set. More...
 
int av_bsf_send_packet (AVBSFContext *ctx, AVPacket *pkt)
 Submit a packet for filtering. More...
 
int av_bsf_receive_packet (AVBSFContext *ctx, AVPacket *pkt)
 Retrieve a filtered packet. More...
 
void av_bsf_flush (AVBSFContext *ctx)
 Reset the internal bitstream filter state. More...
 
void av_bsf_free (AVBSFContext **ctx)
 Free a bitstream filter context and everything associated with it; write NULL into the supplied pointer. More...
 
const AVClassav_bsf_get_class (void)
 Get the AVClass for AVBSFContext. More...
 
AVBSFListav_bsf_list_alloc (void)
 Allocate empty list of bitstream filters. More...
 
void av_bsf_list_free (AVBSFList **lst)
 Free list of bitstream filters. More...
 
int av_bsf_list_append (AVBSFList *lst, AVBSFContext *bsf)
 Append bitstream filter to the list of bitstream filters. More...
 
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. More...
 
int av_bsf_list_finalize (AVBSFList **lst, AVBSFContext **bsf)
 Finalize list of bitstream filters. More...
 
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. More...
 
int av_bsf_get_null_filter (AVBSFContext **bsf)
 Get null/pass-through bitstream filter. More...
 

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().

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.

Definition at line 81 of file bitstream_filters.c.

Referenced by aom_init(), av1_read_header(), bsf_list_append_internal(), detect_stream_specific(), extract_extradata_check(), extract_extradata_init(), ff_stream_add_bitstream_filter(), librav1e_encode_init(), and show_help_bsf().

◆ av_bsf_iterate()

const AVBitStreamFilter* av_bsf_iterate ( void **  opaque)

Iterate over all registered bitstream filters.

Parameters
opaquea 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

Definition at line 69 of file bitstream_filters.c.

Referenced by av_bsf_get_by_name(), ff_bsf_child_class_iterate(), and show_bsfs().

◆ 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
filterthe filter for which to allocate an instance.
[out]ctxa 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

Definition at line 105 of file bsf.c.

Referenced by aom_init(), av1_read_header(), av_bsf_get_null_filter(), av_bsf_list_finalize(), bsf_list_append_internal(), detect_stream_specific(), extract_extradata_init(), ff_stream_add_bitstream_filter(), librav1e_encode_init(), and LLVMFuzzerTestOneInput().

◆ av_bsf_init()

int av_bsf_init ( AVBSFContext ctx)

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

Definition at line 150 of file bsf.c.

Referenced by aom_init(), av1_read_header(), bsf_list_init(), decode_bsfs_init(), detect_stream_specific(), extract_extradata_init(), ff_stream_add_bitstream_filter(), init_output_bsfs(), librav1e_encode_init(), LLVMFuzzerTestOneInput(), and open_slave().

◆ 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
pktthe 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.

Definition at line 203 of file bsf.c.

Referenced by avcodec_send_packet(), bsf_list_filter(), extract_extradata(), filter_packet(), librav1e_receive_packet(), LLVMFuzzerTestOneInput(), output_packet(), storeframe(), tee_write_packet(), and write_packets_from_bsfs().

◆ av_bsf_receive_packet()

int av_bsf_receive_packet ( AVBSFContext ctx,
AVPacket pkt 
)

Retrieve a filtered packet.

Parameters
[out]pktthis 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.

Definition at line 231 of file bsf.c.

Referenced by bsf_list_filter(), extract_extradata(), ff_decode_get_packet(), filter_packet(), librav1e_receive_packet(), LLVMFuzzerTestOneInput(), output_packet(), storeframe(), tee_write_packet(), and write_packets_from_bsfs().

◆ av_bsf_flush()

void av_bsf_flush ( AVBSFContext ctx)

Reset the internal bitstream filter state.

Should be called e.g. when seeking.

Definition at line 191 of file bsf.c.

Referenced by avcodec_flush_buffers(), bsf_list_flush(), and LLVMFuzzerTestOneInput().

◆ av_bsf_free()

void av_bsf_free ( AVBSFContext **  ctx)

◆ 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().

Definition at line 100 of file bsf.c.

Referenced by show_help_default().

◆ 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

Definition at line 421 of file bsf.c.

Referenced by av_bsf_list_parse_str().

◆ av_bsf_list_free()

void av_bsf_list_free ( AVBSFList **  lst)

Free list of bitstream filters.

Parameters
lstPointer to pointer returned by av_bsf_list_alloc()

Definition at line 426 of file bsf.c.

Referenced by av_bsf_list_parse_str().

◆ av_bsf_list_append()

int av_bsf_list_append ( AVBSFList lst,
AVBSFContext bsf 
)

Append bitstream filter to the list of bitstream filters.

Parameters
lstList to append to
bsfFilter context to be appended
Returns
>=0 on success, negative AVERROR in case of failure

Definition at line 439 of file bsf.c.

Referenced by bsf_list_append_internal().

◆ 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
lstList to append to
bsf_nameName of the bitstream filter
optionsOptions for the bitstream filter, can be set to NULL
Returns
>=0 on success, negative AVERROR in case of failure

Definition at line 485 of file bsf.c.

◆ 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
lstFilter list structure to be transformed
[out]bsfPointer to be set to newly created AVBSFContext structure representing the chain of bitstream filters
Returns
>=0 on success, negative AVERROR in case of failure

Definition at line 490 of file bsf.c.

Referenced by av_bsf_list_parse_str().

◆ 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
strString describing chain of bitstream filters in format bsf1[=opt1=val1:opt2=val2][,bsf2]
[out]bsfPointer to be set to newly created AVBSFContext structure representing the chain of bitstream filters
Returns
>=0 on success, negative AVERROR in case of failure

Definition at line 527 of file bsf.c.

Referenced by decode_bsfs_init(), new_output_stream(), and open_slave().

◆ av_bsf_get_null_filter()

int av_bsf_get_null_filter ( AVBSFContext **  bsf)

Get null/pass-through bitstream filter.

Parameters
[out]bsfPointer to be set to new instance of pass-through bitstream filter
Returns

Definition at line 554 of file bsf.c.

Referenced by av_bsf_list_parse_str(), LLVMFuzzerTestOneInput(), and open_slave().