ableton-lom

Ableton Live 对象模型（LOM）API 参考

本技能提供 Ableton Live Remote Scripts 所用 Python API 的完整文档。该 API 通过 _Framework.ControlSurface 基类访问，可对 Live Set 的各个方面进行编程控制。

快速入门

from _Framework.ControlSurface import ControlSurface

class MyScript(ControlSurface):
    def __init__(self, c_instance):
        ControlSurface.__init__(self, c_instance)
        self._song = self.song()  # Access the Live Set (Song object)
        app = self.application()  # Access the Application object

核心对象层级

Application
├── browser (instruments, sounds, drums, audio_effects, midi_effects)
├── control_surfaces[] → ControlSurface
└── Song (live_set)
    ├── tempo, is_playing, loop, metronome
    ├── tracks[] → Track
    │   ├── clip_slots[] → ClipSlot → Clip
    │   ├── devices[] → Device → DeviceParameter
    │   ├── mixer_device → MixerDevice
    │   └── view → Track.View
    ├── return_tracks[] → Track
    ├── master_track → Track
    ├── scenes[] → Scene
    ├── cue_points[] → CuePoint
    ├── groove_pool → GroovePool → Groove
    ├── tuning_system → TuningSystem
    └── view → Song.View

按领域分类的参考文件

根据当前的工作内容加载相应的参考文件：

领域	文件	适用场景
歌曲与传输控制	references/song.md	处理速度、播放、拍号、循环、提示点
轨道	references/track.md	创建／修改轨道、路由、录音准备／独奏／静音、音量表
片段与 MIDI	references/clip.md	创建片段、添加／编辑 MIDI 音符、片段属性、变形
设备	references/device.md	加载设备、访问参数、设备链
专用设备	references/specialized-devices.md	Simpler、Wavetable、Looper、Compressor、EQ8、Drift 等
Rack 设备	references/rack.md	乐器／音频／MIDI／鼓 Rack、链、宏、鼓垫
Session View	references/session.md	场景、片段槽、启动、Session View 导航
视图与 UI	references/views.md	Application.View、Song.View、Track.View、Clip.View、Device.View
浏览器	references/browser.md	浏览／加载乐器、效果器、采样、预设
控制表面	references/control-surface.md	访问已配置的控制表面、接管控件／MIDI、SysEx
Groove 与调音	references/grooves-tuning.md	Groove 池、调音系统
覆盖清单	references/lom-coverage.md	Cycling '74 官方 LOM 对象与文件的审计映射

关键概念

属性访问模式

• 只读：只能获取值
• 读写：可以获取和设置值
• 可观察：可以使用 add_<property>_listener(callback) 添加侦听器

线程

所有状态修改都必须在 Ableton 的主线程上进行：

def modify_state():
    self._song.tempo = 120.0

self.schedule_message(0, modify_state)  # Schedule for main thread

规范路径

通过类似 live_set tracks 0 devices 1 parameters 2 的路径访问对象。可通过这些路径了解对象层级。

特殊根路径包括 live_set（当前 Song）、live_app（Application）、control_surfaces N（已配置的 ControlSurface）和 this_device（包含接收 goto this_device 的 Max for Live live.path 对象的 Device）。

常见模式

遍历轨道和片段：

for track in self._song.tracks:
    for slot in track.clip_slots:
        if slot.has_clip:
            clip = slot.clip
            # Work with clip

添加侦听器：

def on_tempo_changed():
    self.log_message("Tempo: " + str(self._song.tempo))

self._song.add_tempo_listener(on_tempo_changed)

访问设备参数：

device = track.devices[0]
for param in device.parameters:
    self.log_message(param.name + ": " + str(param.value))

版本兼容性

本文档适用于 Live 12.3。版本说明：

• Live 11 及更高版本：需要 Python 3
• Live 11.0 及更高版本：新增 GroovePool、Groove 类
• Live 12.3 及更高版本：新增 insert_device()、insert_chain() 和 AB Compare 功能

重要说明

1. Ableton 未正式发布此 API 的文档——本参考资料基于 Cycling '74 的 Max for Live LOM 参考文档等社区资料
2. 使用备份的 Live Set 测试 Remote Scripts
3. 从错误的线程调用某些操作可能导致崩溃
4. 可观察属性可用于构建响应式 UI