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