FL Studio Python 脚本编程

FL Studio Python API 完整参考文档：MIDI 控制器脚本（14 个模块，427+ 个函数）、钢琴卷帘窗音符操作、Edison 音频编辑，以及使用 PyFLP 解析 FLP 工程文件。

快速开始

系统要求

• FL Studio 20.8.4+，Python 3.6+

检查 API 版本

import general
print(f"API Version: {general.getVersion()}")

脚本安装

将脚本文件放入 SharedPythonUser Scripts 文件夹中。

三种脚本运行上下文

1. MIDI 控制器脚本

用途：通过硬件 MIDI 控制器控制 FL Studio，并向设备发送反馈信号。
运行时机：FL Studio 运行期间持续执行。
可用模块：transport、mixer、channels、arrangement、patterns、playlist、device、ui、general、plugins、screen、launchMapPages、utils、callbacks

入口函数：

def OnInit():
    """脚本启动时调用。"""
    pass

def OnDeInit():
    """脚本停止时调用。"""
    pass

def OnMidiMsg(msg):
    """接收到任意 MIDI 消息时调用。"""
    pass

def OnControlChange(msg):
    """接收到 CC（Control Change）消息时调用。"""
    pass

def OnNoteOn(msg):
    """接收到 Note-On 消息时调用。"""
    pass

def OnRefresh(flags):
    """FL Studio 状态发生变化时调用。"""
    pass

2. 钢琴卷帘窗脚本

用途：在钢琴卷帘窗编辑器中操作音符与标记。
运行时机：用户通过“Scripts”菜单手动触发，仅执行一次。
可用模块：flpianoroll、enveditor

import flpianoroll
score = flpianoroll.score
for note in score.notes:
    note.velocity = 0.8  # 将所有音符力度设为 80%

3. Edison 音频脚本

用途：在 Edison 中编辑和处理音频采样。
运行时机：仅在 Edison 上下文中执行一次。
可用模块：enveditor

API 模块参考映射表

请根据您的具体控制需求，跳转至对应参考文档。
仅当您需要查阅特定 API 函数签名时，才需阅读这些文件。

核心工作流模块

编排相关模块

设备与通信模块

UI 与应用程序控制模块

插件模块

专用硬件显示模块

工具函数、常量与 MIDI 参考模块

回调函数与 FlMidiMsg 类

非 MIDI 脚本 API

钢琴卷帘窗与 Edison

提供用于钢琴卷帘窗操作的 Note、Marker、ScriptDialog、score 类，以及 Edison enveditor 实用工具。
详见 piano-roll-edison.md

FLP 工程文件解析（PyFLP）

一个外部库，支持在不运行 FL Studio 的情况下读写 .flp 工程文件。适用于批量处理、工程分析、自动化生成等场景。
详见 pyflp.md

常用编程模式

最小化 MIDI 控制器脚手架

# name=My Controller
# url=https://example.com

import device
import mixer
import transport

def OnInit():
    if device.isAssigned():
        print(f"Connected: {device.getName()}")

def OnDeInit():
    print("Script shut down")

def OnControlChange(msg):
    if msg.data1 == 7:  # Volume CC
        mixer.setTrackVolume(mixer.trackNumber(), msg.data2 / 127.0)
        msg.handled = True

def OnNoteOn(msg):
    track = msg.data1 % 8
    mixer.setActiveTrack(track)
    msg.handled = True

def OnRefresh(flags):
    pass  # 此处更新硬件显示

关键模式：始终检查设备分配状态

def OnInit():
    if not device.isAssigned():
        print("No output device linked!")
        return
    # 此后可安全调用 device.midiOutMsg() 等函数

关键模式：标记事件为已处理

def OnControlChange(msg):
    if msg.data1 == 7:
        mixer.setTrackVolume(0, msg.data2 / 127.0)
        msg.handled = True  # 防止 FL Studio 对该消息重复处理

关键模式：向硬件发送反馈

def OnRefresh(flags):
    if device.isAssigned():
        # 更新音量推子 LED 状态
        vol = int(mixer.getTrackVolume(0) * 127)
        device.midiOutMsg(0xB0, 0, 7, vol)

完整示例（MIDI 学习、音阶强制、LED 反馈、批量量化、SysEx 处理、性能监控、自动化引擎、调试技巧）请参阅：
examples-patterns.md

最佳实践

性能优化

1. 在模块顶层缓存模块引用（仅 import 一次）
2. 避免在 MIDI 回调中使用密集循环（单次执行应控制在 10ms 内）
3. 批量更新 UI；使用 device.directFeedback() 实现控制器回显

硬件集成

1. 调用任何 device 相关函数前，务必先检查 device.isAssigned()
2. 对所有控件实现双向同步（状态变更时主动发送反馈）
3. 务必在真实硬件上测试（虚拟端口行为可能不同）

代码组织

1. 将 MIDI 映射逻辑与业务逻辑分离（建议封装为独立 controller 类）
2. 保持回调函数响应迅速；复杂任务应异步或延后执行
3. 妥善处理边界情况：非法索引、缺失设备、越界数值等

故障排查

脚本未接收到 MIDI 信号

1. 确认 device.isAssigned() 返回 True
2. 检查 FL Studio MIDI 设置中的输入端口是否已启用
3. 确保回调函数定义在模块层级（不可嵌套于其他函数内）
4. 核对 MIDI 消息状态字节是否符合预期值

钢琴卷帘窗脚本不生效

1. 确认脚本已置于 SharedPythonUser Scripts 文件夹中
2. 运行前确保钢琴卷帘窗中已打开一个 Pattern
3. 通过 flpianoroll.score.notes 访问音符列表

性能问题

1. 避免在 OnIdle() 中执行复杂计算（该函数约每 20ms 调用一次）
2. 避免反复查询未发生变化的值
3. 仅在确实需要峰值电平表（peak meters）时调用 device.setHasMeters()

常见问题解答（FAQ）

• 双击检测：使用 device.isDoubleClick(index)
• 脚本间通信：使用 device.dispatch(ctrlIndex, message)
• LED 控制：device.midiOutMsg(0x90, 0, note, velocity) 用于 Note-On 类型 LED
• processMIDICC 与 OnControlChange 的区别：现代开发推荐使用 On* 系列回调函数
• GUI 访问能力：仅可通过 ui 模块进行有限访问；不支持完整 UI 自动化
• 多设备支持：通过 device.getName() 区分设备，并按端口分别处理

资源链接

• 官方 FL Studio API 文档： https://www.image-line.com/fl-studio/modules/python-scripting/
• PyFLP GitHub 仓库： https://github.com/demberto/PyFLP
• API 函数总数： 427+ 个，覆盖 14 个模块 | 最后更新时间： 2025