Music Attribution Scaffold

▶ Watch the 1-minute demo · 📄 Read the paper (supplementary material includes an annotated screenshot walkthrough)

CI Tests: 1311 Python 3.13 License: MIT DOI Code style: ruff Type checked: mypy uv Docs

Research-grade music attribution infrastructure with calibrated confidence scoring, multi-source entity resolution, and machine-readable consent.

Music metadata is broken — over 40% of records are incorrect or incomplete across databases that don't talk to each other. When generative AI adds millions of new tracks per month, knowing who made what becomes both a legal and economic emergency. This scaffold provides the open-source infrastructure to address it.

The scaffold unifies fragmented music metadata into confidence-scored attribution records with transparent provenance.

What It Does

Architecture

Five sequential pipelines connected by typed Pydantic boundary objects:

  I. ETL          II. ENTITY         III. ATTRIBUTION    IV. API/MCP      V. CHAT
  PIPELINE         RESOLUTION         ENGINE
  ┌─────────┐     ┌─────────────┐    ┌────────────┐     ┌──────────┐    ┌──────┐
  │ Discogs │     │ Fuzzy match │    │ Confidence │     │ FastAPI  │    │ AI   │
  │ MBrainz │────▶│ + dedupe    │───▶│ scoring +  │────▶│ REST +   │───▶│ Chat │
  │ AcoustID│     │ + graph     │    │ provenance │     │ MCP      │    │      │
  └─────────┘     └─────────────┘    └────────────┘     └──────────┘    └──────┘
       │                │                  │                  │              │
  NormalizedRecord  ResolvedEntity   AttributionRecord    JSON + MCP     AG-UI SSE

  Cross-cutting: BatchEnvelope · DriftDetector · PipelineFeedback
  Storage:       PostgreSQL + pgvector

Each boundary crossing carries validation, confidence scores, and provenance metadata. Reverse feedback flows (dispute signals, recalibration requests) travel upstream via PipelineFeedback objects.

Full architecture docs: Architecture Overview · Backend Guide · docs/architecture/

Quick Start

Prerequisites

• Python 3.13+ and uv
• Docker and Docker Compose (for PostgreSQL + pgvector)
• Node.js 18+ and npm (for the frontend)

Setup

git clone https://github.com/petteriTeikari/music-attribution-scaffold.git
cd music-attribution-scaffold

# Install deps, start Docker, run migrations, seed Imogen Heap data
make setup

# Start the backend API + PostgreSQL
make dev
# → http://localhost:8000 (Swagger at /docs)

# In a second terminal: start the frontend
make dev-frontend
# → http://localhost:3000

# Or: full agentic UI (backend + CopilotKit sidebar)
make agent

Assurance Levels (A0–A3)

Every attribution carries an assurance level indicating verification depth. These are mapped to international music industry identifiers:

Confidence Scoring

Every attribution field carries a calibrated confidence score. Unlike typical ML "confidence" (often miscalibrated), the scaffold uses conformal prediction with Adaptive Prediction Sets (APS) to provide distribution-free coverage guarantees.

MCP Consent Infrastructure

The scaffold includes a Model Context Protocol (MCP) server that provides machine-readable permission queries for AI training rights. AI platforms can ask "may I use this recording for training?" and receive structured responses.

AI Platform                    MCP Server                    Rights DB
    │                              │                            │
    │── check_permission ─────────▶│                            │
    │   (recording_id, use_type)   │── query rights ──────────▶│
    │                              │◀── permission + conditions─│
    │◀── ALLOW / DENY / ASK ──────│                            │
    │    + conditions, expiry      │                            │

Responses include: permission status, conditions (attribution required, non-commercial only, etc.), expiry dates, and rights holder contact for ASK responses.

Concept page: MCP Consent · Implementation: src/music_attribution/mcp/

Voice Agent (Experimental)

The scaffold includes an open-source voice agent built on Pipecat (BSD-2-Clause, 10.4k stars). The same 4 domain tools available in the text agent are exposed as voice-callable functions -- ask about confidence scores, search attributions, suggest corrections, and submit feedback by speaking.

Five-panel architecture: Transport → STT → LLM → TTS → Transport, with semantic endpointing as the orchestration layer.

# Quick start — zero API keys, fully local
uv run python scripts/voice_demo.py

# With custom providers
uv run python scripts/voice_demo.py --stt deepgram --tts elevenlabs

# With drift monitoring
uv run python scripts/voice_demo.py --drift-monitoring --verbose

The pipeline in three lines:

Mic → [Silero VAD → STT → ContextAggregator → LLM (4 tools) → DriftMonitor → TTS] → Speaker
       └─ Pipecat Pipeline ──────────────────────────────────────────────────┘

This is a scaffold, not a production voice product. Every component is swappable with a one-line config change:

What Makes This Different

• Scaffold, not product: Branching paths for every component -- teams with different constraints (budget, latency, licensing) can instantiate different stacks from the same blueprint
• Zero-API-key local dev: Default stack (Whisper + Piper + WebSocket) runs entirely on your machine at $0.00/min
• Protocol-based swapping: STTServiceProtocol, TTSServiceProtocol, and DriftDetectorProtocol use Python structural typing -- implement the methods and it just works, no inheritance required
• Persona drift prevention: 5-dimension persona architecture with EWMA-smoothed drift detection prevents the 8-turn persona drift cliff documented in the literature (Li et al., 2024)
• Conditional imports: Config, persona, drift, and tool schemas work without Pipecat installed -- only build_pipecat_pipeline() requires the actual library. All 161 voice tests pass in both modes

Benchmarks (RTX 2070 Super)

STT inference is the latency bottleneck. GPU acceleration provides 4–16x speedup over CPU, with larger models benefiting disproportionately:

Measured on NVIDIA GeForce RTX 2070 Super (7.6 GB VRAM), PyTorch 2.10.0+cu128, 10-second synthetic 440 Hz sine wave (16 kHz, 16-bit PCM). CPU uses int8 quantization; GPU uses float16. Model load times: tiny CPU 5.9s vs CUDA 0.4s; small CPU 41.1s vs CUDA 0.4s.

# CPU + GPU benchmark (tiny and small models)
uv run python scripts/benchmark_voice.py --models tiny,small --output results.json

# CPU-only (no CUDA required)
uv run python scripts/benchmark_voice.py --cpu-only --models tiny

# With synthetic command accuracy (WER + domain keyword survival)
uv run python scripts/benchmark_voice.py --models tiny

# End-to-end pipeline with mock LLM (STT → LLM → TTS latency breakdown)
uv run python scripts/benchmark_voice.py --models tiny --mock-llm --llm-delay-ms 200

A single voice turn: 7 steps from utterance to response, targeting <500ms total.

Full guide: Voice Agent Implementation · Alternatives table: Component Alternatives · Research base: Voice Agent Research · Figure gallery: 48 voice figures · Implementation: src/music_attribution/voice/

Sample Data

The scaffold ships with 8 Imogen Heap works as seed data, spanning the full confidence spectrum from 0.00 to 0.95:

Each record carries a full provenance chain showing how confidence evolved through fetch → resolve → score → review events.

Project Structure

music-attribution-scaffold/
├── src/music_attribution/          # Python package
│   ├── schemas/                    # Pydantic boundary objects
│   ├── etl/                        # Data source connectors + quality gate
│   ├── resolution/                 # 5-strategy entity resolution cascade
│   ├── attribution/                # Aggregation, conformal scoring, priority queue
│   ├── api/                        # FastAPI routes: attribution, health, permissions
│   ├── chat/                       # PydanticAI agent + AG-UI endpoint
│   ├── mcp/                        # MCP permission patchbay server
│   ├── voice/                      # Pipecat voice agent pipeline + persona
│   ├── db/                         # SQLAlchemy models, 8-table schema
│   ├── search/                     # Hybrid search (text + vector + graph)
│   ├── pipeline/                   # DAG runner for orchestration
│   ├── observability/              # Prometheus metrics
│   └── seed/                       # Imogen Heap mock data
├── tests/                          # 744 tests: 687 unit + 43 integration + 14 eval
├── frontend/                       # Next.js 15, TypeScript strict, Tailwind v4
├── docker/                         # Dockerfiles: dev, test, prod
├── alembic/                        # Database migrations
├── docs/                           # MkDocs site + PRD + knowledge base
└── pyproject.toml                  # Single source of truth for all deps

Each module has its own README with architecture details:

Testing

1,304 tests across backend and frontend:

make test-local          # 744 backend tests locally (~30s)
make test                # 744 backend tests in Docker (CI-parity, ~90s)
make test-frontend       # 560 Vitest tests + WCAG accessibility checks (~15s)
make test-all            # Full CI: lint + typecheck + all tests

Documentation

Preview docs locally:

uv sync --group docs && uv run --group docs mkdocs serve
# → http://localhost:8000

Music AI Attribution Landscape

The music AI attribution space is undergoing rapid consolidation. This section provides a compact overview — see the full landscape report for detailed company profiles, academic papers, and buy-vs-build analysis.

Attribution Infrastructure

AI Music Generation (with attribution status)

Licensing & Certification

AI Music Detection

Music Metadata & Credits

Audio Recognition & Fingerprinting APIs

Voice Identity & Ethical Voice AI

Audio Processing & Stem Separation

Royalty Infrastructure

Provenance & Opt-Out Infrastructure

Standards Bodies & Research

Open-Source Tools

Contributing

1. Use uv for all dependency management — pip and conda are banned.
2. Run pre-commit run --all-files before pushing. All 13 hooks must pass.
3. Write tests for all new functionality. Follow tests/README.md.
4. Type-annotate all public functions. Use from __future__ import annotations.
5. Use pathlib.Path for file paths. Always specify encoding='utf-8'.
6. Never modify sections marked with # AIDEV-IMMUTABLE.

See .claude/CLAUDE.md for the full development behavior contract.

Roadmap

Current focus areas tracked as GitHub Issues:

References

Development

This scaffold was developed with extensive use of Anthropic's Claude Opus 4.5 and Opus 4.6 via Claude Code, functioning as a pair-programming agent for multi-file refactors, test generation, and architectural reasoning. All figures were generated using Nano Banana Pro.

Citation

@article{teikariGoverningGenerativeMusic2026,
  title     = {Governing {Generative} {Music}: {Attribution} {Limits},
               {Platform} {Incentives}, and the {Future} of {Creator} {Income}},
  author    = {Teikari, Petteri},
  year      = {2026},
  journal   = {SSRN Electronic Journal},
  doi       = {10.2139/ssrn.6109087},
  url       = {https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6109087},
  keywords  = {Generative AI, Attribution Infrastructure, Music Industry,
               Platform Economics, Provenance Verification, Transaction Costs}
}

License

MIT | Detailed dependency licenses