ableton-ai 1.0.0__tar.gz

ableton_ai-1.0.0/.github/workflows/fix-code-style.yml

@@ -0,0 +1,36 @@
+# The equivalent of Spatie's fix-php-code-style-issues workflow.
+# Instead of failing a PR over formatting, it fixes it and pushes the fix back.
+name: fix code style
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "**.py"
+      - "pyproject.toml"
+
+permissions:
+  contents: write
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    name: ruff fix
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Fix and format
+        run: |
+          uvx ruff check --fix src tests
+          uvx ruff format src tests
+
+      - name: Commit anything that changed
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "Fix code style with ruff"

ableton_ai-1.0.0/.github/workflows/lint.yml

@@ -0,0 +1,32 @@
+name: lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    name: ruff
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --all-extras
+      - name: Check formatting
+        run: uv run ruff format --check src tests
+      - name: Lint
+        run: uv run ruff check src tests
+
+  mypy:
+    runs-on: ubuntu-latest
+    name: mypy
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --all-extras
+      - run: uv run mypy

ableton_ai-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+# Publish to PyPI when a GitHub release is published.
+#
+# Uses PyPI Trusted Publishing (OIDC), so there is no token to store or rotate.
+# One-time setup on PyPI: Project settings, Publishing, add a trusted publisher
+#   Owner:     freekmurze
+#   Repo:      ableton-ai
+#   Workflow:  publish.yml
+#   Environment: (leave blank)
+name: publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # required for Trusted Publishing; no password needed
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Check the tag matches the package version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VERSION=$(uv version --short)
+          if [ "$TAG" != "$VERSION" ]; then
+            echo "Release tag ($TAG) does not match pyproject version ($VERSION)." >&2
+            echo "Bump the version in pyproject.toml and retag." >&2
+            exit 1
+          fi
+
+      - name: Build
+        run: uv build
+
+      - name: Run tests before publishing
+        run: uv run pytest -q -m "not integration"
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

ableton_ai-1.0.0/.github/workflows/tests.yml

@@ -0,0 +1,34 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    name: ${{ matrix.os }} / python ${{ matrix.python-version }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run tests
+        run: uv run pytest --cov --cov-report=term-missing -m "not integration"

ableton_ai-1.0.0/.gitignore

@@ -0,0 +1,19 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.DS_Store
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+
+# bundled at build time via force-include; source-tree copy for local dev only
+src/ableton_ai/_remote_script/

ableton_ai-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+# Install once with: uv run pre-commit install
+# Run against everything with: uv run pre-commit run --all-files
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.2
+    hooks:
+      # Autofix first, then format. Order matters: fixes can change formatting.
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.18.2
+    hooks:
+      - id: mypy
+        files: ^src/
+        additional_dependencies: [types-requests]

ableton_ai-1.0.0/.python-version

@@ -0,0 +1 @@
+3.13

ableton_ai-1.0.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to `ableton-ai` are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 1.0.0
+
+First release.
+
+Control Ableton Live from an AI assistant over MCP. Around 130 tools covering
+most of the Live Object Model: tracks, devices and their parameters, clips,
+MIDI notes, automation, the browser, transport, and the mixer.
+
+Highlights:
+
+- Per-note probability and velocity deviation via `add_notes_with_probability`.
+- Reach devices nested inside racks with `get_chain_device_parameters` and
+  `set_chain_device_parameter`.
+- `set_song_scale`, plus a `get_scale_notes` that follows the song's scale.
+- Clip automation that targets a specific device and returns the real curve when
+  read back.
+- One-command remote-script install: `uvx --from ableton-ai install-remote-script`.
+- A Claude Code skill under `skills/ableton`.

ableton_ai-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# CONTRIBUTING
+
+Contributions are welcome, and are accepted via pull requests.
+Please review these guidelines before submitting any pull requests.
+
+## Process
+
+1. Fork the project
+1. Create a new branch
+1. Code, test, commit and push
+1. Open a pull request detailing your changes
+
+## Guidelines
+
+* Please ensure the coding style running `uv run ruff format src tests`.
+* Send a coherent commit history, making sure each individual commit in your pull request is meaningful.
+* You may need to [rebase](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) to avoid merge conflicts.
+* Please remember that we follow [SemVer](http://semver.org/).
+
+## Setup
+
+Clone your fork, then install the dev dependencies:
+```bash
+uv sync --all-extras
+```
+## Lint
+
+Lint your code:
+```bash
+uv run ruff check src tests
+```
+
+Check types:
+```bash
+uv run mypy
+```
+
+## Tests
+
+Run all tests:
+```bash
+uv run pytest
+```

ableton_ai-1.0.0/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Siddharth Ahuja
+Copyright (c) 2026 Jason Poindexter
+Copyright (c) 2026 Freek Van der Herten
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ableton_ai-1.0.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: ableton-ai
+Version: 1.0.0
+Summary: Control Ableton Live from an AI assistant via MCP: tracks, devices, clips, automation, and generative MIDI with per-note probability.
+Project-URL: Homepage, https://github.com/freekmurze/ableton-ai
+Project-URL: Documentation, https://github.com/freekmurze/ableton-ai#readme
+Project-URL: Bug Tracker, https://github.com/freekmurze/ableton-ai/issues
+Project-URL: Changelog, https://github.com/freekmurze/ableton-ai/blob/main/CHANGELOG.md
+Author-email: Siddharth Ahuja <ahujasid@gmail.com>, Jason Poindexter <jason@theft.studio>, Freek Van der Herten <freek@spatie.be>
+Maintainer-email: Freek Van der Herten <freek@spatie.be>
+License: MIT
+License-File: LICENSE
+Keywords: ableton,ai,claude,daw,live,mcp,midi,music,production
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]>=1.3.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.100.0; extra == 'all'
+Requires-Dist: pydantic>=2.0.0; extra == 'all'
+Requires-Dist: requests>=2.28.0; extra == 'all'
+Requires-Dist: uvicorn>=0.22.0; extra == 'all'
+Provides-Extra: rest
+Requires-Dist: fastapi>=0.100.0; extra == 'rest'
+Requires-Dist: pydantic>=2.0.0; extra == 'rest'
+Requires-Dist: requests>=2.28.0; extra == 'rest'
+Requires-Dist: uvicorn>=0.22.0; extra == 'rest'
+Description-Content-Type: text/markdown
+
+# Ableton AI
+
+Control Ableton Live from an AI assistant like Claude. You describe what you want in plain language, and it builds it in your Live set: tracks, instruments, effects, MIDI clips, automation, and mixing. Around 130 commands covering most of the Live Object Model.
+
+You describe, it builds, you listen and judge. The assistant has no ears, so it handles the mechanical work while you keep the taste.
+
+## What you can do with it
+
+Ask for a sound and get it built:
+
+```text
+Build a dark ambient pad on a new track. Slow attack, long release,
+a filter behind it with a slow LFO on the cutoff. Play a minor chord.
+```
+
+Ask for the tedious things you'd never do by hand:
+
+```text
+Write six clips at 3, 5, 7, 11, 13 and 17 bar lengths. They're coprime,
+so the loop won't repeat for over a million bars.
+```
+
+```text
+Draw a twelve minute filter sweep with 200 automation points, then put
+per-note probability on the hats so they flicker instead of repeating.
+```
+
+Ask it to fix what you just heard:
+
+```text
+The bass is too quiet and the reverb is too wet. Pull them back.
+```
+
+## How it works
+
+The assistant talks to Ableton through the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), an open standard for giving AI tools access to external systems. This project is an MCP server that exposes Ableton's Live Object Model as a set of tools the assistant can call.
+
+There are two pieces:
+
+The MCP server runs on your machine as its own process. Your AI client (Claude Code, Claude Desktop, Cursor) launches it and calls its tools.
+
+A remote script runs inside Ableton itself. Ableton's Control Surface system lets you run Python inside Live, and that script opens a local socket the MCP server talks to. This is the only supported way into Live's API, so it has to be Python and it has to be enabled in Ableton's settings.
+
+When you ask for something, the assistant calls a tool, the server sends a command over the socket, the remote script runs it against Live's API, and the result comes back. You see it happen in Ableton in real time.
+
+## Installation
+
+You need Ableton Live 11 or newer, and [uv](https://docs.astral.sh/uv/).
+
+First, install the remote script into Live. This is the part that runs inside Ableton:
+
+```bash
+uvx --from ableton-ai install-remote-script
+```
+
+Then connect your AI client.
+
+For Claude Code:
+
+```bash
+claude mcp add ableton -s user -- uvx ableton-ai
+```
+
+For Claude Desktop, add this to `claude_desktop_config.json` (find it under Settings, Developer, Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "ableton": {
+      "command": "uvx",
+      "args": ["ableton-ai"]
+    }
+  }
+}
+```
+
+Restart your AI client after either one, so it picks up the new server.
+
+Finally, turn the remote script on in Ableton. Open Settings, then Link, Tempo & MIDI. Under Control Surface, pick AbletonMCP. Leave Input and Output on None.
+
+Ableton's status bar should flash `AbletonMCP: Listening for commands on port 9877`. If it doesn't, the remote script isn't installed, so rerun the first step and restart Live.
+
+## Getting started
+
+Open a Live set you don't mind messing up, then hand your assistant this:
+
+```text
+You're controlling my Ableton Live set. You can't hear anything you make,
+so don't tell me it sounds good. Build what I ask, read the settings back
+to check they landed, and let me be the judge.
+
+Some things in Live are dropdowns you can't set through the API: the LFO
+Map button, a Compressor's sidechain source, Drift's mod matrix routing.
+If you need one of those, tell me and I'll click it.
+
+To start: make a MIDI track, load Drift, and build an ambient pad with a
+slow attack and long release. Add a filter behind it with a slow LFO on
+the cutoff. Play a minor chord and loop it.
+```
+
+That first paragraph is worth keeping around. It saves you re-explaining the same things every session. Better still, install the skill below, which teaches your assistant all of this and more.
+
+## The skill
+
+If you use Claude Code, there's a skill in `skills/ableton` that teaches the assistant how to use these tools well: the parameter names each command expects, how to verify a change actually landed, how to reach inside drum racks, and how to build generative patches with coprime loops and note probability.
+
+Install it:
+
+```bash
+mkdir -p ~/.claude/skills
+cp -R skills/ableton ~/.claude/skills/
+```
+
+Restart Claude Code. It picks the skill up whenever you ask for something musical.
+
+## Editing the remote script
+
+If you change the remote script, Ableton needs a restart to load it, because Live caches the compiled bytecode. Save your set, copy the updated file into place, and restart Live. Toggling the Control Surface off and on is not reliable.
+
+## Safety
+
+The remote script opens an unauthenticated socket on `localhost:9877`. It isn't reachable from the network, but any process running as you can drive Ableton through it.
+
+The more practical point: the assistant has 130 commands that change your project, and it can't hear what it's doing. It will occasionally clear something you cared about. Work on copies, save often, and lean on Cmd+Z, which covers most operations.
+
+## Testing
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check src tests
+uv run mypy
+```
+
+## Credits
+
+Built on the original AbletonMCP by [Siddharth Ahuja](https://github.com/ahujasid) and later work by [Jason Poindexter](https://github.com/jpoindexter), with thanks to [calclavia](https://github.com/calclavia) and [Ronbalt](https://github.com/Ronbalt).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

ableton_ai-1.0.0/README.md

@@ -0,0 +1,141 @@
+# Ableton AI
+
+Control Ableton Live from an AI assistant like Claude. You describe what you want in plain language, and it builds it in your Live set: tracks, instruments, effects, MIDI clips, automation, and mixing. Around 130 commands covering most of the Live Object Model.
+
+You describe, it builds, you listen and judge. The assistant has no ears, so it handles the mechanical work while you keep the taste.
+
+## What you can do with it
+
+Ask for a sound and get it built:
+
+```text
+Build a dark ambient pad on a new track. Slow attack, long release,
+a filter behind it with a slow LFO on the cutoff. Play a minor chord.
+```
+
+Ask for the tedious things you'd never do by hand:
+
+```text
+Write six clips at 3, 5, 7, 11, 13 and 17 bar lengths. They're coprime,
+so the loop won't repeat for over a million bars.
+```
+
+```text
+Draw a twelve minute filter sweep with 200 automation points, then put
+per-note probability on the hats so they flicker instead of repeating.
+```
+
+Ask it to fix what you just heard:
+
+```text
+The bass is too quiet and the reverb is too wet. Pull them back.
+```
+
+## How it works
+
+The assistant talks to Ableton through the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), an open standard for giving AI tools access to external systems. This project is an MCP server that exposes Ableton's Live Object Model as a set of tools the assistant can call.
+
+There are two pieces:
+
+The MCP server runs on your machine as its own process. Your AI client (Claude Code, Claude Desktop, Cursor) launches it and calls its tools.
+
+A remote script runs inside Ableton itself. Ableton's Control Surface system lets you run Python inside Live, and that script opens a local socket the MCP server talks to. This is the only supported way into Live's API, so it has to be Python and it has to be enabled in Ableton's settings.
+
+When you ask for something, the assistant calls a tool, the server sends a command over the socket, the remote script runs it against Live's API, and the result comes back. You see it happen in Ableton in real time.
+
+## Installation
+
+You need Ableton Live 11 or newer, and [uv](https://docs.astral.sh/uv/).
+
+First, install the remote script into Live. This is the part that runs inside Ableton:
+
+```bash
+uvx --from ableton-ai install-remote-script
+```
+
+Then connect your AI client.
+
+For Claude Code:
+
+```bash
+claude mcp add ableton -s user -- uvx ableton-ai
+```
+
+For Claude Desktop, add this to `claude_desktop_config.json` (find it under Settings, Developer, Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "ableton": {
+      "command": "uvx",
+      "args": ["ableton-ai"]
+    }
+  }
+}
+```
+
+Restart your AI client after either one, so it picks up the new server.
+
+Finally, turn the remote script on in Ableton. Open Settings, then Link, Tempo & MIDI. Under Control Surface, pick AbletonMCP. Leave Input and Output on None.
+
+Ableton's status bar should flash `AbletonMCP: Listening for commands on port 9877`. If it doesn't, the remote script isn't installed, so rerun the first step and restart Live.
+
+## Getting started
+
+Open a Live set you don't mind messing up, then hand your assistant this:
+
+```text
+You're controlling my Ableton Live set. You can't hear anything you make,
+so don't tell me it sounds good. Build what I ask, read the settings back
+to check they landed, and let me be the judge.
+
+Some things in Live are dropdowns you can't set through the API: the LFO
+Map button, a Compressor's sidechain source, Drift's mod matrix routing.
+If you need one of those, tell me and I'll click it.
+
+To start: make a MIDI track, load Drift, and build an ambient pad with a
+slow attack and long release. Add a filter behind it with a slow LFO on
+the cutoff. Play a minor chord and loop it.
+```
+
+That first paragraph is worth keeping around. It saves you re-explaining the same things every session. Better still, install the skill below, which teaches your assistant all of this and more.
+
+## The skill
+
+If you use Claude Code, there's a skill in `skills/ableton` that teaches the assistant how to use these tools well: the parameter names each command expects, how to verify a change actually landed, how to reach inside drum racks, and how to build generative patches with coprime loops and note probability.
+
+Install it:
+
+```bash
+mkdir -p ~/.claude/skills
+cp -R skills/ableton ~/.claude/skills/
+```
+
+Restart Claude Code. It picks the skill up whenever you ask for something musical.
+
+## Editing the remote script
+
+If you change the remote script, Ableton needs a restart to load it, because Live caches the compiled bytecode. Save your set, copy the updated file into place, and restart Live. Toggling the Control Surface off and on is not reliable.
+
+## Safety
+
+The remote script opens an unauthenticated socket on `localhost:9877`. It isn't reachable from the network, but any process running as you can drive Ableton through it.
+
+The more practical point: the assistant has 130 commands that change your project, and it can't hear what it's doing. It will occasionally clear something you cared about. Work on copies, save often, and lean on Cmd+Z, which covers most operations.
+
+## Testing
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check src tests
+uv run mypy
+```
+
+## Credits
+
+Built on the original AbletonMCP by [Siddharth Ahuja](https://github.com/ahujasid) and later work by [Jason Poindexter](https://github.com/jpoindexter), with thanks to [calclavia](https://github.com/calclavia) and [Ronbalt](https://github.com/Ronbalt).
+
+## License
+
+MIT. See [LICENSE](LICENSE).