VGAudio-fork 2.3.0

VGAudio

This a fork of the original VGAudio Library by Alex Barney that uses the latest commit since the original nuget is 2 years older than the latest. I will be providing updates to this fork to address issues in the original project.

Using VGAudio as a library

This document shows basic ways to use VGAudio programmatically: installing the library, reading container files, converting to PCM, decoding raw codec streams, and creating audio programmatically.

Install

The library is published to NuGet. From a .NET project:

dotnet add package VGAudio-fork

Then add references in your C# files:

using System.IO;
using VGAudio.Containers;
using VGAudio.Formats;
using VGAudio.Formats.Pcm16;

Read audio files (containers)

VGAudio provides AudioReader implementations for the supported containers (WAV, AT9, BRSTM, BFSTM, DSP, HCA, etc.). Use the appropriate reader for the container (or write a small auto-detect wrapper that chooses based on extension).

Example (AT9):

using (var stream = File.OpenRead("input.at9"))
{
    var reader = new VGAudio.Containers.At9.At9Reader();
    // ReadWithConfig returns both the IAudioFormat and the container-specific config
    var audioWithConfig = reader.ReadWithConfig(stream);

    IAudioFormat format = audioWithConfig.AudioFormat;
    // Convert to PCM16
    Pcm16Format pcm = format.ToPcm16();
    // pcm.Channels is short[][]; pcm.SampleRate is an int
}

Other readers follow the same pattern: create the reader (e.g., new SomeContainerReader()), and call Read, ReadFormat, or ReadWithConfig with a Stream or byte[].

Work with PCM (Pcm16Format)

Pcm16Format represents 16-bit PCM audio:

• short[][] Channels — array per channel
• int SampleRate
• int SampleCount, int ChannelCount
• Looping metadata via WithLoop(...) builder-style methods

Create a Pcm16Format from channel arrays:

short[][] channels = ...; // channels[channelIndex][sampleIndex]
int sampleRate = 44100;
Pcm16Format pcm = Pcm16Format.GetBuilder(channels, sampleRate).Build();

You can convert any IAudioFormat to PCM:

Pcm16Format pcm = myFormat.ToPcm16();

To access raw PCM samples:

short[] channel0 = pcm.Channels[0];
int sampleRate = pcm.SampleRate;

Decode raw codec streams (example: ATRAC9)

For some codecs (ATRAC9, Opus, ADX, GC-ADPCM, HCA, ...) there are dedicated decoder classes that operate on codec data (not the container). Example: Atrac9Decoder.

Typical usage pattern for ATRAC9 (low-level):

using VGAudio.Codecs.Atrac9;

var decoder = new Atrac9Decoder();

// configData is the 4-byte ATRAC9 config (from the container fmt ext or metadata)
decoder.Initialize(configData);

// Prepare buffers sized according to decoder.Config
int channels = decoder.Config.ChannelCount;
int superframeSamples = decoder.Config.SuperframeSamples;
int superframeBytes = decoder.Config.SuperframeBytes;

byte[] atracSuperframe = ...; // one superframe of ATRAC9 data, length >= superframeBytes
short[][] pcmOut = new short[channels][];
for (int c = 0; c < channels; c++)
    pcmOut[c] = new short[superframeSamples];

// Decode one superframe
decoder.Decode(atracSuperframe, pcmOut);

// Now pcmOut contains decoded 16-bit PCM for this superframe

Notes:

• You must initialize the decoder with the codec/container config before calling Decode.
• Decode writes into a provided short[][] with shape [channelCount][superframeSamples].

Writing a WAV file (example helper)

If you obtain PCM in Pcm16Format and want to write a simple WAV file, you can use this helper to produce a standard PCM16 WAV:

static void WriteWav(string path, Pcm16Format pcm)
{
    int channels = pcm.ChannelCount;
    int sampleRate = pcm.SampleRate;
    int sampleCount = pcm.SampleCount;

    // Interleave channels
    using (var fs = File.Create(path))
    using (var writer = new BinaryWriter(fs))
    {
        int bytesPerSample = 2;
        int blockAlign = channels * bytesPerSample;
        int dataSize = sampleCount * blockAlign;

        // RIFF header
        writer.Write(System.Text.Encoding.ASCII.GetBytes("RIFF"));
        writer.Write(36 + dataSize);
        writer.Write(System.Text.Encoding.ASCII.GetBytes("WAVE"));

        // fmt chunk
        writer.Write(System.Text.Encoding.ASCII.GetBytes("fmt "));
        writer.Write(16);
        writer.Write((short)1); // PCM
        writer.Write((short)channels);
        writer.Write(sampleRate);
        writer.Write(sampleRate * blockAlign);
        writer.Write((short)blockAlign);
        writer.Write((short)(bytesPerSample * 8));

        // data chunk
        writer.Write(System.Text.Encoding.ASCII.GetBytes("data"));
        writer.Write(dataSize);

        // Write interleaved samples
        for (int i = 0; i < sampleCount; i++)
        {
            for (int ch = 0; ch < channels; ch++)
            {
                short sample = pcm.Channels[ch][i];
                writer.Write(sample);
            }
        }
    }
}

Creating audio programmatically

You can build Pcm16Format from generated samples (sine, noise, etc.):

short[][] channels = new short[2][];
channels[0] = new short[sampleCount];
channels[1] = new short[sampleCount];
// fill sample arrays...
var pcm = Pcm16Format.GetBuilder(channels, 44100).Build();

The repository contains test/sample helpers (e.g., GenerateAudio.GeneratePcmSineWave) that can be copied for your use.