Custom Audio Formats

It is highly recommended to check the Basic Setup page if you haven't already.
Some of the features mentioned in this page will not work if MonoSound has not been initialized.

Table of Contents
Preface
Registering the Format
Audio Loading
Audio Streaming
CustomAudioFormat API

Preface

By default, MonoSound supports loading and streaming audio files from the following formats:

• WAVE (.wav)
• OGG Vorbis (.ogg)
• MPEG Audio Layer III (.mp3)
• Compiled SoundEffect (.xnb)
• XACT Banks (.xwb and .xsb)
• Ram PCM Audio (.pcm) via class PcmFormat : CustomAudioFormat

If you want to use another audio format, you'll have to register the format. By doing so, MonoSound will attempt to load the audio using the format when the default formats don't apply to a given file or stream.

Registering the Format

To register a custom audio format, call MonoSoundLibrary.RegisterFormat():

// Theoretical format for a ".mm3" file
MonoSoundLibrary.RegisterFormat(new Mm3Format());

Audio Loading

Registered custom formats will automatically be checked when attempting to load or stream audio from files or data streams.
However, registering the format is not necessary to use it. In fact, the built-in SegmentedOggFormat format that MonoSound provides shouldn't be registered.

To load audio from a file with a specific format, call the overload of EffectLoader.GetEffect():

SoundEffect customSound = EffectLoader.GetEffect("Content/thing.mm3", new Mm3Format());
customSound.Play();

In a similar manner, the methods in EffectLoader for loading sounds with applied sound filters also have overloads that use CustomAudioFormat:

SoundEffect customFilteredEffect = EffectLoader.GetFilteredEffect("Content/thing.mm3", new Mm3Format(), id);
customFilteredEffect.Play();

The corresponding methods that use System.IO.Stream also have overloads that use CustomAudioFormat.

Audio Streaming

Much like audio loading, creating audio streams using a custom format is performed by calling the overload of StreamLoader.GetStreamedSound():

// Load an audio stream with format detection
// "state" is unused in this example, but it can be anything
StreamPackage stream = StreamLoader.GetStreamedSound("Content/thing.mm3", looping: true, state: null);
stream.Play();

// Load an audio stream with a specific format
StreamPackage stream = StreamLoader.GetStreamedSound("Content/thing.mm3", new Mm3Format(), looping: true, state: 20);
stream.Play();

The corresponding methods that use System.IO.Stream also have overloads that use CustomAudioFormat.

CustomAudioFormat API

Listed below is the publicly-visible API for CustomAudioFormat:

• string[] ValidExtensions { get; }
  • The array of valid file extensions that this format should attempt to read
  • Throw an exception here to prevent the format from being registered (SegmentedOggStream does this)
• FormatWav ReadWav(string)
  • Fully decode the audio at the given file to the WAVE format via FormatWav
• FormatWav ReadWav(string, object)
  • Fully decode the audio at the given file to the WAVE format via FormatWav
  • An optional object is provided for use when reading the file
• FormatWav ReadWav(Stream)
  • Fully decode the audio in the given data stream to the WAVE format via FormatWav
  • Return null if the stream was not in the correct format
• FormatWav ReadWav(Stream, object)
  • Fully decode the audio in the given data stream to the WAVE format via FormatWav
  • An optional object is provided for use when reading the stream
  • Return null if the stream was not in the correct format
• StreamPackage CreateStream(string, object)
  • Create an audio stream that will read the data from the file
  • An optional object is provided for use by the created stream
• StreamPackage CreateStream(Stream, object)
  • Create an audio stream that will read the data from the file
  • An optional object is provided for use by the created stream
  • Return null if the stream was not in the correct format