LevelAPI2 & LevelShow2
R128 Loudness C API Documentation

LevelAPI2 is a high-performance C dynamic library for loudness measurement and normalization to EBU R128 and ATSC A/85 (CALM Act) broadcast standards. This reference covers the full API, integration workflow, and all function signatures. The realtime adjuster, which holds a live signal on a loudness target in a single pass, has its own chapter. LevelShow2, the bundled DirectShow filter for Windows pipelines, is documented in the second half.

01 Introduction

LevelAPI2 and LevelShow2 are built to support the transition from peak normalization to loudness normalization, one of the most significant changes in broadcast audio in decades. This shift began when the ITU published BS.1770 (LKFS/LUFS loudness metering) in 2006. The European Broadcast Union built on this foundation with EBU R128, released in 2010, which became the global broadcast loudness standard.

The library interface consists entirely of C functions exposed through a dynamic library (.dll on Windows, .so on Linux). This makes it callable from any language with standard C FFI support: C, C++, Java, LUA, Python, Rust, Go, .NET, Delphi, and others.

02 System Requirements

• Windows 7 or later (x86 / x64)
• Linux: built on CentOS 7 (x64); custom builds available for other distributions
• System memory: 512 MB minimum
• Disk space: approximately 10 MB

03 Upgrading from LevelAPI v1

If you are migrating from the original LevelAPI, note the following breaking changes:

Renamed functions

Renamed enum values

Behaviour changes

• All functions that return a boolean now return 1 (true) on success and 0 (false) on failure. Previously this was inconsistent.
• PPM and RMS meters are disabled by default. Enable with SetPPMEnable(true) and SetRMSEnable(true).
• TruePeak HP and LP have been merged into a single high-precision TruePeak.

04 Usage Guide

Implementing LevelAPI2 follows a consistent pattern regardless of language or platform. The steps below describe the complete workflow from loading the library to retrieving results.

1. 1

   Load the dynamic library at runtime

   Use your platform's dynamic linking API (dlopen on Linux, LoadLibrary on Windows) to load the library file. A helper macro LevelAPI2_LoadDLL(path, &handles) is provided in the header to retrieve all function pointers in one call.

2. 2

   Validate your certificate

   Call SetCertificate(cert_string, length) as the first call after loading. This validates your license. If it returns false, call GetErrorString() to retrieve the failure reason. The certificate string should be embedded or loaded from a secure location in your application.

3. 3

   Create a handle

   Call Create_LevelAPI2(channels, samplerate, bitdepth) to create an instance. Every subsequent function call requires this handle as its first argument. You can create multiple handles to measure multiple sources simultaneously. Always call Destroy_LevelAPI2(handle) when done.

4. 4

   Configure measurement standard

   For EBU R128 compliance, call SetPresetEBU_R128(handle). For ATSC A/85, call SetPresetATSC(handle). These convenience functions set calibration, relative gate, dialog gate, target type and level in one call. You can then override individual settings using the Advanced Settings functions if needed.

5. 5

   Feed audio samples

   Call AnalyseInterleaved(handle, samples, numframes) with your interleaved float buffer. The numframes argument is in sample frames: for a stereo buffer of 512 samples, numframes = 256. For best performance, pass blocks of at least 256 frames. There is no maximum: a whole file in one call measures the same as the same file in blocks. For file-based workflows, use AnalyseFile(handle, filepath) directly.

6. 6

   Read meter levels

   At any point after analysis, call GetLevel(handle, meterType, channel) using values from the MeterTypes enum. Pass -1 as channel to get the combined result across all channels. Key values: LU, LRA, TruePeak, LU_Max_M, LU_Max_S.

7. 7

   Normalize the audio

   After analysis is complete, call AdjustInterleaved(handle, samples, numframes) to apply gain correction to your sample buffer. If using the same handle for both steps, the required adjustment level is already known. If using a separate handle for adjustment, first call SetAdjustLevel(handle, dB) with the value from GetAdjustLevel() or GetLevel(AdjustLevel). The built-in peak limiter activates automatically when needed.

Minimal C example

#include "LevelAPI2_dynlib.h"

// 1. Load library
struct LevelAPI2_FunctionHandles api;
void* lib = LevelAPI2_LoadDLL(library_path, &api);

// 2. Validate certificate
api.SetCertificate(cert_string, strlen(cert_string));

// 3. Create handle
LevelAPI2Ptr h = api.Create_LevelAPI2(channels, samplerate, bitdepth);

// 4. Configure for EBU R128
api.SetPresetEBU_R128(h);

// 5. Feed samples (interleaved float buffer)
//    numframes = total_samples / channels
api.AnalyseInterleaved(h, samples, numframes);

// 6. Read results
float lu       = api.GetLevel(h, LU,       -1);
float lra      = api.GetLevel(h, LRA,      -1);
float truepeak = api.GetLevel(h, TruePeak, -1);

// 7. Normalize
api.AdjustInterleaved(h, samples, numframes);

// Cleanup
api.Destroy_LevelAPI2(h);
LevelAPI2_UnloadDLL(lib);

05 Constants & Enums

DataRanges

SurroundOrders

LoudnessStandards

Used as the standard argument in SetPresetStandard(). Each value names one loudness standard, and one variant of it where a single document defines more than one recipe. The parameters each value applies are in section 11.

The numeric values are permanent: they are never renumbered and never reused, and each family has its own block of 100 so that one family can grow without moving any other value. A build that does not know a value returns false from SetPresetStandard() and changes nothing, so a version mismatch fails visibly instead of measuring to the wrong practice.

MeterTypes

Used as the meterType argument in GetLevel() and related functions. Values marked (*) are generally for testing only and not intended for display to end users.

06 Dynlib Initialization

These functions are called immediately after loading the dynamic library, before creating any handles.

07 Library Initialization

The following functions return stream format properties set during initialization:

08 Processing

09 Results

10 Advanced Settings

These functions modify measurement behaviour beyond the standard presets. For straightforward EBU R128 or ATSC A/85 compliance, the preset functions are sufficient. All Set functions return true on success.

Adjust Target

Channels

Gates

Calibration

Limiter

Time Window

Legacy Meters (PPM / RMS)

PPM and RMS are legacy meters, disabled by default. Enable them only if your integration specifically requires them.

Histogram Access

Raw histogram data is available for detailed loudness distribution analysis:

Conversion helpers between histogram positions and dB values:

11 Loudness Standards

A technician handed a delivery spec does not want to configure a meter. They want to pick the name printed on the document their broadcaster gave them. SetPresetStandard() takes one value from LoudnessStandards and applies that practice in full: the target, the relative gate, the dialogue gate, the true-peak ceiling, and which meter normalization moves onto the target.

Ten standards ship in this build. The library can also list and describe them at runtime, so a preset dropdown is generated from the loaded library rather than typed out by hand. A library update then adds standards to your product without a line of code changing.

For the plain-language version, with what each practice asks for and why the variants differ, see levelapi.dev/loudness-standards.

What each preset applies

A relative gate of 0 means ungated. The normalizes column is the meter Adjust() moves onto the target: an anchor-based practice normalizes dialogue loudness rather than the full mix. The limiter threshold is set but the limiter is never switched on or off by a preset, so a preset cannot move your audio for a reason you did not ask for.

Constants are shown without their LEVELAPI2_STANDARD_ prefix. The full names and their numeric values are in section 05.

Two rows are anchor-based and behave differently from the rest: EBU_R128_S4_CINEMA and ATSC_A85_LONGFORM normalize dialogue loudness rather than programme loudness. The dialogue meters fall back to the full mix on their own when the material carries less than 10% dialogue.

ITU-R BS.1770 publishes no target level. It defines a measurement, not a delivery practice, so the two ITU rows carry the library's own −23 default in order to be usable on their own. BS.1770 spells the unit LKFS; those two rows are labelled LUFS here because that is what the library reports for them at runtime through GetStandardDescription().

Function reference

Building a preset menu from the library

Enumerate rather than hardcode. A host built against a newer header but running against an older library then sees a shorter list, never a wrong answer.

// Populate a dropdown with whatever this build supports
int count = api.GetStandardCount(h);
for (int i = 0; i < count; i++)
{
    enum LoudnessStandards s = api.GetStandardAt(h, i);
    add_menu_item(api.GetStandardName(h, s),
                  api.GetStandardDescription(h, s),
                  (int)s);
}

// Apply the user's choice, and check the result
if (!api.SetPresetStandard(h, chosen))
{
    // This library build does not know that standard.
    // Nothing was changed. Do not measure and report anyway.
    report_unsupported_standard(chosen);
}

The two original presets

SetPresetEBU_R128() and SetPresetATSC() are unchanged and are not deprecated. They are exactly SetPresetStandard(LEVELAPI2_STANDARD_EBU_R128) and SetPresetStandard(LEVELAPI2_STANDARD_ATSC_A85_LONGFORM). Existing integrations need no edit.

How far these are verified

All ten presets are verified to configure exactly what their own standard's document specifies. Three are additionally verified against that body's own published reference audio: EBU R 128, ITU-R BS.1770 and ARIB TR-B32. The other seven have no published reference set to measure against: only some standards bodies release conformance audio. Full per-file results, with the tolerance and the document clause beside every measurement, are at levelapi.dev/compliance.

12 Technical Specifications

Surround channel orders

13 Realtime Adjuster

The realtime adjuster holds a live signal on a loudness target while the audio is passing through it. It measures and corrects in a single pass, with no analysis stage and no knowledge of what is coming next, which is what allows it to sit in a path where the audio has to come out now: a live console insert, a monitor path, a stream encoder, a broadcast chain.

Most of the time it only rides the gain, slowly and in small steps, so the dynamics of the material are left alone. A sudden jump in level is too fast for that ride, so a peak stage catches it within a fraction of a second: a short cut, a gentle compressor that is active only while the cut is, and a true-peak limiter. The ride then takes the correction over and the peak stage lets go.

EBU R128 asks produced programme to sit within ±0.5 LU of target, and permits ±1.0 LU on less predictable material such as live mixed programme. That wider window is the one the adjuster works to, once it is warmed up. Treat it as a target rather than a guarantee: difficult live material with extreme dynamics can land outside the band.

The adjuster is a separate object from the measurement API, with its own handle type (LevelAPI2_RealtimeAdjusterPtr) and its own create and destroy calls. A single process can run both, and any number of either.

Integration overview

1. 1

   Load the library and validate your certificate

   Identical to the measurement API. SetCertificate() is a global call made once per process after loading, not once per handle.

2. 2

   Create an adjuster

   Create_RealtimeAdjuster(channels, samplerate, bitdepth) returns the handle every other call takes as its first argument. There is no standard preset pair to choose here: the adjuster works to a LUFS target you set directly.

3. 3

   Set the preset and the target

   The constructor takes neither, so both are applied immediately afterwards with RealtimeAdjuster_SetPreset() and RealtimeAdjuster_SetTargetLUFS().

4. 4

   Call Adjust() on every block

   The buffer is modified in place. Nothing else has to happen per block, and no result has to be read for the adjuster to do its job.

#include "LevelAPI2_dynlib.h"

// 1. Load library and validate certificate (once per process)
struct LevelAPI2_FunctionHandles api;
void* lib = LevelAPI2_LoadDLL(library_path, &api);
api.SetCertificate(cert_string, strlen(cert_string));

// 2. Create an adjuster instance
LevelAPI2_RealtimeAdjusterPtr h =
    api.Create_RealtimeAdjuster(channels, samplerate, bitdepth);

// 3. Configure: preset and target loudness
api.RealtimeAdjuster_SetPreset(h, 1);          // 1 = medium (default)
api.RealtimeAdjuster_SetTargetLUFS(h, -23.0f); // EBU R128 programme target

// 4. Per audio block: adjust in place (planar buffers)
api.RealtimeAdjuster_Adjust(h, channel_pointers, numframes);

// Optional: read what it is doing, for display
float applied = api.RealtimeAdjuster_GetLastAppliedGainDb(h);
float lufs    = api.RealtimeAdjuster_GetLUFS(h);

// With video: delay the picture by the adjuster's latency to keep lip-sync.
// The loader leaves a function NULL on an older library, so check it first.
unsigned int delay = api.RealtimeAdjuster_GetLatencySamples
    ? api.RealtimeAdjuster_GetLatencySamples(h) : 0;

// Cleanup
api.Destroy_RealtimeAdjuster(h);
LevelAPI2_UnloadDLL(lib);

That is the whole integration. Everything below is optional refinement.

Latency and the limiter

The peak stage looks ahead, so the adjuster delays the audio by 50 ms: 2205 frames at 44.1 kHz, 2400 at 48 kHz. The delay is fixed from Create_RealtimeAdjuster() or Reset() until the next Reset(), whatever the preset or the limiter switch, so a host can compensate for it once. RealtimeAdjuster_GetLatencySamples() reports it in frames; delay the picture by that amount to keep lip-sync.

The limiter holds the output at -1 dBTP by default, measured as true peak on a 4x oversampled signal, so the inter-sample peaks that a sample-peak limiter misses are caught as well. Delivery specifications differ (ATSC A/85 and Free TV OP-59 ask for -2 dBTP), so the ceiling is a setting: RealtimeAdjuster_SetTruePeakCeilingDb(handle, -2.0f) takes anything from -12 to 0 dBTP and is kept across Reset(). Lowered mid-stream, the new ceiling is reached within 20 ms.

The limiter holds the ceiling on its own 4x estimate. On material with strong content close to half the sample rate (noise, some synthesised or lossy sources) a BS.1770 true-peak meter can read up to about 0.6 dB higher. For a guarantee on such material, set the ceiling that much lower. On programme material the two agree.

RealtimeAdjuster_SetLimiterEnabled(handle, false) switches the limiter off if your chain already has one. The 50 ms delay stays, and so does the rest of the peak stage. Without the limiter a fast transient can clip, so peak protection has to exist somewhere in your chain.

Warmup and settling

The adjuster corrects from the first block of audio. There is no warmup period to wait through, and no opening stretch during which the output plays closer to the input level than to the target.

Warmup is a property of the preset rather than of the adjuster, so a preset can choose to ease its correction in instead. No preset in this version does. Because the value comes from the preset, calling SetPreset() mid-stream can change it.

Separately, the adjuster's own integrated meter needs audio behind it before the loudness it reports means anything, so calibration strength ramps in over 5 seconds on every preset. That clock starts where the main warmup ends, so under a preset that has one the total wait is the two added together; with no warmup it starts at the first block. The moment it reaches zero is also the moment GetLUFS() is fully settled, which makes it the honest gate for anything that displays or logs a measured level.

Four read-outs report the two clocks, all in seconds:

• GetWarmupSecondsLeft() and GetCalibrationSecondsLeft() count down to 0 and stay there. <= 0 is the test for done.
• GetWarmupSecondsMax() and GetCalibrationSecondsMax() report the lengths the current preset is configured for, so a countdown can be drawn without hardcoding a duration. A maximum of 0 means the preset has no such period at all.

A completed warmup is latched. Switching preset while audio is running can shorten a warmup still in progress, but it never re-opens one that has already finished.

Presets

SetPreset() takes a plain unsigned int, so the legal values are listed here rather than expressed as an enum across the library boundary. Once tuned, the presets differ in how quickly the adjuster responds and how strongly it weights recent audio against the programme so far. They are close to each other by design: the intent is a stable output level, and the reason to change preset is that the output is not reaching the target, not that you want a different sound.

Medium is what LevelAnchor ships with, hard-coded, and it is what has been tuned against real material. In this version Slow and Fast use Medium's values: the values 0 and 2 are still accepted and returned, so code that selects them keeps working, and each gets its own tuning in a later version.

Threading and lifecycle

Adjust() and AdjustInterleaved() never allocate memory and never take a lock, so they are safe on a realtime audio thread. Every other getter and setter is safe from any thread, with one exception: GetLevel() reads a live meter, so call it from the thread that calls Adjust(), between calls. A setter takes effect at the start of the next Adjust() call, and the loudness ride acts on it at its next 10 ms step.

One adjuster instance handles one stream. Create as many as you have streams. Reset() starts a fresh stream, optionally in a new format: nothing the previous stream measured or decided carries over. The preset, the target, the limiter switch and the program length are kept.

Buffers are modified in place. Adjust() takes planar channel pointers, AdjustInterleaved() takes one interleaved buffer. Maximum 16 channels, and any number of frames per call.

Internally the adjuster decides on a 10 ms grid, counted from the start of the stream. The output does not depend on the host's block size: any number of frames per call gives exactly the same output, sample for sample. With dither on, the dither noise is the same noise drawn in a different order. Very small blocks cost more CPU per second of audio: 64-frame blocks take about twice the CPU of 10 ms blocks.

Setting the target with SetTargetLUFS() while audio is running is supported and is the normal way to change target. The adjuster ramps toward the new value rather than jumping to it.

Continuous feeds (24/7)

By default the adjuster's long-term correction looks at the whole stream since Create_RealtimeAdjuster() or the last Reset(). That suits a programme with a beginning and an end, with a Reset() at its start.

A feed that runs for hours or days should set a program length instead, so the correction keeps responding when the feed's loudness changes. After a day of audio, one new hour is too small a share of the whole to move it. 900 seconds is the tested value.

// Right after Create, before any audio: costs nothing there
api.RealtimeAdjuster_SetProgramLengthSeconds(h, 900);

On material up to an hour long, 900 s changes nothing for the first 15 minutes and keeps the programme's integrated level where the default puts it, within 0.06 LU. Later in a long programme it holds the short-term level inside ±1 LU slightly more often, for 1 to 3 % more gain movement. It costs nothing measurable on shorter programmes. Set mid-stream, it restarts the long-term correction from an empty meter; the gain does not jump.

Measured behaviour

The adjuster is measured by a published test method on 113 cases at -23 LUFS and 67 at -16 LUFS: synthetic level jumps and pauses, broadcast recordings, films, music, audiobooks, conversation and a live stream. The results list every graded criterion with every failing case and its figure, and a table of what a listener hears in each situation and what changes it. In short:

• Whole programmes end within ±1 LU of the target: all of them at -23 LUFS. At -16 LUFS, material quieter than about -28 LUFS stays under it, because +12 dB is the most the adjuster adds.
• After a jump to louder material the output is too loud for about half a minute, by up to about 7.5 LU, then settles. A host that knows where the programme changes (a playlist change, an ad insertion) can call Reset() there, off the audio thread.
• On a feed that runs for hours, set a program length.

Function reference

All functions below take a LevelAPI2_RealtimeAdjusterPtr as their first argument. All Set functions return true on success.

Informational read-outs

These report what the adjuster is measuring. None of them is required to run it, and an integration that only needs correct loudness can ignore this section entirely.

LevelAnchor, the free OBS plugin built on this API, deliberately displays none of these. It shows a target and an output level, and nothing else. They are here because a product might want them, not because the adjuster needs them.

Worked example

LevelAnchor, the free OBS loudness plugin, is a complete, shipping integration of this exact header: a Windows VST plugin that holds a live audio source on a LUFS target. Its source is public, and the released binary is built from it. The file to read is Source/LevelApiDynamic.cpp, which loads the library, resolves the function table, creates one adjuster per plugin instance and calls Adjust() from the audio callback.

14 LevelShow2: Overview

LevelShow2 is a Windows DirectShow filter that wraps LevelAPI2 for use in Windows media pipeline applications. It is included with every LevelAPI2 license.

It exposes the same measurement and normalization capabilities as LevelAPI2 through two interfaces: a graphical properties page for manual operation, and the ILevelShow2 COM interface for programmatic control.

15 LevelShow2: Usage

LevelShow2 can be implemented in two ways:

• Single instance: one filter handles both analysis and adjustment in sequence. Simpler workflow, suitable for most use cases.
• Two instances: one filter analyses, a second applies the adjustment. Allows analysing multiple files first, then normalizing them in a separate pass.

Basic workflow

1. 1

   Build your DirectShow graph

   Connect your audio source to the LevelShow2 input pin and connect the output pin downstream.

2. 2

   Configure analysis settings

   Enter your certificate, set Mode to Analyse, select your standard (EBU R128 or ATSC), and if using surround, select the correct channel order.

3. 3

   Stream the audio

   Run the graph to pass all audio through the filter. LevelShow2 accumulates measurement data throughout the stream.

4. 4

   Switch to Adjust mode

   Set Mode to Adjust. The filter automatically configures itself with the calculated normalization gain. To reset for a new stream, set Mode to −1.

5. 5

   Re-stream to apply normalization

   Pass the audio through the filter again. The output is now level-normalized. Alternatively, pass the AdjustLevel value to a second instance set to Adjust mode.

16 LevelShow2: Programmatic Interface

Query the ILevelShow2 interface via IUnknown::QueryInterface to control the filter programmatically. The interface mirrors the graphical controls exactly.

License

Mode

Analyse settings

Results

17 References

• tech.ebu.ch/loudness: EBU R128 recommendation, official documents, guidelines, and introduction videos
• ATSC A/85 Recommendation, available from the ATSC website
• ITU-R BS.1770, the foundational loudness metering standard

18 Release Notes

What changed for users of the library, newest first. The version is the number GetRevision() returns.

202609280

Check these before upgrading

• The realtime adjuster's output no longer depends on the host's block size: every block size gives what 10 ms blocks give, sample for sample. Code that fed other sizes hears the same level with a slightly different gain path.

New

• RealtimeAdjuster_SetTruePeakCeilingDb() / GetTruePeakCeilingDb(): the limiter's ceiling as a setting, -1 dBTP by default. See Latency and the limiter.
• The realtime adjuster's measured results, by a published test method.

Fixed

• After 20 to 45 seconds of digital silence, the returning programme could be up to 7 LU too loud for several seconds.
• After a realtime Reset() to another sample rate, one internal clock kept the old rate.

The compliance example passes 162 of 173 checks, the same on Windows and Linux: full results. The realtime adjuster's row left it for its own results.

202609270

Check these before upgrading

• The realtime adjuster's latency is now 50 ms (was 20 ms), and it stays 50 ms with the limiter off. Read it with RealtimeAdjuster_GetLatencySamples().
• The realtime limiter's ceiling is now -1 dBTP true peak (was -1 dBFS sample peak).
• The Slow and Fast realtime presets behave as Medium for now, so Slow no longer has its 30-second warmup.
• RealtimeAdjuster_GetLastAppliedGainDb() now dips briefly on a sudden jump in level.
• A realtime adjuster uses about twice the CPU of the previous version, and roughly 50 MB of memory.
• PSR can read higher than before on dynamic material.

New

• A new realtime processing chain, tuned on real programme material: it catches a sudden jump in level within a fraction of a second. See Realtime Adjuster.
• RealtimeAdjuster_GetLatencySamples(), RealtimeAdjuster_GetGainReductionDb(), and RealtimeAdjuster_SetProgramLengthSeconds() / GetProgramLengthSeconds() for 24/7 feeds.
• No limit on frames per call, on every analyse, adjust and realtime call.
• The realtime audio path never allocates memory or takes a lock, and the realtime getters are safe from any thread except GetLevel().

Fixed

• Realtime Reset() now starts a completely fresh stream.
• AnalyseInterleaved() could write past its buffer on a very large block.
• LRA and PSR read wrong after Init() was called again on the same handle.
• PSR could dip below zero after a pause.
• Dither no longer uses the system random generator: it is the same on every platform, takes no lock on Linux, and leaves your own use of rand() alone.

The compliance example passes 162 of 174 checks, the same on Windows and Linux: full results.

202609080

• Ten named loudness standard presets. See Loudness Standards.
• The compliance example, which measures the published EBU, ITU and ARIB reference files.