FFmpeg 5.1.6
bsf.h
Go to the documentation of this file.
1/*
2 * Bitstream filters public API
3 *
4 * This file is part of FFmpeg.
5 *
6 * FFmpeg is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * FFmpeg is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with FFmpeg; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19 */
20
21#ifndef AVCODEC_BSF_H
22#define AVCODEC_BSF_H
23
24#include "libavutil/dict.h"
25#include "libavutil/log.h"
26#include "libavutil/rational.h"
27
28#include "codec_id.h"
29#include "codec_par.h"
30#include "packet.h"
31
32/**
33 * @defgroup lavc_bsf Bitstream filters
34 * @ingroup libavc
35 *
36 * Bitstream filters transform encoded media data without decoding it. This
37 * allows e.g. manipulating various header values. Bitstream filters operate on
38 * @ref AVPacket "AVPackets".
39 *
40 * The bitstream filtering API is centered around two structures:
41 * AVBitStreamFilter and AVBSFContext. The former represents a bitstream filter
42 * in abstract, the latter a specific filtering process. Obtain an
43 * AVBitStreamFilter using av_bsf_get_by_name() or av_bsf_iterate(), then pass
44 * it to av_bsf_alloc() to create an AVBSFContext. Fill in the user-settable
45 * AVBSFContext fields, as described in its documentation, then call
46 * av_bsf_init() to prepare the filter context for use.
47 *
48 * Submit packets for filtering using av_bsf_send_packet(), obtain filtered
49 * results with av_bsf_receive_packet(). When no more input packets will be
50 * sent, submit a NULL AVPacket to signal the end of the stream to the filter.
51 * av_bsf_receive_packet() will then return trailing packets, if any are
52 * produced by the filter.
53 *
54 * Finally, free the filter context with av_bsf_free().
55 * @{
56 */
57
58/**
59 * The bitstream filter state.
60 *
61 * This struct must be allocated with av_bsf_alloc() and freed with
62 * av_bsf_free().
63 *
64 * The fields in the struct will only be changed (by the caller or by the
65 * filter) as described in their documentation, and are to be considered
66 * immutable otherwise.
67 */
68typedef struct AVBSFContext {
69 /**
70 * A class for logging and AVOptions
71 */
73
74 /**
75 * The bitstream filter this context is an instance of.
76 */
78
79 /**
80 * Opaque filter-specific private data. If filter->priv_class is non-NULL,
81 * this is an AVOptions-enabled struct.
82 */
83 void *priv_data;
84
85 /**
86 * Parameters of the input stream. This field is allocated in
87 * av_bsf_alloc(), it needs to be filled by the caller before
88 * av_bsf_init().
89 */
91
92 /**
93 * Parameters of the output stream. This field is allocated in
94 * av_bsf_alloc(), it is set by the filter in av_bsf_init().
95 */
97
98 /**
99 * The timebase used for the timestamps of the input packets. Set by the
100 * caller before av_bsf_init().
101 */
103
104 /**
105 * The timebase used for the timestamps of the output packets. Set by the
106 * filter in av_bsf_init().
107 */
110
111typedef struct AVBitStreamFilter {
112 const char *name;
113
114 /**
115 * A list of codec ids supported by the filter, terminated by
116 * AV_CODEC_ID_NONE.
117 * May be NULL, in that case the bitstream filter works with any codec id.
118 */
119 const enum AVCodecID *codec_ids;
120
121 /**
122 * A class for the private data, used to declare bitstream filter private
123 * AVOptions. This field is NULL for bitstream filters that do not declare
124 * any options.
125 *
126 * If this field is non-NULL, the first member of the filter private data
127 * must be a pointer to AVClass, which will be set by libavcodec generic
128 * code to this class.
129 */
132
133/**
134 * @return a bitstream filter with the specified name or NULL if no such
135 * bitstream filter exists.
136 */
137const AVBitStreamFilter *av_bsf_get_by_name(const char *name);
138
139/**
140 * Iterate over all registered bitstream filters.
141 *
142 * @param opaque a pointer where libavcodec will store the iteration state. Must
143 * point to NULL to start the iteration.
144 *
145 * @return the next registered bitstream filter or NULL when the iteration is
146 * finished
147 */
148const AVBitStreamFilter *av_bsf_iterate(void **opaque);
149
150/**
151 * Allocate a context for a given bitstream filter. The caller must fill in the
152 * context parameters as described in the documentation and then call
153 * av_bsf_init() before sending any data to the filter.
154 *
155 * @param filter the filter for which to allocate an instance.
156 * @param[out] ctx a pointer into which the pointer to the newly-allocated context
157 * will be written. It must be freed with av_bsf_free() after the
158 * filtering is done.
159 *
160 * @return 0 on success, a negative AVERROR code on failure
161 */
163
164/**
165 * Prepare the filter for use, after all the parameters and options have been
166 * set.
167 */
169
170/**
171 * Submit a packet for filtering.
172 *
173 * After sending each packet, the filter must be completely drained by calling
174 * av_bsf_receive_packet() repeatedly until it returns AVERROR(EAGAIN) or
175 * AVERROR_EOF.
176 *
177 * @param pkt the packet to filter. The bitstream filter will take ownership of
178 * the packet and reset the contents of pkt. pkt is not touched if an error occurs.
179 * If pkt is empty (i.e. NULL, or pkt->data is NULL and pkt->side_data_elems zero),
180 * it signals the end of the stream (i.e. no more non-empty packets will be sent;
181 * sending more empty packets does nothing) and will cause the filter to output
182 * any packets it may have buffered internally.
183 *
184 * @return
185 * - 0 on success.
186 * - AVERROR(EAGAIN) if packets need to be retrieved from the filter (using
187 * av_bsf_receive_packet()) before new input can be consumed.
188 * - Another negative AVERROR value if an error occurs.
189 */
191
192/**
193 * Retrieve a filtered packet.
194 *
195 * @param[out] pkt this struct will be filled with the contents of the filtered
196 * packet. It is owned by the caller and must be freed using
197 * av_packet_unref() when it is no longer needed.
198 * This parameter should be "clean" (i.e. freshly allocated
199 * with av_packet_alloc() or unreffed with av_packet_unref())
200 * when this function is called. If this function returns
201 * successfully, the contents of pkt will be completely
202 * overwritten by the returned data. On failure, pkt is not
203 * touched.
204 *
205 * @return
206 * - 0 on success.
207 * - AVERROR(EAGAIN) if more packets need to be sent to the filter (using
208 * av_bsf_send_packet()) to get more output.
209 * - AVERROR_EOF if there will be no further output from the filter.
210 * - Another negative AVERROR value if an error occurs.
211 *
212 * @note one input packet may result in several output packets, so after sending
213 * a packet with av_bsf_send_packet(), this function needs to be called
214 * repeatedly until it stops returning 0. It is also possible for a filter to
215 * output fewer packets than were sent to it, so this function may return
216 * AVERROR(EAGAIN) immediately after a successful av_bsf_send_packet() call.
217 */
219
220/**
221 * Reset the internal bitstream filter state. Should be called e.g. when seeking.
222 */
224
225/**
226 * Free a bitstream filter context and everything associated with it; write NULL
227 * into the supplied pointer.
228 */
230
231/**
232 * Get the AVClass for AVBSFContext. It can be used in combination with
233 * AV_OPT_SEARCH_FAKE_OBJ for examining options.
234 *
235 * @see av_opt_find().
236 */
238
239/**
240 * Structure for chain/list of bitstream filters.
241 * Empty list can be allocated by av_bsf_list_alloc().
242 */
243typedef struct AVBSFList AVBSFList;
244
245/**
246 * Allocate empty list of bitstream filters.
247 * The list must be later freed by av_bsf_list_free()
248 * or finalized by av_bsf_list_finalize().
249 *
250 * @return Pointer to @ref AVBSFList on success, NULL in case of failure
251 */
253
254/**
255 * Free list of bitstream filters.
256 *
257 * @param lst Pointer to pointer returned by av_bsf_list_alloc()
258 */
260
261/**
262 * Append bitstream filter to the list of bitstream filters.
263 *
264 * @param lst List to append to
265 * @param bsf Filter context to be appended
266 *
267 * @return >=0 on success, negative AVERROR in case of failure
268 */
270
271/**
272 * Construct new bitstream filter context given it's name and options
273 * and append it to the list of bitstream filters.
274 *
275 * @param lst List to append to
276 * @param bsf_name Name of the bitstream filter
277 * @param options Options for the bitstream filter, can be set to NULL
278 *
279 * @return >=0 on success, negative AVERROR in case of failure
280 */
281int av_bsf_list_append2(AVBSFList *lst, const char * bsf_name, AVDictionary **options);
282/**
283 * Finalize list of bitstream filters.
284 *
285 * This function will transform @ref AVBSFList to single @ref AVBSFContext,
286 * so the whole chain of bitstream filters can be treated as single filter
287 * freshly allocated by av_bsf_alloc().
288 * If the call is successful, @ref AVBSFList structure is freed and lst
289 * will be set to NULL. In case of failure, caller is responsible for
290 * freeing the structure by av_bsf_list_free()
291 *
292 * @param lst Filter list structure to be transformed
293 * @param[out] bsf Pointer to be set to newly created @ref AVBSFContext structure
294 * representing the chain of bitstream filters
295 *
296 * @return >=0 on success, negative AVERROR in case of failure
297 */
299
300/**
301 * Parse string describing list of bitstream filters and create single
302 * @ref AVBSFContext describing the whole chain of bitstream filters.
303 * Resulting @ref AVBSFContext can be treated as any other @ref AVBSFContext freshly
304 * allocated by av_bsf_alloc().
305 *
306 * @param str String describing chain of bitstream filters in format
307 * `bsf1[=opt1=val1:opt2=val2][,bsf2]`
308 * @param[out] bsf Pointer to be set to newly created @ref AVBSFContext structure
309 * representing the chain of bitstream filters
310 *
311 * @return >=0 on success, negative AVERROR in case of failure
312 */
313int av_bsf_list_parse_str(const char *str, AVBSFContext **bsf);
314
315/**
316 * Get null/pass-through bitstream filter.
317 *
318 * @param[out] bsf Pointer to be set to new instance of pass-through bitstream filter
319 *
320 * @return
321 */
323
324/**
325 * @}
326 */
327
328#endif // AVCODEC_BSF_H
static AVPacket * pkt
Public dictionary API.
void av_bsf_free(AVBSFContext **ctx)
Free a bitstream filter context and everything associated with it; write NULL into the supplied point...
void av_bsf_list_free(AVBSFList **lst)
Free list of bitstream filters.
const AVBitStreamFilter * av_bsf_iterate(void **opaque)
Iterate over all registered bitstream filters.
int av_bsf_init(AVBSFContext *ctx)
Prepare the filter for use, after all the parameters and options have been set.
int av_bsf_list_append(AVBSFList *lst, AVBSFContext *bsf)
Append bitstream filter to the list of bitstream filters.
void av_bsf_flush(AVBSFContext *ctx)
Reset the internal bitstream filter state.
const AVClass * av_bsf_get_class(void)
Get the AVClass for AVBSFContext.
int av_bsf_alloc(const AVBitStreamFilter *filter, AVBSFContext **ctx)
Allocate a context for a given bitstream filter.
int av_bsf_receive_packet(AVBSFContext *ctx, AVPacket *pkt)
Retrieve a filtered packet.
int av_bsf_list_finalize(AVBSFList **lst, AVBSFContext **bsf)
Finalize list of bitstream filters.
int av_bsf_send_packet(AVBSFContext *ctx, AVPacket *pkt)
Submit a packet for filtering.
AVBSFList * av_bsf_list_alloc(void)
Allocate empty 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...
struct AVBSFList AVBSFList
Structure for chain/list of bitstream filters.
Definition: bsf.h:243
int av_bsf_get_null_filter(AVBSFContext **bsf)
Get null/pass-through bitstream filter.
const AVBitStreamFilter * av_bsf_get_by_name(const char *name)
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 bitst...
AVCodecID
Identify the syntax and semantics of the bitstream.
Definition: codec_id.h:47
struct AVDictionary AVDictionary
Definition: dict.h:84
Utilties for rational number calculation.
The bitstream filter state.
Definition: bsf.h:68
AVRational time_base_out
The timebase used for the timestamps of the output packets.
Definition: bsf.h:108
void * priv_data
Opaque filter-specific private data.
Definition: bsf.h:83
AVCodecParameters * par_in
Parameters of the input stream.
Definition: bsf.h:90
const AVClass * av_class
A class for logging and AVOptions.
Definition: bsf.h:72
AVCodecParameters * par_out
Parameters of the output stream.
Definition: bsf.h:96
AVRational time_base_in
The timebase used for the timestamps of the input packets.
Definition: bsf.h:102
const struct AVBitStreamFilter * filter
The bitstream filter this context is an instance of.
Definition: bsf.h:77
const AVClass * priv_class
A class for the private data, used to declare bitstream filter private AVOptions.
Definition: bsf.h:130
const char * name
Definition: bsf.h:112
enum AVCodecID * codec_ids
A list of codec ids supported by the filter, terminated by AV_CODEC_ID_NONE.
Definition: bsf.h:119
Describe the class of an AVClass context structure.
Definition: log.h:66
This struct describes the properties of an encoded stream.
Definition: codec_par.h:53
This structure stores compressed data.
Definition: packet.h:351
Rational number (pair of numerator and denominator).
Definition: rational.h:58