FL Studio Python Scripting
Complete reference for FL Studio's Python API: MIDI controller scripting (14 modules, 427+ functions), piano roll note manipulation, Edison audio editing, and FLP file parsing with PyFLP.
Quick Start
Requirements
- FL Studio 20.8.4+, Python 3.6+
Check API Version
import general
print(f"API Version: {general.getVersion()}")
Script Installation
Place scripts in Shared\Python\User Scripts folder.
Three Scripting Contexts
1. MIDI Controller Scripting
Purpose: Control FL Studio through hardware MIDI controllers and send feedback to devices.
Runs: Continuously while FL Studio is open.
Available modules: transport, mixer, channels, arrangement, patterns, playlist, device, ui, general, plugins, screen, launchMapPages, utils, callbacks
Entry points:
def OnInit():
"""Called when script starts."""
pass
def OnDeInit():
"""Called when script stops."""
pass
def OnMidiMsg(msg):
"""Called for incoming MIDI messages."""
pass
def OnControlChange(msg):
"""Called for CC messages."""
pass
def OnNoteOn(msg):
"""Called for note-on messages."""
pass
def OnRefresh(flags):
"""Called when FL Studio state changes."""
pass
2. Piano Roll Scripting
Purpose: Manipulate notes and markers in the piano roll editor.
Runs: Once when user invokes through Scripts menu.
Available modules: flpianoroll, enveditor
import flpianoroll
score = flpianoroll.score
for note in score.notes:
note.velocity = 0.8 # Set all velocities to 80%
3. Edison Audio Scripting
Purpose: Edit and process audio samples in Edison.
Runs: Once within Edison's context.
Available modules: enveditor
API Module Reference Map
Navigate to the appropriate reference file based on what you need to control.
Read these files ONLY when you need specific API signatures.
Core Workflow Modules
| Module |
Functions |
What It Controls |
Reference |
| transport |
20 |
Play, stop, record, position, tempo, looping |
api-transport.md |
| mixer |
69 |
Track volume/pan/mute/solo, EQ, routing, effects |
api-mixer.md |
| channels |
48 |
Channel rack, grid bits, step sequencer, notes |
api-channels.md |
Arrangement Modules
| Module |
Functions |
What It Controls |
Reference |
| arrangement + patterns |
9 + 25 |
Markers, time, pattern control, groups |
api-arrangement-patterns.md |
| playlist |
41 |
Playlist tracks, live mode, performance, blocks |
api-playlist.md |
Device & Communication
| Module |
Functions |
What It Controls |
Reference |
| device |
34 |
MIDI I/O, sysex, dispatch, hardware refresh |
api-device.md |
UI & Application Control
| Module |
Functions |
What It Controls |
Reference |
| ui + general |
71 + 24 |
Windows, navigation, undo/redo, version, snap |
api-ui-general.md |
Plugins
| Module |
Functions |
What It Controls |
Reference |
| plugins |
13 |
Plugin parameters, presets, names, colors |
api-plugins.md |
Specialized Hardware Display
| Module |
Functions |
What It Controls |
Reference |
| screen + launchMapPages |
9 + 12 |
AKAI Fire screen, launchpad page management |
api-screen-launchmap.md |
Utilities, Constants & MIDI Reference
| Module |
Functions |
What It Controls |
Reference |
| utils + constants |
21 |
Color conversion, math, note names, MIDI tables |
api-utils-constants.md |
Callbacks & FlMidiMsg
| Module |
Functions |
What It Controls |
Reference |
| callbacks |
26 |
All callback functions, FlMidiMsg class, event flow |
api-callbacks.md |
Non-MIDI Scripting APIs
Piano Roll & Edison
Note, Marker, ScriptDialog, score classes for piano roll manipulation plus Edison enveditor utilities.
See piano-roll-edison.md
FLP File Parsing (PyFLP)
External library for reading/writing .flp project files without FL Studio running. Batch processing, analysis, automated generation.
See pyflp.md
Common Patterns
Minimal MIDI Controller Skeleton
# 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 # Update hardware display here
Key Pattern: Always Check Device Assignment
def OnInit():
if not device.isAssigned():
print("No output device linked!")
return
# Safe to use device.midiOutMsg() etc.
Key Pattern: Mark Events as Handled
def OnControlChange(msg):
if msg.data1 == 7:
mixer.setTrackVolume(0, msg.data2 / 127.0)
msg.handled = True # Prevent FL Studio from also processing this
Key Pattern: Send Feedback to Hardware
def OnRefresh(flags):
if device.isAssigned():
# Update volume fader LED
vol = int(mixer.getTrackVolume(0) * 127)
device.midiOutMsg(0xB0, 0, 7, vol)
For complete examples (MIDI learn, scale enforcer, LED feedback, batch quantization, sysex handling, performance monitoring, automation engine, debugging):
See examples-patterns.md
Best Practices
Performance
- Cache module references at top level (import once)
- Avoid tight loops in MIDI callbacks (keep under 10ms)
- Batch UI updates; use
device.directFeedback() for controller echo
Hardware Integration
- Always check
device.isAssigned() before device functions
- Implement two-way sync for all controls (send feedback on state change)
- Test on real hardware (virtual ports behave differently)
Code Organization
- Separate MIDI mapping from business logic (use a controller class)
- Keep callbacks responsive; offload complex work
- Handle edge cases: invalid indices, missing devices, out-of-range values
Troubleshooting
Script Not Receiving MIDI
- Check
device.isAssigned() returns True
- Verify MIDI input port in FL Studio MIDI Settings
- Ensure callback functions are defined at module level (not nested)
- Check MIDI message status bytes match expected values
Piano Roll Script Not Working
- Verify script is in
Shared\Python\User Scripts folder
- Ensure a pattern is open in piano roll before running
- Access notes via
flpianoroll.score.notes
Performance Issues
- Avoid complex calculations inside
OnIdle() (called every ~20ms)
- Don't repeatedly query values that haven't changed
- Use
device.setHasMeters() only if peak meters are needed
FAQ
- Double-click detection: Use
device.isDoubleClick(index)
- Inter-script communication: Use
device.dispatch(ctrlIndex, message)
- LED control:
device.midiOutMsg(0x90, 0, note, velocity) for note-on LEDs
- processMIDICC vs OnControlChange: Use
On* callbacks for modern code
- GUI access: Limited through
ui module; full UI automation not available
- Multiple devices: Check
device.getName() to identify, handle per-port
Resources
1---2name: flstudio-scripting3description: FL Studio Python scripting for MIDI controller development, piano roll manipulation, Edison audio editing, workflow automation, and FLP file parsing with PyFLP. Use for programmatic configuration, device customization, MIDI transport, macros, and save file manipulation. Covers all 427+ API functions across 14 MIDI scripting modules plus piano roll, Edison, and PyFLP contexts.4pipeline-status:5 - new6metadata:7 source: https://skillmd.com/skills/delorenj/flstudio-scripting8---910# FL Studio Python Scripting1112Complete reference for FL Studio's Python API: MIDI controller scripting (14 modules, 427+ functions), piano roll note manipulation, Edison audio editing, and FLP file parsing with PyFLP.1314## Quick Start1516### Requirements17- FL Studio 20.8.4+, Python 3.6+1819### Check API Version20```python21import general22print(f"API Version: {general.getVersion()}")23```2425### Script Installation26Place scripts in `Shared\Python\User Scripts` folder.2728---2930## Three Scripting Contexts3132### 1. MIDI Controller Scripting3334**Purpose:** Control FL Studio through hardware MIDI controllers and send feedback to devices.35**Runs:** Continuously while FL Studio is open.36**Available modules:** transport, mixer, channels, arrangement, patterns, playlist, device, ui, general, plugins, screen, launchMapPages, utils, callbacks3738**Entry points:**39```python40def OnInit():41 """Called when script starts."""42 pass4344def OnDeInit():45 """Called when script stops."""46 pass4748def OnMidiMsg(msg):49 """Called for incoming MIDI messages."""50 pass5152def OnControlChange(msg):53 """Called for CC messages."""54 pass5556def OnNoteOn(msg):57 """Called for note-on messages."""58 pass5960def OnRefresh(flags):61 """Called when FL Studio state changes."""62 pass63```6465### 2. Piano Roll Scripting6667**Purpose:** Manipulate notes and markers in the piano roll editor.68**Runs:** Once when user invokes through Scripts menu.69**Available modules:** `flpianoroll`, `enveditor`7071```python72import flpianoroll73score = flpianoroll.score74for note in score.notes:75 note.velocity = 0.8 # Set all velocities to 80%76```7778### 3. Edison Audio Scripting7980**Purpose:** Edit and process audio samples in Edison.81**Runs:** Once within Edison's context.82**Available modules:** `enveditor`8384---8586## API Module Reference Map8788Navigate to the appropriate reference file based on what you need to control.89Read these files ONLY when you need specific API signatures.9091### Core Workflow Modules9293| Module | Functions | What It Controls | Reference |94|--------|-----------|-----------------|-----------|95| **transport** | 20 | Play, stop, record, position, tempo, looping | [api-transport.md](references/api-transport.md) |96| **mixer** | 69 | Track volume/pan/mute/solo, EQ, routing, effects | [api-mixer.md](references/api-mixer.md) |97| **channels** | 48 | Channel rack, grid bits, step sequencer, notes | [api-channels.md](references/api-channels.md) |9899### Arrangement Modules100101| Module | Functions | What It Controls | Reference |102|--------|-----------|-----------------|-----------|103| **arrangement** + **patterns** | 9 + 25 | Markers, time, pattern control, groups | [api-arrangement-patterns.md](references/api-arrangement-patterns.md) |104| **playlist** | 41 | Playlist tracks, live mode, performance, blocks | [api-playlist.md](references/api-playlist.md) |105106### Device & Communication107108| Module | Functions | What It Controls | Reference |109|--------|-----------|-----------------|-----------|110| **device** | 34 | MIDI I/O, sysex, dispatch, hardware refresh | [api-device.md](references/api-device.md) |111112### UI & Application Control113114| Module | Functions | What It Controls | Reference |115|--------|-----------|-----------------|-----------|116| **ui** + **general** | 71 + 24 | Windows, navigation, undo/redo, version, snap | [api-ui-general.md](references/api-ui-general.md) |117118### Plugins119120| Module | Functions | What It Controls | Reference |121|--------|-----------|-----------------|-----------|122| **plugins** | 13 | Plugin parameters, presets, names, colors | [api-plugins.md](references/api-plugins.md) |123124### Specialized Hardware Display125126| Module | Functions | What It Controls | Reference |127|--------|-----------|-----------------|-----------|128| **screen** + **launchMapPages** | 9 + 12 | AKAI Fire screen, launchpad page management | [api-screen-launchmap.md](references/api-screen-launchmap.md) |129130### Utilities, Constants & MIDI Reference131132| Module | Functions | What It Controls | Reference |133|--------|-----------|-----------------|-----------|134| **utils** + constants | 21 | Color conversion, math, note names, MIDI tables | [api-utils-constants.md](references/api-utils-constants.md) |135136### Callbacks & FlMidiMsg137138| Module | Functions | What It Controls | Reference |139|--------|-----------|-----------------|-----------|140| **callbacks** | 26 | All callback functions, FlMidiMsg class, event flow | [api-callbacks.md](references/api-callbacks.md) |141142---143144## Non-MIDI Scripting APIs145146### Piano Roll & Edison147Note, Marker, ScriptDialog, score classes for piano roll manipulation plus Edison enveditor utilities.148See [piano-roll-edison.md](references/piano-roll-edison.md)149150### FLP File Parsing (PyFLP)151External library for reading/writing .flp project files without FL Studio running. Batch processing, analysis, automated generation.152See [pyflp.md](references/pyflp.md)153154---155156## Common Patterns157158### Minimal MIDI Controller Skeleton159160```python161# name=My Controller162# url=https://example.com163164import device165import mixer166import transport167168def OnInit():169 if device.isAssigned():170 print(f"Connected: {device.getName()}")171172def OnDeInit():173 print("Script shut down")174175def OnControlChange(msg):176 if msg.data1 == 7: # Volume CC177 mixer.setTrackVolume(mixer.trackNumber(), msg.data2 / 127.0)178 msg.handled = True179180def OnNoteOn(msg):181 track = msg.data1 % 8182 mixer.setActiveTrack(track)183 msg.handled = True184185def OnRefresh(flags):186 pass # Update hardware display here187```188189### Key Pattern: Always Check Device Assignment190191```python192def OnInit():193 if not device.isAssigned():194 print("No output device linked!")195 return196 # Safe to use device.midiOutMsg() etc.197```198199### Key Pattern: Mark Events as Handled200201```python202def OnControlChange(msg):203 if msg.data1 == 7:204 mixer.setTrackVolume(0, msg.data2 / 127.0)205 msg.handled = True # Prevent FL Studio from also processing this206```207208### Key Pattern: Send Feedback to Hardware209210```python211def OnRefresh(flags):212 if device.isAssigned():213 # Update volume fader LED214 vol = int(mixer.getTrackVolume(0) * 127)215 device.midiOutMsg(0xB0, 0, 7, vol)216```217218For complete examples (MIDI learn, scale enforcer, LED feedback, batch quantization, sysex handling, performance monitoring, automation engine, debugging):219See [examples-patterns.md](references/examples-patterns.md)220221---222223## Best Practices224225### Performance2261. Cache module references at top level (import once)2272. Avoid tight loops in MIDI callbacks (keep under 10ms)2283. Batch UI updates; use `device.directFeedback()` for controller echo229230### Hardware Integration2311. Always check `device.isAssigned()` before device functions2322. Implement two-way sync for all controls (send feedback on state change)2333. Test on real hardware (virtual ports behave differently)234235### Code Organization2361. Separate MIDI mapping from business logic (use a controller class)2372. Keep callbacks responsive; offload complex work2383. Handle edge cases: invalid indices, missing devices, out-of-range values239240---241242## Troubleshooting243244### Script Not Receiving MIDI2451. Check `device.isAssigned()` returns `True`2462. Verify MIDI input port in FL Studio MIDI Settings2473. Ensure callback functions are defined at module level (not nested)2484. Check MIDI message status bytes match expected values249250### Piano Roll Script Not Working2511. Verify script is in `Shared\Python\User Scripts` folder2522. Ensure a pattern is open in piano roll before running2533. Access notes via `flpianoroll.score.notes`254255### Performance Issues2561. Avoid complex calculations inside `OnIdle()` (called every ~20ms)2572. Don't repeatedly query values that haven't changed2583. Use `device.setHasMeters()` only if peak meters are needed259260---261262## FAQ263264- **Double-click detection:** Use `device.isDoubleClick(index)`265- **Inter-script communication:** Use `device.dispatch(ctrlIndex, message)`266- **LED control:** `device.midiOutMsg(0x90, 0, note, velocity)` for note-on LEDs267- **processMIDICC vs OnControlChange:** Use `On*` callbacks for modern code268- **GUI access:** Limited through `ui` module; full UI automation not available269- **Multiple devices:** Check `device.getName()` to identify, handle per-port270271---272273## Resources274275- **Official FL Studio API:** https://www.image-line.com/fl-studio/modules/python-scripting/276- **PyFLP GitHub:** https://github.com/demberto/PyFLP277- **API Functions:** 427+ across 14 modules | **Last Updated:** 2025