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 2 17 #define EBUR128_VERSION_PATCH 0 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 * See definitions in ITU R-REC-BS 1770-4 24 */ 25 enum channel { 26 EBUR128_UNUSED = 0, /**< unused channel (for example LFE channel) */ 27 EBUR128_LEFT, 28 EBUR128_Mp030 = 1, /**< itu M+030 */ 29 EBUR128_RIGHT, 30 EBUR128_Mm030 = 2, /**< itu M-030 */ 31 EBUR128_CENTER, 32 EBUR128_Mp000 = 3, /**< itu M+000 */ 33 EBUR128_LEFT_SURROUND, 34 EBUR128_Mp110 = 4, /**< itu M+110 */ 35 EBUR128_RIGHT_SURROUND, 36 EBUR128_Mm110 = 5, /**< itu M-110 */ 37 EBUR128_DUAL_MONO, /**< a channel that is counted twice */ 38 EBUR128_MpSC, /**< itu M+SC */ 39 EBUR128_MmSC, /**< itu M-SC */ 40 EBUR128_Mp060, /**< itu M+060 */ 41 EBUR128_Mm060, /**< itu M-060 */ 42 EBUR128_Mp090, /**< itu M+090 */ 43 EBUR128_Mm090, /**< itu M-090 */ 44 EBUR128_Mp135, /**< itu M+135 */ 45 EBUR128_Mm135, /**< itu M-135 */ 46 EBUR128_Mp180, /**< itu M+180 */ 47 EBUR128_Up000, /**< itu U+000 */ 48 EBUR128_Up030, /**< itu U+030 */ 49 EBUR128_Um030, /**< itu U-030 */ 50 EBUR128_Up045, /**< itu U+045 */ 51 EBUR128_Um045, /**< itu U-030 */ 52 EBUR128_Up090, /**< itu U+090 */ 53 EBUR128_Um090, /**< itu U-090 */ 54 EBUR128_Up110, /**< itu U+110 */ 55 EBUR128_Um110, /**< itu U-110 */ 56 EBUR128_Up135, /**< itu U+135 */ 57 EBUR128_Um135, /**< itu U-135 */ 58 EBUR128_Up180, /**< itu U+180 */ 59 EBUR128_Tp000, /**< itu T+000 */ 60 EBUR128_Bp000, /**< itu B+000 */ 61 EBUR128_Bp045, /**< itu B+045 */ 62 EBUR128_Bm045 /**< itu B-045 */ 63 }; 64 65 /** \enum error 66 * Error return values. 67 */ 68 enum error { 69 EBUR128_SUCCESS = 0, 70 EBUR128_ERROR_NOMEM, 71 EBUR128_ERROR_INVALID_MODE, 72 EBUR128_ERROR_INVALID_CHANNEL_INDEX, 73 EBUR128_ERROR_NO_CHANGE 74 }; 75 76 /** \enum mode 77 * Use these values in ebur128_init (or'ed). Try to use the lowest possible 78 * modes that suit your needs, as performance will be better. 79 */ 80 enum mode { 81 /** can call ebur128_loudness_momentary */ 82 EBUR128_MODE_M = (1 << 0), 83 /** can call ebur128_loudness_shortterm */ 84 EBUR128_MODE_S = (1 << 1) | EBUR128_MODE_M, 85 /** can call ebur128_loudness_global_* and ebur128_relative_threshold */ 86 EBUR128_MODE_I = (1 << 2) | EBUR128_MODE_M, 87 /** can call ebur128_loudness_range */ 88 EBUR128_MODE_LRA = (1 << 3) | EBUR128_MODE_S, 89 /** can call ebur128_sample_peak */ 90 EBUR128_MODE_SAMPLE_PEAK = (1 << 4) | EBUR128_MODE_M, 91 /** can call ebur128_true_peak */ 92 EBUR128_MODE_TRUE_PEAK = (1 << 5) | EBUR128_MODE_M 93 | EBUR128_MODE_SAMPLE_PEAK, 94 /** uses histogram algorithm to calculate loudness */ 95 EBUR128_MODE_HISTOGRAM = (1 << 6) 96 }; 97 98 /** forward declaration of ebur128_state_internal */ 99 struct ebur128_state_internal; 100 101 /** \brief Contains information about the state of a loudness measurement. 102 * 103 * You should not need to modify this struct directly. 104 */ 105 typedef struct { 106 int mode; /**< The current mode. */ 107 unsigned int channels; /**< The number of channels. */ 108 unsigned long samplerate; /**< The sample rate. */ 109 struct ebur128_state_internal* d; /**< Internal state. */ 110 } ebur128_state; 111 112 /** \brief Get library version number. Do not pass null pointers here. 113 * 114 * @param major major version number of library 115 * @param minor minor version number of library 116 * @param patch patch version number of library 117 */ 118 void ebur128_get_version(int* major, int* minor, int* patch); 119 120 /** \brief Initialize library state. 121 * 122 * @param channels the number of channels. 123 * @param samplerate the sample rate. 124 * @param mode see the mode enum for possible values. 125 * @return an initialized library state. 126 */ 127 ebur128_state* ebur128_init(unsigned int channels, 128 unsigned long samplerate, 129 int mode); 130 131 /** \brief Destroy library state. 132 * 133 * @param st pointer to a library state. 134 */ 135 void ebur128_destroy(ebur128_state** st); 136 137 /** \brief Set channel type. 138 * 139 * The default is: 140 * - 0 -> EBUR128_LEFT 141 * - 1 -> EBUR128_RIGHT 142 * - 2 -> EBUR128_CENTER 143 * - 3 -> EBUR128_UNUSED 144 * - 4 -> EBUR128_LEFT_SURROUND 145 * - 5 -> EBUR128_RIGHT_SURROUND 146 * 147 * @param st library state. 148 * @param channel_number zero based channel index. 149 * @param value channel type from the "channel" enum. 150 * @return 151 * - EBUR128_SUCCESS on success. 152 * - EBUR128_ERROR_INVALID_CHANNEL_INDEX if invalid channel index. 153 */ 154 int ebur128_set_channel(ebur128_state* st, 155 unsigned int channel_number, 156 int value); 157 158 /** \brief Change library parameters. 159 * 160 * Note that the channel map will be reset when setting a different number of 161 * channels. The current unfinished block will be lost. 162 * 163 * @param st library state. 164 * @param channels new number of channels. 165 * @param samplerate new sample rate. 166 * @return 167 * - EBUR128_SUCCESS on success. 168 * - EBUR128_ERROR_NOMEM on memory allocation error. The state will be 169 * invalid and must be destroyed. 170 * - EBUR128_ERROR_NO_CHANGE if channels and sample rate were not changed. 171 */ 172 int ebur128_change_parameters(ebur128_state* st, 173 unsigned int channels, 174 unsigned long samplerate); 175 176 /** \brief Set the maximum window duration. 177 * 178 * Set the maximum duration that will be used for ebur128_window_loudness(). 179 * Note that this destroys the current content of the audio buffer. 180 * 181 * @param st library state. 182 * @param window duration of the window in ms. 183 * @return 184 * - EBUR128_SUCCESS on success. 185 * - EBUR128_ERROR_NOMEM on memory allocation error. The state will be 186 * invalid and must be destroyed. 187 * - EBUR128_ERROR_NO_CHANGE if window duration not changed. 188 */ 189 int ebur128_set_max_window(ebur128_state* st, unsigned long window); 190 191 /** \brief Set the maximum history. 192 * 193 * Set the maximum history that will be stored for loudness integration. 194 * More history provides more accurate results, but requires more resources. 195 * 196 * Applies to ebur128_loudness_range() and ebur128_loudness_global() when 197 * EBUR128_MODE_HISTOGRAM is not set. 198 * 199 * Default is ULONG_MAX (at least ~50 days). 200 * Minimum is 3000ms for EBUR128_MODE_LRA and 400ms for EBUR128_MODE_M. 201 * 202 * @param st library state. 203 * @param history duration of history in ms. 204 * @return 205 * - EBUR128_SUCCESS on success. 206 * - EBUR128_ERROR_NO_CHANGE if history not changed. 207 */ 208 int ebur128_set_max_history(ebur128_state* st, unsigned long history); 209 210 /** \brief Add frames to be processed. 211 * 212 * @param st library state. 213 * @param src array of source frames. Channels must be interleaved. 214 * @param frames number of frames. Not number of samples! 215 * @return 216 * - EBUR128_SUCCESS on success. 217 * - EBUR128_ERROR_NOMEM on memory allocation error. 218 */ 219 int ebur128_add_frames_short(ebur128_state* st, 220 const short* src, 221 size_t frames); 222 /** \brief See \ref ebur128_add_frames_short */ 223 int ebur128_add_frames_int(ebur128_state* st, 224 const int* src, 225 size_t frames); 226 /** \brief See \ref ebur128_add_frames_short */ 227 int ebur128_add_frames_float(ebur128_state* st, 228 const float* src, 229 size_t frames); 230 /** \brief See \ref ebur128_add_frames_short */ 231 int ebur128_add_frames_double(ebur128_state* st, 232 const double* src, 233 size_t frames); 234 235 /** \brief Get global integrated loudness in LUFS. 236 * 237 * @param st library state. 238 * @param out integrated loudness in LUFS. -HUGE_VAL if result is negative 239 * infinity. 240 * @return 241 * - EBUR128_SUCCESS on success. 242 * - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_I" has not been set. 243 */ 244 int ebur128_loudness_global(ebur128_state* st, double* out); 245 /** \brief Get global integrated loudness in LUFS across multiple instances. 246 * 247 * @param sts array of library states. 248 * @param size length of sts 249 * @param out integrated loudness in LUFS. -HUGE_VAL if result is negative 250 * infinity. 251 * @return 252 * - EBUR128_SUCCESS on success. 253 * - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_I" has not been set. 254 */ 255 int ebur128_loudness_global_multiple(ebur128_state** sts, 256 size_t size, 257 double* out); 258 259 /** \brief Get momentary loudness (last 400ms) in LUFS. 260 * 261 * @param st library state. 262 * @param out momentary loudness in LUFS. -HUGE_VAL if result is negative 263 * infinity. 264 * @return 265 * - EBUR128_SUCCESS on success. 266 */ 267 int ebur128_loudness_momentary(ebur128_state* st, double* out); 268 /** \brief Get short-term loudness (last 3s) in LUFS. 269 * 270 * @param st library state. 271 * @param out short-term loudness in LUFS. -HUGE_VAL if result is negative 272 * infinity. 273 * @return 274 * - EBUR128_SUCCESS on success. 275 * - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_S" has not been set. 276 */ 277 int ebur128_loudness_shortterm(ebur128_state* st, double* out); 278 279 /** \brief Get loudness of the specified window in LUFS. 280 * 281 * window must not be larger than the current window set in st. 282 * The current window can be changed by calling ebur128_set_max_window(). 283 * 284 * @param st library state. 285 * @param window window in ms to calculate loudness. 286 * @param out loudness in LUFS. -HUGE_VAL if result is negative infinity. 287 * @return 288 * - EBUR128_SUCCESS on success. 289 * - EBUR128_ERROR_INVALID_MODE if window larger than current window in st. 290 */ 291 int ebur128_loudness_window(ebur128_state* st, 292 unsigned long window, 293 double* out); 294 295 /** \brief Get loudness range (LRA) of programme in LU. 296 * 297 * Calculates loudness range according to EBU 3342. 298 * 299 * @param st library state. 300 * @param out loudness range (LRA) in LU. Will not be changed in case of 301 * error. EBUR128_ERROR_NOMEM or EBUR128_ERROR_INVALID_MODE will be 302 * returned in this case. 303 * @return 304 * - EBUR128_SUCCESS on success. 305 * - EBUR128_ERROR_NOMEM in case of memory allocation error. 306 * - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_LRA" has not been set. 307 */ 308 int ebur128_loudness_range(ebur128_state* st, double* out); 309 /** \brief Get loudness range (LRA) in LU across multiple instances. 310 * 311 * Calculates loudness range according to EBU 3342. 312 * 313 * @param sts array of library states. 314 * @param size length of sts 315 * @param out loudness range (LRA) in LU. Will not be changed in case of 316 * error. EBUR128_ERROR_NOMEM or EBUR128_ERROR_INVALID_MODE will be 317 * returned in this case. 318 * @return 319 * - EBUR128_SUCCESS on success. 320 * - EBUR128_ERROR_NOMEM in case of memory allocation error. 321 * - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_LRA" has not been set. 322 */ 323 int ebur128_loudness_range_multiple(ebur128_state** sts, 324 size_t size, 325 double* out); 326 327 /** \brief Get maximum sample peak from all frames that have been processed. 328 * 329 * The equation to convert to dBFS is: 20 * log10(out) 330 * 331 * @param st library state 332 * @param channel_number channel to analyse 333 * @param out maximum sample peak in float format (1.0 is 0 dBFS) 334 * @return 335 * - EBUR128_SUCCESS on success. 336 * - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_SAMPLE_PEAK" has not 337 * been set. 338 * - EBUR128_ERROR_INVALID_CHANNEL_INDEX if invalid channel index. 339 */ 340 int ebur128_sample_peak(ebur128_state* st, 341 unsigned int channel_number, 342 double* out); 343 344 /** \brief Get maximum sample peak from the last call to add_frames(). 345 * 346 * The equation to convert to dBFS is: 20 * log10(out) 347 * 348 * @param st library state 349 * @param channel_number channel to analyse 350 * @param out maximum sample peak in float format (1.0 is 0 dBFS) 351 * @return 352 * - EBUR128_SUCCESS on success. 353 * - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_SAMPLE_PEAK" has not 354 * been set. 355 * - EBUR128_ERROR_INVALID_CHANNEL_INDEX if invalid channel index. 356 */ 357 int ebur128_prev_sample_peak(ebur128_state* st, 358 unsigned int channel_number, 359 double* out); 360 361 /** \brief Get maximum true peak from all frames that have been processed. 362 * 363 * Uses an implementation defined algorithm to calculate the true peak. Do not 364 * try to compare resulting values across different versions of the library, 365 * as the algorithm may change. 366 * 367 * The current implementation uses a custom polyphase FIR interpolator to 368 * calculate true peak. Will oversample 4x for sample rates < 96000 Hz, 2x for 369 * sample rates < 192000 Hz and leave the signal unchanged for 192000 Hz. 370 * 371 * The equation to convert to dBTP is: 20 * log10(out) 372 * 373 * @param st library state 374 * @param channel_number channel to analyse 375 * @param out maximum true peak in float format (1.0 is 0 dBTP) 376 * @return 377 * - EBUR128_SUCCESS on success. 378 * - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_TRUE_PEAK" has not 379 * been set. 380 * - EBUR128_ERROR_INVALID_CHANNEL_INDEX if invalid channel index. 381 */ 382 int ebur128_true_peak(ebur128_state* st, 383 unsigned int channel_number, 384 double* out); 385 386 /** \brief Get maximum true peak from the last call to add_frames(). 387 * 388 * Uses an implementation defined algorithm to calculate the true peak. Do not 389 * try to compare resulting values across different versions of the library, 390 * as the algorithm may change. 391 * 392 * The current implementation uses a custom polyphase FIR interpolator to 393 * calculate true peak. Will oversample 4x for sample rates < 96000 Hz, 2x for 394 * sample rates < 192000 Hz and leave the signal unchanged for 192000 Hz. 395 * 396 * The equation to convert to dBTP is: 20 * log10(out) 397 * 398 * @param st library state 399 * @param channel_number channel to analyse 400 * @param out maximum true peak in float format (1.0 is 0 dBTP) 401 * @return 402 * - EBUR128_SUCCESS on success. 403 * - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_TRUE_PEAK" has not 404 * been set. 405 * - EBUR128_ERROR_INVALID_CHANNEL_INDEX if invalid channel index. 406 */ 407 int ebur128_prev_true_peak(ebur128_state* st, 408 unsigned int channel_number, 409 double* out); 410 411 /** \brief Get relative threshold in LUFS. 412 * 413 * @param st library state 414 * @param out relative threshold in LUFS. 415 * @return 416 * - EBUR128_SUCCESS on success. 417 * - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_I" has not 418 * been set. 419 */ 420 int ebur128_relative_threshold(ebur128_state* st, double* out); 421 422 #ifdef __cplusplus 423 } 424 #endif 425 426 #endif /* EBUR128_H_ */ 427