gst-libs/gst/audio/audio-resampler.h

   1 /* GStreamer
   2  * Copyright (C) <2015> Wim Taymans <wim.taymans@gmail.com>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  17  * Boston, MA 02110-1301, USA.
  18  */
  19
  20 #ifndef __GST_AUDIO_RESAMPLER_H__
  21 #define __GST_AUDIO_RESAMPLER_H__
  22
  23 #include <gst/gst.h>
  24 #include <gst/audio/audio.h>
  25
  26 G_BEGIN_DECLS
  27
  28 typedef struct _GstAudioResampler GstAudioResampler;
  29
  30 /**
  31  * GST_AUDIO_RESAMPLER_OPT_CUTOFF
  32  *
  33  * G_TYPE_DOUBLE, Cutoff parameter for the filter. 0.940 is the default.
  34  */
  35 #define GST_AUDIO_RESAMPLER_OPT_CUTOFF      "GstAudioResampler.cutoff"
  36 /**
  37  * GST_AUDIO_RESAMPLER_OPT_STOP_ATTENUTATION
  38  *
  39  * G_TYPE_DOUBLE, stopband attenuation in debibels. The attenutation
  40  * after the stopband for the kaiser window. 85 dB is the default.
  41  */
  42 #define GST_AUDIO_RESAMPLER_OPT_STOP_ATTENUATION "GstAudioResampler.stop-attenutation"
  43 /**
  44  * GST_AUDIO_RESAMPLER_OPT_TRANSITION_BANDWIDTH
  45  *
  46  * G_TYPE_DOUBLE, transition bandwidth. The width of the
  47  * transition band for the kaiser window. 0.087 is the default.
  48  */
  49 #define GST_AUDIO_RESAMPLER_OPT_TRANSITION_BANDWIDTH "GstAudioResampler.transition-bandwidth"
  50
  51 /**
  52  * GST_AUDIO_RESAMPLER_OPT_CUBIC_B:
  53  *
  54  * G_TYPE_DOUBLE, B parameter of the cubic filter.
  55  * Values between 0.0 and 2.0 are accepted. 1.0 is the default.
  56  *
  57  * Below are some values of popular filters:
  58  *                    B       C
  59  * Hermite           0.0     0.0
  60  * Spline            1.0     0.0
  61  * Catmull-Rom       0.0     1/2
  62  */
  63 #define GST_AUDIO_RESAMPLER_OPT_CUBIC_B      "GstAudioResampler.cubic-b"
  64 /**
  65  * GST_AUDIO_RESAMPLER_OPT_CUBIC_C:
  66  *
  67  * G_TYPE_DOUBLE, C parameter of the cubic filter.
  68  * Values between 0.0 and 2.0 are accepted. 0.0 is the default.
  69  *
  70  * See #GST_AUDIO_RESAMPLER_OPT_CUBIC_B for some more common values
  71  */
  72 #define GST_AUDIO_RESAMPLER_OPT_CUBIC_C      "GstAudioResampler.cubic-c"
  73
  74 /**
  75  * GST_AUDIO_RESAMPLER_OPT_N_TAPS:
  76  *
  77  * G_TYPE_INT: the number of taps to use for the filter.
  78  * 0 is the default and selects the taps automatically.
  79  */
  80 #define GST_AUDIO_RESAMPLER_OPT_N_TAPS      "GstAudioResampler.n-taps"
  81
  82 /**
  83  * GstAudioResamplerFilterMode:
  84  * @GST_AUDIO_RESAMPLER_FILTER_MODE_INTERPOLATED: Use interpolated filter tables. This
  85  *     uses less memory but more CPU and is slightly less accurate.
  86  * @GST_AUDIO_RESAMPLER_FILTER_MODE_FULL: Use full filter table. This uses more memory
  87  *     but less CPU.
  88  * @GST_AUDIO_RESAMPLER_FILTER_MODE_AUTO: Automatically choose between interpolated
  89  *     and full filter tables.
  90  *
  91  * Select for the filter tables should be set up.
  92  */
  93 typedef enum {
  94   GST_AUDIO_RESAMPLER_FILTER_MODE_INTERPOLATED = (0),
  95   GST_AUDIO_RESAMPLER_FILTER_MODE_FULL,
  96   GST_AUDIO_RESAMPLER_FILTER_MODE_AUTO,
  97 } GstAudioResamplerFilterMode;
  98 /**
  99  * GST_AUDIO_RESAMPLER_OPT_FILTER_MODE:
 100  *
 101  * GST_TYPE_AUDIO_RESAMPLER_FILTER_MODE: how the filter tables should be
 102  * constructed.
 103  * GST_AUDIO_RESAMPLER_FILTER_MODE_AUTO is the default.
 104  */
 105 #define GST_AUDIO_RESAMPLER_OPT_FILTER_MODE      "GstAudioResampler.filter-mode"
 106 /**
 107  * GST_AUDIO_RESAMPLER_OPT_FILTER_MODE_THRESHOLD:
 108  *
 109  * G_TYPE_UINT: the amount of memory to use for full filter tables before
 110  * switching to interpolated filter tables.
 111  * 1048576 is the default.
 112  */
 113 #define GST_AUDIO_RESAMPLER_OPT_FILTER_MODE_THRESHOLD "GstAudioResampler.filter-mode-threshold"
 114
 115 /**
 116  * GstAudioResamplerMethod:
 117  * @GST_AUDIO_RESAMPLER_METHOD_NEAREST: Duplicates the samples when
 118  *    upsampling and drops when downsampling
 119  * @GST_AUDIO_RESAMPLER_METHOD_LINEAR: Uses linear interpolation to reconstruct
 120  *    missing samples and averaging to downsample
 121  * @GST_AUDIO_RESAMPLER_METHOD_CUBIC: Uses cubic interpolation
 122  * @GST_AUDIO_RESAMPLER_METHOD_BLACKMAN_NUTTALL: Uses Blackman-Nuttall windowed sinc interpolation
 123  * @GST_AUDIO_RESAMPLER_METHOD_KAISER: Uses Kaiser windowed sinc interpolation
 124  *
 125  * Different subsampling and upsampling methods
 126  *
 127  * Since: 1.6
 128  */
 129 typedef enum {
 130   GST_AUDIO_RESAMPLER_METHOD_NEAREST,
 131   GST_AUDIO_RESAMPLER_METHOD_LINEAR,
 132   GST_AUDIO_RESAMPLER_METHOD_CUBIC,
 133   GST_AUDIO_RESAMPLER_METHOD_BLACKMAN_NUTTALL,
 134   GST_AUDIO_RESAMPLER_METHOD_KAISER
 135 } GstAudioResamplerMethod;
 136
 137 /**
 138  * GstAudioResamplerFlags:
 139  * @GST_AUDIO_RESAMPLER_FLAG_NONE: no flags
 140  * @GST_AUDIO_RESAMPLER_FLAG_NON_INTERLEAVED: samples are non-interleaved. an array
 141  *    of blocks of samples, one for each channel, should be passed to the resample
 142  *    function.
 143  *
 144  * Different resampler flags.
 145  */
 146 typedef enum {
 147   GST_AUDIO_RESAMPLER_FLAG_NONE                 = (0),
 148   GST_AUDIO_RESAMPLER_FLAG_NON_INTERLEAVED      = (1 << 0),
 149 } GstAudioResamplerFlags;
 150
 151 #define GST_AUDIO_RESAMPLER_QUALITY_MIN 0
 152 #define GST_AUDIO_RESAMPLER_QUALITY_MAX 10
 153 #define GST_AUDIO_RESAMPLER_QUALITY_DEFAULT 4
 154
 155 void           gst_audio_resampler_options_set_quality   (GstAudioResamplerMethod method,
 156                                                           guint quality,
 157                                                           gint in_rate, gint out_rate,
 158                                                           GstStructure *options);
 159
 160 GstAudioResampler * gst_audio_resampler_new              (GstAudioResamplerMethod method,
 161                                                           GstAudioResamplerFlags flags,
 162                                                           GstAudioFormat format, gint channels,
 163                                                           gint in_rate, gint out_rate,
 164                                                           GstStructure *options);
 165 void                gst_audio_resampler_free             (GstAudioResampler *resampler);
 166
 167 void                gst_audio_resampler_reset            (GstAudioResampler *resampler);
 168
 169 gboolean            gst_audio_resampler_update           (GstAudioResampler *resampler,
 170                                                           gint in_rate, gint out_rate,
 171                                                           GstStructure *options);
 172
 173 gsize               gst_audio_resampler_get_out_frames   (GstAudioResampler *resampler,
 174                                                           gsize in_frames);
 175 gsize               gst_audio_resampler_get_in_frames    (GstAudioResampler *resampler,
 176                                                           gsize out_frames);
 177
 178 gsize               gst_audio_resampler_get_max_latency  (GstAudioResampler *resampler);
 179
 180 void                gst_audio_resampler_resample         (GstAudioResampler * resampler,
 181                                                           gpointer in[], gsize in_frames,
 182                                                           gpointer out[], gsize out_frames);
 183
 184 G_END_DECLS
 185
 186 #endif /* __GST_AUDIO_RESAMPLER_H__ */