ebur128.h File Reference

libebur128 - a library for loudness measurement according to the EBU R128 standard. More...

#include <stddef.h>

Go to the source code of this file.

Data Structures
struct	FFEBUR128State
	Contains information about the state of a loudness measurement. More...

Enumerations
enum	channel {   FF_EBUR128_UNUSED = 0, FF_EBUR128_LEFT, FF_EBUR128_Mp030 = 1, FF_EBUR128_RIGHT,   FF_EBUR128_Mm030 = 2, FF_EBUR128_CENTER, FF_EBUR128_Mp000 = 3, FF_EBUR128_LEFT_SURROUND,   FF_EBUR128_Mp110 = 4, FF_EBUR128_RIGHT_SURROUND, FF_EBUR128_Mm110 = 5, FF_EBUR128_DUAL_MONO,   FF_EBUR128_MpSC, FF_EBUR128_MmSC, FF_EBUR128_Mp060, FF_EBUR128_Mm060,   FF_EBUR128_Mp090, FF_EBUR128_Mm090, FF_EBUR128_Mp135, FF_EBUR128_Mm135,   FF_EBUR128_Mp180, FF_EBUR128_Up000, FF_EBUR128_Up030, FF_EBUR128_Um030,   FF_EBUR128_Up045, FF_EBUR128_Um045, FF_EBUR128_Up090, FF_EBUR128_Um090,   FF_EBUR128_Up110, FF_EBUR128_Um110, FF_EBUR128_Up135, FF_EBUR128_Um135,   FF_EBUR128_Up180, FF_EBUR128_Tp000, FF_EBUR128_Bp000, FF_EBUR128_Bp045,   FF_EBUR128_Bm045 }
	Use these values when setting the channel map with ebur128_set_channel(). More...
enum	mode {   FF_EBUR128_MODE_M = (1 << 0), FF_EBUR128_MODE_S = (1 << 1) | FF_EBUR128_MODE_M, FF_EBUR128_MODE_I = (1 << 2) | FF_EBUR128_MODE_M, FF_EBUR128_MODE_LRA = (1 << 3) | FF_EBUR128_MODE_S,   FF_EBUR128_MODE_SAMPLE_PEAK = (1 << 4) | FF_EBUR128_MODE_M, MODE_NONE, MODE_RO, MODE_RW,   MODE_TOGGLE, MODE_RANDOM, NB_MODES, MODE_COVER,   MODE_BLUR, NB_MODES, MODE_HARD, MODE_SOFT,   MODE_MEDIUM, MODE_HARD, MODE_SOFT, NB_MODES }
	Use these values in ebur128_init (or'ed). More...

Functions
FFEBUR128State *	ff_ebur128_init (unsigned int channels, unsigned long samplerate, unsigned long window, int mode)
	Initialize library state. More...
void	ff_ebur128_destroy (FFEBUR128State **st)
	Destroy library state. More...
int	ff_ebur128_set_channel (FFEBUR128State *st, unsigned int channel_number, int value)
	Set channel type. More...
void	ff_ebur128_add_frames_short (FFEBUR128State *st, const short *src, size_t frames)
	Add frames to be processed. More...
void	ff_ebur128_add_frames_int (FFEBUR128State *st, const int *src, size_t frames)
	See ebur128_add_frames_short. More...
void	ff_ebur128_add_frames_float (FFEBUR128State *st, const float *src, size_t frames)
	See ebur128_add_frames_short. More...
void	ff_ebur128_add_frames_double (FFEBUR128State *st, const double *src, size_t frames)
	See ebur128_add_frames_short. More...
void	ff_ebur128_add_frames_planar_short (FFEBUR128State *st, const short **srcs, size_t frames, int stride)
	Add frames to be processed. More...
void	ff_ebur128_add_frames_planar_int (FFEBUR128State *st, const int **srcs, size_t frames, int stride)
	See ebur128_add_frames_planar_short. More...
void	ff_ebur128_add_frames_planar_float (FFEBUR128State *st, const float **srcs, size_t frames, int stride)
	See ebur128_add_frames_planar_short. More...
void	ff_ebur128_add_frames_planar_double (FFEBUR128State *st, const double **srcs, size_t frames, int stride)
	See ebur128_add_frames_planar_short. More...
int	ff_ebur128_loudness_global (FFEBUR128State *st, double *out)
	Get global integrated loudness in LUFS. More...
int	ff_ebur128_loudness_global_multiple (FFEBUR128State **sts, size_t size, double *out)
	Get global integrated loudness in LUFS across multiple instances. More...
int	ff_ebur128_loudness_momentary (FFEBUR128State *st, double *out)
	Get momentary loudness (last 400ms) in LUFS. More...
int	ff_ebur128_loudness_shortterm (FFEBUR128State *st, double *out)
	Get short-term loudness (last 3s) in LUFS. More...
int	ff_ebur128_loudness_window (FFEBUR128State *st, unsigned long window, double *out)
	Get loudness of the specified window in LUFS. More...
int	ff_ebur128_loudness_range (FFEBUR128State *st, double *out)
	Get loudness range (LRA) of programme in LU. More...
int	ff_ebur128_loudness_range_multiple (FFEBUR128State **sts, size_t size, double *out)
	Get loudness range (LRA) in LU across multiple instances. More...
int	ff_ebur128_sample_peak (FFEBUR128State *st, unsigned int channel_number, double *out)
	Get maximum sample peak of selected channel in float format. More...
int	ff_ebur128_relative_threshold (FFEBUR128State *st, double *out)
	Get relative threshold in LUFS. More...

Detailed Description

libebur128 - a library for loudness measurement according to the EBU R128 standard.

Definition in file ebur128.h.

Enumeration Type Documentation

channel

enum channel

Use these values when setting the channel map with ebur128_set_channel().

See definitions in ITU R-REC-BS 1770-4

Enumerator
FF_EBUR128_UNUSED	unused channel (for example LFE channel)
FF_EBUR128_LEFT
FF_EBUR128_Mp030	itu M+030
FF_EBUR128_RIGHT
FF_EBUR128_Mm030	itu M-030
FF_EBUR128_CENTER
FF_EBUR128_Mp000	itu M+000
FF_EBUR128_LEFT_SURROUND
FF_EBUR128_Mp110	itu M+110
FF_EBUR128_RIGHT_SURROUND
FF_EBUR128_Mm110	itu M-110
FF_EBUR128_DUAL_MONO	a channel that is counted twice
FF_EBUR128_MpSC	itu M+SC
FF_EBUR128_MmSC	itu M-SC
FF_EBUR128_Mp060	itu M+060
FF_EBUR128_Mm060	itu M-060
FF_EBUR128_Mp090	itu M+090
FF_EBUR128_Mm090	itu M-090
FF_EBUR128_Mp135	itu M+135
FF_EBUR128_Mm135	itu M-135
FF_EBUR128_Mp180	itu M+180
FF_EBUR128_Up000	itu U+000
FF_EBUR128_Up030	itu U+030
FF_EBUR128_Um030	itu U-030
FF_EBUR128_Up045	itu U+045
FF_EBUR128_Um045	itu U-030
FF_EBUR128_Up090	itu U+090
FF_EBUR128_Um090	itu U-090
FF_EBUR128_Up110	itu U+110
FF_EBUR128_Um110	itu U-110
FF_EBUR128_Up135	itu U+135
FF_EBUR128_Um135	itu U-135
FF_EBUR128_Up180	itu U+180
FF_EBUR128_Tp000	itu T+000
FF_EBUR128_Bp000	itu B+000
FF_EBUR128_Bp045	itu B+045
FF_EBUR128_Bm045	itu B-045

Definition at line 39 of file ebur128.h.

mode

enum mode

Use these values in ebur128_init (or'ed).

Try to use the lowest possible modes that suit your needs, as performance will be better.

Enumerator
FF_EBUR128_MODE_M	can call ff_ebur128_loudness_momentary
FF_EBUR128_MODE_S	can call ff_ebur128_loudness_shortterm
FF_EBUR128_MODE_I	can call ff_ebur128_loudness_global_* and ff_ebur128_relative_threshold
FF_EBUR128_MODE_LRA	can call ff_ebur128_loudness_range
FF_EBUR128_MODE_SAMPLE_PEAK	can call ff_ebur128_sample_peak
MODE_NONE
MODE_RO
MODE_RW
MODE_TOGGLE
MODE_RANDOM
NB_MODES
MODE_COVER
MODE_BLUR
NB_MODES
MODE_HARD
MODE_SOFT
MODE_MEDIUM
MODE_HARD
MODE_SOFT
NB_MODES

Definition at line 83 of file ebur128.h.

Function Documentation

ff_ebur128_init()

FFEBUR128State* ff_ebur128_init	(	unsigned int	channels,
		unsigned long	samplerate,
		unsigned long	window,
		int	mode
	)

Initialize library state.

Parameters

channels	the number of channels.
samplerate	the sample rate.
window	set the maximum window size in ms, set to 0 for auto.
mode	see the mode enum for possible values.

Returns

an initialized library state.

Definition at line 217 of file ebur128.c.

Referenced by config_input().

ff_ebur128_destroy()

void ff_ebur128_destroy

(

FFEBUR128State **

st

)

Destroy library state.

Parameters

st	pointer to a library state.

Definition at line 302 of file ebur128.c.

Referenced by uninit().

ff_ebur128_set_channel()

int ff_ebur128_set_channel	(	FFEBUR128State *	st,
		unsigned int	channel_number,
		int	value
	)

Set channel type.

The default is:

• 0 -> FF_EBUR128_LEFT
• 1 -> FF_EBUR128_RIGHT
• 2 -> FF_EBUR128_CENTER
• 3 -> FF_EBUR128_UNUSED
• 4 -> FF_EBUR128_LEFT_SURROUND
• 5 -> FF_EBUR128_RIGHT_SURROUND

Parameters

st	library state.
channel_number	zero based channel index.
value	channel type from the "channel" enum.

Returns

• 0 on success.
• AVERROR(EINVAL) if invalid channel index.

Definition at line 446 of file ebur128.c.

Referenced by config_input().

ff_ebur128_add_frames_short()

void ff_ebur128_add_frames_short	(	FFEBUR128State *	st,
		const short *	src,
		size_t	frames
	)

Add frames to be processed.

Parameters

st	library state.
src	array of source frames. Channels must be interleaved.
frames	number of frames. Not number of samples!

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_add_frames_float()

void ff_ebur128_add_frames_float	(	FFEBUR128State *	st,
		const float *	src,
		size_t	frames
	)

See ebur128_add_frames_short.

ff_ebur128_add_frames_double()

void ff_ebur128_add_frames_double	(	FFEBUR128State *	st,
		const double *	src,
		size_t	frames
	)

See ebur128_add_frames_short.

Referenced by filter_frame().

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.

Parameters

st	library state.
srcs	array of source frame channel data pointers
frames	number of frames. Not number of samples!
stride	number of samples to skip to for the next sample of the same channel

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.

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_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_loudness_global()

int ff_ebur128_loudness_global	(	FFEBUR128State *	st,
		double *	out
	)

Get global integrated loudness in LUFS.

Parameters

st	library state.
out	integrated loudness in LUFS. -HUGE_VAL if result is negative infinity.

Returns

• 0 on success.
• AVERROR(EINVAL) if mode "FF_EBUR128_MODE_I" has not been set.

Definition at line 603 of file ebur128.c.

Referenced by filter_frame(), and uninit().

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.

Parameters

sts	array of library states.
size	length of sts
out	integrated loudness in LUFS. -HUGE_VAL if result is negative infinity.

Returns

• 0 on success.
• AVERROR(EINVAL) if mode "FF_EBUR128_MODE_I" has not been set.

Definition at line 608 of file ebur128.c.

ff_ebur128_loudness_momentary()

int ff_ebur128_loudness_momentary	(	FFEBUR128State *	st,
		double *	out
	)

Get momentary loudness (last 400ms) in LUFS.

Parameters

st	library state.
out	momentary loudness in LUFS. -HUGE_VAL if result is negative infinity.

Returns

• 0 on success.

Definition at line 630 of file ebur128.c.

ff_ebur128_loudness_shortterm()

int ff_ebur128_loudness_shortterm	(	FFEBUR128State *	st,
		double *	out
	)

Get short-term loudness (last 3s) in LUFS.

Parameters

st	library state.
out	short-term loudness in LUFS. -HUGE_VAL if result is negative infinity.

Returns

• 0 on success.
• AVERROR(EINVAL) if mode "FF_EBUR128_MODE_S" has not been set.

Definition at line 645 of file ebur128.c.

Referenced by filter_frame().

ff_ebur128_loudness_window()

int ff_ebur128_loudness_window	(	FFEBUR128State *	st,
		unsigned long	window,
		double *	out
	)

Get loudness of the specified window in LUFS.

window must not be larger than the current window set in st.

Parameters

st	library state.
window	window in ms to calculate loudness.
out	loudness in LUFS. -HUGE_VAL if result is negative infinity.

Returns

• 0 on success.
• AVERROR(EINVAL) if window larger than current window in st.

Definition at line 659 of file ebur128.c.

ff_ebur128_loudness_range()

int ff_ebur128_loudness_range	(	FFEBUR128State *	st,
		double *	out
	)

Get loudness range (LRA) of programme in LU.

Calculates loudness range according to EBU 3342.

Parameters

st	library state.
out	loudness range (LRA) in LU. Will not be changed in case of error. AVERROR(EINVAL) will be returned in this case.

Returns

• 0 on success.
• AVERROR(EINVAL) if mode "FF_EBUR128_MODE_LRA" has not been set.

Definition at line 753 of file ebur128.c.

Referenced by filter_frame(), and uninit().

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.

Calculates loudness range according to EBU 3342.

Parameters

sts	array of library states.
size	length of sts
out	loudness range (LRA) in LU. Will not be changed in case of error. AVERROR(EINVAL) will be returned in this case.

Returns

• 0 on success.
• AVERROR(EINVAL) if mode "FF_EBUR128_MODE_LRA" has not been set.

Definition at line 676 of file ebur128.c.

Referenced by ff_ebur128_loudness_range().

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.

Parameters

st	library state
channel_number	channel to analyse
out	maximum sample peak in float format (1.0 is 0 dBFS)

Returns

• 0 on success.
• AVERROR(EINVAL) if mode "FF_EBUR128_MODE_SAMPLE_PEAK" has not been set.
• AVERROR(EINVAL) if invalid channel index.

Definition at line 758 of file ebur128.c.

Referenced by filter_frame(), and uninit().

ff_ebur128_relative_threshold()

int ff_ebur128_relative_threshold	(	FFEBUR128State *	st,
		double *	out
	)

Get relative threshold in LUFS.

Parameters

st	library state
out	relative threshold in LUFS.

Returns

• 0 on success.
• AVERROR(EINVAL) if mode "FF_EBUR128_MODE_I" has not been set.

Definition at line 587 of file ebur128.c.

Referenced by filter_frame(), and uninit().