Quick Start Guide¶

Get up and running with VimAbl in 5 minutes!

Prerequisites

Make sure you've completed the Installation Guide first.

Step 1: Launch Ableton Live¶

Open Ableton Live
Load any project (or start a new one)
Verify the Remote Script is loaded:
```
echo "GET_VIEW" | nc 127.0.0.1 9001
```
You should see: {"view": "session"} or {"view": "arrangement"}

Step 2: Try Your First Commands¶

In Session View¶

Make sure you're in Session View (Tab to switch views if needed).

Jump to First Scene:

Press: g g (quickly, twice)

Your view should jump to the first scene.

Jump to Last Scene:

Press: Shift + G

Your view should jump to the last scene.

In Arrangement View¶

Switch to Arrangement View (Tab).

Jump to First Track:

Press: g g (quickly, twice)

The first track should be selected and the view should scroll to it.

Jump to Last Track:

Press: Shift + G

The last track should be selected and the view should scroll to it.

Step 3: Try Editing Commands¶

Undo:

Press: z a

This triggers Ableton's undo function.

Delete (Double-tap):

Press: d d (quickly, twice)

This triggers delete on the selected item.

Toggle Browser:

Press: Ctrl + -

The device browser should toggle open/closed.

Step 4: Explore the Web TreeViewer¶

The TreeViewer provides real-time visualization of your Ableton project.

Automatic Mode (Recommended)¶

Make sure your Ableton project is saved
Launch Ableton Live
Wait ~5 seconds (WebSocket server starts automatically)
Open http://localhost:5173 in your browser

You should see a tree visualization of your project!

Manual Mode¶

# Terminal 1: Start WebSocket server
uv run python -m src.main Example_Project/example.als --mode=websocket

# Terminal 2: Start Svelte dev server
cd src/web/frontend
npm run dev

# Open http://localhost:5173 in browser

Try It Out¶

In the web UI, expand tracks and devices
In Ableton Live, rename a track
Watch the UI update in real-time!
Try changing track colors, adding devices, etc.

Step 5: Check Real-Time Observers¶

VimAbl includes UDP/OSC observers that stream Live events in real-time.

Start the UDP Listener¶

# Terminal 1: Start listener
python3 src/udp_listener/listener.py

Make Changes in Ableton¶

Rename a track → See event in terminal
Mute/unmute a track → See event in terminal
Adjust volume → See debounced events
Change tempo → See event in terminal

Check Observer Status¶

echo "GET_OBSERVER_STATUS" | nc localhost 9001

You should see statistics about active observers.

Common Keybindings¶

Session View¶

Keybinding	Action
`gg`	Jump to first scene
`G`	Jump to last scene
`za`	Undo
`dd`	Delete (double-tap)
`Ctrl + -`	Toggle browser

Arrangement View¶

Keybinding	Action
`gg`	Jump to first track (with scroll)
`G`	Jump to last track (with scroll)
`za`	Undo
`dd`	Delete (double-tap)
`Ctrl + -`	Toggle browser

Web TreeViewer Controls¶

Keybinding	Action
`Cmd+Shift+W`	Toggle WebSocket server
`Cmd+Shift+R`	Restart WebSocket server
`Cmd+Shift+I`	Show server status

Next Steps¶

Now that you've got the basics, dive deeper:

User Guide - Learn all features in detail
Keybindings Reference - Complete command list
Architecture - Understand how it works
Development Guide - Extend VimAbl with your own commands

Troubleshooting¶

Commands Not Working¶

✅ Check Ableton Live is the frontmost application
✅ Verify Hammerspoon is running (menu bar icon)
✅ Check Hammerspoon console for errors
✅ Reload Hammerspoon config

WebSocket Server Not Starting¶

✅ Make sure your project is saved (.als file exists)
✅ Check port 8765 is not in use: lsof -i :8765
✅ Check Hammerspoon console for errors
✅ Try manual mode to debug

UDP Events Not Appearing¶

✅ Check listener is running: lsof -i :9002
✅ Verify Remote Script is loaded (check Log.txt)
✅ Restart Ableton Live
✅ Check observer status: echo "GET_OBSERVER_STATUS" | nc localhost 9001

Need more help? Check the Full Troubleshooting Guide.