breaks-machine 0.1.0__tar.gz

breaks_machine-0.1.0/.claude/CLAUDE.md

@@ -0,0 +1,204 @@
+# breaks-machine Development Guide
+
+CLI tool for time-stretching drum breaks to target BPMs while preserving transient quality.
+
+## Project Overview
+
+**breaks-machine** is a command-line tool designed to time-stretch drum breaks to specific BPMs using Rubberband's industry-standard algorithm. It's perfect for preparing breaks for hardware samplers, live performance, or production workflows.
+
+**Tech Stack:**
+- **pyrubberband**: Python wrapper for Rubberband time-stretching
+- **librosa**: Audio analysis and BPM detection
+- **soundfile**: Audio I/O for WAV/FLAC files
+- **click**: CLI framework
+- **Python 3.13** with **uv** for package management
+
+## Key Components
+
+### Core Modules
+
+- **[cli.py](../../src/breaks_machine/cli.py)** - Click-based CLI entry point
+  - Handles command-line arguments and user input
+  - Orchestrates the processing pipeline
+  - Entry point: `breaks-machine stretch`
+
+- **[detector.py](../../src/breaks_machine/detector.py)** - BPM detection
+  - Parses BPM from filename patterns (e.g., `amen_170.wav`)
+  - Multi-strategy librosa detection with subdivision correction
+  - Priority: manual override → filename → auto-detection
+
+- **[stretcher.py](../../src/breaks_machine/stretcher.py)** - Rubberband wrapper
+  - Time-stretching with crispness=5 (optimized for drums)
+  - Ratio calculation: `target_bpm / source_bpm`
+  - Preserves transients and minimizes phase artifacts
+
+- **[converter.py](../../src/breaks_machine/converter.py)** - Format conversion
+  - Optional sample rate conversion
+  - Bit depth conversion (16/24-bit)
+  - Stereo to mono downmixing
+
+- **[processor.py](../../src/breaks_machine/processor.py)** - Pipeline orchestration
+  - Single file and batch directory processing
+  - Output structure: `output/{filename}/{filename}_{bpm}bpm.{ext}`
+  - Target parsing (single, multiple, range modes)
+
+## Development Workflow
+
+### Testing
+
+```bash
+# Run all tests
+uv run pytest tests
+
+# Run with coverage
+uv run pytest tests --cov=src/breaks_machine
+
+# Run specific test file
+uv run pytest tests/test_detector.py -v
+
+# Watch mode (if using pytest-watch)
+uv run ptw tests/
+```
+
+### Code Quality
+
+```bash
+# Format code
+uvx ruff format
+
+# Lint and fix issues
+uvx ruff check --fix
+
+# Check formatting without changes
+uvx ruff format --check
+
+# Full quality check
+uvx ruff check && uvx ruff format --check
+```
+
+### Manual Testing
+
+Test with real drum breaks in the `breaks/` directory:
+
+```bash
+# Test auto-detection
+uv run breaks-machine stretch breaks/FR_Drum_Loop_160.wav -t 140
+
+# Test with manual BPM override
+uv run breaks-machine stretch breaks/amen_RUDE.wav --bpm 175 -t 140
+
+# Test batch processing
+uv run breaks-machine stretch breaks/ --targets 90,120,140 -o test_output/
+```
+
+## Audio Processing Notes
+
+### Supported Formats
+
+- **Input**: WAV, FLAC
+- **Output**: Same format as input (preserves original format by default)
+
+### Rubberband Crispness Settings
+
+The `--crispness` parameter (0-6) controls transient preservation:
+
+- **0-2**: Smoother, less transient preservation (not ideal for drums)
+- **3-4**: Balanced
+- **5**: Default for breaks-machine - optimized for drums
+- **6**: Maximum transient preservation
+
+### BPM Detection Improvements
+
+Recent improvements to `detector.py`:
+
+- **Multi-strategy detection**: Tries multiple tempo priors (120, 140, 170 BPM)
+- **Subdivision correction**: Accounts for common misdetections (half-time, 2/3 time, etc.)
+- **Smart selection**: Prefers direct detections over derived subdivisions
+- **Breakbeat bias**: Favors common breakbeat range (140-180 BPM)
+
+This significantly improved accuracy on complex breaks like the Amen break (now detects 172 BPM vs previous 117 BPM).
+
+### System Dependencies
+
+Required for time-stretching functionality:
+
+- **rubberband-cli**: The actual time-stretching engine
+- **libsndfile1**: Audio file I/O library
+- **ffmpeg**: Audio codec support
+
+**Installation:**
+
+**macOS:**
+```bash
+brew install rubberband
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt-get install rubberband-cli libsndfile1 ffmpeg
+```
+
+**Windows:**
+Download from https://breakfastquay.com/rubberband/ and add to PATH.
+
+**Optional: Use devcontainer** - Copy `.devcontainer-template/` to `.devcontainer/` for automatic setup.
+
+## Quick Reference
+
+### Common Commands
+
+- Add dependency: `uv add <package>`
+- Add dev dependency: `uv add --dev <package>`
+- Run CLI: `uv run breaks-machine stretch <file> [options]`
+- Run tests: `uv run pytest tests`
+- Format code: `uvx ruff format`
+- Lint code: `uvx ruff check --fix`
+
+### CLI Usage Examples
+
+```bash
+# Single target
+breaks-machine stretch amen_170.wav --target 140
+
+# Multiple targets
+breaks-machine stretch break.wav --targets 90,120,140,160
+
+# Range with step
+breaks-machine stretch break.wav --range 80-160 --step 10
+
+# Batch directory
+breaks-machine stretch ./breaks/ -t 140 -o ./output/
+
+# With format conversion
+breaks-machine stretch break.wav -t 140 --sample-rate 44100 --mono
+
+# Manual BPM override
+breaks-machine stretch break.wav --bpm 175 -t 140
+```
+
+### Important Files
+
+- `pyproject.toml` - Project metadata and dependency specifications
+- `uv.lock` - Locked dependency tree (always commit!)
+- `.python-version` - Python version pinning (3.13)
+- `src/breaks_machine/` - Source code
+- `tests/` - Test suite
+- `breaks/` - Test audio files for manual testing
+- `.devcontainer-template/` - Optional devcontainer configuration
+- `.github/workflows/ci.yml` - CI/CD pipeline configuration
+
+## Detailed Documentation
+
+For more information about the development environment and tooling:
+
+- **uv quick reference**: [.claude/rules/uv-guide.md](rules/uv-guide.md)
+- **CI/CD pipeline**: [.claude/rules/cicd.md](rules/cicd.md)
+- **Troubleshooting**: [.claude/rules/troubleshooting.md](rules/troubleshooting.md)
+
+## Project Principles
+
+- **Reproducibility**: `uv.lock` ensures identical dependencies across all environments
+- **Standard Python package**: Installable via pip/uv without Docker
+- **Optional devcontainer**: Available for zero-friction setup if preferred
+- **Quality first**: Comprehensive test suite with 58 tests, all passing
+- **Fast feedback**: Linting and formatting enforced in CI/CD

breaks_machine-0.1.0/.claude/rules/cicd.md

@@ -0,0 +1,409 @@
+# CI/CD Pipeline Guide
+
+## Pipeline Overview
+
+**File**: `.github/workflows/ci.yml`
+
+### Pipeline Stages
+
+```
+Trigger (push to any branch, pull request to main)
+  ↓
+Job: Lint, Format Check, and Test
+  ↓
+1. Checkout code (actions/checkout@v4)
+  ↓
+2. Setup Python (actions/setup-python@v5)
+  ↓
+3. Install uv (astral-sh/setup-uv@v7 with caching)
+  ↓
+4. Lint (uvx ruff check)
+  ↓
+5. Format check (uvx ruff format --check)
+  ↓
+6. Test (uv run pytest tests)
+```
+
+### Key Characteristics
+
+- **Runner**: `ubuntu-latest` (Ubuntu 22.04 with Python pre-installed)
+- **Python setup**: Via `actions/setup-python@v5` reading `.python-version`
+- **uv setup**: Via official `astral-sh/setup-uv@v7` action
+- **Consistency**: Uses same uv commands as local development
+- **Lock file**: Uses `uv.lock` for reproducible dependencies
+- **Caching**: Built-in uv cache via `enable-cache: true`
+
+## Current Configuration
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: ["*"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  lint-format-test:
+    name: Lint, Format Check, and Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.9.22"
+          enable-cache: true
+
+      - name: Verify uv installation
+        run: uv --version
+
+      - name: Lint with Ruff
+        run: uvx ruff check
+
+      - name: Check code formatting with Ruff
+        run: uvx ruff format --check
+
+      - name: Run tests with pytest
+        run: uv run pytest tests
+```
+
+## How It Works
+
+### Step 1: Checkout Code
+```yaml
+- name: Checkout code
+  uses: actions/checkout@v4
+```
+Clones the repository code into the runner workspace.
+
+### Step 2: Set up Python
+```yaml
+- name: Set up Python
+  uses: actions/setup-python@v5
+  with:
+    python-version-file: ".python-version"
+```
+Installs Python 3.13 by reading the `.python-version` file. Uses GitHub's pre-cached Python versions for fast setup.
+
+### Step 3: Install uv
+```yaml
+- name: Install uv
+  uses: astral-sh/setup-uv@v7
+  with:
+    version: "0.9.22"
+    enable-cache: true
+```
+Installs uv package manager with version pinning and automatic caching enabled.
+
+### Step 4: Lint
+```bash
+uvx ruff check
+```
+Runs ruff linter. Fails workflow if linting errors found.
+
+### Step 5: Format Check
+```bash
+uvx ruff format --check
+```
+Verifies code is properly formatted without modifying files.
+
+### Step 6: Test
+```bash
+uv run pytest tests
+```
+Installs dependencies from `uv.lock` automatically and runs pytest.
+
+## Trigger Conditions
+
+**Push to any branch**:
+```yaml
+on:
+  push:
+    branches: ["*"]
+```
+
+**Pull requests to main**:
+```yaml
+on:
+  pull_request:
+    branches: ["main"]
+```
+
+**Both triggers combined**:
+```yaml
+on:
+  push:
+    branches: ["*"]
+  pull_request:
+    branches: ["main"]
+```
+
+### Common Modifications
+
+**Run on specific branch patterns**:
+```yaml
+on:
+  push:
+    branches:
+      - main
+      - 'feature/**'
+      - 'release/*'
+```
+
+**Run only on tagged commits**:
+```yaml
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    name: Release build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: docker build -t myapp:${{ github.ref_name }} .
+```
+
+**Scheduled builds**:
+```yaml
+on:
+  schedule:
+    - cron: '0 0 * * *'  # Daily at midnight UTC
+  push:
+    branches: ["main"]
+
+jobs:
+  nightly-tests:
+    name: Nightly tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv run pytest tests
+```
+
+**Matrix builds** (test multiple Python versions):
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv run pytest tests
+```
+
+## Secrets and Environment Variables
+
+### Setting Secrets
+
+1. GitHub repo → Settings → Secrets and variables → Actions
+2. Click "New repository secret"
+3. Add name and value (e.g., `API_KEY`, `DATABASE_URL`, `DOCKER_PASSWORD`)
+
+### Using Secrets
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Run tests with secrets
+        env:
+          API_KEY: ${{ secrets.API_KEY }}
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+        run: uv run pytest tests
+```
+
+### Environment Variables
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      DEBUG: "true"
+      ENVIRONMENT: "ci"
+    steps:
+      - uses: actions/checkout@v4
+      - run: uv run pytest tests  # DEBUG and ENVIRONMENT available
+```
+
+### Reusable Workflows
+
+Create `.github/workflows/reusable-test.yml`:
+```yaml
+name: Reusable Test Workflow
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        required: false
+        type: string
+        default: "3.13"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ inputs.python-version }}
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv run pytest tests
+```
+
+Use it in another workflow:
+```yaml
+jobs:
+  call-test:
+    uses: ./.github/workflows/reusable-test.yml
+    with:
+      python-version: "3.13"
+```
+
+## Common CI Issues
+
+### Tests Pass Locally But Fail in CI
+
+**Cause**: Uncommitted `uv.lock` or local-only changes.
+
+**Solution**:
+```bash
+git status  # Check for uncommitted files
+git add uv.lock
+git commit -m "Update lock file"
+git push
+```
+
+### Workflow Not Triggering
+
+**Causes**:
+1. Workflow file has syntax errors (check Actions tab for parsing errors)
+2. GitHub Actions not enabled for the repository
+3. Branch protection rules blocking workflow runs
+
+**Solution**:
+1. Validate YAML syntax
+2. Settings → Actions → General → Enable "Allow all actions and reusable workflows"
+3. Settings → Branches → Check branch protection settings
+
+### Caching Not Working
+
+Check workflow logs for cache hit/miss messages:
+```
+Run astral-sh/setup-uv@v7
+  Cache hit: ~/.cache/uv
+```
+
+If cache misses frequently, verify:
+1. `enable-cache: true` is set in setup-uv step
+2. `uv.lock` file is committed
+3. Cache hasn't been manually cleared
+
+### Debugging
+
+Run the same commands locally:
+```bash
+uvx ruff check
+uvx ruff format --check
+uv run pytest tests
+```
+
+Use GitHub Actions locally with [act](https://github.com/nektos/act):
+```bash
+# Install act
+brew install act  # macOS
+# or: https://github.com/nektos/act#installation
+
+# Run workflow locally
+act push
+```
+
+## Best Practices
+
+1. **Keep CI commands identical to local**: Use same commands in CI as local development
+2. **Always commit `uv.lock`**: Ensures CI uses same dependency versions
+3. **Fail fast**: Put linting before tests (faster feedback)
+4. **Use caching**: Enable built-in caching with `enable-cache: true`
+5. **Pin action versions**: Use `@v4` not `@latest` for reproducibility
+6. **Protect main branch**: Require status checks to pass before merging (Settings → Branches → Branch protection rules)
+7. **Use concurrency control**: Prevent multiple runs on same PR
+   ```yaml
+   concurrency:
+     group: ${{ github.workflow }}-${{ github.ref }}
+     cancel-in-progress: true
+   ```
+
+## Viewing Workflow Results
+
+1. **Actions tab**: Click "Actions" in repository navigation
+2. **Workflow runs**: See all runs with status (success, failure, in progress)
+3. **Logs**: Click a run → Click job name → Expand steps to see detailed logs
+4. **Re-run failed jobs**: Click "Re-run jobs" button on failed runs
+
+## Branch Protection
+
+Require CI to pass before merging:
+
+1. Settings → Branches → Add branch protection rule
+2. Branch name pattern: `main`
+3. Enable "Require status checks to pass before merging"
+4. Search for and select: "Lint, Format Check, and Test"
+5. Enable "Require branches to be up to date before merging"
+6. Save changes
+
+## Cost & Limits
+
+**Free tier** (public repos):
+- 2,000 minutes/month for private repos
+- Unlimited minutes for public repos
+
+**This project's usage**:
+- ~2-3 minutes per run (first run with cache miss)
+- ~1-2 minutes per run (subsequent runs with cache hit)
+- Well within free tier limits
+
+## Resources
+
+- **GitHub Actions docs**: https://docs.github.com/en/actions
+- **Using uv in GitHub Actions**: https://docs.astral.sh/uv/guides/integration/github/
+- **astral-sh/setup-uv**: https://github.com/astral-sh/setup-uv
+- **Workflow syntax**: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
+- **uv documentation**: https://docs.astral.sh/uv/