Skip to content

Architecture Overview

This section contains detailed technical documentation about audiomancer's implementation.

Module Organization

Project Structure

src/audiomancer/
├── analyzers/       # Audio analysis (Essentia, librosa)
├── converters/      # MIDI ↔ TidalCycles ↔ SuperCollider
├── generators/      # Pattern generation (algorithmic)
├── library/         # Sample pack management
│   ├── manager.py   # LibraryManager class
│   ├── scanner.py   # Category detection, file scanning
│   ├── schema.py    # TypedDict definitions
│   └── interfaces.py # Protocol definitions
├── storage/         # SQLite + LanceDB
├── server.py        # MCP server (15 tools)
├── cli.py           # Typer CLI
├── config.py        # Pydantic config
└── errors.py        # Error hierarchy

Component Overview

Analyzers

The analyzers module provides comprehensive audio analysis:

  • Basic metadata: Duration, sample rate, file hash
  • Spectral features: Centroid, bandwidth, RMS energy
  • Rhythm features: BPM detection, onset detection
  • Audio embeddings: 128-dimensional vectors for similarity search

See Analyzers Implementation for details.

Library Management

The library module manages sample packs:

  • Scanner: Auto-categorizes samples by filename
  • Manager: Copies files, creates symlinks, tracks status
  • Pack management: Enable, disable, purge operations

Storage

The storage module provides persistence:

  • SQLite: Sample metadata and configuration
  • LanceDB: Vector embeddings for similarity search
  • Unified interface: Single API for all storage operations

See Storage Implementation for details.

Generators

The generators module creates patterns:

  • Pattern generation: Algorithmic drum, melody, bass patterns
  • Synth evolution: Genetic algorithms for SynthDef generation
  • TidalCycles output: Native Haskell pattern code

See Pattern Generation for details.

MCP Server

The MCP server exposes 15 tools to AI assistants:

  • Library management (7 tools)
  • Analysis & search (4 tools)
  • Generation & synths (3 tools)
  • Statistics (1 tool)

See MCP Server for details.

System Architecture

Audiomancer Architecture Audiomancer Architecture

The diagram shows the complete data flow through the system:

  1. Sample Library (source directory) contains original sample packs
  2. Library Manager copies files to local cache and creates symlinks
  3. Audio Analyzers extract features and generate ML embeddings
  4. Storage Layer persists metadata (SQLite) and vectors (LanceDB)
  5. Pattern Generators query samples and create TidalCycles code
  6. MCP Server exposes 15 tools to AI clients
  7. SuperDirt loads enabled samples via symlinks

Data Flow

Sample Pack (local source directory)
        |
        v
LibraryManager.enable_pack()
        |
        ├──> Copy files to samples/
        ├──> Create symlinks in library/
        └──> Analyze audio → SQLite + LanceDB
                |
                v
        Embeddings for similarity search
                |
                v
        PatternGenerator uses samples
                |
                v
        TidalCycles pattern code

Next Steps

Browse the detailed technical documentation: