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. Maximum is 16 × 1024 = 16384 frames per call. 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.

It modulates level toward the target rather than reshaping the signal, so the dynamics of the material are left alone.

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);

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

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

Latency and the limiter

The adjuster's only delay is its built-in peak limiter: 20 ms. Level modulation itself needs no look-ahead, so with the limiter disabled the adjuster runs at zero latency.

RealtimeAdjuster_SetLimiterEnabled(handle, false) switches it off. Without the limiter a fast transient can clip, so peak protection has to exist somewhere in your chain.

Most broadcast and production chains already have a limiter. If yours does, disabling the built-in one removes the delay rather than stacking two limiters and paying 20 ms for the second one.

Warmup and settling

On the default preset 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. Of the three, only Slow does: it brings gain correction up over its first 30 seconds. Medium and Fast have none. Because the value comes from the preset, calling SetPreset() mid-stream changes 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. 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.

They also differ in warmup. Slow brings its correction up over the first 30 seconds; medium and fast correct from the first block. See Warmup and settling.

Medium is what LevelAnchor ships with, hard-coded, and it is what has been tuned against real material.

Threading and lifecycle

One adjuster instance handles one stream. Create as many as you have streams. Reset() reconfigures an existing instance for a new stream format and clears its measurement history.

Buffers are modified in place. Adjust() takes planar channel pointers, AdjustInterleaved() takes one interleaved buffer. Maximum 16 channels, and at most 16384 sample frames per call, so split larger blocks across successive calls.

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.

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