Mermaid Diagram Setup¶

Purpose¶

Guide for using Mermaid diagrams in AudioLab documentation as an alternative to PlantUML. Mermaid renders directly in markdown, making it ideal for quick diagrams and browser-based documentation.

What is Mermaid?¶

Mermaid is a JavaScript-based diagramming tool that renders markdown-like syntax into diagrams directly in the browser.

Advantages: - ✅ Renders in markdown (MkDocs, GitHub, GitLab) - ✅ No external tools needed for viewing - ✅ Simple syntax - ✅ Interactive (zoomable, pan) - ✅ Version control friendly (text-based)

Disadvantages: - ❌ Less powerful than PlantUML - ❌ Fewer diagram types - ❌ Less customization options - ❌ Browser-dependent rendering

Supported Diagram Types¶

Flowcharts¶

flowchart LR
    A[Input] --> B[Process]
    B --> C[Output]

Sequence Diagrams¶

sequenceDiagram
    participant Host
    participant Plugin
    Host->>Plugin: processBlock()
    Plugin-->>Host: return

Class Diagrams¶

classDiagram
    class AudioBuffer {
        +getNumChannels()
        +getNumSamples()
    }

State Diagrams¶

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing
    Processing --> Idle
    Processing --> [*]

Gantt Charts¶

gantt
    title Development Timeline
    section Phase 1
    Core Framework :2025-01-01, 30d
    DSP Modules    :2025-02-01, 45d

Git Graphs¶

gitGraph
    commit
    branch develop
    commit
    commit
    checkout main
    merge develop

MkDocs Integration¶

Enabled in mkdocs.yml¶

Already configured in 03_11_01_user_documentation/mkdocs.yml:

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

Usage in Markdown¶

```mermaid
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
```

Diagram Examples¶

1. Audio Processing Flowchart¶

```mermaid
flowchart LR
    Input[Audio Input] --> Pre[Pre-Processing]
    Pre --> EQ[EQ]
    EQ --> Comp[Compressor]
    Comp --> Delay[Delay]
    Delay --> Rev[Reverb]
    Rev --> Output[Audio Output]

    Params[(Parameters)] --> EQ
    Params --> Comp
    Params --> Delay
    Params --> Rev

    style Input fill:#3498db
    style Output fill:#27ae60
    style Params fill:#f39c12
```

Result:

flowchart LR
    Input[Audio Input] --> Pre[Pre-Processing]
    Pre --> EQ[EQ]
    EQ --> Comp[Compressor]
    Comp --> Delay[Delay]
    Delay --> Rev[Reverb]
    Rev --> Output[Audio Output]

    Params[(Parameters)] --> EQ
    Params --> Comp
    Params --> Delay
    Params --> Rev

    style Input fill:#3498db
    style Output fill:#27ae60
    style Params fill:#f39c12

2. Plugin Lifecycle Sequence¶

```mermaid
sequenceDiagram
    participant Host
    participant Plugin
    participant Processor
    participant Parameters

    Host->>Plugin: load()
    Plugin->>Plugin: allocate resources
    Host->>Plugin: initialize(sampleRate)
    Plugin->>Processor: setup(sampleRate)
    Plugin->>Parameters: initDefaults()

    loop Audio Callback
        Host->>Plugin: processBlock(buffer)
        Plugin->>Parameters: getCurrentValues()
        Parameters-->>Plugin: values
        Plugin->>Processor: process(buffer, values)
        Processor-->>Plugin: processed buffer
        Plugin-->>Host: return
    end

    Host->>Plugin: shutdown()
    Plugin->>Processor: cleanup()
    Host->>Plugin: unload()
```

3. Class Hierarchy¶

```mermaid
classDiagram
    class AudioProcessor {
        <<abstract>>
        +process(buffer) void
        +initialize(sampleRate) void
        #sampleRate float
    }

    class GainProcessor {
        +process(buffer) void
        +setGain(gain) void
        -currentGain float
    }

    class FilterProcessor {
        +process(buffer) void
        +setCutoff(freq) void
        -coefficients float[]
    }

    AudioProcessor <|-- GainProcessor
    AudioProcessor <|-- FilterProcessor

    class ParameterManager {
        +getParameter(name) float
        +setParameter(name, value) void
        -parameters Map
    }

    GainProcessor --> ParameterManager : uses
    FilterProcessor --> ParameterManager : uses
```

4. State Machine¶

```mermaid
stateDiagram-v2
    [*] --> Unloaded

    Unloaded --> Loaded : load()
    Loaded --> Initialized : initialize()
    Initialized --> Active : activate()

    Active --> Processing : processBlock()
    Processing --> Active : return

    Active --> Initialized : deactivate()
    Initialized --> Loaded : shutdown()
    Loaded --> Unloaded : unload()

    note right of Active
        RT-SAFE zone
        No allocations
    end note

    note right of Initialized
        RT-UNSAFE
        Can allocate
    end note
```

5. System Architecture¶

```mermaid
graph TB
    subgraph "Application Layer"
        UI[User Interface]
        Host[Plugin Host]
    end

    subgraph "Core Framework"
        PM[Parameter Manager]
        EM[Event Manager]
        BM[Buffer Manager]
    end

    subgraph "DSP Layer"
        FX[Effects]
        FILT[Filters]
        ANAL[Analysis]
    end

    subgraph "Platform Layer"
        IO[Audio I/O]
        SIMD[SIMD Utils]
        RT[RT Safety]
    end

    UI --> Host
    Host --> PM
    Host --> EM
    Host --> BM

    PM --> FX
    EM --> FX
    BM --> FX

    FX --> SIMD
    FILT --> SIMD
    BM --> IO
    FX --> RT

    style UI fill:#3498db
    style FX fill:#27ae60
    style IO fill:#e74c3c
```

Styling and Theming¶

AudioLab Color Scheme¶

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#ECF0F1',
    'primaryTextColor': '#2C3E50',
    'primaryBorderColor': '#2C3E50',
    'lineColor': '#3498DB',
    'secondaryColor': '#3498DB',
    'tertiaryColor': '#E74C3C'
  }
}}%%

Inline Styling¶

flowchart LR
    A[RT-Safe] --> B[Process]
    B --> C[Output]

    style A fill:#27ae60,stroke:#2c3e50,stroke-width:2px
    style B fill:#3498db,stroke:#2c3e50,stroke-width:2px
    style C fill:#e74c3c,stroke:#2c3e50,stroke-width:2px

Class-Based Styling¶

flowchart LR
    A[Input]:::safe --> B[Process]:::process
    B --> C[Output]:::safe

    classDef safe fill:#27ae60,stroke:#2c3e50
    classDef process fill:#3498db,stroke:#2c3e50

Best Practices¶

1. Keep It Simple¶

Limit to 10-15 nodes per diagram
Use subgraphs for grouping
Avoid crossing arrows when possible

2. Use Descriptive Labels¶

flowchart LR
    A[Audio Input Buffer] --> B[Apply Gain]
    B --> C[Audio Output Buffer]

Better than:

flowchart LR
    A[Input] --> B[Process]
    B --> C[Output]

3. Add Notes for Context¶

sequenceDiagram
    Note over Plugin: RT-SAFE section begins
    Plugin->>Processor: process()
    Note over Plugin: No allocations allowed

4. Use Appropriate Diagram Types¶

Flowchart: Decision logic, process flow
Sequence: Message passing, protocols
Class: Static structure
State: State machines

5. Consistent Direction¶

Left to Right (LR): Signal flow, pipelines
Top to Bottom (TD): Hierarchies, workflows
Bottom to Top (BT): Data flow upward

CLI Tool (Optional)¶

Installation¶

npm install -g @mermaid-js/mermaid-cli

Generate Images¶

# PNG
mmdc -i diagram.mmd -o diagram.png

# SVG
mmdc -i diagram.mmd -o diagram.svg

# PDF
mmdc -i diagram.mmd -o diagram.pdf

Batch Convert¶

# Convert all .mmd files
Get-ChildItem *.mmd | ForEach-Object {
    mmdc -i $_.Name -o ($_.BaseName + '.svg')
}

GitHub Integration¶

Mermaid renders automatically on GitHub:

```mermaid
graph LR
    A[Feature] --> B[Review]
    B --> C[Merge]
```

Displays as interactive diagram in GitHub README, PRs, issues.

VS Code Extension¶

Install Mermaid Preview¶

Ext: Mermaid Preview
ID: bierner.markdown-mermaid

Features¶

Live preview as you type
Syntax highlighting
Error detection
Export to PNG/SVG

Common Patterns for Audio Software¶

Signal Flow¶

flowchart LR
    In((In)) --> HP[High Pass]
    HP --> Sat[Saturation]
    Sat --> LP[Low Pass]
    LP --> Out((Out))

Parameter Flow¶

flowchart TD
    UI[User Interface] -->|setValue| PM[Parameter Manager]
    PM -->|notify| DSP[DSP Processor]
    PM -->|notify| VIS[Visualizer]
    DSP -->|getValue| PM

Thread Communication¶

sequenceDiagram
    participant UI Thread
    participant Message Queue
    participant Audio Thread

    UI Thread->>Message Queue: push(parameter change)
    Note over Message Queue: Lock-free FIFO
    Audio Thread->>Message Queue: pop(if available)
    Message Queue-->>Audio Thread: parameter value
    Audio Thread->>Audio Thread: smooth to new value

Build Dependencies¶

graph TD
    Core[Core Library] --> Effects[Effects Module]
    Core --> Analysis[Analysis Module]
    Effects --> Plugin[Plugin Binary]
    Analysis --> Plugin
    Core --> Tests[Unit Tests]
    Effects --> Tests

Syntax Reference¶

Flowchart Shapes¶

A[Rectangle]
B(Rounded)
C([Stadium])
D[[Subroutine]]
E[(Database)]
F((Circle))
G>Flag]
H{Diamond}
I{{Hexagon}}
J[/Parallelogram/]
K[\Reverse/]
L[/Trapezoid\]
M[\Reverse\]

Arrow Types¶

A --> B   (Solid arrow)
A -.-> B  (Dotted arrow)
A ==> B   (Thick arrow)
A --x B   (Cross arrow)
A --o B   (Circle arrow)

Labels¶

A -->|Label| B
A -- Text --> B