# naudio/nlayer architecture

> Architecture diagram of the GitHub repository naudio/nlayer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/naudio/nlayer
- Repository: https://github.com/naudio/nlayer

## Overview

##### Project type and purpose
- NLayer is a fully-managed, stand-alone MP3-to-WAV decoder library written in C#. It provides two deliverables:
a) A core decoder (in the `NLayer` folder) that implements MPEG frame parsing and sample decoding.
b) An NAudio integration layer (in `NLayer.NAudioSupport`) that lets you plug NLayer into the NAudio playback/conversion pipeline.
- There is also a small WinForms “TestApp” showing how to consume the decoder in a GUI.

##### File structure
- Top-level projects:
- NLayer (core decoder)
– `Decoder` folder: implements each stage of MP3 decoding (bit reservoir, frame parsing, Huffman, layer-specific decoders, VBR headers, etc.)
– Public façade: `MpegFile`, `MpegFrameDecoder`, `IMpegFrame`
- NLayer.NAudioSupport
– Wrappers (`Mp3FrameDecompressor`, `ManagedMpegStream`) that implement NAudio’s `FrameDecompressorBuilder` pattern
- TestApp
– A Windows Forms application that references both NLayer and NAudio to demonstrate real-time playback or conversion
- Key config files: two .csproj files (core and NAudio support), a solution file, and a small test project.

##### Readme insights
- Shows simple API: construct `new MpegFile(...)` then `ReadSamples(...)` for raw PCM floats
- Illustrates NAudio usage: build an `Mp3FileReader` by supplying our decompressor builder, then feed into `waveOut` for playback

##### Components
a. External Actor/Client
– TestApp (or any consumer application)
b. NLayer Core
– File I/O / Stream Reader (`MpegStreamReader`)
– Frame Decoder (`MpegFrameDecoder`, layer-specific decoders, bit reservoir, Huffman, VBRInfo)
– Public API (`MpegFile`, `IMpegFrame`)
c. NAudio Integration Layer
– `Mp3FrameDecompressor` / `ManagedMpegStream` classes implementing NAudio interfaces
d. Optional External Service
– NAudio library (for playback, file conversion)
e. Underlying MP3 file (source) and WAV/PCM samples (output)

##### Relationships and data flow
- A directional flow:
1) Consumer App → (calls) MpegFile constructor → passes MP3 file stream
2) MpegFile → uses MpegStreamReader to read raw MPEG frames
3) MpegStreamReader → hands off to MpegFrameDecoder → pipeline of layer decoders (LayerI/II/III) → Huffman → bit reservoir → VBR/ID3 parsing
4) Decoder → outputs float[] PCM samples
5) (If using NAudioSupport) Mp3FrameDecompressor wraps the MpegFile pipeline and implements NAudio’s `FrameDecompressorBuilder` → feeds samples into `Mp3FileReader` → waveOut

##### Architectural patterns and design principles
- Layered architecture: separate I/O, decoding pipeline, public façade, and integration layer
- Dependency-inversion for NAudio integration: the core does not reference NAudio; instead NAudioSupport references both NLayer and NAudio
- Single-responsibility: each decoder class handles a specific MP3 layer or function (Huffman, reservoir, ID3, etc.)

##### Elements
- Through each Decoder stage → PCM Samples
- From Samples → TestApp (or WaveOut via NAudio)
- Core decoder (e.g. green)
- Integration layer (e.g. blue)
- External libraries (e.g. orange)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External MP3 source
    MP3["MP3 File"]:::file
    MP3 -->|stream| MpegStreamReader

    %% NLayer Core Decoder
    subgraph "NLayer Core" 
        direction TB
        MpegStreamReader["MpegStreamReader"]:::core
        MpegFile["MpegFile"]:::core
        MpegFrameDecoder["MpegFrameDecoder"]:::core
        IMpegFrame["IMpegFrame"]:::core

        MpegStreamReader -->|"reads frames"| MpegFrameDecoder
        MpegFile -->|"ReadSamples()"| MpegStreamReader
        MpegFile -->|"returns IMpegFrame"| IMpegFrame
        MpegFrameDecoder --> DecodingPipeline
    end

    %% Decoding Pipeline
    subgraph "Decoding Pipeline" 
        direction TB
        BitReservoir["BitReservoir"]:::core
        Huffman["Huffman"]:::core
        LayerDecoderBase["LayerDecoderBase"]:::core
        LayerIDecoder["LayerIDecoder"]:::core
        LayerIIDecoderBase["LayerIIDecoderBase"]:::core
        LayerIIDecoder["LayerIIDecoder"]:::core
        LayerIIIDecoder["LayerIIIDecoder"]:::core
        VBRInfo["VBRInfo"]:::core
        ID3Frame["ID3Frame"]:::core
        RiffHeaderFrame["RiffHeaderFrame"]:::core
        MpegFrame["MpegFrame"]:::core
        FrameBase["FrameBase"]:::core

        MpegFrameDecoder --> BitReservoir
        BitReservoir --> Huffman
        Huffman --> LayerDecoderBase
        LayerDecoderBase --> LayerIDecoder
        LayerIDecoder --> LayerIIDecoderBase
        LayerIIDecoderBase --> LayerIIDecoder
        LayerIIDecoder --> LayerIIIDecoder
        LayerIIIDecoder --> VBRInfo
        VBRInfo --> ID3Frame
        ID3Frame --> RiffHeaderFrame
        RiffHeaderFrame --> MpegFrame
        MpegFrame --> FrameBase
        FrameBase -->|"PCM float[]"| PCM
    end

    %% PCM output
    PCM["PCM Samples"]:::core

    %% Optional NAudio Integration
    PCM --> NAudioFlow
    subgraph "NLayer.NAudioSupport"
        direction TB
        Mp3FrameDecompressor["Mp3FrameDecompressor"]:::integration
        ManagedMpegStream["ManagedMpegStream"]:::integration
        Mp3FrameWrapper["Mp3FrameWrapper"]:::integration

        PCM --> Mp3FrameDecompressor
        Mp3FrameDecompressor --> ManagedMpegStream
        ManagedMpegStream --> Mp3FrameWrapper
    end

    %% External NAudio library
    NAudio["NAudio Library"]:::external
    Mp3FrameWrapper -->|FrameDecompressorBuilder| NAudio
    NAudio --> WaveOut["WaveOut (Playback)"]:::external

    %% Consumer Application
    WaveOut --> TestAppSubgraph

    subgraph "TestApp (Consumer)"
        direction TB
        Program["Program.cs"]:::external
        Form1["Form1.cs"]:::external
        Form1Designer["Form1.Designer.cs"]:::external
    end
    WaveOut -->|"plays samples"| Program

    %% Click events
    click Program "https://github.com/naudio/nlayer/blob/master/TestApp/Program.cs"
    click Form1 "https://github.com/naudio/nlayer/blob/master/TestApp/Form1.cs"
    click Form1Designer "https://github.com/naudio/nlayer/blob/master/TestApp/Form1.Designer.cs"
    click MpegFile "https://github.com/naudio/nlayer/blob/master/NLayer/MpegFile.cs"
    click MpegFrameDecoder "https://github.com/naudio/nlayer/blob/master/NLayer/MpegFrameDecoder.cs"
    click IMpegFrame "https://github.com/naudio/nlayer/blob/master/NLayer/IMpegFrame.cs"
    click MpegStreamReader "https://github.com/naudio/nlayer/blob/master/NLayer/Decoder/MpegStreamReader.cs"
    click BitReservoir "https://github.com/naudio/nlayer/blob/master/NLayer/Decoder/BitReservoir.cs"
    click Huffman "https://github.com/naudio/nlayer/blob/master/NLayer/Decoder/Huffman.cs"
    click LayerDecoderBase "https://github.com/naudio/nlayer/blob/master/NLayer/Decoder/LayerDecoderBase.cs"
    click LayerIDecoder "https://github.com/naudio/nlayer/blob/master/NLayer/Decoder/LayerIDecoder.cs"
    click LayerIIDecoderBase "https://github.com/naudio/nlayer/blob/master/NLayer/Decoder/LayerIIDecoderBase.cs"
    click LayerIIDecoder "https://github.com/naudio/nlayer/blob/master/NLayer/Decoder/LayerIIDecoder.cs"
    click LayerIIIDecoder "https://github.com/naudio/nlayer/blob/master/NLayer/Decoder/LayerIIIDecoder.cs"
    click MpegFrame "https://github.com/naudio/nlayer/blob/master/NLayer/Decoder/MpegFrame.cs"
    click ID3Frame "https://github.com/naudio/nlayer/blob/master/NLayer/Decoder/ID3Frame.cs"
    click VBRInfo "https://github.com/naudio/nlayer/blob/master/NLayer/Decoder/VBRInfo.cs"
    click RiffHeaderFrame "https://github.com/naudio/nlayer/blob/master/NLayer/Decoder/RiffHeaderFrame.cs"
    click FrameBase "https://github.com/naudio/nlayer/blob/master/NLayer/Decoder/FrameBase.cs"
    click Mp3FrameDecompressor "https://github.com/naudio/nlayer/blob/master/NLayer.NAudioSupport/Mp3FrameDecompressor.cs"
    click ManagedMpegStream "https://github.com/naudio/nlayer/blob/master/NLayer.NAudioSupport/ManagedMpegStream.cs"
    click Mp3FrameWrapper "https://github.com/naudio/nlayer/blob/master/NLayer.NAudioSupport/Mp3FrameWrapper.cs"
    click NAudio "https://github.com/naudio/nlayer/blob/master/NLayer.NAudioSupport/NLayer.NAudioSupport.csproj"

    %% Styles
    classDef core fill:#e0f7e9,stroke:#2d7a2d,color:#204d20;
    classDef integration fill:#d0e7ff,stroke:#2a5a9f,color:#13345a;
    classDef external fill:#ffe8cc,stroke:#cc7700,color:#663d00;
    classDef file fill:#f2f2f2,stroke:#999999,color:#333333;
```
