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  * @addtogroup lavc_core
34  * @{
35  */
36 
37 /**
38  * The bitstream filter state.
39  *
40  * This struct must be allocated with av_bsf_alloc() and freed with
41  * av_bsf_free().
42  *
43  * The fields in the struct will only be changed (by the caller or by the
44  * filter) as described in their documentation, and are to be considered
45  * immutable otherwise.
46  */
47 typedef struct AVBSFContext {
48  /**
49  * A class for logging and AVOptions
50  */
51  const AVClass *av_class;
52 
53  /**
54  * The bitstream filter this context is an instance of.
55  */
56  const struct AVBitStreamFilter *filter;
57 
58  /**
59  * Opaque filter-specific private data. If filter->priv_class is non-NULL,
60  * this is an AVOptions-enabled struct.
61  */
62  void *priv_data;
63 
64  /**
65  * Parameters of the input stream. This field is allocated in
66  * av_bsf_alloc(), it needs to be filled by the caller before
67  * av_bsf_init().
68  */
70 
71  /**
72  * Parameters of the output stream. This field is allocated in
73  * av_bsf_alloc(), it is set by the filter in av_bsf_init().
74  */
76 
77  /**
78  * The timebase used for the timestamps of the input packets. Set by the
79  * caller before av_bsf_init().
80  */
82 
83  /**
84  * The timebase used for the timestamps of the output packets. Set by the
85  * filter in av_bsf_init().
86  */
88 } AVBSFContext;
89 
90 typedef struct AVBitStreamFilter {
91  const char *name;
92 
93  /**
94  * A list of codec ids supported by the filter, terminated by
95  * AV_CODEC_ID_NONE.
96  * May be NULL, in that case the bitstream filter works with any codec id.
97  */
98  const enum AVCodecID *codec_ids;
99 
100  /**
101  * A class for the private data, used to declare bitstream filter private
102  * AVOptions. This field is NULL for bitstream filters that do not declare
103  * any options.
104  *
105  * If this field is non-NULL, the first member of the filter private data
106  * must be a pointer to AVClass, which will be set by libavcodec generic
107  * code to this class.
108  */
110 
111  /*****************************************************************
112  * No fields below this line are part of the public API. They
113  * may not be used outside of libavcodec and can be changed and
114  * removed at will.
115  * New public fields should be added right above.
116  *****************************************************************
117  */
118 
122  void (*close)(AVBSFContext *ctx);
123  void (*flush)(AVBSFContext *ctx);
125 
126 /**
127  * @return a bitstream filter with the specified name or NULL if no such
128  * bitstream filter exists.
129  */
130 const AVBitStreamFilter *av_bsf_get_by_name(const char *name);
131 
132 /**
133  * Iterate over all registered bitstream filters.
134  *
135  * @param opaque a pointer where libavcodec will store the iteration state. Must
136  * point to NULL to start the iteration.
137  *
138  * @return the next registered bitstream filter or NULL when the iteration is
139  * finished
140  */
141 const AVBitStreamFilter *av_bsf_iterate(void **opaque);
142 
143 /**
144  * Allocate a context for a given bitstream filter. The caller must fill in the
145  * context parameters as described in the documentation and then call
146  * av_bsf_init() before sending any data to the filter.
147  *
148  * @param filter the filter for which to allocate an instance.
149  * @param ctx a pointer into which the pointer to the newly-allocated context
150  * will be written. It must be freed with av_bsf_free() after the
151  * filtering is done.
152  *
153  * @return 0 on success, a negative AVERROR code on failure
154  */
156 
157 /**
158  * Prepare the filter for use, after all the parameters and options have been
159  * set.
160  */
162 
163 /**
164  * Submit a packet for filtering.
165  *
166  * After sending each packet, the filter must be completely drained by calling
167  * av_bsf_receive_packet() repeatedly until it returns AVERROR(EAGAIN) or
168  * AVERROR_EOF.
169  *
170  * @param pkt the packet to filter. The bitstream filter will take ownership of
171  * the packet and reset the contents of pkt. pkt is not touched if an error occurs.
172  * If pkt is empty (i.e. NULL, or pkt->data is NULL and pkt->side_data_elems zero),
173  * it signals the end of the stream (i.e. no more non-empty packets will be sent;
174  * sending more empty packets does nothing) and will cause the filter to output
175  * any packets it may have buffered internally.
176  *
177  * @return 0 on success. AVERROR(EAGAIN) if packets need to be retrieved from the
178  * filter (using av_bsf_receive_packet()) before new input can be consumed. Another
179  * negative AVERROR value if an error occurs.
180  */
182 
183 /**
184  * Retrieve a filtered packet.
185  *
186  * @param[out] pkt this struct will be filled with the contents of the filtered
187  * packet. It is owned by the caller and must be freed using
188  * av_packet_unref() when it is no longer needed.
189  * This parameter should be "clean" (i.e. freshly allocated
190  * with av_packet_alloc() or unreffed with av_packet_unref())
191  * when this function is called. If this function returns
192  * successfully, the contents of pkt will be completely
193  * overwritten by the returned data. On failure, pkt is not
194  * touched.
195  *
196  * @return 0 on success. AVERROR(EAGAIN) if more packets need to be sent to the
197  * filter (using av_bsf_send_packet()) to get more output. AVERROR_EOF if there
198  * will be no further output from the filter. Another negative AVERROR value if
199  * an error occurs.
200  *
201  * @note one input packet may result in several output packets, so after sending
202  * a packet with av_bsf_send_packet(), this function needs to be called
203  * repeatedly until it stops returning 0. It is also possible for a filter to
204  * output fewer packets than were sent to it, so this function may return
205  * AVERROR(EAGAIN) immediately after a successful av_bsf_send_packet() call.
206  */
208 
209 /**
210  * Reset the internal bitstream filter state. Should be called e.g. when seeking.
211  */
213 
214 /**
215  * Free a bitstream filter context and everything associated with it; write NULL
216  * into the supplied pointer.
217  */
219 
220 /**
221  * Get the AVClass for AVBSFContext. It can be used in combination with
222  * AV_OPT_SEARCH_FAKE_OBJ for examining options.
223  *
224  * @see av_opt_find().
225  */
226 const AVClass *av_bsf_get_class(void);
227 
228 /**
229  * Structure for chain/list of bitstream filters.
230  * Empty list can be allocated by av_bsf_list_alloc().
231  */
232 typedef struct AVBSFList AVBSFList;
233 
234 /**
235  * Allocate empty list of bitstream filters.
236  * The list must be later freed by av_bsf_list_free()
237  * or finalized by av_bsf_list_finalize().
238  *
239  * @return Pointer to @ref AVBSFList on success, NULL in case of failure
240  */
242 
243 /**
244  * Free list of bitstream filters.
245  *
246  * @param lst Pointer to pointer returned by av_bsf_list_alloc()
247  */
248 void av_bsf_list_free(AVBSFList **lst);
249 
250 /**
251  * Append bitstream filter to the list of bitstream filters.
252  *
253  * @param lst List to append to
254  * @param bsf Filter context to be appended
255  *
256  * @return >=0 on success, negative AVERROR in case of failure
257  */
259 
260 /**
261  * Construct new bitstream filter context given it's name and options
262  * and append it to the list of bitstream filters.
263  *
264  * @param lst List to append to
265  * @param bsf_name Name of the bitstream filter
266  * @param options Options for the bitstream filter, can be set to NULL
267  *
268  * @return >=0 on success, negative AVERROR in case of failure
269  */
270 int av_bsf_list_append2(AVBSFList *lst, const char * bsf_name, AVDictionary **options);
271 /**
272  * Finalize list of bitstream filters.
273  *
274  * This function will transform @ref AVBSFList to single @ref AVBSFContext,
275  * so the whole chain of bitstream filters can be treated as single filter
276  * freshly allocated by av_bsf_alloc().
277  * If the call is successful, @ref AVBSFList structure is freed and lst
278  * will be set to NULL. In case of failure, caller is responsible for
279  * freeing the structure by av_bsf_list_free()
280  *
281  * @param lst Filter list structure to be transformed
282  * @param[out] bsf Pointer to be set to newly created @ref AVBSFContext structure
283  * representing the chain of bitstream filters
284  *
285  * @return >=0 on success, negative AVERROR in case of failure
286  */
288 
289 /**
290  * Parse string describing list of bitstream filters and create single
291  * @ref AVBSFContext describing the whole chain of bitstream filters.
292  * Resulting @ref AVBSFContext can be treated as any other @ref AVBSFContext freshly
293  * allocated by av_bsf_alloc().
294  *
295  * @param str String describing chain of bitstream filters in format
296  * `bsf1[=opt1=val1:opt2=val2][,bsf2]`
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  */
302 int av_bsf_list_parse_str(const char *str, AVBSFContext **bsf);
303 
304 /**
305  * Get null/pass-through bitstream filter.
306  *
307  * @param[out] bsf Pointer to be set to new instance of pass-through bitstream filter
308  *
309  * @return
310  */
312 
313 /**
314  * @}
315  */
316 
317 #endif // AVCODEC_BSF_H
AVBSFContext::par_in
AVCodecParameters * par_in
Parameters of the input stream.
Definition: bsf.h:69
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:52
rational.h
AVBitStreamFilter::name
const char * name
Definition: bsf.h:91
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:145
av_bsf_list_alloc
AVBSFList * av_bsf_list_alloc(void)
Allocate empty list of bitstream filters.
Definition: bsf.c:416
AVBitStreamFilter::priv_data_size
int priv_data_size
Definition: bsf.h:119
AVBSFContext::av_class
const AVClass * av_class
A class for logging and AVOptions.
Definition: bsf.h:51
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
av_bsf_iterate
const AVBitStreamFilter * av_bsf_iterate(void **opaque)
Iterate over all registered bitstream filters.
Definition: bitstream_filters.c:67
AVDictionary
Definition: dict.c:30
AVBSFContext
The bitstream filter state.
Definition: bsf.h:47
av_bsf_get_by_name
const AVBitStreamFilter * av_bsf_get_by_name(const char *name)
Definition: bitstream_filters.c:78
av_bsf_get_null_filter
int av_bsf_get_null_filter(AVBSFContext **bsf)
Get null/pass-through bitstream filter.
Definition: bsf.c:549
AVBSFContext::par_out
AVCodecParameters * par_out
Parameters of the output stream.
Definition: bsf.h:75
pkt
AVPacket * pkt
Definition: movenc.c:59
codec_id.h
av_bsf_list_free
void av_bsf_list_free(AVBSFList **lst)
Free list of bitstream filters.
Definition: bsf.c:421
av_bsf_get_class
const AVClass * av_bsf_get_class(void)
Get the AVClass for AVBSFContext.
Definition: bsf.c:95
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:81
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:98
av_bsf_list_finalize
int av_bsf_list_finalize(AVBSFList **lst, AVBSFContext **bsf)
Finalize list of bitstream filters.
Definition: bsf.c:485
AVClass
Describe the class of an AVClass context structure.
Definition: log.h:66
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:522
AVRational
Rational number (pair of numerator and denominator).
Definition: rational.h:58
AVBitStreamFilter::close
void(* close)(AVBSFContext *ctx)
Definition: bsf.h:122
AVBitStreamFilter::priv_class
const AVClass * priv_class
A class for the private data, used to declare bitstream filter private AVOptions.
Definition: bsf.h:109
AVCodecID
AVCodecID
Identify the syntax and semantics of the bitstream.
Definition: codec_id.h:47
options
const OptionDef options[]
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:480
log.h
av_bsf_receive_packet
int av_bsf_receive_packet(AVBSFContext *ctx, AVPacket *pkt)
Retrieve a filtered packet.
Definition: bsf.c:226
packet.h
AVBitStreamFilter::filter
int(* filter)(AVBSFContext *ctx, AVPacket *pkt)
Definition: bsf.h:121
AVBSFContext::time_base_out
AVRational time_base_out
The timebase used for the timestamps of the output packets.
Definition: bsf.h:87
AVBSFContext::priv_data
void * priv_data
Opaque filter-specific private data.
Definition: bsf.h:62
dict.h
av_bsf_send_packet
int av_bsf_send_packet(AVBSFContext *ctx, AVPacket *pkt)
Submit a packet for filtering.
Definition: bsf.c:198
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:434
av_bsf_flush
void av_bsf_flush(AVBSFContext *ctx)
Reset the internal bitstream filter state.
Definition: bsf.c:186
AVBSFList
Structure for chain/list of bitstream filters.
Definition: bsf.c:411
AVBitStreamFilter
Definition: bsf.h:90
AVBSFContext::filter
const struct AVBitStreamFilter * filter
The bitstream filter this context is an instance of.
Definition: bsf.h:56
codec_par.h
AVPacket
This structure stores compressed data.
Definition: packet.h:350
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:48
AVBitStreamFilter::init
int(* init)(AVBSFContext *ctx)
Definition: bsf.h:120
convert_header.str
string str
Definition: convert_header.py:20
AVBitStreamFilter::flush
void(* flush)(AVBSFContext *ctx)
Definition: bsf.h:123
int
int
Definition: ffmpeg_filter.c:156
av_bsf_alloc
int av_bsf_alloc(const AVBitStreamFilter *filter, AVBSFContext **ctx)
Allocate a context for a given bitstream filter.
Definition: bsf.c:100