Advanced OSC Integration with TouchOSC, QLab, and More

Introduction

OSC (Open Sound Control) opens up endless possibilities for integrating song data with professional creative software. Beyond VJ applications like Resolume, Song Overlays Pro works with TouchOSC, QLab, Isadora, Max/MSP, and any OSC-compatible application.

What you'll achieve:

• Build custom control surfaces in TouchOSC
• Trigger theater cues in QLab based on songs
• Create interactive installations with Isadora
• Process music data in Max/MSP
• Connect to any OSC-compatible software

Prerequisites

Before starting, make sure you have:

• macOS 13.0 (Ventura) or later
• Song Overlays Pro installed and running
• OSC-compatible software (TouchOSC, QLab, Isadora, Max/MSP, etc.)
• Basic understanding of OSC concepts (addresses, ports)
• Network connectivity between devices (if using multiple machines)

Understanding Song Overlays Pro's OSC Output

Before diving into specific applications, understand what data is available.

OSC Addresses

Song Overlays Pro sends to these addresses when a song is detected:

Address	Data Type	Example
/song/title	String	"Bohemian Rhapsody"
/song/artist	String	"Queen"
/song/album	String	"A Night at the Opera"
/song/artwork	String (URL)	"https://..."
/song/isrc	String	"GBUM71029604"
/song/appleMusicUrl	String (URL)	"https://music.apple.com/..."
/song/changed	Boolean	true

Message Format

• Messages are sent as OSC bundles
• All strings are UTF-8 encoded
• Sent immediately when a new song is detected
• /song/changed fires with every detection (useful for triggers)

Step 1: Configure OSC in Song Overlays Pro

Set up the OSC output for your target application.

1. Open Song Overlays Pro
2. Click OSC in the sidebar
3. Toggle Enable OSC to on
4. Configure connection settings:
   • Host: Target device IP (or 127.0.0.1 for same machine)
   • Port: Match your receiving application's port
5. Click Test to verify connectivity

Multiple Destinations

Send to multiple applications simultaneously:

1. Click Add Destination
2. Enter additional host/port combinations
3. Each destination receives identical data
4. Useful for redundancy or multi-system setups

Step 2: TouchOSC Integration

Build a custom control surface that displays song information.

Setting Up TouchOSC

1. Open TouchOSC on your iPad/iPhone/Android
2. Go to Connections → OSC
3. Configure to receive from your Mac:
   • Receive Port: Match Song Overlays Pro's output port
   • Send Host/Port: Your Mac's IP and desired port (for bidirectional)

Creating a Song Display Layout

1. Open TouchOSC Editor (desktop app)
2. Create a new layout
3. Add Label controls for song data:
   • Label for title: Set OSC address to /song/title
   • Label for artist: Set OSC address to /song/artist
   • Label for album: Set OSC address to /song/album

Label Configuration

For each label:

• Receive: Enable
• OSC Address: Corresponding /song/... address
• Value: Text (receives string)
• Font/Size: Style as desired

Advanced TouchOSC Ideas

Now Playing Panel:

┌─────────────────────────┐
│  🎵 NOW PLAYING         │
│  ─────────────────────  │
│  Title: {/song/title}   │
│  Artist: {/song/artist} │
│  Album: {/song/album}   │
└─────────────────────────┘

DJ Controller Integration:

• Add song display to existing DJ layouts
• Combine with mixer controls
• Create set management views

Step 3: QLab Integration

Trigger cues in theater productions based on songs.

Configuring QLab for OSC

1. Open QLab (version 4 or 5)
2. Go to Settings → Network
3. Under OSC Input:
   • Enable OSC input
   • Set port to match Song Overlays Pro's output
   • Note QLab's IP if on different machine

Creating Song-Triggered Cues

Method 1: OSC Trigger Cues

1. Create a new OSC cue
2. Set as trigger cue (responds to incoming OSC)
3. Configure the trigger:
   • Address: /song/changed
   • Arguments: (any value triggers)

Method 2: Script Cues

For more control, use AppleScript:

-- This script runs when song changes
tell application id "com.figure53.QLab.5"
    set songTitle to (osc value "/song/title")
    -- Use songTitle to control cues
end tell

Theater Use Cases

Musical Transitions:

• Auto-advance cues when songs change
• Sync lighting with music changes
• Trigger scene markers

Immersive Experiences:

• Display song info on projection
• Trigger effects based on specific songs
• Create dynamic setlists

Example: Auto-Advance Playlist

1. Create a group cue for each song
2. Add OSC trigger that fires when /song/changed is received
3. Use conditions to match /song/title to expected song
4. Auto-fire the next cue group

Step 4: Isadora Integration

Create interactive visuals that respond to music metadata.

Setting Up Isadora

1. Open Isadora
2. Go to Communications → OSC Setup
3. Enable OSC Input on a specific port
4. Match port in Song Overlays Pro

Basic Song Display Patch

1. Add OSC Listener actor
2. Set address to /song/title
3. Connect to Text Draw actor
4. Route to output stage

Creating Reactive Visuals

Song Title Display:

[OSC Listener] → [Text Draw] → [Projector]
    /song/title     font/size      stage 1

Album Art Display:

[OSC Listener] → [Picture Player] → [Projector]
   /song/artwork      URL input        stage 1

Advanced Isadora Techniques

Trigger on Song Change:

1. Use OSC Listener for /song/changed
2. Connect to Trigger Delay
3. Fire scene changes or effect triggers

Genre-Based Visuals:

1. Parse song metadata for keywords
2. Use Text Parser to detect genres
3. Switch visual scenes based on music style

Step 5: Max/MSP Integration

Process song data for custom audio-visual applications.

Receiving OSC in Max

1. Create a new patch
2. Add [udpreceive 7000] object (match your port)
3. Connect to [OSC-route /song]
4. Further route to /title, /artist, etc.

Basic Patch Structure

[udpreceive 7000]
      |
[OSC-route /song]
      |
[OSC-route /title /artist /album]
   |        |        |
[print] [print] [print]

Practical Applications

Text-to-Speech Announcements:

[OSC-route /song/title]
      |
[sprintf "Now playing %s"]
      |
[aka.speech]

Data Logging:

[OSC-route /song]
      |
[coll song_history]
      |
[text song_log.txt]

Visualizer Integration:

[OSC-route /song/changed]
      |
[trigger b]
      |
[jit.gl.text] -- Update visual display

Step 6: Other OSC Applications

Song Overlays Pro works with any OSC-compatible software.

Ableton Live (via Max for Live)

1. Create a Max for Live device
2. Use OSC receive objects
3. Map to Live parameters or display

MadMapper

1. Enable OSC input in MadMapper
2. Map song data to text overlays
3. Trigger surfaces on song changes

VDMX

1. Open OSC settings in VDMX
2. Receive on matching port
3. Use for text sources and triggers

Chataigne

1. Add OSC input module
2. Map values to any output
3. Create complex automation rules

TouchDesigner

1. Add OSC In CHOP
2. Route string data to text TOPs
3. Build reactive visual systems

Step 7: Network Configuration

Set up multi-machine OSC routing.

Same Computer

• Host: 127.0.0.1 (localhost)
• No firewall concerns
• Lowest latency

Local Network

1. Find target machine's IP address:

   • Mac: System Settings → Network
   • Windows: ipconfig in Command Prompt

2. Enter IP in Song Overlays Pro's host field

3. Ensure firewall allows OSC port:

   • Mac: System Settings → Firewall → Options
   • Add exception for the port

Multiple Targets

To send to multiple machines:

1. Add each machine as a separate destination
2. Use same port across all machines (easier management)
3. Or use different ports if applications conflict

OSC Bridge/Router

For complex setups, use an OSC router:

• OSCRouter — Route between applications
• Protokol — Monitor and debug OSC
• oscHook — Transform and filter messages

Troubleshooting

Not Receiving OSC

1. Verify ports match — Sender and receiver must use same port
2. Check IP addresses — Use correct IP for target machine
3. Test with OSC monitor — Use Protokol or similar to verify messages are sent
4. Firewall issues — Add exceptions for OSC port

Garbled or Missing Data

1. Check encoding — Ensure UTF-8 support
2. Verify addresses — OSC addresses are case-sensitive
3. Buffer size — Some apps need buffer adjustment for long strings

Latency Issues

1. Use local network — Avoid internet routing
2. Reduce destinations — Each adds overhead
3. Check network congestion — Other traffic affects OSC

Application-Specific Issues

TouchOSC:

• Ensure "Receive" is enabled on labels
• Check layout is deployed to device

QLab:

• Verify OSC input is enabled in workspace settings
• Check cue triggers are armed

Max/MSP:

• Ensure udpreceive port matches
• Check patch is not in edit mode

Advanced: Custom OSC Processing

Filtering Messages

Create rules to only send certain data:

• Only send when specific artists play
• Filter out songs below certain duration
• Rate-limit messages to prevent spam

Transforming Data

Modify OSC output format:

• Change address structure to match existing systems
• Add prefixes for multi-source setups
• Convert encoding for legacy systems

Bidirectional Communication

Some setups benefit from two-way OSC:

• Control Song Overlays Pro from external surfaces
• Request song data on demand
• Sync state across applications

Next Steps

You're now ready to integrate song data with any OSC application. Explore these related resources:

Resolume Integration

If you're using Resolume Arena/Avenue, see the dedicated guide.

Resolume OSC setup

Visual Design

Make your song displays look professional.

Theme customization

Join the Community

Connect with other creative professionals using Song Overlays Pro.

Join Discord

---

The possibilities are endless! With OSC output, Song Overlays Pro becomes a bridge between music and any creative software you use. Theater, live performance, installations, interactive art — if it speaks OSC, it can display what's playing.