git.sesse.net Git - mlt/blob - src/modules/plus/ebur128/ebur128.h

   1 /* See COPYING file for copyright and license details. */
   2
   3 #ifndef EBUR128_H_
   4 #define EBUR128_H_
   5
   6 /** \file ebur128.h
   7  *  \brief libebur128 - a library for loudness measurement according to
   8  *         the EBU R128 standard.
   9  */
  10
  11 #ifdef __cplusplus
  12 extern "C" {
  13 #endif
  14
  15 #define EBUR128_VERSION_MAJOR 1
  16 #define EBUR128_VERSION_MINOR 0
  17 #define EBUR128_VERSION_PATCH 1
  18
  19 #include <stddef.h>       /* for size_t */
  20
  21 /** \enum channel
  22  *  Use these values when setting the channel map with ebur128_set_channel().
  23  */
  24 enum channel {
  25   EBUR128_UNUSED = 0,     /**< unused channel (for example LFE channel) */
  26   EBUR128_LEFT,           /**< left channel */
  27   EBUR128_RIGHT,          /**< right channel */
  28   EBUR128_CENTER,         /**< center channel */
  29   EBUR128_LEFT_SURROUND,  /**< left surround channel */
  30   EBUR128_RIGHT_SURROUND, /**< right surround channel */
  31   EBUR128_DUAL_MONO       /**< a channel that is counted twice */
  32 };
  33
  34 /** \enum error
  35  *  Error return values.
  36  */
  37 enum error {
  38   EBUR128_SUCCESS = 0,
  39   EBUR128_ERROR_NOMEM,
  40   EBUR128_ERROR_INVALID_MODE,
  41   EBUR128_ERROR_INVALID_CHANNEL_INDEX,
  42   EBUR128_ERROR_NO_CHANGE
  43 };
  44
  45 /** \enum mode
  46  *  Use these values in ebur128_init (or'ed). Try to use the lowest possible
  47  *  modes that suit your needs, as performance will be better.
  48  */
  49 enum mode {
  50   /** can call ebur128_loudness_momentary */
  51   EBUR128_MODE_M           = (1 << 0),
  52   /** can call ebur128_loudness_shortterm */
  53   EBUR128_MODE_S           = (1 << 1) | EBUR128_MODE_M,
  54   /** can call ebur128_gated_loudness_* */
  55   EBUR128_MODE_I           = (1 << 2) | EBUR128_MODE_M,
  56   /** can call ebur128_loudness_range */
  57   EBUR128_MODE_LRA         = (1 << 3) | EBUR128_MODE_S,
  58   /** can call ebur128_sample_peak */
  59   EBUR128_MODE_SAMPLE_PEAK = (1 << 4) | EBUR128_MODE_M,
  60   /** can call ebur128_true_peak */
  61   EBUR128_MODE_TRUE_PEAK   = (1 << 5) | EBUR128_MODE_M
  62                                       | EBUR128_MODE_SAMPLE_PEAK,
  63   /** uses histogram algorithm to calculate loudness */
  64   EBUR128_MODE_HISTOGRAM   = (1 << 6)
  65 };
  66
  67 /** forward declaration of ebur128_state_internal */
  68 struct ebur128_state_internal;
  69
  70 /** \brief Contains information about the state of a loudness measurement.
  71  *
  72  *  You should not need to modify this struct directly.
  73  */
  74 typedef struct {
  75   int mode;                           /**< The current mode. */
  76   unsigned int channels;              /**< The number of channels. */
  77   unsigned long samplerate;           /**< The sample rate. */
  78   struct ebur128_state_internal* d;   /**< Internal state. */
  79 } ebur128_state;
  80
  81 /** \brief Get library version number. Do not pass null pointers here.
  82  *
  83  *  @param major major version number of library
  84  *  @param minor minor version number of library
  85  *  @param patch patch version number of library
  86  */
  87 void ebur128_get_version(int* major, int* minor, int* patch);
  88
  89 /** \brief Initialize library state.
  90  *
  91  *  @param channels the number of channels.
  92  *  @param samplerate the sample rate.
  93  *  @param mode see the mode enum for possible values.
  94  *  @return an initialized library state.
  95  */
  96 ebur128_state* ebur128_init(unsigned int channels,
  97                             unsigned long samplerate,
  98                             int mode);
  99
 100 /** \brief Destroy library state.
 101  *
 102  *  @param st pointer to a library state.
 103  */
 104 void ebur128_destroy(ebur128_state** st);
 105
 106 /** \brief Set channel type.
 107  *
 108  *  The default is:
 109  *  - 0 -> EBUR128_LEFT
 110  *  - 1 -> EBUR128_RIGHT
 111  *  - 2 -> EBUR128_CENTER
 112  *  - 3 -> EBUR128_UNUSED
 113  *  - 4 -> EBUR128_LEFT_SURROUND
 114  *  - 5 -> EBUR128_RIGHT_SURROUND
 115  *
 116  *  @param st library state.
 117  *  @param channel_number zero based channel index.
 118  *  @param value channel type from the "channel" enum.
 119  *  @return
 120  *    - EBUR128_SUCCESS on success.
 121  *    - EBUR128_ERROR_INVALID_CHANNEL_INDEX if invalid channel index.
 122  */
 123 int ebur128_set_channel(ebur128_state* st,
 124                         unsigned int channel_number,
 125                         int value);
 126
 127 /** \brief Change library parameters.
 128  *
 129  *  Note that the channel map will be reset when setting a different number of
 130  *  channels. The current unfinished block will be lost.
 131  *
 132  *  @param st library state.
 133  *  @param channels new number of channels.
 134  *  @param samplerate new sample rate.
 135  *  @return
 136  *    - EBUR128_SUCCESS on success.
 137  *    - EBUR128_ERROR_NOMEM on memory allocation error. The state will be
 138  *      invalid and must be destroyed.
 139  *    - EBUR128_ERROR_NO_CHANGE if channels and sample rate were not changed.
 140  */
 141 int ebur128_change_parameters(ebur128_state* st,
 142                               unsigned int channels,
 143                               unsigned long samplerate);
 144
 145 /** \brief Add frames to be processed.
 146  *
 147  *  @param st library state.
 148  *  @param src array of source frames. Channels must be interleaved.
 149  *  @param frames number of frames. Not number of samples!
 150  *  @return
 151  *    - EBUR128_SUCCESS on success.
 152  *    - EBUR128_ERROR_NOMEM on memory allocation error.
 153  */
 154 int ebur128_add_frames_short(ebur128_state* st,
 155                              const short* src,
 156                              size_t frames);
 157 /** \brief See \ref ebur128_add_frames_short */
 158 int ebur128_add_frames_int(ebur128_state* st,
 159                              const int* src,
 160                              size_t frames);
 161 /** \brief See \ref ebur128_add_frames_short */
 162 int ebur128_add_frames_float(ebur128_state* st,
 163                              const float* src,
 164                              size_t frames);
 165 /** \brief See \ref ebur128_add_frames_short */
 166 int ebur128_add_frames_double(ebur128_state* st,
 167                              const double* src,
 168                              size_t frames);
 169
 170 /** \brief Get global integrated loudness in LUFS.
 171  *
 172  *  @param st library state.
 173  *  @param out integrated loudness in LUFS. -HUGE_VAL if result is negative
 174  *             infinity.
 175  *  @return
 176  *    - EBUR128_SUCCESS on success.
 177  *    - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_I" has not been set.
 178  */
 179 int ebur128_loudness_global(ebur128_state* st, double* out);
 180 /** \brief Get global integrated loudness in LUFS across multiple instances.
 181  *
 182  *  @param sts array of library states.
 183  *  @param size length of sts
 184  *  @param out integrated loudness in LUFS. -HUGE_VAL if result is negative
 185  *             infinity.
 186  *  @return
 187  *    - EBUR128_SUCCESS on success.
 188  *    - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_I" has not been set.
 189  */
 190 int ebur128_loudness_global_multiple(ebur128_state** sts,
 191                                      size_t size,
 192                                      double* out);
 193
 194 /** \brief Get momentary loudness (last 400ms) in LUFS.
 195  *
 196  *  @param st library state.
 197  *  @param out momentary loudness in LUFS. -HUGE_VAL if result is negative
 198  *             infinity.
 199  *  @return
 200  *    - EBUR128_SUCCESS on success.
 201  */
 202 int ebur128_loudness_momentary(ebur128_state* st, double* out);
 203 /** \brief Get short-term loudness (last 3s) in LUFS.
 204  *
 205  *  @param st library state.
 206  *  @param out short-term loudness in LUFS. -HUGE_VAL if result is negative
 207  *             infinity.
 208  *  @return
 209  *    - EBUR128_SUCCESS on success.
 210  *    - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_S" has not been set.
 211  */
 212 int ebur128_loudness_shortterm(ebur128_state* st, double* out);
 213
 214 /** \brief Get loudness range (LRA) of programme in LU.
 215  *
 216  *  Calculates loudness range according to EBU 3342.
 217  *
 218  *  @param st library state.
 219  *  @param out loudness range (LRA) in LU. Will not be changed in case of
 220  *             error. EBUR128_ERROR_NOMEM or EBUR128_ERROR_INVALID_MODE will be
 221  *             returned in this case.
 222  *  @return
 223  *    - EBUR128_SUCCESS on success.
 224  *    - EBUR128_ERROR_NOMEM in case of memory allocation error.
 225  *    - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_LRA" has not been set.
 226  */
 227 int ebur128_loudness_range(ebur128_state* st, double* out);
 228 /** \brief Get loudness range (LRA) in LU across multiple instances.
 229  *
 230  *  Calculates loudness range according to EBU 3342.
 231  *
 232  *  @param sts array of library states.
 233  *  @param size length of sts
 234  *  @param out loudness range (LRA) in LU. Will not be changed in case of
 235  *             error. EBUR128_ERROR_NOMEM or EBUR128_ERROR_INVALID_MODE will be
 236  *             returned in this case.
 237  *  @return
 238  *    - EBUR128_SUCCESS on success.
 239  *    - EBUR128_ERROR_NOMEM in case of memory allocation error.
 240  *    - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_LRA" has not been set.
 241  */
 242 int ebur128_loudness_range_multiple(ebur128_state** sts,
 243                                     size_t size,
 244                                     double* out);
 245
 246 /** \brief Get maximum sample peak of selected channel in float format.
 247  *
 248  *  @param st library state
 249  *  @param channel_number channel to analyse
 250  *  @param out maximum sample peak in float format (1.0 is 0 dBFS)
 251  *  @return
 252  *    - EBUR128_SUCCESS on success.
 253  *    - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_SAMPLE_PEAK" has not
 254  *      been set.
 255  *    - EBUR128_ERROR_INVALID_CHANNEL_INDEX if invalid channel index.
 256  */
 257 int ebur128_sample_peak(ebur128_state* st,
 258                         unsigned int channel_number,
 259                         double* out);
 260
 261 /** \brief Get maximum true peak of selected channel in float format.
 262  *
 263  *  Uses an implementation defined algorithm to calculate the true peak. Do not
 264  *  try to compare resulting values across different versions of the library,
 265  *  as the algorithm may change.
 266  *
 267  *  The current implementation uses the Speex resampler with quality level 8 to
 268  *  calculate true peak. Will oversample 4x for sample rates < 96000 Hz, 2x for
 269  *  sample rates < 192000 Hz and leave the signal unchanged for 192000 Hz.
 270  *
 271  *  @param st library state
 272  *  @param channel_number channel to analyse
 273  *  @param out maximum true peak in float format (1.0 is 0 dBFS)
 274  *  @return
 275  *    - EBUR128_SUCCESS on success.
 276  *    - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_TRUE_PEAK" has not
 277  *      been set.
 278  *    - EBUR128_ERROR_INVALID_CHANNEL_INDEX if invalid channel index.
 279  */
 280 int ebur128_true_peak(ebur128_state* st,
 281                       unsigned int channel_number,
 282                       double* out);
 283
 284 #ifdef __cplusplus
 285 }
 286 #endif
 287
 288 #endif  /* EBUR128_H_ */