Skip to content

Configuration System

Audiomancer uses a three-tier configuration system with inheritance:

1. Builtin defaults (hardcoded in config.py)
   ↓
2. Global config (~/.config/audiomancer/config.yaml)
   ↓ (overrides)
3. Project config (.audiomancer.yaml in project directory)
   ↓ (overrides)
Final merged configuration

Configuration Files

Global Config

Location: ~/.config/audiomancer/config.yaml

  • Shared settings across all projects
  • Personal defaults (sample sources, analysis settings)
  • Optional - if missing, uses builtin defaults

Project Config

Location: .audiomancer.yaml in project root

  • Project-specific overrides
  • Auto-generated by audiomancer init
  • Auto-detected when starting MCP server in a project directory
  • Optional - if missing, uses global config or builtin defaults

Example Global Config

~/.config/audiomancer/config.yaml:

# Sample library paths
library:
  source_dir: ~/path/to/samples  # Where packs live (any local directory)
  auto_analyze: true
  max_file_size_mb: 10
  copy_workers: 16

# Analysis settings
analysis:
  max_file_size_mb: 50
  embedding_dim: 128

# Sample sources (for scanning)
sources:
  samples:
    paths:
      - ~/Music/Samples
  synths:
    paths:
      - ~/synths

# Storage paths
storage:
  db_path: ~/.local/share/audiomancer/audiomancer.db
  embeddings_path: ~/.local/share/audiomancer/embeddings
  models_path: ~/.local/share/audiomancer/models

Example Project Config

.audiomancer.yaml (auto-generated by audiomancer init):

# Project-specific settings
library:
  project_root: ~/Development/my-music  # This project's root
  source_dir: ~/path/to/samples         # Override global sample source

# Project can override any global setting
analysis:
  max_file_size_mb: 20  # Different limit for this project

Config Auto-Detection

When running audiomancer serve or using MCP tools, the server automatically:

  1. Searches upward from current directory for .audiomancer.yaml
  2. If found, uses that project as the context
  3. Merges project config with global config and builtin defaults
  4. All file paths in tools are relative to detected project root

This means Claude Code can automatically detect which project you're working in when you start the MCP server.

Project Structure

{project_root}/
├── .audiomancer.yaml   # Project-specific config
├── .mcp.json          # MCP server detection
├── samples/           # Local cache (copied from source)
├── library/           # Active samples (symlinks to samples/)
├── session.tidal      # TidalCycles session
├── start_superdirt.scd # SuperDirt startup
└── CLAUDE.md          # Claude Code project instructions

Next Steps