1 /* 2 * Copyright (c) 2012 Justin Ruggles <justin.ruggles@gmail.com> 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 AVRESAMPLE_AVRESAMPLE_H 22 #define AVRESAMPLE_AVRESAMPLE_H 23 24 /** 25 * @file 26 * @ingroup lavr 27 * external API header 28 */ 29 30 /** 31 * @defgroup lavr libavresample 32 * @{ 33 * 34 * Libavresample (lavr) is a library that handles audio resampling, sample 35 * format conversion and mixing. 36 * 37 * Interaction with lavr is done through AVAudioResampleContext, which is 38 * allocated with avresample_alloc_context(). It is opaque, so all parameters 39 * must be set with the @ref avoptions API. 40 * 41 * For example the following code will setup conversion from planar float sample 42 * format to interleaved signed 16-bit integer, downsampling from 48kHz to 43 * 44.1kHz and downmixing from 5.1 channels to stereo (using the default mixing 44 * matrix): 45 * @code 46 * AVAudioResampleContext *avr = avresample_alloc_context(); 47 * av_opt_set_int(avr, "in_channel_layout", AV_CH_LAYOUT_5POINT1, 0); 48 * av_opt_set_int(avr, "out_channel_layout", AV_CH_LAYOUT_STEREO, 0); 49 * av_opt_set_int(avr, "in_sample_rate", 48000, 0); 50 * av_opt_set_int(avr, "out_sample_rate", 44100, 0); 51 * av_opt_set_int(avr, "in_sample_fmt", AV_SAMPLE_FMT_FLTP, 0); 52 * av_opt_set_int(avr, "out_sample_fmt", AV_SAMPLE_FMT_S16, 0); 53 * @endcode 54 * 55 * Once the context is initialized, it must be opened with avresample_open(). If 56 * you need to change the conversion parameters, you must close the context with 57 * avresample_close(), change the parameters as described above, then reopen it 58 * again. 59 * 60 * The conversion itself is done by repeatedly calling avresample_convert(). 61 * Note that the samples may get buffered in two places in lavr. The first one 62 * is the output FIFO, where the samples end up if the output buffer is not 63 * large enough. The data stored in there may be retrieved at any time with 64 * avresample_read(). The second place is the resampling delay buffer, 65 * applicable only when resampling is done. The samples in it require more input 66 * before they can be processed. Their current amount is returned by 67 * avresample_get_delay(). At the end of conversion the resampling buffer can be 68 * flushed by calling avresample_convert() with NULL input. 69 * 70 * The following code demonstrates the conversion loop assuming the parameters 71 * from above and caller-defined functions get_input() and handle_output(): 72 * @code 73 * uint8_t **input; 74 * int in_linesize, in_samples; 75 * 76 * while (get_input(&input, &in_linesize, &in_samples)) { 77 * uint8_t *output 78 * int out_linesize; 79 * int out_samples = avresample_get_out_samples(avr, in_samples); 80 * 81 * av_samples_alloc(&output, &out_linesize, 2, out_samples, 82 * AV_SAMPLE_FMT_S16, 0); 83 * out_samples = avresample_convert(avr, &output, out_linesize, out_samples, 84 * input, in_linesize, in_samples); 85 * handle_output(output, out_linesize, out_samples); 86 * av_freep(&output); 87 * } 88 * @endcode 89 * 90 * When the conversion is finished and the FIFOs are flushed if required, the 91 * conversion context and everything associated with it must be freed with 92 * avresample_free(). 93 */ 94 95 #include "libavutil/avutil.h" 96 #include "libavutil/channel_layout.h" 97 #include "libavutil/dict.h" 98 #include "libavutil/frame.h" 99 #include "libavutil/log.h" 100 #include "libavutil/mathematics.h" 101 102 #include "libavresample/version.h" 103 104 #define AVRESAMPLE_MAX_CHANNELS 32 105 106 typedef struct AVAudioResampleContext AVAudioResampleContext; 107 108 /** 109 * @deprecated use libswresample 110 * 111 * Mixing Coefficient Types */ 112 enum attribute_deprecated AVMixCoeffType { 113 AV_MIX_COEFF_TYPE_Q8, /** 16-bit 8.8 fixed-point */ 114 AV_MIX_COEFF_TYPE_Q15, /** 32-bit 17.15 fixed-point */ 115 AV_MIX_COEFF_TYPE_FLT, /** floating-point */ 116 AV_MIX_COEFF_TYPE_NB, /** Number of coeff types. Not part of ABI */ 117 }; 118 119 /** 120 * @deprecated use libswresample 121 * 122 * Resampling Filter Types */ 123 enum attribute_deprecated AVResampleFilterType { 124 AV_RESAMPLE_FILTER_TYPE_CUBIC, /**< Cubic */ 125 AV_RESAMPLE_FILTER_TYPE_BLACKMAN_NUTTALL, /**< Blackman Nuttall Windowed Sinc */ 126 AV_RESAMPLE_FILTER_TYPE_KAISER, /**< Kaiser Windowed Sinc */ 127 }; 128 129 /** 130 * @deprecated use libswresample 131 */ 132 enum attribute_deprecated AVResampleDitherMethod { 133 AV_RESAMPLE_DITHER_NONE, /**< Do not use dithering */ 134 AV_RESAMPLE_DITHER_RECTANGULAR, /**< Rectangular Dither */ 135 AV_RESAMPLE_DITHER_TRIANGULAR, /**< Triangular Dither*/ 136 AV_RESAMPLE_DITHER_TRIANGULAR_HP, /**< Triangular Dither with High Pass */ 137 AV_RESAMPLE_DITHER_TRIANGULAR_NS, /**< Triangular Dither with Noise Shaping */ 138 AV_RESAMPLE_DITHER_NB, /**< Number of dither types. Not part of ABI. */ 139 }; 140 141 /** 142 * 143 * @deprecated use libswresample 144 * 145 * Return the LIBAVRESAMPLE_VERSION_INT constant. 146 */ 147 attribute_deprecated 148 unsigned avresample_version(void); 149 150 /** 151 * 152 * @deprecated use libswresample 153 * 154 * Return the libavresample build-time configuration. 155 * @return configure string 156 */ 157 attribute_deprecated 158 const char *avresample_configuration(void); 159 160 /** 161 * 162 * @deprecated use libswresample 163 * 164 * Return the libavresample license. 165 */ 166 attribute_deprecated 167 const char *avresample_license(void); 168 169 /** 170 * 171 * @deprecated use libswresample 172 * 173 * Get the AVClass for AVAudioResampleContext. 174 * 175 * Can be used in combination with AV_OPT_SEARCH_FAKE_OBJ for examining options 176 * without allocating a context. 177 * 178 * @see av_opt_find(). 179 * 180 * @return AVClass for AVAudioResampleContext 181 */ 182 attribute_deprecated 183 const AVClass *avresample_get_class(void); 184 185 /** 186 * 187 * @deprecated use libswresample 188 * 189 * Allocate AVAudioResampleContext and set options. 190 * 191 * @return allocated audio resample context, or NULL on failure 192 */ 193 attribute_deprecated 194 AVAudioResampleContext *avresample_alloc_context(void); 195 196 /** 197 * 198 * @deprecated use libswresample 199 * 200 * Initialize AVAudioResampleContext. 201 * @note The context must be configured using the AVOption API. 202 * @note The fields "in_channel_layout", "out_channel_layout", 203 * "in_sample_rate", "out_sample_rate", "in_sample_fmt", 204 * "out_sample_fmt" must be set. 205 * 206 * @see av_opt_set_int() 207 * @see av_opt_set_dict() 208 * @see av_get_default_channel_layout() 209 * 210 * @param avr audio resample context 211 * @return 0 on success, negative AVERROR code on failure 212 */ 213 attribute_deprecated 214 int avresample_open(AVAudioResampleContext *avr); 215 216 /** 217 * 218 * @deprecated use libswresample 219 * 220 * Check whether an AVAudioResampleContext is open or closed. 221 * 222 * @param avr AVAudioResampleContext to check 223 * @return 1 if avr is open, 0 if avr is closed. 224 */ 225 attribute_deprecated 226 int avresample_is_open(AVAudioResampleContext *avr); 227 228 /** 229 * 230 * @deprecated use libswresample 231 * 232 * Close AVAudioResampleContext. 233 * 234 * This closes the context, but it does not change the parameters. The context 235 * can be reopened with avresample_open(). It does, however, clear the output 236 * FIFO and any remaining leftover samples in the resampling delay buffer. If 237 * there was a custom matrix being used, that is also cleared. 238 * 239 * @see avresample_convert() 240 * @see avresample_set_matrix() 241 * 242 * @param avr audio resample context 243 */ 244 attribute_deprecated 245 void avresample_close(AVAudioResampleContext *avr); 246 247 /** 248 * 249 * @deprecated use libswresample 250 * 251 * Free AVAudioResampleContext and associated AVOption values. 252 * 253 * This also calls avresample_close() before freeing. 254 * 255 * @param avr audio resample context 256 */ 257 attribute_deprecated 258 void avresample_free(AVAudioResampleContext **avr); 259 260 /** 261 * 262 * @deprecated use libswresample 263 * 264 * Generate a channel mixing matrix. 265 * 266 * This function is the one used internally by libavresample for building the 267 * default mixing matrix. It is made public just as a utility function for 268 * building custom matrices. 269 * 270 * @param in_layout input channel layout 271 * @param out_layout output channel layout 272 * @param center_mix_level mix level for the center channel 273 * @param surround_mix_level mix level for the surround channel(s) 274 * @param lfe_mix_level mix level for the low-frequency effects channel 275 * @param normalize if 1, coefficients will be normalized to prevent 276 * overflow. if 0, coefficients will not be 277 * normalized. 278 * @param[out] matrix mixing coefficients; matrix[i + stride * o] is 279 * the weight of input channel i in output channel o. 280 * @param stride distance between adjacent input channels in the 281 * matrix array 282 * @param matrix_encoding matrixed stereo downmix mode (e.g. dplii) 283 * @return 0 on success, negative AVERROR code on failure 284 */ 285 attribute_deprecated 286 int avresample_build_matrix(uint64_t in_layout, uint64_t out_layout, 287 double center_mix_level, double surround_mix_level, 288 double lfe_mix_level, int normalize, double *matrix, 289 int stride, enum AVMatrixEncoding matrix_encoding); 290 291 /** 292 * 293 * @deprecated use libswresample 294 * 295 * Get the current channel mixing matrix. 296 * 297 * If no custom matrix has been previously set or the AVAudioResampleContext is 298 * not open, an error is returned. 299 * 300 * @param avr audio resample context 301 * @param matrix mixing coefficients; matrix[i + stride * o] is the weight of 302 * input channel i in output channel o. 303 * @param stride distance between adjacent input channels in the matrix array 304 * @return 0 on success, negative AVERROR code on failure 305 */ 306 attribute_deprecated 307 int avresample_get_matrix(AVAudioResampleContext *avr, double *matrix, 308 int stride); 309 310 /** 311 * 312 * @deprecated use libswresample 313 * 314 * Set channel mixing matrix. 315 * 316 * Allows for setting a custom mixing matrix, overriding the default matrix 317 * generated internally during avresample_open(). This function can be called 318 * anytime on an allocated context, either before or after calling 319 * avresample_open(), as long as the channel layouts have been set. 320 * avresample_convert() always uses the current matrix. 321 * Calling avresample_close() on the context will clear the current matrix. 322 * 323 * @see avresample_close() 324 * 325 * @param avr audio resample context 326 * @param matrix mixing coefficients; matrix[i + stride * o] is the weight of 327 * input channel i in output channel o. 328 * @param stride distance between adjacent input channels in the matrix array 329 * @return 0 on success, negative AVERROR code on failure 330 */ 331 attribute_deprecated 332 int avresample_set_matrix(AVAudioResampleContext *avr, const double *matrix, 333 int stride); 334 335 /** 336 * 337 * @deprecated use libswresample 338 * 339 * Set a customized input channel mapping. 340 * 341 * This function can only be called when the allocated context is not open. 342 * Also, the input channel layout must have already been set. 343 * 344 * Calling avresample_close() on the context will clear the channel mapping. 345 * 346 * The map for each input channel specifies the channel index in the source to 347 * use for that particular channel, or -1 to mute the channel. Source channels 348 * can be duplicated by using the same index for multiple input channels. 349 * 350 * Examples: 351 * 352 * Reordering 5.1 AAC order (C,L,R,Ls,Rs,LFE) to FFmpeg order (L,R,C,LFE,Ls,Rs): 353 * { 1, 2, 0, 5, 3, 4 } 354 * 355 * Muting the 3rd channel in 4-channel input: 356 * { 0, 1, -1, 3 } 357 * 358 * Duplicating the left channel of stereo input: 359 * { 0, 0 } 360 * 361 * @param avr audio resample context 362 * @param channel_map customized input channel mapping 363 * @return 0 on success, negative AVERROR code on failure 364 */ 365 attribute_deprecated 366 int avresample_set_channel_mapping(AVAudioResampleContext *avr, 367 const int *channel_map); 368 369 /** 370 * 371 * @deprecated use libswresample 372 * 373 * Set compensation for resampling. 374 * 375 * This can be called anytime after avresample_open(). If resampling is not 376 * automatically enabled because of a sample rate conversion, the 377 * "force_resampling" option must have been set to 1 when opening the context 378 * in order to use resampling compensation. 379 * 380 * @param avr audio resample context 381 * @param sample_delta compensation delta, in samples 382 * @param compensation_distance compensation distance, in samples 383 * @return 0 on success, negative AVERROR code on failure 384 */ 385 attribute_deprecated 386 int avresample_set_compensation(AVAudioResampleContext *avr, int sample_delta, 387 int compensation_distance); 388 389 /** 390 * 391 * @deprecated use libswresample 392 * 393 * Provide the upper bound on the number of samples the configured 394 * conversion would output. 395 * 396 * @param avr audio resample context 397 * @param in_nb_samples number of input samples 398 * 399 * @return number of samples or AVERROR(EINVAL) if the value 400 * would exceed INT_MAX 401 */ 402 attribute_deprecated 403 int avresample_get_out_samples(AVAudioResampleContext *avr, int in_nb_samples); 404 405 /** 406 * 407 * @deprecated use libswresample 408 * 409 * Convert input samples and write them to the output FIFO. 410 * 411 * The upper bound on the number of output samples can be obtained through 412 * avresample_get_out_samples(). 413 * 414 * The output data can be NULL or have fewer allocated samples than required. 415 * In this case, any remaining samples not written to the output will be added 416 * to an internal FIFO buffer, to be returned at the next call to this function 417 * or to avresample_read(). 418 * 419 * If converting sample rate, there may be data remaining in the internal 420 * resampling delay buffer. avresample_get_delay() tells the number of remaining 421 * samples. To get this data as output, call avresample_convert() with NULL 422 * input. 423 * 424 * At the end of the conversion process, there may be data remaining in the 425 * internal FIFO buffer. avresample_available() tells the number of remaining 426 * samples. To get this data as output, either call avresample_convert() with 427 * NULL input or call avresample_read(). 428 * 429 * @see avresample_get_out_samples() 430 * @see avresample_read() 431 * @see avresample_get_delay() 432 * 433 * @param avr audio resample context 434 * @param output output data pointers 435 * @param out_plane_size output plane size, in bytes. 436 * This can be 0 if unknown, but that will lead to 437 * optimized functions not being used directly on the 438 * output, which could slow down some conversions. 439 * @param out_samples maximum number of samples that the output buffer can hold 440 * @param input input data pointers 441 * @param in_plane_size input plane size, in bytes 442 * This can be 0 if unknown, but that will lead to 443 * optimized functions not being used directly on the 444 * input, which could slow down some conversions. 445 * @param in_samples number of input samples to convert 446 * @return number of samples written to the output buffer, 447 * not including converted samples added to the internal 448 * output FIFO 449 */ 450 attribute_deprecated 451 int avresample_convert(AVAudioResampleContext *avr, uint8_t **output, 452 int out_plane_size, int out_samples, 453 uint8_t * const *input, int in_plane_size, 454 int in_samples); 455 456 /** 457 * 458 * @deprecated use libswresample 459 * 460 * Return the number of samples currently in the resampling delay buffer. 461 * 462 * When resampling, there may be a delay between the input and output. Any 463 * unconverted samples in each call are stored internally in a delay buffer. 464 * This function allows the user to determine the current number of samples in 465 * the delay buffer, which can be useful for synchronization. 466 * 467 * @see avresample_convert() 468 * 469 * @param avr audio resample context 470 * @return number of samples currently in the resampling delay buffer 471 */ 472 attribute_deprecated 473 int avresample_get_delay(AVAudioResampleContext *avr); 474 475 /** 476 * 477 * @deprecated use libswresample 478 * 479 * Return the number of available samples in the output FIFO. 480 * 481 * During conversion, if the user does not specify an output buffer or 482 * specifies an output buffer that is smaller than what is needed, remaining 483 * samples that are not written to the output are stored to an internal FIFO 484 * buffer. The samples in the FIFO can be read with avresample_read() or 485 * avresample_convert(). 486 * 487 * @see avresample_read() 488 * @see avresample_convert() 489 * 490 * @param avr audio resample context 491 * @return number of samples available for reading 492 */ 493 attribute_deprecated 494 int avresample_available(AVAudioResampleContext *avr); 495 496 /** 497 * 498 * @deprecated use libswresample 499 * 500 * Read samples from the output FIFO. 501 * 502 * During conversion, if the user does not specify an output buffer or 503 * specifies an output buffer that is smaller than what is needed, remaining 504 * samples that are not written to the output are stored to an internal FIFO 505 * buffer. This function can be used to read samples from that internal FIFO. 506 * 507 * @see avresample_available() 508 * @see avresample_convert() 509 * 510 * @param avr audio resample context 511 * @param output output data pointers. May be NULL, in which case 512 * nb_samples of data is discarded from output FIFO. 513 * @param nb_samples number of samples to read from the FIFO 514 * @return the number of samples written to output 515 */ 516 attribute_deprecated 517 int avresample_read(AVAudioResampleContext *avr, uint8_t **output, int nb_samples); 518 519 /** 520 * 521 * @deprecated use libswresample 522 * 523 * Convert the samples in the input AVFrame and write them to the output AVFrame. 524 * 525 * Input and output AVFrames must have channel_layout, sample_rate and format set. 526 * 527 * The upper bound on the number of output samples is obtained through 528 * avresample_get_out_samples(). 529 * 530 * If the output AVFrame does not have the data pointers allocated the nb_samples 531 * field will be set using avresample_get_out_samples() and av_frame_get_buffer() 532 * is called to allocate the frame. 533 * 534 * The output AVFrame can be NULL or have fewer allocated samples than required. 535 * In this case, any remaining samples not written to the output will be added 536 * to an internal FIFO buffer, to be returned at the next call to this function 537 * or to avresample_convert() or to avresample_read(). 538 * 539 * If converting sample rate, there may be data remaining in the internal 540 * resampling delay buffer. avresample_get_delay() tells the number of 541 * remaining samples. To get this data as output, call this function or 542 * avresample_convert() with NULL input. 543 * 544 * At the end of the conversion process, there may be data remaining in the 545 * internal FIFO buffer. avresample_available() tells the number of remaining 546 * samples. To get this data as output, either call this function or 547 * avresample_convert() with NULL input or call avresample_read(). 548 * 549 * If the AVAudioResampleContext configuration does not match the output and 550 * input AVFrame settings the conversion does not take place and depending on 551 * which AVFrame is not matching AVERROR_OUTPUT_CHANGED, AVERROR_INPUT_CHANGED 552 * or AVERROR_OUTPUT_CHANGED|AVERROR_INPUT_CHANGED is returned. 553 * 554 * @see avresample_get_out_samples() 555 * @see avresample_available() 556 * @see avresample_convert() 557 * @see avresample_read() 558 * @see avresample_get_delay() 559 * 560 * @param avr audio resample context 561 * @param output output AVFrame 562 * @param input input AVFrame 563 * @return 0 on success, AVERROR on failure or nonmatching 564 * configuration. 565 */ 566 attribute_deprecated 567 int avresample_convert_frame(AVAudioResampleContext *avr, 568 AVFrame *output, AVFrame *input); 569 570 /** 571 * 572 * @deprecated use libswresample 573 * 574 * Configure or reconfigure the AVAudioResampleContext using the information 575 * provided by the AVFrames. 576 * 577 * The original resampling context is reset even on failure. 578 * The function calls avresample_close() internally if the context is open. 579 * 580 * @see avresample_open(); 581 * @see avresample_close(); 582 * 583 * @param avr audio resample context 584 * @param out output AVFrame 585 * @param in input AVFrame 586 * @return 0 on success, AVERROR on failure. 587 */ 588 attribute_deprecated 589 int avresample_config(AVAudioResampleContext *avr, AVFrame *out, AVFrame *in); 590 591 /** 592 * @} 593 */ 594 595 #endif /* AVRESAMPLE_AVRESAMPLE_H */ 596