Merge commit 'b200a2c8da403b5a5c8b50f8cb4a75fd4f0131b1'
authorJames Almer <jamrial@gmail.com>
Thu, 26 Oct 2017 19:58:39 +0000 (16:58 -0300)
committerJames Almer <jamrial@gmail.com>
Thu, 26 Oct 2017 20:03:09 +0000 (17:03 -0300)
* commit 'b200a2c8da403b5a5c8b50f8cb4a75fd4f0131b1':
  examples: Fixed and extended Doxygen documentation

Merged-by: James Almer <jamrial@gmail.com>
1  2 
doc/examples/transcode_aac.c

@@@ -1,14 -1,16 +1,16 @@@
  /*
 - * This file is part of Libav.
+  * Copyright (c) 2013-2017 Andreas Unterweger
+  *
 + * This file is part of FFmpeg.
   *
 - * Libav is free software; you can redistribute it and/or
 + * FFmpeg is free software; you can redistribute it and/or
   * modify it under the terms of the GNU Lesser General Public
   * License as published by the Free Software Foundation; either
   * version 2.1 of the License, or (at your option) any later version.
   *
 - * Libav is distributed in the hope that it will be useful,
 + * FFmpeg is distributed in the hope that it will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
-  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   * Lesser General Public License for more details.
   *
   * You should have received a copy of the GNU Lesser General Public
  
  /**
   * @file
-  * simple audio converter
+  * Simple audio converter
   *
   * @example transcode_aac.c
 - * Convert an input audio file to AAC in an MP4 container using Libav.
 + * Convert an input audio file to AAC in an MP4 container using FFmpeg.
+  * Formats other than MP4 are supported based on the output file extension.
   * @author Andreas Unterweger (dustsigns@gmail.com)
   */
  
  #include "libavutil/frame.h"
  #include "libavutil/opt.h"
  
 -#include "libavresample/avresample.h"
 +#include "libswresample/swresample.h"
  
- /** The output bit rate in kbit/s */
+ /* The output bit rate in bit/s */
  #define OUTPUT_BIT_RATE 96000
- /** The number of output channels */
+ /* The number of output channels */
  #define OUTPUT_CHANNELS 2
  
- /** Open an input file and the required decoder. */
+ /**
 - * Convert an error code into a text message.
 - * @param error Error code to be converted
 - * @return Corresponding error text (not thread-safe)
 - */
 -static char *get_error_text(const int error)
 -{
 -    static char error_buffer[255];
 -    av_strerror(error, error_buffer, sizeof(error_buffer));
 -    return error_buffer;
 -}
 -
 -/**
+  * Open an input file and the required decoder.
+  * @param      filename             File to be opened
+  * @param[out] input_format_context Format context of opened file
+  * @param[out] input_codec_context  Codec context of opened file
+  * @return Error code (0 if successful)
+  */
  static int open_input_file(const char *filename,
                             AVFormatContext **input_format_context,
                             AVCodecContext **input_codec_context)
          return error;
      }
  
-     /** Get information on the input file (number of streams etc.). */
+     /* Get information on the input file (number of streams etc.). */
      if ((error = avformat_find_stream_info(*input_format_context, NULL)) < 0) {
          fprintf(stderr, "Could not open find stream info (error '%s')\n",
 -                get_error_text(error));
 +                av_err2str(error));
          avformat_close_input(input_format_context);
          return error;
      }
          return error;
      }
  
-     /** Open the decoder for the audio stream to use it later. */
+     /* Open the decoder for the audio stream to use it later. */
      if ((error = avcodec_open2(avctx, input_codec, NULL)) < 0) {
          fprintf(stderr, "Could not open input codec (error '%s')\n",
 -                get_error_text(error));
 +                av_err2str(error));
          avcodec_free_context(&avctx);
          avformat_close_input(input_format_context);
          return error;
@@@ -204,10 -225,10 +214,10 @@@ static int open_output_file(const char 
      if ((*output_format_context)->oformat->flags & AVFMT_GLOBALHEADER)
          avctx->flags |= AV_CODEC_FLAG_GLOBAL_HEADER;
  
-     /** Open the encoder for the audio stream to use it later. */
+     /* Open the encoder for the audio stream to use it later. */
      if ((error = avcodec_open2(avctx, output_codec, NULL)) < 0) {
          fprintf(stderr, "Could not open output codec (error '%s')\n",
 -                get_error_text(error));
 +                av_err2str(error));
          goto cleanup;
      }
  
@@@ -252,46 -280,53 +269,50 @@@ static int init_input_frame(AVFrame **f
  /**
   * Initialize the audio resampler based on the input and output codec settings.
   * If the input and output sample formats differ, a conversion is required
 - * libavresample takes care of this, but requires initialization.
 + * libswresample takes care of this, but requires initialization.
+  * @param      input_codec_context  Codec context of the input file
+  * @param      output_codec_context Codec context of the output file
+  * @param[out] resample_context     Resample context for the required conversion
+  * @return Error code (0 if successful)
   */
  static int init_resampler(AVCodecContext *input_codec_context,
                            AVCodecContext *output_codec_context,
 -                          AVAudioResampleContext **resample_context)
 +                          SwrContext **resample_context)
  {
 -    /* Only initialize the resampler if it is necessary, i.e.,
 -     * if and only if the sample formats differ. */
 -    if (input_codec_context->sample_fmt != output_codec_context->sample_fmt ||
 -        input_codec_context->channels != output_codec_context->channels) {
          int error;
  
-         /**
 -        /* Create a resampler context for the conversion. */
 -        if (!(*resample_context = avresample_alloc_context())) {
 -            fprintf(stderr, "Could not allocate resample context\n");
 -            return AVERROR(ENOMEM);
 -        }
 -
 -        /* Set the conversion parameters.
++        /*
 +         * Create a resampler context for the conversion.
 +         * Set the conversion parameters.
           * Default channel layouts based on the number of channels
           * are assumed for simplicity (they are sometimes not detected
           * properly by the demuxer and/or decoder).
           */
 -        av_opt_set_int(*resample_context, "in_channel_layout",
 -                       av_get_default_channel_layout(input_codec_context->channels), 0);
 -        av_opt_set_int(*resample_context, "out_channel_layout",
 -                       av_get_default_channel_layout(output_codec_context->channels), 0);
 -        av_opt_set_int(*resample_context, "in_sample_rate",
 -                       input_codec_context->sample_rate, 0);
 -        av_opt_set_int(*resample_context, "out_sample_rate",
 -                       output_codec_context->sample_rate, 0);
 -        av_opt_set_int(*resample_context, "in_sample_fmt",
 -                       input_codec_context->sample_fmt, 0);
 -        av_opt_set_int(*resample_context, "out_sample_fmt",
 -                       output_codec_context->sample_fmt, 0);
 +        *resample_context = swr_alloc_set_opts(NULL,
 +                                              av_get_default_channel_layout(output_codec_context->channels),
 +                                              output_codec_context->sample_fmt,
 +                                              output_codec_context->sample_rate,
 +                                              av_get_default_channel_layout(input_codec_context->channels),
 +                                              input_codec_context->sample_fmt,
 +                                              input_codec_context->sample_rate,
 +                                              0, NULL);
 +        if (!*resample_context) {
 +            fprintf(stderr, "Could not allocate resample context\n");
 +            return AVERROR(ENOMEM);
 +        }
-         /**
++        /*
 +        * Perform a sanity check so that the number of converted samples is
 +        * not greater than the number of samples to be converted.
 +        * If the sample rates differ, this case has to be handled differently
 +        */
 +        av_assert0(output_codec_context->sample_rate == input_codec_context->sample_rate);
  
-         /** Open the resampler with the specified parameters. */
+         /* Open the resampler with the specified parameters. */
 -        if ((error = avresample_open(*resample_context)) < 0) {
 +        if ((error = swr_init(*resample_context)) < 0) {
              fprintf(stderr, "Could not open resample context\n");
 -            avresample_free(resample_context);
 +            swr_free(resample_context);
              return error;
          }
 -    }
      return 0;
  }
  
@@@ -330,9 -386,9 +372,9 @@@ static int decode_audio_frame(AVFrame *
      int error;
      init_packet(&input_packet);
  
-     /** Read one audio frame from the input file into a temporary packet. */
+     /* Read one audio frame from the input file into a temporary packet. */
      if ((error = av_read_frame(input_format_context, &input_packet)) < 0) {
-         /** If we are at the end of the file, flush the decoder below. */
 -        /* If we are the the end of the file, flush the decoder below. */
++        /* If we are at the end of the file, flush the decoder below. */
          if (error == AVERROR_EOF)
              *finished = 1;
          else {
@@@ -408,21 -464,27 +450,28 @@@ static int init_converted_samples(uint8
  
  /**
   * Convert the input audio samples into the output sample format.
-  * The conversion happens on a per-frame basis, the size of which is specified
-  * by frame_size.
+  * The conversion happens on a per-frame basis, the size of which is
+  * specified by frame_size.
+  * @param      input_data       Samples to be decoded. The dimensions are
+  *                              channel (for multi-channel audio), sample.
+  * @param[out] converted_data   Converted samples. The dimensions are channel
+  *                              (for multi-channel audio), sample.
+  * @param      frame_size       Number of samples to be converted
+  * @param      resample_context Resample context for the conversion
+  * @return Error code (0 if successful)
   */
 -static int convert_samples(uint8_t **input_data,
 +static int convert_samples(const uint8_t **input_data,
                             uint8_t **converted_data, const int frame_size,
 -                           AVAudioResampleContext *resample_context)
 +                           SwrContext *resample_context)
  {
      int error;
  
-     /** Convert the samples using the resampler. */
+     /* Convert the samples using the resampler. */
 -    if ((error = avresample_convert(resample_context, converted_data, 0,
 -                                    frame_size, input_data, 0, frame_size)) < 0) {
 +    if ((error = swr_convert(resample_context,
 +                             converted_data, frame_size,
 +                             input_data    , frame_size)) < 0) {
          fprintf(stderr, "Could not convert input samples (error '%s')\n",
 -                get_error_text(error));
 +                av_err2str(error));
          return error;
      }
  
@@@ -455,19 -530,31 +509,31 @@@ static int add_samples_to_fifo(AVAudioF
  }
  
  /**
-  * Read one audio frame from the input file, decodes, converts and stores
+  * Read one audio frame from the input file, decode, convert and store
   * it in the FIFO buffer.
 - * @param      resample_context     Resample context for the conversion
+  * @param      fifo                 Buffer used for temporary storage
+  * @param      input_format_context Format context of the input file
+  * @param      input_codec_context  Codec context of the input file
+  * @param      output_codec_context Codec context of the output file
++ * @param      resampler_context    Resample context for the conversion
+  * @param[out] finished             Indicates whether the end of file has
+  *                                  been reached and all data has been
+  *                                  decoded. If this flag is false,
+  *                                  there is more data to be decoded,
+  *                                  i.e., this function has to be called
+  *                                  again.
+  * @return Error code (0 if successful)
   */
  static int read_decode_convert_and_store(AVAudioFifo *fifo,
                                           AVFormatContext *input_format_context,
                                           AVCodecContext *input_codec_context,
                                           AVCodecContext *output_codec_context,
 -                                         AVAudioResampleContext *resample_context,
 +                                         SwrContext *resampler_context,
                                           int *finished)
  {
-     /** Temporary storage of the input samples of the frame read from the file. */
+     /* Temporary storage of the input samples of the frame read from the file. */
      AVFrame *input_frame = NULL;
-     /** Temporary storage for the converted input samples. */
+     /* Temporary storage for the converted input samples. */
      uint8_t **converted_input_samples = NULL;
      int data_present;
      int ret = AVERROR_EXIT;
                                     input_frame->nb_samples))
              goto cleanup;
  
-         /**
-          * Convert the input samples to the desired output sample format.
-          * This requires a temporary storage provided by converted_input_samples.
-          */
+         /* Convert the input samples to the desired output sample format.
+          * This requires a temporary storage provided by converted_input_samples. */
 -        if (convert_samples(input_frame->extended_data, converted_input_samples,
 -                            input_frame->nb_samples, resample_context))
 +        if (convert_samples((const uint8_t**)input_frame->extended_data, converted_input_samples,
 +                            input_frame->nb_samples, resampler_context))
              goto cleanup;
  
-         /** Add the converted input samples to the FIFO buffer for later processing. */
+         /* Add the converted input samples to the FIFO buffer for later processing. */
          if (add_samples_to_fifo(fifo, converted_input_samples,
                                  input_frame->nb_samples))
              goto cleanup;
@@@ -549,13 -634,11 +613,11 @@@ static int init_output_frame(AVFrame **
      (*frame)->format         = output_codec_context->sample_fmt;
      (*frame)->sample_rate    = output_codec_context->sample_rate;
  
-     /**
-      * Allocate the samples of the created frame. This call will make
-      * sure that the audio frame can hold as many samples as specified.
-      */
+     /* Allocate the samples of the created frame. This call will make
+      * sure that the audio frame can hold as many samples as specified. */
      if ((error = av_frame_get_buffer(*frame, 0)) < 0) {
          fprintf(stderr, "Could not allocate output frame samples (error '%s')\n",
 -                get_error_text(error));
 +                av_err2str(error));
          av_frame_free(frame);
          return error;
      }