Ableton-Device-Creator: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Ableton Device Creator V3.0 is a modern Python library for creating and modifying Ableton Live devices (drum racks, sampler instruments, and Simpler devices) from audio sample libraries.

Status: Production-ready, actively maintained Version: 3.0.0 (first public release 2026-09-27; alpha November 2025) Python: 3.8+ Dependencies: Zero (core), Click 8.0+ (CLI optional)

Architecture

V3.0 Structure (Current)

src/ableton_device_creator/     # Modern Python package
├── core/                        # ADG encoder/decoder
│   ├── decoder.py
│   ├── encoder.py
│   └── __init__.py
├── drum_racks/                  # Drum rack creation
│   ├── creator.py
│   ├── modifier.py
│   ├── sample_utils.py
│   └── __init__.py
├── sampler/                     # Sampler creation
│   ├── creator.py
│   ├── simpler.py
│   └── __init__.py
├── macro_mapping/               # Color, transpose
│   ├── color_mapper.py
│   ├── transpose.py
│   └── __init__.py
├── cli.py                       # Command-line interface
└── __init__.py                  # Package exports

Legacy Code

• archive-v2-scripts/ - V2 reference scripts (111 scripts, read-only)
• archive-v1/ - V1 code (preserved, not functional)

Ad-Hoc Scripts (scripts/)

One-off/donor-based workflows that sit on top of the core package rather than extending its public API — batch-processing specific sample libraries, donor-template cloning, one-time XML surgery. See Sampler-Based Drum Rack Workflow below for the active one. Not covered by the package's normal __init__.py exports; run directly with PYTHONPATH=src python3 scripts/<name>.py.

Key Technical Information

ADG/ADV File Format

• ADG (Ableton Device Group) and ADV (Ableton Device) files are gzipped XML files
• Core workflow: Decompress → Modify XML → Recompress
• Compression format: gzip with mtime=0, no filename header