1 /* See COPYING file for copyright and license details. */
7 * \brief libebur128 - a library for loudness measurement according to
8 * the EBU R128 standard.
15 #define EBUR128_VERSION_MAJOR 1
16 #define EBUR128_VERSION_MINOR 0
17 #define EBUR128_VERSION_PATCH 1
19 #include <stddef.h> /* for size_t */
22 * Use these values when setting the channel map with ebur128_set_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 */
35 * Error return values.
40 EBUR128_ERROR_INVALID_MODE,
41 EBUR128_ERROR_INVALID_CHANNEL_INDEX,
42 EBUR128_ERROR_NO_CHANGE
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.
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)
67 /** forward declaration of ebur128_state_internal */
68 struct ebur128_state_internal;
70 /** \brief Contains information about the state of a loudness measurement.
72 * You should not need to modify this struct directly.
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. */
81 /** \brief Get library version number. Do not pass null pointers here.
83 * @param major major version number of library
84 * @param minor minor version number of library
85 * @param patch patch version number of library
87 void ebur128_get_version(int* major, int* minor, int* patch);
89 /** \brief Initialize library state.
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.
96 ebur128_state* ebur128_init(unsigned int channels,
97 unsigned long samplerate,
100 /** \brief Destroy library state.
102 * @param st pointer to a library state.
104 void ebur128_destroy(ebur128_state** st);
106 /** \brief Set channel type.
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
116 * @param st library state.
117 * @param channel_number zero based channel index.
118 * @param value channel type from the "channel" enum.
120 * - EBUR128_SUCCESS on success.
121 * - EBUR128_ERROR_INVALID_CHANNEL_INDEX if invalid channel index.
123 int ebur128_set_channel(ebur128_state* st,
124 unsigned int channel_number,
127 /** \brief Change library parameters.
129 * Note that the channel map will be reset when setting a different number of
130 * channels. The current unfinished block will be lost.
132 * @param st library state.
133 * @param channels new number of channels.
134 * @param samplerate new sample rate.
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.
141 int ebur128_change_parameters(ebur128_state* st,
142 unsigned int channels,
143 unsigned long samplerate);
145 /** \brief Add frames to be processed.
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!
151 * - EBUR128_SUCCESS on success.
152 * - EBUR128_ERROR_NOMEM on memory allocation error.
154 int ebur128_add_frames_short(ebur128_state* st,
157 /** \brief See \ref ebur128_add_frames_short */
158 int ebur128_add_frames_int(ebur128_state* st,
161 /** \brief See \ref ebur128_add_frames_short */
162 int ebur128_add_frames_float(ebur128_state* st,
165 /** \brief See \ref ebur128_add_frames_short */
166 int ebur128_add_frames_double(ebur128_state* st,
170 /** \brief Get global integrated loudness in LUFS.
172 * @param st library state.
173 * @param out integrated loudness in LUFS. -HUGE_VAL if result is negative
176 * - EBUR128_SUCCESS on success.
177 * - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_I" has not been set.
179 int ebur128_loudness_global(ebur128_state* st, double* out);
180 /** \brief Get global integrated loudness in LUFS across multiple instances.
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
187 * - EBUR128_SUCCESS on success.
188 * - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_I" has not been set.
190 int ebur128_loudness_global_multiple(ebur128_state** sts,
194 /** \brief Get momentary loudness (last 400ms) in LUFS.
196 * @param st library state.
197 * @param out momentary loudness in LUFS. -HUGE_VAL if result is negative
200 * - EBUR128_SUCCESS on success.
202 int ebur128_loudness_momentary(ebur128_state* st, double* out);
203 /** \brief Get short-term loudness (last 3s) in LUFS.
205 * @param st library state.
206 * @param out short-term loudness in LUFS. -HUGE_VAL if result is negative
209 * - EBUR128_SUCCESS on success.
210 * - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_S" has not been set.
212 int ebur128_loudness_shortterm(ebur128_state* st, double* out);
214 /** \brief Get loudness range (LRA) of programme in LU.
216 * Calculates loudness range according to EBU 3342.
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.
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.
227 int ebur128_loudness_range(ebur128_state* st, double* out);
228 /** \brief Get loudness range (LRA) in LU across multiple instances.
230 * Calculates loudness range according to EBU 3342.
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.
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.
242 int ebur128_loudness_range_multiple(ebur128_state** sts,
246 /** \brief Get maximum sample peak of selected channel in float format.
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)
252 * - EBUR128_SUCCESS on success.
253 * - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_SAMPLE_PEAK" has not
255 * - EBUR128_ERROR_INVALID_CHANNEL_INDEX if invalid channel index.
257 int ebur128_sample_peak(ebur128_state* st,
258 unsigned int channel_number,
261 /** \brief Get maximum true peak of selected channel in float format.
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.
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.
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)
275 * - EBUR128_SUCCESS on success.
276 * - EBUR128_ERROR_INVALID_MODE if mode "EBUR128_MODE_TRUE_PEAK" has not
278 * - EBUR128_ERROR_INVALID_CHANNEL_INDEX if invalid channel index.
280 int ebur128_true_peak(ebur128_state* st,
281 unsigned int channel_number,
288 #endif /* EBUR128_H_ */