Feature request: Route mono source to stereo output and vice versa

[yorkshiretwist]

Please accept my apologies if this is in the docs somewhere.I see from the source code of BaseAudioSource.OutputChannelMapping that it looks like I can only route a source to the same number of channels, i.e. a mono source to 1 channel, a stereo source to 2 channels.

Is it possible to route a mono source to more than 1 channel (i.e. splitting it) or route a stereo source to 1 channel (summing L+R to a mono signal)?

I've also noticed, related to #25 that I need to set the number of targetChannels to 0 to get the correct value for StreamInfo.Channels. However, when I do that I must then route the source to a channel or playback is badly distorted. This simple program demonstrates it:

using OwnaudioNET;
using OwnaudioNET.Mixing;
using OwnaudioNET.Sources;
using System.Text.Json;

await OwnaudioNet.InitializeAsync();
OwnaudioNet.Start();

// Force Ownaudio.Native to be loaded so that [ModuleInitializer] can be run
var _ = typeof(Ownaudio.Native.NativeAudioEngine);

Console.WriteLine("WAV");
var fileSource = new FileSource("mono.wav", 8192, 48000, 0); // <== the final parameter here has to be 0 in order for StreamInfo.Channels to be 1
Console.WriteLine(JsonSerializer.Serialize(fileSource, new JsonSerializerOptions
{
    WriteIndented = true,
}));

Console.WriteLine("Press enter to play file...");
Console.ReadLine();

// if I comment out this line the audio is distorted
fileSource.RouteToChannels([0]);

var mixer = new AudioMixer(OwnaudioNet.Engine!.UnderlyingEngine);
mixer.Start();

mixer.AddSource(fileSource);

Console.WriteLine("Press enter to exit...");
Console.ReadLine();

mixer.Dispose();
await OwnaudioNet.ShutdownAsync();

mono.wav

[ModernMube]

The rule is that the length of the OutputChannelMapping array should be equal to the number of original channels of the source (Config.Channels).

However, the solution is not to manipulate OutputChannelMapping, but to use the framework's built-in, source-level channel converter (AudioFormatConverter).

Here's how you can solve it:

Split a mono source into multiple channels (Mono -> Stereo Upmix)

When you instantiate a FileSource, you can directly specify the desired number of channels (targetChannels) in the constructor. Behind the scenes, the engine will automatically duplicate the mono signal to stereo (or even multichannel) during loading/decoding.

// Loading a mono file, but forcing the system to return 2 channels (stereo)
var mySource = new FileSource("mono_audio.wav", targetChannels: 2);
// Then mySource.Config.Channels will be 2!
// This way you can freely map to 2 different physical/mixer output channels:
mySource.OutputChannelMapping = new[] { 0, 1 };

Routing a stereo source to one channel (Stereo -> Mono Downmix)

There are two solutions for this in the API:

1. Averaging is the cleanest method, if you convert the file to mono when loading. The internal AudioChannelConverter then halves (averages) the left and right channels (L+R) * 0.5f, thus avoiding clipping.

// Loading a stereo file, but treating it as mono (1 channel)
var mySource = new FileSource("stereo_audio.wav", targetChannels: 1);
// mySource.Config.Channels == 1, can go to 1 target channel:
mySource.OutputChannelMapping = new[] { 0 };

2. Using OutputChannelMapping Although you can't do mono -> stereo separation with OutputChannelMapping (due to the length requirement), you can do stereo -> mono downmix! Since the mixer uses an additive algorithm, you can simply route both source channels to the same output channel:

var mySource = new FileSource("stereo_audio.wav"); // Remain stereo (2 channels)
// We route both the Left (element 0) and Right (element 1) channels of the source to channel 0 of the mixer:
mySource.OutputChannelMapping = new[] { 0, 0 };

Since the mixer simply adds the values ​​of the two channels (does not average them), the output signal will be louder. Although the built-in limiter protects against digital distortion (clipping), if the original file is very loud, method 1 is the better and recommended method.

[yorkshiretwist]

Thank you for the quick and detailed response. I was hoping to be able to change the output channels for a source without having to reload it - even changing the output channels while the source is playing - but if that's not possible then I'll have to reload the source when I want to change the channels.

This shows part of my UI (you can see I've used a lot of the OwnAudio.Example.MultitrackPlayer project):

Each track says "S" or "M" for stereo or mono, and there's a ComboBox to select the channel outputs. I want to change the values in the ComboBox so that any source can go to either a single mono channel or stereo pair of channels (i.e. 1+2, 3+4 etc). It looks like I'll have to reload the FileSource in the TrackInfo instance to do that, which should be OK as it's pretty quick to load files.

Thank you again :)

[ModernMube]

Hi!
Here's how you can use a multi-channel audio device:

Sources on separate physical channels

If you want to send each source to a separate pair of physical channels, call each source. The mixer will automatically route the source's stereo sound to the specified logical channel locations and reset the others. RouteToChannels()

Routing per source using RouteToChannels()

// 8-channel interface: music on physical channels 0+1, metronome on physical channels 4+5
// AudioConfig uses 4 logical channels, which are mapped to physical channels 0, 1, 4, 5
var config = new AudioConfig
{
Channels = 4,
OutputChannelSelectors = new[] { 0, 1, 4, 5 }
};
await OwnaudioNet.InitializeAsync(config);
OwnaudioNet.Start();

var engine = OwnaudioNet.Engine!.UnderlyingEngine;
var mixer = new AudioMixer(engine, bufferSizeInFrames: 512);

var music = new FileSource("music.wav", 8192, targetSampleRate: 48000, targetChannels: 2);

var metronome = new FileSource("click.wav", 8192, targetSampleRate: 48000, targetChannels: 2);

// Route each source to its own logical channel pair.
// The engine then performs a logical → physical mapping using OutputChannelSelectors:
// logical 0+1 → physical 0+1 (music)
// logical 2+3 → physical 4+5 (metronome)

music.RouteToChannels(0, 1);

metronome.RouteToChannels(2, 3);

mixer.AddSource(music);

mixer.AddSource(metronome);

mixer.Start();

music.Play();

metronome.Play();

RouteToChannels() and functions are available in all BaseAudioSource subclasses: and all custom subclasses. The length of the mapping array must match the length of the source.

[yorkshiretwist]

That's very useful, thanks. In my app I'll always be using all the available physical channels on the interface, which removes the need to mentally map between physical and logical channel numbers.

However (and apologies for this question as I'm sure I'd seen it somewhere in the docs/examples but now I can't find it) how do I a) display a list of interfaces to allow the user to select one and b) detect the number of available physical channels for the selected interface?

Thank you again.

[ModernMube]

I think that's what you mean!

AudioDeviceInfo

Information about an audio device.

Property Type Description

DeviceId string - Unique device identifier
Name string - Human-readable device name
IsInput bool - True if device supports input
IsOutput bool - True if device supports output
IsDefault bool - True if this is the default device
State AudioDeviceState - Current device state
MaxInputChannels int - Maximum number of input channels supported (0 if unavailable)
MaxOutputChannels int - Maximum number of output channels supported (0 if unavailable)

Device Enumeration & Channel Routing

using var engine = AudioEngineFactory.CreateDefault();

// List output devices and their channel counts
var devices = engine.GetOutputDevices();
foreach (var device in devices)
{
    Console.WriteLine($"Device: {device.Name}");
    Console.WriteLine($"  ID: {device.DeviceId}");
    Console.WriteLine($"  Default: {device.IsDefault}");
    Console.WriteLine($"  Max Input Channels: {device.MaxInputChannels}");
    Console.WriteLine($"  Max Output Channels: {device.MaxOutputChannels}");
}

// Route stereo output to physical channels 4 and 5 (e.g. second pair of a multi-output interface)
var config = new AudioConfig
{
    Channels = 2,
    OutputChannelSelectors = new[] { 4, 5 }  // physical channel indices (0-based)
};
using var engine2 = AudioEngineFactory.Create(config);

// ASIO with native hardware channel selection
var asioConfig = new AudioConfig
{
    HostType = EngineHostType.ASIO,
    Channels = 2,
    OutputChannelSelectors = new[] { 4, 5 }  // native ASIO channel selectors
};
using var asioEngine = AudioEngineFactory.Create(asioConfig);