# ableton-live-stubs

PEP 561 type stubs for Ableton Live 12.3.6's Python API (`Live.*` modules).

These stubs are for developers building **MIDI Remote Scripts** (Control Surfaces) that run inside
Ableton Live's embedded Python runtime. They provide type information for the `Live` module that Live
exposes to scripts at runtime but is not available for static analysis outside of Live.

## Installation

```
pip install ableton-live-stubs
```

## Usage

Once installed, type checkers (pyright, mypy) automatically discover the `Live` module stubs.
No configuration needed.

Import types under `TYPE_CHECKING` to avoid runtime import errors (the `Live` module only exists inside
Ableton Live's Python runtime):

```python
from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    import Live
    from Live.Song import Song

def on_tempo_changed(song: Song) -> None:
    app: Live.Application.Application = Live.Application.get_application()
    print(f"Live {app.get_major_version()}: tempo is now {song.tempo}")
```

## Manual setup (without pip)

Download the zip from the
[GitHub release](https://github.com/PhotonicVelocity/LiveAPI/releases/tag/v12.3.6)
and add the extracted directory (the parent of `Live/`) to your type checker's stub path:

```json
// pyrightconfig.json
{
  "stubPath": "path/to/Live-stubs"
}
```

## Version matching

Each release of `ableton-live-stubs` corresponds to a specific Ableton Live version. Install the
version that matches your target Live version — the API surface changes between releases.

## Documentation

For detailed API documentation — including property restrictions (e.g. which track/clip types support
a given property), valid input ranges, and observable properties — see the
[LiveAPI reference](https://photonicvelocity.github.io/LiveAPI/).

## Source

Generated from runtime introspection of Ableton Live 12.3.6.
See [LiveAPI](https://github.com/PhotonicVelocity/LiveAPI) for details.
