git.sesse.net Git - ffmpeg/blob - libavfilter/ebur128.h

   1 /*
   2  * Copyright (c) 2011 Jan Kokemüller
   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  * This file is based on libebur128 which is available at
  21  * https://github.com/jiixyj/libebur128/
  22  *
  23 */
  24
  25 #ifndef AVFILTER_EBUR128_H
  26 #define AVFILTER_EBUR128_H
  27
  28 /** \file ebur128.h
  29  *  \brief libebur128 - a library for loudness measurement according to
  30  *         the EBU R128 standard.
  31  */
  32
  33 #include <stddef.h>             /* for size_t */
  34
  35 /** \enum channel
  36  *  Use these values when setting the channel map with ebur128_set_channel().
  37  *  See definitions in ITU R-REC-BS 1770-4
  38  */
  39 enum channel {
  40     FF_EBUR128_UNUSED = 0,   /**< unused channel (for example LFE channel) */
  41     FF_EBUR128_LEFT,
  42     FF_EBUR128_Mp030 = 1,    /**< itu M+030 */
  43     FF_EBUR128_RIGHT,
  44     FF_EBUR128_Mm030 = 2,    /**< itu M-030 */
  45     FF_EBUR128_CENTER,
  46     FF_EBUR128_Mp000 = 3,    /**< itu M+000 */
  47     FF_EBUR128_LEFT_SURROUND,
  48     FF_EBUR128_Mp110 = 4,    /**< itu M+110 */
  49     FF_EBUR128_RIGHT_SURROUND,
  50     FF_EBUR128_Mm110 = 5,    /**< itu M-110 */
  51     FF_EBUR128_DUAL_MONO,    /**< a channel that is counted twice */
  52     FF_EBUR128_MpSC,         /**< itu M+SC */
  53     FF_EBUR128_MmSC,         /**< itu M-SC */
  54     FF_EBUR128_Mp060,        /**< itu M+060 */
  55     FF_EBUR128_Mm060,        /**< itu M-060 */
  56     FF_EBUR128_Mp090,        /**< itu M+090 */
  57     FF_EBUR128_Mm090,        /**< itu M-090 */
  58     FF_EBUR128_Mp135,        /**< itu M+135 */
  59     FF_EBUR128_Mm135,        /**< itu M-135 */
  60     FF_EBUR128_Mp180,        /**< itu M+180 */
  61     FF_EBUR128_Up000,        /**< itu U+000 */
  62     FF_EBUR128_Up030,        /**< itu U+030 */
  63     FF_EBUR128_Um030,        /**< itu U-030 */
  64     FF_EBUR128_Up045,        /**< itu U+045 */
  65     FF_EBUR128_Um045,        /**< itu U-030 */
  66     FF_EBUR128_Up090,        /**< itu U+090 */
  67     FF_EBUR128_Um090,        /**< itu U-090 */
  68     FF_EBUR128_Up110,        /**< itu U+110 */
  69     FF_EBUR128_Um110,        /**< itu U-110 */
  70     FF_EBUR128_Up135,        /**< itu U+135 */
  71     FF_EBUR128_Um135,        /**< itu U-135 */
  72     FF_EBUR128_Up180,        /**< itu U+180 */
  73     FF_EBUR128_Tp000,        /**< itu T+000 */
  74     FF_EBUR128_Bp000,        /**< itu B+000 */
  75     FF_EBUR128_Bp045,        /**< itu B+045 */
  76     FF_EBUR128_Bm045         /**< itu B-045 */
  77 };
  78
  79 /** \enum mode
  80  *  Use these values in ebur128_init (or'ed). Try to use the lowest possible
  81  *  modes that suit your needs, as performance will be better.
  82  */
  83 enum mode {
  84   /** can resurrrect and call ff_ebur128_loudness_momentary */
  85     FF_EBUR128_MODE_M = (1 << 0),
  86   /** can call ff_ebur128_loudness_shortterm */
  87     FF_EBUR128_MODE_S = (1 << 1) | FF_EBUR128_MODE_M,
  88   /** can call ff_ebur128_loudness_global_* and ff_ebur128_relative_threshold */
  89     FF_EBUR128_MODE_I = (1 << 2) | FF_EBUR128_MODE_M,
  90   /** can call ff_ebur128_loudness_range */
  91     FF_EBUR128_MODE_LRA = (1 << 3) | FF_EBUR128_MODE_S,
  92   /** can call ff_ebur128_sample_peak */
  93     FF_EBUR128_MODE_SAMPLE_PEAK = (1 << 4) | FF_EBUR128_MODE_M,
  94 };
  95
  96 /** forward declaration of FFEBUR128StateInternal */
  97 struct FFEBUR128StateInternal;
  98
  99 /** \brief Contains information about the state of a loudness measurement.
 100  *
 101  *  You should not need to modify this struct directly.
 102  */
 103 typedef struct FFEBUR128State {
 104     int mode;                         /**< The current mode. */
 105     unsigned int channels;            /**< The number of channels. */
 106     unsigned long samplerate;         /**< The sample rate. */
 107     struct FFEBUR128StateInternal *d; /**< Internal state. */
 108 } FFEBUR128State;
 109
 110 /** \brief Initialize library state.
 111  *
 112  *  @param channels the number of channels.
 113  *  @param samplerate the sample rate.
 114  *  @param window set the maximum window size in ms, set to 0 for auto.
 115  *  @param mode see the mode enum for possible values.
 116  *  @return an initialized library state.
 117  */
 118 FFEBUR128State *ff_ebur128_init(unsigned int channels,
 119                                 unsigned long samplerate,
 120                                 unsigned long window, int mode);
 121
 122 /** \brief Destroy library state.
 123  *
 124  *  @param st pointer to a library state.
 125  */
 126 void ff_ebur128_destroy(FFEBUR128State ** st);
 127
 128 /** \brief Set channel type.
 129  *
 130  *  The default is:
 131  *  - 0 -> FF_EBUR128_LEFT
 132  *  - 1 -> FF_EBUR128_RIGHT
 133  *  - 2 -> FF_EBUR128_CENTER
 134  *  - 3 -> FF_EBUR128_UNUSED
 135  *  - 4 -> FF_EBUR128_LEFT_SURROUND
 136  *  - 5 -> FF_EBUR128_RIGHT_SURROUND
 137  *
 138  *  @param st library state.
 139  *  @param channel_number zero based channel index.
 140  *  @param value channel type from the "channel" enum.
 141  *  @return
 142  *    - 0 on success.
 143  *    - AVERROR(EINVAL) if invalid channel index.
 144  */
 145 int ff_ebur128_set_channel(FFEBUR128State * st,
 146                            unsigned int channel_number, int value);
 147
 148 /** \brief Add frames to be processed.
 149  *
 150  *  @param st library state.
 151  *  @param src array of source frames. Channels must be interleaved.
 152  *  @param frames number of frames. Not number of samples!
 153  */
 154 void ff_ebur128_add_frames_double(FFEBUR128State * st,
 155                                   const double *src, size_t frames);
 156
 157 /** \brief Get global integrated loudness in LUFS.
 158  *
 159  *  @param st library state.
 160  *  @param out integrated loudness in LUFS. -HUGE_VAL if result is negative
 161  *             infinity.
 162  *  @return
 163  *    - 0 on success.
 164  *    - AVERROR(EINVAL) if mode "FF_EBUR128_MODE_I" has not been set.
 165  */
 166 int ff_ebur128_loudness_global(FFEBUR128State * st, double *out);
 167
 168 /** \brief Get short-term loudness (last 3s) in LUFS.
 169  *
 170  *  @param st library state.
 171  *  @param out short-term loudness in LUFS. -HUGE_VAL if result is negative
 172  *             infinity.
 173  *  @return
 174  *    - 0 on success.
 175  *    - AVERROR(EINVAL) if mode "FF_EBUR128_MODE_S" has not been set.
 176  */
 177 int ff_ebur128_loudness_shortterm(FFEBUR128State * st, double *out);
 178
 179 /** \brief Get loudness range (LRA) of programme in LU.
 180  *
 181  *  Calculates loudness range according to EBU 3342.
 182  *
 183  *  @param st library state.
 184  *  @param out loudness range (LRA) in LU. Will not be changed in case of
 185  *             error. AVERROR(EINVAL) will be returned in this case.
 186  *  @return
 187  *    - 0 on success.
 188  *    - AVERROR(EINVAL) if mode "FF_EBUR128_MODE_LRA" has not been set.
 189  */
 190 int ff_ebur128_loudness_range(FFEBUR128State * st, double *out);
 191 /** \brief Get loudness range (LRA) in LU across multiple instances.
 192  *
 193  *  Calculates loudness range according to EBU 3342.
 194  *
 195  *  @param sts array of library states.
 196  *  @param size length of sts
 197  *  @param out loudness range (LRA) in LU. Will not be changed in case of
 198  *             error. AVERROR(EINVAL) will be returned in this case.
 199  *  @return
 200  *    - 0 on success.
 201  *    - AVERROR(EINVAL) if mode "FF_EBUR128_MODE_LRA" has not been set.
 202  */
 203 int ff_ebur128_loudness_range_multiple(FFEBUR128State ** sts,
 204                                        size_t size, double *out);
 205
 206 /** \brief Get maximum sample peak of selected channel in float format.
 207  *
 208  *  @param st library state
 209  *  @param channel_number channel to analyse
 210  *  @param out maximum sample peak in float format (1.0 is 0 dBFS)
 211  *  @return
 212  *    - 0 on success.
 213  *    - AVERROR(EINVAL) if mode "FF_EBUR128_MODE_SAMPLE_PEAK" has not been set.
 214  *    - AVERROR(EINVAL) if invalid channel index.
 215  */
 216 int ff_ebur128_sample_peak(FFEBUR128State * st,
 217                            unsigned int channel_number, double *out);
 218
 219 /** \brief Get relative threshold in LUFS.
 220  *
 221  *  @param st library state
 222  *  @param out relative threshold in LUFS.
 223  *  @return
 224  *    - 0 on success.
 225  *    - AVERROR(EINVAL) if mode "FF_EBUR128_MODE_I" has not been set.
 226  */
 227 int ff_ebur128_relative_threshold(FFEBUR128State * st, double *out);
 228
 229 #endif                          /* AVFILTER_EBUR128_H */