LevelAPI2 & LevelShow2
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. 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 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, 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

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 Technical Specifications

Surround channel orders

12 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.

13 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.

14 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

15 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