avfilter: rename variables in geq
[ffmpeg.git] / libavfilter / ebur128.h
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) */
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  */
83 enum 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 */
97 struct 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. */
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  */
118 FFEBUR128State *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  */
126 void 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  */
145 int 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  */
154 void ff_ebur128_add_frames_short(FFEBUR128State * st,
155                                  const short *src, size_t frames);
156 /** \brief See \ref ebur128_add_frames_short */
157 void ff_ebur128_add_frames_int(FFEBUR128State * st,
158                                const int *src, size_t frames);
159 /** \brief See \ref ebur128_add_frames_short */
160 void ff_ebur128_add_frames_float(FFEBUR128State * st,
161                                  const float *src, size_t frames);
162 /** \brief See \ref ebur128_add_frames_short */
163 void 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  */
173 void 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 */
177 void 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 */
181 void 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 */
185 void 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  */
198 int 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  */
209 int 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  */
220 int 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  */
230 int 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  */
243 int 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  */
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  */
270 int 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  */
283 int 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  */
294 int ff_ebur128_relative_threshold(FFEBUR128State * st, double *out);
295
296 #endif                          /* AVFILTER_EBUR128_H */