summaryrefslogtreecommitdiff
path: root/libavfilter/ebur128.h (plain)
blob: b94cd2492816c0eadfb1287de4f83c992b722741
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 */
39enum 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 */
83enum mode {
84 /** can 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 */
97struct 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 */
103typedef struct {
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 */
118FFEBUR128State *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 */
126void 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 */
145int 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 */
154void ff_ebur128_add_frames_short(FFEBUR128State * st,
155 const short *src, size_t frames);
156/** \brief See \ref ebur128_add_frames_short */
157void ff_ebur128_add_frames_int(FFEBUR128State * st,
158 const int *src, size_t frames);
159/** \brief See \ref ebur128_add_frames_short */
160void ff_ebur128_add_frames_float(FFEBUR128State * st,
161 const float *src, size_t frames);
162/** \brief See \ref ebur128_add_frames_short */
163void ff_ebur128_add_frames_double(FFEBUR128State * st,
164 const double *src, size_t frames);
165
166/** \brief Add frames to be processed.
167 *
168 * @param st library state.
169 * @param srcs array of source frame channel data pointers
170 * @param frames number of frames. Not number of samples!
171 * @param stride number of samples to skip to for the next sample of the same channel
172 */
173void ff_ebur128_add_frames_planar_short(FFEBUR128State * st,
174 const short **srcs,
175 size_t frames, int stride);
176/** \brief See \ref ebur128_add_frames_planar_short */
177void ff_ebur128_add_frames_planar_int(FFEBUR128State * st,
178 const int **srcs,
179 size_t frames, int stride);
180/** \brief See \ref ebur128_add_frames_planar_short */
181void ff_ebur128_add_frames_planar_float(FFEBUR128State * st,
182 const float **srcs,
183 size_t frames, int stride);
184/** \brief See \ref ebur128_add_frames_planar_short */
185void ff_ebur128_add_frames_planar_double(FFEBUR128State * st,
186 const double **srcs,
187 size_t frames, int stride);
188
189/** \brief Get global integrated loudness in LUFS.
190 *
191 * @param st library state.
192 * @param out integrated loudness in LUFS. -HUGE_VAL if result is negative
193 * infinity.
194 * @return
195 * - 0 on success.
196 * - AVERROR(EINVAL) if mode "FF_EBUR128_MODE_I" has not been set.
197 */
198int ff_ebur128_loudness_global(FFEBUR128State * st, double *out);
199/** \brief Get global integrated loudness in LUFS across multiple instances.
200 *
201 * @param sts array of library states.
202 * @param size length of sts
203 * @param out integrated loudness in LUFS. -HUGE_VAL if result is negative
204 * infinity.
205 * @return
206 * - 0 on success.
207 * - AVERROR(EINVAL) if mode "FF_EBUR128_MODE_I" has not been set.
208 */
209int ff_ebur128_loudness_global_multiple(FFEBUR128State ** sts,
210 size_t size, double *out);
211
212/** \brief Get momentary loudness (last 400ms) in LUFS.
213 *
214 * @param st library state.
215 * @param out momentary loudness in LUFS. -HUGE_VAL if result is negative
216 * infinity.
217 * @return
218 * - 0 on success.
219 */
220int ff_ebur128_loudness_momentary(FFEBUR128State * st, double *out);
221/** \brief Get short-term loudness (last 3s) in LUFS.
222 *
223 * @param st library state.
224 * @param out short-term loudness in LUFS. -HUGE_VAL if result is negative
225 * infinity.
226 * @return
227 * - 0 on success.
228 * - AVERROR(EINVAL) if mode "FF_EBUR128_MODE_S" has not been set.
229 */
230int ff_ebur128_loudness_shortterm(FFEBUR128State * st, double *out);
231
232/** \brief Get loudness of the specified window in LUFS.
233 *
234 * window must not be larger than the current window set in st.
235 *
236 * @param st library state.
237 * @param window window in ms to calculate loudness.
238 * @param out loudness in LUFS. -HUGE_VAL if result is negative infinity.
239 * @return
240 * - 0 on success.
241 * - AVERROR(EINVAL) if window larger than current window in st.
242 */
243int ff_ebur128_loudness_window(FFEBUR128State * st,
244 unsigned long window, double *out);
245
246/** \brief Get loudness range (LRA) of programme in LU.
247 *
248 * Calculates loudness range according to EBU 3342.
249 *
250 * @param st library state.
251 * @param out loudness range (LRA) in LU. Will not be changed in case of
252 * error. AVERROR(EINVAL) will be returned in this case.
253 * @return
254 * - 0 on success.
255 * - AVERROR(EINVAL) if mode "FF_EBUR128_MODE_LRA" has not been set.
256 */
257int ff_ebur128_loudness_range(FFEBUR128State * st, double *out);
258/** \brief Get loudness range (LRA) in LU across multiple instances.
259 *
260 * Calculates loudness range according to EBU 3342.
261 *
262 * @param sts array of library states.
263 * @param size length of sts
264 * @param out loudness range (LRA) in LU. Will not be changed in case of
265 * error. AVERROR(EINVAL) will be returned in this case.
266 * @return
267 * - 0 on success.
268 * - AVERROR(EINVAL) if mode "FF_EBUR128_MODE_LRA" has not been set.
269 */
270int ff_ebur128_loudness_range_multiple(FFEBUR128State ** sts,
271 size_t size, double *out);
272
273/** \brief Get maximum sample peak of selected channel in float format.
274 *
275 * @param st library state
276 * @param channel_number channel to analyse
277 * @param out maximum sample peak in float format (1.0 is 0 dBFS)
278 * @return
279 * - 0 on success.
280 * - AVERROR(EINVAL) if mode "FF_EBUR128_MODE_SAMPLE_PEAK" has not been set.
281 * - AVERROR(EINVAL) if invalid channel index.
282 */
283int ff_ebur128_sample_peak(FFEBUR128State * st,
284 unsigned int channel_number, double *out);
285
286/** \brief Get relative threshold in LUFS.
287 *
288 * @param st library state
289 * @param out relative threshold in LUFS.
290 * @return
291 * - 0 on success.
292 * - AVERROR(EINVAL) if mode "FF_EBUR128_MODE_I" has not been set.
293 */
294int ff_ebur128_relative_threshold(FFEBUR128State * st, double *out);
295
296#endif /* AVFILTER_EBUR128_H */
297
generated by cgit at 2024-05-17 05:12:46 (GMT)