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 */ 297