FFmpeg
ebur128.h
Go to the documentation of this file.
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  */
39 enum channel {
40  FF_EBUR128_UNUSED = 0, /**< unused channel (for example LFE channel) */
42  FF_EBUR128_Mp030 = 1, /**< itu M+030 */
44  FF_EBUR128_Mm030 = 2, /**< itu M-030 */
46  FF_EBUR128_Mp000 = 3, /**< itu M+000 */
48  FF_EBUR128_Mp110 = 4, /**< itu M+110 */
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  */
83 enum mode {
84  /** can call ff_ebur128_loudness_momentary */
85  FF_EBUR128_MODE_M = (1 << 0),
86  /** can call ff_ebur128_loudness_shortterm */
88  /** can call ff_ebur128_loudness_global_* and ff_ebur128_relative_threshold */
90  /** can call ff_ebur128_loudness_range */
92  /** can call ff_ebur128_sample_peak */
94 };
95 
96 /** forward declaration of 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  */
103 typedef struct FFEBUR128State {
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. */
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  */
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  */
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  */
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  */
155  const short *src, size_t frames);
156 /** \brief See \ref ebur128_add_frames_short */
158  const int *src, size_t frames);
159 /** \brief See \ref ebur128_add_frames_short */
161  const float *src, size_t frames);
162 /** \brief See \ref ebur128_add_frames_short */
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  */
174  const short **srcs,
175  size_t frames, int stride);
176 /** \brief See \ref ebur128_add_frames_planar_short */
178  const int **srcs,
179  size_t frames, int stride);
180 /** \brief See \ref ebur128_add_frames_planar_short */
182  const float **srcs,
183  size_t frames, int stride);
184 /** \brief See \ref ebur128_add_frames_planar_short */
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  */
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  */
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  */
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  */
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  */
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  */
257 int 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  */
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  */
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  */
295 
296 #endif /* AVFILTER_EBUR128_H */
stride
int stride
Definition: mace.c:144
ff_ebur128_loudness_range_multiple
int ff_ebur128_loudness_range_multiple(FFEBUR128State **sts, size_t size, double *out)
Get loudness range (LRA) in LU across multiple instances.
Definition: ebur128.c:676
FF_EBUR128_Mp030
@ FF_EBUR128_Mp030
itu M+030
Definition: ebur128.h:42
FF_EBUR128_RIGHT_SURROUND
@ FF_EBUR128_RIGHT_SURROUND
Definition: ebur128.h:49
FFEBUR128State::d
struct FFEBUR128StateInternal * d
Internal state.
Definition: ebur128.h:107
out
FILE * out
Definition: movenc.c:54
ff_ebur128_loudness_range
int ff_ebur128_loudness_range(FFEBUR128State *st, double *out)
Get loudness range (LRA) of programme in LU.
Definition: ebur128.c:753
FF_EBUR128_MmSC
@ FF_EBUR128_MmSC
itu M-SC
Definition: ebur128.h:53
FF_EBUR128_LEFT_SURROUND
@ FF_EBUR128_LEFT_SURROUND
Definition: ebur128.h:47
ff_ebur128_set_channel
int ff_ebur128_set_channel(FFEBUR128State *st, unsigned int channel_number, int value)
Set channel type.
Definition: ebur128.c:446
ff_ebur128_loudness_global_multiple
int ff_ebur128_loudness_global_multiple(FFEBUR128State **sts, size_t size, double *out)
Get global integrated loudness in LUFS across multiple instances.
Definition: ebur128.c:608
FF_EBUR128_Um110
@ FF_EBUR128_Um110
itu U-110
Definition: ebur128.h:69
FF_EBUR128_MODE_I
@ FF_EBUR128_MODE_I
can call ff_ebur128_loudness_global_* and ff_ebur128_relative_threshold
Definition: ebur128.h:89
FF_EBUR128_Um030
@ FF_EBUR128_Um030
itu U-030
Definition: ebur128.h:63
FF_EBUR128_Tp000
@ FF_EBUR128_Tp000
itu T+000
Definition: ebur128.h:73
FF_EBUR128_Up090
@ FF_EBUR128_Up090
itu U+090
Definition: ebur128.h:66
FF_EBUR128_Mp180
@ FF_EBUR128_Mp180
itu M+180
Definition: ebur128.h:60
FF_EBUR128_Um090
@ FF_EBUR128_Um090
itu U-090
Definition: ebur128.h:67
window
static SDL_Window * window
Definition: ffplay.c:368
FF_EBUR128_LEFT
@ FF_EBUR128_LEFT
Definition: ebur128.h:41
frames
if it could not because there are no more frames
Definition: filter_design.txt:266
FF_EBUR128_UNUSED
@ FF_EBUR128_UNUSED
unused channel (for example LFE channel)
Definition: ebur128.h:40
FF_EBUR128_Um135
@ FF_EBUR128_Um135
itu U-135
Definition: ebur128.h:71
FF_EBUR128_Bm045
@ FF_EBUR128_Bm045
itu B-045
Definition: ebur128.h:76
FF_EBUR128_DUAL_MONO
@ FF_EBUR128_DUAL_MONO
a channel that is counted twice
Definition: ebur128.h:51
FFEBUR128State::samplerate
unsigned long samplerate
The sample rate.
Definition: ebur128.h:106
FF_EBUR128_MODE_LRA
@ FF_EBUR128_MODE_LRA
can call ff_ebur128_loudness_range
Definition: ebur128.h:91
ff_ebur128_add_frames_short
void ff_ebur128_add_frames_short(FFEBUR128State *st, const short *src, size_t frames)
Add frames to be processed.
FF_EBUR128_Up180
@ FF_EBUR128_Up180
itu U+180
Definition: ebur128.h:72
FF_EBUR128_Mm060
@ FF_EBUR128_Mm060
itu M-060
Definition: ebur128.h:55
FFEBUR128State::mode
int mode
The current mode.
Definition: ebur128.h:104
ff_ebur128_add_frames_double
void ff_ebur128_add_frames_double(FFEBUR128State *st, const double *src, size_t frames)
See ebur128_add_frames_short.
FF_EBUR128_Mm110
@ FF_EBUR128_Mm110
itu M-110
Definition: ebur128.h:50
channels
channels
Definition: aptx.h:33
ff_ebur128_init
FFEBUR128State * ff_ebur128_init(unsigned int channels, unsigned long samplerate, unsigned long window, int mode)
Initialize library state.
Definition: ebur128.c:217
ff_ebur128_loudness_window
int ff_ebur128_loudness_window(FFEBUR128State *st, unsigned long window, double *out)
Get loudness of the specified window in LUFS.
Definition: ebur128.c:659
ff_ebur128_sample_peak
int ff_ebur128_sample_peak(FFEBUR128State *st, unsigned int channel_number, double *out)
Get maximum sample peak of selected channel in float format.
Definition: ebur128.c:758
FF_EBUR128_Mm030
@ FF_EBUR128_Mm030
itu M-030
Definition: ebur128.h:44
FF_EBUR128_Bp000
@ FF_EBUR128_Bp000
itu B+000
Definition: ebur128.h:74
src
#define src
Definition: vp8dsp.c:254
FF_EBUR128_Mp060
@ FF_EBUR128_Mp060
itu M+060
Definition: ebur128.h:54
FF_EBUR128_Up030
@ FF_EBUR128_Up030
itu U+030
Definition: ebur128.h:62
FF_EBUR128_Mm135
@ FF_EBUR128_Mm135
itu M-135
Definition: ebur128.h:59
size
int size
Definition: twinvq_data.h:11134
FF_EBUR128_Mp090
@ FF_EBUR128_Mp090
itu M+090
Definition: ebur128.h:56
ff_ebur128_add_frames_planar_double
void ff_ebur128_add_frames_planar_double(FFEBUR128State *st, const double **srcs, size_t frames, int stride)
See ebur128_add_frames_planar_short.
FF_EBUR128_MODE_S
@ FF_EBUR128_MODE_S
can call ff_ebur128_loudness_shortterm
Definition: ebur128.h:87
FF_EBUR128_Mm090
@ FF_EBUR128_Mm090
itu M-090
Definition: ebur128.h:57
FF_EBUR128_RIGHT
@ FF_EBUR128_RIGHT
Definition: ebur128.h:43
FFEBUR128State::channels
unsigned int channels
The number of channels.
Definition: ebur128.h:105
ff_ebur128_add_frames_planar_float
void ff_ebur128_add_frames_planar_float(FFEBUR128State *st, const float **srcs, size_t frames, int stride)
See ebur128_add_frames_planar_short.
FF_EBUR128_MODE_M
@ FF_EBUR128_MODE_M
can call ff_ebur128_loudness_momentary
Definition: ebur128.h:85
value
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf default value
Definition: writing_filters.txt:86
FFEBUR128State
Contains information about the state of a loudness measurement.
Definition: ebur128.h:103
FF_EBUR128_MpSC
@ FF_EBUR128_MpSC
itu M+SC
Definition: ebur128.h:52
ff_ebur128_add_frames_float
void ff_ebur128_add_frames_float(FFEBUR128State *st, const float *src, size_t frames)
See ebur128_add_frames_short.
FF_EBUR128_Mp110
@ FF_EBUR128_Mp110
itu M+110
Definition: ebur128.h:48
ff_ebur128_add_frames_int
void ff_ebur128_add_frames_int(FFEBUR128State *st, const int *src, size_t frames)
See ebur128_add_frames_short.
FF_EBUR128_Up135
@ FF_EBUR128_Up135
itu U+135
Definition: ebur128.h:70
FF_EBUR128_CENTER
@ FF_EBUR128_CENTER
Definition: ebur128.h:45
mode
mode
Definition: ebur128.h:83
ff_ebur128_add_frames_planar_short
void ff_ebur128_add_frames_planar_short(FFEBUR128State *st, const short **srcs, size_t frames, int stride)
Add frames to be processed.
FFEBUR128StateInternal
Definition: ebur128.c:66
ff_ebur128_relative_threshold
int ff_ebur128_relative_threshold(FFEBUR128State *st, double *out)
Get relative threshold in LUFS.
Definition: ebur128.c:587
ff_ebur128_loudness_momentary
int ff_ebur128_loudness_momentary(FFEBUR128State *st, double *out)
Get momentary loudness (last 400ms) in LUFS.
Definition: ebur128.c:630
FF_EBUR128_Um045
@ FF_EBUR128_Um045
itu U-030
Definition: ebur128.h:65
FF_EBUR128_Up000
@ FF_EBUR128_Up000
itu U+000
Definition: ebur128.h:61
ff_ebur128_destroy
void ff_ebur128_destroy(FFEBUR128State **st)
Destroy library state.
Definition: ebur128.c:302
ff_ebur128_loudness_global
int ff_ebur128_loudness_global(FFEBUR128State *st, double *out)
Get global integrated loudness in LUFS.
Definition: ebur128.c:603
FF_EBUR128_MODE_SAMPLE_PEAK
@ FF_EBUR128_MODE_SAMPLE_PEAK
can call ff_ebur128_sample_peak
Definition: ebur128.h:93
FF_EBUR128_Mp000
@ FF_EBUR128_Mp000
itu M+000
Definition: ebur128.h:46
FF_EBUR128_Up045
@ FF_EBUR128_Up045
itu U+045
Definition: ebur128.h:64
FF_EBUR128_Bp045
@ FF_EBUR128_Bp045
itu B+045
Definition: ebur128.h:75
FF_EBUR128_Up110
@ FF_EBUR128_Up110
itu U+110
Definition: ebur128.h:68
channel
channel
Definition: ebur128.h:39
FF_EBUR128_Mp135
@ FF_EBUR128_Mp135
itu M+135
Definition: ebur128.h:58
ff_ebur128_loudness_shortterm
int ff_ebur128_loudness_shortterm(FFEBUR128State *st, double *out)
Get short-term loudness (last 3s) in LUFS.
Definition: ebur128.c:645
ff_ebur128_add_frames_planar_int
void ff_ebur128_add_frames_planar_int(FFEBUR128State *st, const int **srcs, size_t frames, int stride)
See ebur128_add_frames_planar_short.