名称： flstudio-scripting
描述： FL Studio Python 脚本开发指南，涵盖 MIDI 控制器开发、钢琴卷帘操作、Edison 音频编辑、工作流自动化以及使用 PyFLP 解析 FLP 文件。适用于程序化配置、设备定制、MIDI 传输、宏操作和工程文件处理。覆盖 14 个 MIDI 脚本模块的 427+ 个 API 函数，以及钢琴卷帘、Edison 和 PyFLP 相关功能。

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 版本: {general.getVersion()}")

脚本安装

将脚本放置在 Shared\Python\User 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 控制变更消息时调用。"""
    pass

def OnNoteOn(msg):
    """接收到音符开启消息时调用。"""
    pass

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

2. 钢琴卷帘脚本

用途： 在钢琴卷帘编辑器中操作音符和标记。
运行方式： 用户通过脚本菜单调用时执行一次。
可用模块： flpianoroll, enveditor

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

3. Edison 音频脚本

用途： 在 Edison 中编辑和处理音频样本。
运行方式： 在 Edison 上下文中执行一次。
可用模块： enveditor

API 模块参考索引

根据你的控制需求，导航到相应的参考文件。
仅在需要特定 API 签名时阅读这些文件。

核心工作流模块

编排模块

设备与通信

用户界面与应用控制

插件

专用硬件显示

工具、常量与 MIDI 参考

回调函数与 FlMidiMsg

非 MIDI 脚本 API

钢琴卷帘与 Edison

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

FLP 文件解析 (PyFLP)

无需运行 FL Studio 即可读写 .flp 工程文件的外部库。支持批处理、分析和自动生成。
详见 pyflp.md

常用模式

最小化 MIDI 控制器框架

# name=我的控制器
# url=https://example.com

import device
import mixer
import transport

def OnInit():
    if device.isAssigned():
        print(f"已连接: {device.getName()}")

def OnDeInit():
    print("脚本已关闭")

def OnControlChange(msg):
    if msg.data1 == 7:  # 音量 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("未链接输出设备！")
        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 反馈、批量量化、系统专用信息处理、性能监控、自动化引擎、调试）：
详见 examples-patterns.md

最佳实践

性能

1. 在顶层缓存模块引用（仅导入一次）
2. 避免在 MIDI 回调中进行紧密循环（保持低于 10ms）
3. 批量更新 UI；使用 device.directFeedback() 处理控制器回显

硬件集成

1. 在使用设备函数前，始终检查 device.isAssigned()
2. 为所有控件实现双向同步（状态变更时发送反馈）
3. 在真实硬件上测试（虚拟端口行为不同）

代码组织

1. 将 MIDI 映射与业务逻辑分离（使用控制器类）
2. 保持回调函数响应迅速；将复杂工作卸载
3. 处理边界情况：无效索引、缺失设备、超出范围的值

故障排除

脚本未接收到 MIDI

1. 检查 device.isAssigned() 是否返回 True
2. 在 FL Studio MIDI 设置中验证 MIDI 输入端口
3. 确保回调函数在模块级别定义（非嵌套）
4. 检查 MIDI 消息状态字节是否符合预期值

钢琴卷帘脚本不工作

1. 确认脚本位于 Shared\Python\User Scripts 文件夹中
2. 确保运行前已在钢琴卷帘中打开一个样式
3. 通过 flpianoroll.score.notes 访问音符

性能问题

1. 避免在 OnIdle() 中进行复杂计算（约每 20ms 调用一次）
2. 不要重复查询未更改的值
3. 仅在需要峰值表时使用 device.setHasMeters()

常见问题解答

• 双击检测： 使用 device.isDoubleClick(index)
• 脚本间通信： 使用 device.dispatch(ctrlIndex, message)
• LED 控制： 使用 device.midiOutMsg(0x90, 0, note, velocity) 控制音符开启 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 函数： 14 个模块共 427+ 个 | 最后更新： 2025