FFmpeg
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  */
68 typedef struct AVBSFContext {
69  /**
70  * A class for logging and AVOptions
71  */
72  const AVClass *av_class;
73 
74  /**
75  * The bitstream filter this context is an instance of.
76  */
77  const struct AVBitStreamFilter *filter;
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  */
109 } AVBSFContext;
110 
111 typedef 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  */
137 const 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  */
148 const 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  *
168  * @param ctx a AVBSFContext previously allocated with av_bsf_alloc()
169  */
171 
172 /**
173  * Submit a packet for filtering.
174  *
175  * After sending each packet, the filter must be completely drained by calling
176  * av_bsf_receive_packet() repeatedly until it returns AVERROR(EAGAIN) or
177  * AVERROR_EOF.
178  *
179  * @param ctx an initialized AVBSFContext
180  * @param pkt the packet to filter. The bitstream filter will take ownership of
181  * the packet and reset the contents of pkt. pkt is not touched if an error occurs.
182  * If pkt is empty (i.e. NULL, or pkt->data is NULL and pkt->side_data_elems zero),
183  * it signals the end of the stream (i.e. no more non-empty packets will be sent;
184  * sending more empty packets does nothing) and will cause the filter to output
185  * any packets it may have buffered internally.
186  *
187  * @return
188  * - 0 on success.
189  * - AVERROR(EAGAIN) if packets need to be retrieved from the filter (using
190  * av_bsf_receive_packet()) before new input can be consumed.
191  * - Another negative AVERROR value if an error occurs.
192  */
194 
195 /**
196  * Retrieve a filtered packet.
197  *
198  * @param ctx an initialized AVBSFContext
199  * @param[out] pkt this struct will be filled with the contents of the filtered
200  * packet. It is owned by the caller and must be freed using
201  * av_packet_unref() when it is no longer needed.
202  * This parameter should be "clean" (i.e. freshly allocated
203  * with av_packet_alloc() or unreffed with av_packet_unref())
204  * when this function is called. If this function returns
205  * successfully, the contents of pkt will be completely
206  * overwritten by the returned data. On failure, pkt is not
207  * touched.
208  *
209  * @return
210  * - 0 on success.
211  * - AVERROR(EAGAIN) if more packets need to be sent to the filter (using
212  * av_bsf_send_packet()) to get more output.
213  * - AVERROR_EOF if there will be no further output from the filter.
214  * - Another negative AVERROR value if an error occurs.
215  *
216  * @note one input packet may result in several output packets, so after sending
217  * a packet with av_bsf_send_packet(), this function needs to be called
218  * repeatedly until it stops returning 0. It is also possible for a filter to
219  * output fewer packets than were sent to it, so this function may return
220  * AVERROR(EAGAIN) immediately after a successful av_bsf_send_packet() call.
221  */
223 
224 /**
225  * Reset the internal bitstream filter state. Should be called e.g. when seeking.
226  */
228 
229 /**
230  * Free a bitstream filter context and everything associated with it; write NULL
231  * into the supplied pointer.
232  */
234 
235 /**
236  * Get the AVClass for AVBSFContext. It can be used in combination with
237  * AV_OPT_SEARCH_FAKE_OBJ for examining options.
238  *
239  * @see av_opt_find().
240  */
241 const AVClass *av_bsf_get_class(void);
242 
243 /**
244  * Structure for chain/list of bitstream filters.
245  * Empty list can be allocated by av_bsf_list_alloc().
246  */
247 typedef struct AVBSFList AVBSFList;
248 
249 /**
250  * Allocate empty list of bitstream filters.
251  * The list must be later freed by av_bsf_list_free()
252  * or finalized by av_bsf_list_finalize().
253  *
254  * @return Pointer to @ref AVBSFList on success, NULL in case of failure
255  */
257 
258 /**
259  * Free list of bitstream filters.
260  *
261  * @param lst Pointer to pointer returned by av_bsf_list_alloc()
262  */
263 void av_bsf_list_free(AVBSFList **lst);
264 
265 /**
266  * Append bitstream filter to the list of bitstream filters.
267  *
268  * @param lst List to append to
269  * @param bsf Filter context to be appended
270  *
271  * @return >=0 on success, negative AVERROR in case of failure
272  */
274 
275 /**
276  * Construct new bitstream filter context given it's name and options
277  * and append it to the list of bitstream filters.
278  *
279  * @param lst List to append to
280  * @param bsf_name Name of the bitstream filter
281  * @param options Options for the bitstream filter, can be set to NULL
282  *
283  * @return >=0 on success, negative AVERROR in case of failure
284  */
285 int av_bsf_list_append2(AVBSFList *lst, const char * bsf_name, AVDictionary **options);
286 /**
287  * Finalize list of bitstream filters.
288  *
289  * This function will transform @ref AVBSFList to single @ref AVBSFContext,
290  * so the whole chain of bitstream filters can be treated as single filter
291  * freshly allocated by av_bsf_alloc().
292  * If the call is successful, @ref AVBSFList structure is freed and lst
293  * will be set to NULL. In case of failure, caller is responsible for
294  * freeing the structure by av_bsf_list_free()
295  *
296  * @param lst Filter list structure to be transformed
297  * @param[out] bsf Pointer to be set to newly created @ref AVBSFContext structure
298  * representing the chain of bitstream filters
299  *
300  * @return >=0 on success, negative AVERROR in case of failure
301  */
303 
304 /**
305  * Parse string describing list of bitstream filters and create single
306  * @ref AVBSFContext describing the whole chain of bitstream filters.
307  * Resulting @ref AVBSFContext can be treated as any other @ref AVBSFContext freshly
308  * allocated by av_bsf_alloc().
309  *
310  * @param str String describing chain of bitstream filters in format
311  * `bsf1[=opt1=val1:opt2=val2][,bsf2]`
312  * @param[out] bsf Pointer to be set to newly created @ref AVBSFContext structure
313  * representing the chain of bitstream filters
314  *
315  * @return >=0 on success, negative AVERROR in case of failure
316  */
317 int av_bsf_list_parse_str(const char *str, AVBSFContext **bsf);
318 
319 /**
320  * Get null/pass-through bitstream filter.
321  *
322  * @param[out] bsf Pointer to be set to new instance of pass-through bitstream filter
323  *
324  * @return
325  */
327 
328 /**
329  * @}
330  */
331 
332 #endif // AVCODEC_BSF_H
AVBSFContext::par_in
AVCodecParameters * par_in
Parameters of the input stream.
Definition: bsf.h:90
name
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf default minimum maximum flags name is the option name
Definition: writing_filters.txt:88
AVCodecParameters
This struct describes the properties of an encoded stream.
Definition: codec_par.h:47
rational.h
AVBitStreamFilter::name
const char * name
Definition: bsf.h:112
AVBSFContext::av_class
const AVClass * av_class
A class for logging and AVOptions.
Definition: bsf.h:72
filter
filter_frame For filters that do not use the this method is called when a frame is pushed to the filter s input It can be called at any time except in a reentrant way If the input frame is enough to produce then the filter should push the output frames on the output link immediately As an exception to the previous rule if the input frame is enough to produce several output frames then the filter needs output only at least one per link The additional frames can be left buffered in the filter
Definition: filter_design.txt:228
AVDictionary
Definition: dict.c:34
av_bsf_free
void av_bsf_free(AVBSFContext **ctx)
Free a bitstream filter context and everything associated with it; write NULL into the supplied point...
Definition: bsf.c:52
AVBSFContext
The bitstream filter state.
Definition: bsf.h:68
AVBSFContext::par_out
AVCodecParameters * par_out
Parameters of the output stream.
Definition: bsf.h:96
pkt
AVPacket * pkt
Definition: movenc.c:59
codec_id.h
av_bsf_flush
void av_bsf_flush(AVBSFContext *ctx)
Reset the internal bitstream filter state.
Definition: bsf.c:190
av_bsf_list_free
void av_bsf_list_free(AVBSFList **lst)
Free list of bitstream filters.
Definition: bsf.c:425
ctx
AVFormatContext * ctx
Definition: movenc.c:48
AVBSFContext::time_base_in
AVRational time_base_in
The timebase used for the timestamps of the input packets.
Definition: bsf.h:102
av_bsf_alloc
int av_bsf_alloc(const AVBitStreamFilter *filter, AVBSFContext **ctx)
Allocate a context for a given bitstream filter.
Definition: bsf.c:104
AVBitStreamFilter::codec_ids
enum AVCodecID * codec_ids
A list of codec ids supported by the filter, terminated by AV_CODEC_ID_NONE.
Definition: bsf.h:119
av_bsf_init
int av_bsf_init(AVBSFContext *ctx)
Prepare the filter for use, after all the parameters and options have been set.
Definition: bsf.c:149
AVClass
Describe the class of an AVClass context structure.
Definition: log.h:66
av_bsf_get_class
const AVClass * av_bsf_get_class(void)
Get the AVClass for AVBSFContext.
Definition: bsf.c:99
av_bsf_receive_packet
int av_bsf_receive_packet(AVBSFContext *ctx, AVPacket *pkt)
Retrieve a filtered packet.
Definition: bsf.c:230
AVRational
Rational number (pair of numerator and denominator).
Definition: rational.h:58
AVBitStreamFilter::priv_class
const AVClass * priv_class
A class for the private data, used to declare bitstream filter private AVOptions.
Definition: bsf.h:130
AVCodecID
AVCodecID
Identify the syntax and semantics of the bitstream.
Definition: codec_id.h:49
options
const OptionDef options[]
av_bsf_send_packet
int av_bsf_send_packet(AVBSFContext *ctx, AVPacket *pkt)
Submit a packet for filtering.
Definition: bsf.c:202
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 bitst...
Definition: bsf.c:484
log.h
packet.h
AVBSFContext::time_base_out
AVRational time_base_out
The timebase used for the timestamps of the output packets.
Definition: bsf.h:108
av_bsf_list_alloc
AVBSFList * av_bsf_list_alloc(void)
Allocate empty list of bitstream filters.
Definition: bsf.c:420
AVBSFContext::priv_data
void * priv_data
Opaque filter-specific private data.
Definition: bsf.h:83
av_bsf_iterate
const AVBitStreamFilter * av_bsf_iterate(void **opaque)
Iterate over all registered bitstream filters.
Definition: bitstream_filters.c:74
av_bsf_get_null_filter
int av_bsf_get_null_filter(AVBSFContext **bsf)
Get null/pass-through bitstream filter.
Definition: bsf.c:553
dict.h
AVBSFList
Structure for chain/list of bitstream filters.
Definition: bsf.c:415
AVBitStreamFilter
Definition: bsf.h:111
AVBSFContext::filter
const struct AVBitStreamFilter * filter
The bitstream filter this context is an instance of.
Definition: bsf.h:77
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...
Definition: bsf.c:526
codec_par.h
AVPacket
This structure stores compressed data.
Definition: packet.h:499
av_bsf_list_finalize
int av_bsf_list_finalize(AVBSFList **lst, AVBSFContext **bsf)
Finalize list of bitstream filters.
Definition: bsf.c:489
av_bsf_list_append
int av_bsf_list_append(AVBSFList *lst, AVBSFContext *bsf)
Append bitstream filter to the list of bitstream filters.
Definition: bsf.c:438
av_bsf_get_by_name
const AVBitStreamFilter * av_bsf_get_by_name(const char *name)
Definition: bitstream_filters.c:86