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 */ 90 AVCodecParameters *par_in; 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 */ 96 AVCodecParameters *par_out; 97 98 /** 99 * The timebase used for the timestamps of the input packets. Set by the 100 * caller before av_bsf_init(). 101 */ 102 AVRational time_base_in; 103 104 /** 105 * The timebase used for the timestamps of the output packets. Set by the 106 * filter in av_bsf_init(). 107 */ 108 AVRational time_base_out; 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 */ 130 const AVClass *priv_class; 131 } AVBitStreamFilter; 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 */ 162 int av_bsf_alloc(const AVBitStreamFilter *filter, AVBSFContext **ctx); 163 164 /** 165 * Prepare the filter for use, after all the parameters and options have been 166 * set. 167 */ 168 int av_bsf_init(AVBSFContext *ctx); 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 */ 190 int av_bsf_send_packet(AVBSFContext *ctx, AVPacket *pkt); 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 */ 218 int av_bsf_receive_packet(AVBSFContext *ctx, AVPacket *pkt); 219 220 /** 221 * Reset the internal bitstream filter state. Should be called e.g. when seeking. 222 */ 223 void av_bsf_flush(AVBSFContext *ctx); 224 225 /** 226 * Free a bitstream filter context and everything associated with it; write NULL 227 * into the supplied pointer. 228 */ 229 void av_bsf_free(AVBSFContext **ctx); 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 */ 237 const AVClass *av_bsf_get_class(void); 238 239 /** 240 * Structure for chain/list of bitstream filters. 241 * Empty list can be allocated by av_bsf_list_alloc(). 242 */ 243 typedef 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 */ 252 AVBSFList *av_bsf_list_alloc(void); 253 254 /** 255 * Free list of bitstream filters. 256 * 257 * @param lst Pointer to pointer returned by av_bsf_list_alloc() 258 */ 259 void av_bsf_list_free(AVBSFList **lst); 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 */ 269 int av_bsf_list_append(AVBSFList *lst, AVBSFContext *bsf); 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 */ 281 int 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 */ 298 int av_bsf_list_finalize(AVBSFList **lst, AVBSFContext **bsf); 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 */ 313 int 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 */ 322 int av_bsf_get_null_filter(AVBSFContext **bsf); 323 324 /** 325 * @} 326 */ 327 328 #endif // AVCODEC_BSF_H 329