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