ebur128

README

ebur128

Pure Go implementation of EBU R-128 / ITU-R BS.1770-4 loudness measurement.

Features

• Integrated loudness (LUFS) with absolute and relative gating
• True peak (dBTP) via 4x polyphase FIR oversampling
• Loudness range (LU) per EBU TECH 3342
• Stereo and 5.1 surround support

Input: interleaved []float64 or []float32 PCM at 48 kHz, stereo or 5.1.

Usage

meter, err := ebur128.New(ebur128.LayoutStereo, 48000)
if err != nil {
    log.Fatal(err)
}
meter.Write(buf) // []float64, interleaved L/R
res := meter.Loudness()
fmt.Printf("Integrated: %.1f LUFS\n", res.IntegratedLoudness)
fmt.Printf("True peak:  %.1f dBTP\n", res.TruePeak)
fmt.Printf("LRA:        %.1f LU\n", res.LoudnessRange)

See cmd/example for a complete CLI tool.

Also available: WriteFloat32, Reset, Finalize (zero-pads trailing partial sub-block), Reserve (pre-alloc for known duration).

Accuracy

Cross-validated with ffmpeg -af ebur128=peak=true on generated test signals (see testdata/generate.sh):

Metric	Tolerance
Integrated loudness	±0.2 LUFS
True peak	±0.5 dB
Loudness range	±1.0 LU

Example:

$ go run ./cmd/example testdata/sine_stereo_1k_loud.wav
Integrated loudness:  -20.0 LUFS
True peak:            -20.0 dBTP
Loudness range:         0.0 LU

$ ffmpeg -i testdata/sine_stereo_1k_loud.wav -af ebur128=peak=true -f null -
I: -20.0 LUFS
Peak: -20.0 dBFS
LRA: 0.0 LU

Testing

Integration tests require WAV files generated with ffmpeg:

bash testdata/generate.sh   # generates ~6 MB of test WAVs
go test -v -count=1

Tests skip automatically if the WAV files are missing.

Performance

Benchmarks (Apple M2 Max 16-core CPU):

Operation	Throughput	Allocations
Write (Stereo, float64)	~215 MB/s (>140x real-time)	0 allocs/op
WriteFloat32 (Stereo)	~115 MB/s (>75x real-time)	0 allocs/op
Loudness (60s analysis)	~20 µs	3 allocs/op

Write and WriteFloat32 are allocation-free in steady state.

References

• EBU R 128 / ITU-R BS.1770-4
• EBU TECH 3341 (loudness metering)
• EBU TECH 3342 (loudness range)

Documentation

Overview

Package ebur128 implements EBU R-128 loudness measurement (integrated loudness, true peak, loudness range).

Only 48 kHz is supported.

Index

• type ChannelLayout
• type Meter
  • func New(layout ChannelLayout, sampleRate int) (*Meter, error)
  • func (m *Meter) Finalize()
  • func (m *Meter) Loudness() Result
  • func (m *Meter) Reserve(seconds float64)
  • func (m *Meter) Reset()
  • func (m *Meter) Write(buf []float64)
  • func (m *Meter) WriteFloat32(input []float32)
• type Result

Examples

• Meter

Types

type ChannelLayout

type ChannelLayout int

const (
	LayoutStereo ChannelLayout = iota // 2ch: L, R
	Layout51                          // 6ch: L, R, C, LFE, Ls, Rs
)

type Meter

type Meter struct {
	// contains filtered or unexported fields
}

Example

package main

import (
	"fmt"

	"github.com/exaring/ebur128"
)

func main() {
	meter, _ := ebur128.New(ebur128.LayoutStereo, 48000)

	buf := make([]float64, 48000*2) // 1 sec stereo silence
	meter.Write(buf)

	res := meter.Loudness()
	fmt.Printf("I: %.1f LUFS\n", res.IntegratedLoudness)
}

Output:

I: -99.0 LUFS

func New

func New(layout ChannelLayout, sampleRate int) (*Meter, error)

func (*Meter) Finalize

func (m *Meter) Finalize()

Finalize flushes any incomplete sub-block (zero-padded). Idempotent.

func (*Meter) Loudness

func (m *Meter) Loudness() Result

Loudness returns the measurement. Call Finalize first to include trailing samples.

func (*Meter) Reserve

func (m *Meter) Reserve(seconds float64)

func (*Meter) Reset

func (m *Meter) Reset()

func (*Meter) Write

func (m *Meter) Write(buf []float64)

func (*Meter) WriteFloat32

func (m *Meter) WriteFloat32(input []float32)

type Result

type Result struct {
	IntegratedLoudness float64 // LUFS (gated)
	TruePeak           float64 // dBTP, max across channels
	LoudnessRange      float64 // LU; 0 if unmeasurable

	// Number of 400ms blocks that passed both gates (0 = unmeasurable).
	GatedBlockCount int
	// Number of 3s windows that passed both gates for LRA (<2 = unmeasurable).
	LRAGatedWindowCount int
}

Result of a loudness measurement. Fields are set to loudnessUnmeasurable (-99) when the input is too short or fully gated out.