LAudioMixer Reference Manual & Multi-Channel Mixing Guide

The LAudioMixer class is the multi-channel audio mixing and VU level monitoring engine of the now2sdk framework, derived from the LObject class. It allows developers to register multiple audio sources (such as LFile or LLive), configure individual volume gains, toggle mute states, apply master volume rules, and query real-time peak VU levels for both inputs and master outputs.

Under the hood, LAudioMixer automatically handles sample rate conversion, channel layout mapping, and bit depth resampling to 48kHz Stereo S16 PCM via AudioMixerSink for each registered channel, ensuring glitch-free mixing of different audio sources.

1. Multi-Channel Audio Mixing Architecture

graph TD
    A[Audio Source 1 - LFile/LLive] -->|pushAudioFrame| B[AudioMixerSink 1]
    C[Audio Source 2 - LFile/LLive] -->|pushAudioFrame| D[AudioMixerSink 2]
    B -->|Resample to target format| E[LAudioMixer Mix Loop]
    D -->|Resample to target format| E
    E -->|Apply Track Gain & Mute| F[Per-Channel Gain/Mute]
    F -->|Routing Matrix 16x16| G[PCM Mix Bus]
    G -->|Apply Master Gain & Mute| H[Peak VU Calculator - 16ch]
    H -->|Mixed Output| I[distributeAudioFrame]
    H -->|Query| J[getChannelLevel / getMasterLevel]

Key Audio Features:

• Automatic Resampling: Each track has a dedicated AudioMixerSink that normalizes any input to the configured audioFormatProps.
• 16-Channel Architecture: All track/channel gain, mute, and level arrays support up to 16 channels natively.
• Routing Matrix: Supports arbitrary source→destination channel routing per track.
• Real-Time VU Metering: Per-channel level queries from 0.0f to 1.0f for individual tracks and master output.

2. API Reference & Public Methods

📌 Track Management

void addTrack(const std::string& id, LObject* obj);
void removeTrack(const std::string& id);

Registers/deregisters an audio source with a unique id. Each track automatically gets a dedicated AudioMixerSink.

📌 Track-Level Gain & Mute

void setTrackGain(const std::string& id, int gain);
int  getTrackGain(const std::string& id);
void setTrackMute(const std::string& id, bool mute);
bool getTrackMute(const std::string& id);

Sets/gets overall volume (0–100) and mute state for the entire track.

📌 Per-Channel Gain & Mute

void setChannelGain(const std::string& id, int channel, int gain);
int  getChannelGain(const std::string& id, int channel);
void setChannelMute(const std::string& id, int channel, bool mute);
bool getChannelMute(const std::string& id, int channel);

Fine-grained control per channel within a track. channel is 0-based (0–15).

📌 Routing Matrix

void addRouting(const std::string& id, int srcCh, int dstCh);
void removeRouting(const std::string& id, int srcCh, int dstCh);
void changeRouting(const std::string& id, int srcCh, int oldDstCh, int newDstCh);
void clearRouting(const std::string& id);
bool getRouting(const std::string& id, int srcCh, int dstCh);

Configures a 16×16 source→destination channel routing matrix per track.

📌 Master Controls

void setMasterGain(int gain);
int  getMasterGain();
void setMasterMute(bool mute);
bool getMasterMute();

Controls master output gain (0–100) and mute applied after all tracks are mixed.

📌 Format & Clock

void setAudioFormat(const audioFormatProps& props);
void getAudioFormat(audioFormatProps& props);
void setFPS(double fps);

Configures the target output audio format. setFPS sets the video FPS driving the mix loop timing (default: 50.0).

📌 Real-Time VU Level Queries

float getChannelLevel(const std::string& id, int channel);
float getMasterLevel(int channel);

Returns real-time peak amplitude (0.0f–1.0f) for a specific channel within a track or for the master output. channel is 0-based (supports up to 16 channels).

3. C++ Integration Code Example

#include "LAudioMixer.h"
#include "LFile.h"
#include <iostream>
#include <thread>
#include <chrono>

void setupAudioMixer() {
    LFile* music = new LFile();
    music->fileNameSet("/media/music.wav");

    LAudioMixer* mixer = new LAudioMixer();

    // Configure output format (8-channel example)
    audioFormatProps ap;
    ap.setAudioFormat = aF_48000_16bit_8ch;
    mixer->setAudioFormat(ap);
    mixer->setFPS(50.0);

    // Add tracks
    mixer->addTrack("music", music);

    // Track-level controls
    mixer->setTrackGain("music", 80);

    // Mute channel 3 (0-based index 2) of music track
    mixer->setChannelMute("music", 2, true);

    // Routing: send music CH1 to master CH1
    mixer->addRouting("music", 0, 0);
    mixer->addRouting("music", 1, 1);

    // Master gain
    mixer->setMasterGain(90);
    mixer->setMasterMute(false);

    music->play();

    // Real-time VU monitoring
    for (int i = 0; i < 20; ++i) {
        std::this_thread::sleep_for(std::chrono::milliseconds(500));
        float ch0 = mixer->getChannelLevel("music", 0);
        float masterL = mixer->getMasterLevel(0);
        float masterR = mixer->getMasterLevel(1);
        std::cout << "CH1=" << (int)(ch0*100) << "% Master L=" << (int)(masterL*100) << "% R=" << (int)(masterR*100) << "%" << std::endl;
    }

    music->stop();
    delete mixer;
    delete music;
}