MonoStereo 1.1.7
See the version list below for details.
dotnet add package MonoStereo --version 1.1.7
NuGet\Install-Package MonoStereo -Version 1.1.7
<PackageReference Include="MonoStereo" Version="1.1.7" />
paket add MonoStereo --version 1.1.7
#r "nuget: MonoStereo, 1.1.7"
// Install MonoStereo as a Cake Addin #addin nuget:?package=MonoStereo&version=1.1.7 // Install MonoStereo as a Cake Tool #tool nuget:?package=MonoStereo&version=1.1.7
MonoStereo
MonoStereo is an audio engine built for MonoGame using the NAudio audio framework.
MonoGame's included audio support is lackluster, leaving many users to find audio implementation through other projects like FMOD. MonoStereo aims to be a free, open-source, entirely C# native audio engine, built specifically for MonoGame.
With included support for the Content Pipeline, dynamic filter application, multi-threaded safety, and the ability to supply your own custom audio sources/filters where MonoStereo's provided implementations don't meet your needs, you'll have everything you need to make your game's audio stand out above the rest.
Features
- Entirely C# native
- Cross platform
- MonoGame Content Pipeline integration
- Default audio looping support from audio metadata with
LOOPSTART
andLOOPEND
/LOOPLENGTH
tags - Dynamic audio filtering with 7 built-in filters
- Custom audio source support
- Direct PCM sample access
- Support for changing audio output device
Installation
MonoStereo is available as a package on Nuget. To install, simply add it as a package reference through your project's package manager.
To use MonoStereo's Pipeline integration, you'll need to add a reference to a built MonoStereo.dll
. The easiest way to go about this is to build your project once after MonoStereo has been installed - a compiled MonoStereo.dll
should appear in your project's output directory. Reference this file and you should be able to use MonoStereo's custom audio importers and processors.
Usage/Examples
Setup
To begin using MonoStereo, first initialize the audio engine in your game's startup code. This can be done anywhere, but it's recommended to place inside of your Game
's Initialize()
method.
Use the AudioManager.Initialize()
method to start the audio engine. You should supply this method with a Func<bool>
that lets the audio engine know when to shut down, as it runs on a separate thread to improve performance.
protected override void Initialize()
{
base.Initialize();
// Your other initialization code here
// `isRunning` will be false when the game stops.
AudioManager.Initialize(() => !isRunning);
}
You also have access to a few extra variables on startup, namely latency
, masterVolume
, musicVolume
, and soundEffectVolume
.
latency
is the desired latency, in milliseconds, before audio reaches the output device. Increasing this can create a slight delay in audio playback, but helps to reduce choppy audio when lots of post-processing effects are applied. The default 100ms is typically fine, but you may find yourself increasing or decreasing this value depending on your use-case.masterVolume
,musicVolume
, andsoundEffectVolume
are pretty self explanatory. These values should befloat
s that range from 0-1, with 1 being max volume, and 0 being mute. If you want to change the music, sound, or master volumes later, they are available with the propertiesAudioManager.MasterVolume
,AudioManager.MusicVolume
, andAudioManager.SoundEffectVolume
.
Playback
Playing audio with MonoStereo is very simple. To play a song, use the following:
Song song = new Song("path/to/song");
song.Play();
Your song path should be the path to the .xnb file generated by the content pipeline, without .xnb at the end.
When playing sound effects, you have 2 options. For sounds that won't be played back very frequently, you can create and play them the same way you would with a song.
SoundEffect sound = new SoundEffect("path/to/sound");
sound.Play();
Alternatively, if a sound is going to be played back frequently, it may be better to cache the sound's data in memory for quicker and more efficient access.
CachedSoundEffect cachedSound = new CachedSoundEffect("path/to/sound");
Now that the sound is cached in memory, you can play it one of two ways:
// Option 1
cachedSound.PlayInstance();
// Option 2
SoundEffect sound = cachedSound.GetInstance(); // Alternatively: new SoundEffect(cachedSound);
sound.Play();
When you no longer need the cached sound effect, call cachedSound.Dispose()
to dispose the object.
For both songs and sounds, you have access to the Song
and SoundEffect
instances that control playback for these objects. Looping support is integrated by default - just change the IsLooped
property. Additionally, you can call Pause()
, Resume()
, and Stop()
to control the playback state.
Filters
Adding filters to your audio with MonoStereo is very easy. All you need to do is create a new filter instance, and add it to your audio with the AddFilter()
method.
Song song = new("path/to/song");
song.Play();
// Whenever you want to add the filter...
PitchShiftFilter filter = new PitchShiftFilter(pitch);
song.AddFilter(filter);
// Whenever you want to remove the filter...
song.RemoveFilter(filter);
MonoStereo contains 7 built-in filters available to use:
HighPassFilter
LowPassFilter
PanFilter
PitchShiftFilter
PositionFilter
SpeedChangeFilter
VolumeFilter
Additionally, filter instances are shareable across multiple audio instances. If you create one instance of aPitchShiftFilter
, it can be applied to multiple audio sources (songs and sounds alike), and even be applied to the same source multiple times. Changing a property of the filter will carry that change over to every other audio source using the same filter.
SpeedChangeFilter speed = new(0.5f);
song1.AddFilter(speed);
song2.AddFilter(speed);
speed.Speed = 0.4f;
// Applies to both song1 and song2
If you want to apply a filter to every instance of a song or sound, rather than individually applying it to each one, apply it to the respective mixer:
AudioManager.MusicMixer.AddFilter(filter);
AudioManager.SoundMixer.AddFilter(filter);
AudioManager.MasterMixer.AddFilter(filter);
Note: since filters are reference types, in order to remove them, you will need to keep track of your filter's object instance.
Custom Implementations
MonoStereo supports custom implementations for songs, sounds, and filters. To use them, you can have classes inherit from ISongSource
, ISoundEffectSource
, and AudioFilter
.
You will need to provider a couple methods for each, and some more customization is optionally available through virtual overrides.
To use the custom sources:
Song song = new Song(new MyCustomSongSource());
SoundEffect sound = new SoundEffect(new MyCustomSoundEffectSource());
song.AddFilter(new MyCustomAudioFilter());
Audio reading is done through 32-bit IEEE floating-point samples. In order to implement any of the above classes, you'll need to supply a method that works with these samples. If you are unfamiliar with the inner-workings of audio reading, it is recommended to stick with MonoStereo's supplied implementations - but if you would like to learn, NAudio has some great references to study from.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net8.0
- NAudio (>= 2.2.1)
- z440.atl.core (>= 6.1.0)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on MonoStereo:
Package | Downloads |
---|---|
MonoStereo.Pipeline
MonoGame pipeline integration for the MonoStereo audio engine. |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
1.5.1 | 46 | 10/25/2024 |
1.5.0 | 41 | 10/21/2024 |
1.4.0 | 70 | 10/18/2024 |
1.3.0 | 52 | 9/26/2024 |
1.2.8 | 123 | 9/15/2024 |
1.2.7 | 107 | 9/15/2024 |
1.2.6 | 79 | 9/13/2024 |
1.2.5 | 102 | 9/6/2024 |
1.2.4 | 96 | 9/4/2024 |
1.2.3 | 97 | 9/4/2024 |
1.2.2 | 99 | 9/1/2024 |
1.2.1 | 92 | 9/1/2024 |
1.2.0 | 107 | 9/1/2024 |
1.1.9 | 98 | 9/1/2024 |
1.1.8 | 87 | 9/1/2024 |
1.1.7 | 83 | 9/1/2024 |
1.1.6 | 92 | 9/1/2024 |