Skip to main content

Custom OSC Action

Send fully customized OSC (Open Sound Control) messages to any application, address, and port. Perfect for advanced integrations beyond VRChat or when you need fine-grained control over OSC communication.

What You Need​

  • An application that receives OSC messages
  • Knowledge of the OSC address you want to target
  • The port number the application listens on
  • Understanding of the value type required (String, Float, Int, Bool)

Quick Start​

  1. Identify your target OSC address and port
  2. Create or edit an alert
  3. Add the Custom OSC Message action
  4. Enter OSC address (e.g., /avatar/parameters/MyParam)
  5. Select value type (String, Float, Int, Bool)
  6. Enter the value to send
  7. Optionally set remote address and port (defaults: 127.0.0.1:9000)
  8. Save and test
Screenshot Coming Soon

Configuration interface screenshot will be added here.

Configuration Options​

OSC Address​

OSC Address

  • The OSC address path to send to
  • Always starts with /
  • Example: /avatar/parameters/MyParam
  • Case-sensitive
  • Required field
Address Format

OSC addresses use path-like syntax:

  • /avatar/parameters/Param1
  • /filter/cutoff
  • /1/fader1

Check your target application's documentation for valid addresses.

Value Configuration​

Value Type

  • The data type of the value you're sending
  • Options:
    • String: Text (e.g., "hello", "{username}")
    • Float: Decimal number (e.g., 1.5, 0.75)
    • Integer: Whole number (e.g., 1, 100, -5)
    • Boolean: true/false
  • Required field
  • Must match what receiving application expects

Value

  • The actual value to send
  • Type depends on Value Type selection:
    • String: Any text, supports placeholders
    • Float: Decimal number (e.g., 1.0, 0.5, -2.75)
    • Integer: Whole number (e.g., 1, 50, -10)
    • Boolean: true or false
  • Required field
  • Supports dynamic placeholders (e.g., \{username\}, \{amount\})
Dynamic Values

Use placeholders for dynamic content:

  • \{username\} - Viewer name
  • \{amount\} - Tip/sub amount
  • \{message\} - Viewer message
  • Works with String, Float, and Int types

Network Configuration​

Remote Address

  • IP address of the target machine
  • Default: 127.0.0.1 (localhost)
  • Use for local applications
  • Or enter IP for networked devices
  • Optional (uses default if empty)

Remote Port

  • UDP port the target listens on
  • Default: 9000
  • Common OSC ports: 9000, 8000, 7000
  • Check application documentation
  • Optional (uses default if empty)

Local Port (Optional)

  • Port for TipLink to listen on (for two-way OSC)
  • Leave empty for send-only mode (recommended)
  • Only needed if target sends responses back
  • Most use cases don't need this
Send-Only vs Two-Way

Most alert actions only need to send OSC messages. Leave Local Port empty unless your application requires two-way communication.

Setup Guide​

Basic Setup​

  1. Identify Target Information

    • Application name (e.g., TouchOSC, Max/MSP, VRChat)
    • OSC address (e.g., /1/fader1)
    • Value type required
    • Port number (check app settings)

  2. Create Alert

    • Navigate to Alerts
    • Create new or edit existing
    • Set trigger conditions

  3. Add Custom OSC Action

    • Actions → Add Action
    • Select "Send Custom OSC Message"

  4. Configure Message

    • OSC Address: /your/address
    • Value Type: Select appropriate type
    • Value: Enter your value
    • Leave network defaults (127.0.0.1:9000) if local

  5. Test

    • Save alert
    • Trigger while target app is running
    • Verify message received

VRChat Custom Parameters​

To send to VRChat (alternative to built-in VRChat action):

  1. OSC Address: /avatar/parameters/MyParameter
  2. Value Type: Bool (or Float/Int depending on parameter)
  3. Value: true or 1
  4. Remote Port: 9000 (default)
  5. Remote Address: 127.0.0.1 (default)

TouchOSC Integration​

For controlling TouchOSC:

  1. Find TouchOSC port

    • Check TouchOSC → Connections settings
    • Default often 9000 or 8000

  2. OSC Address: /1/fader1 (or your control's address)

  3. Value Type: Float

  4. Value: 0.75 (0.0 to 1.0 range)

  5. Remote Port: Your TouchOSC port

Max/MSP Integration​

For Max/MSP patches:

  1. Setup udpreceive in Max

    • Add udpreceive 9000 object
    • Add route /your/address object

  2. Configure TipLink

    • OSC Address: /your/address
    • Value Type: Match your Max patch
    • Remote Port: 9000

Networked OSC Device​

For OSC devices on your network:

  1. Find device IP

    • Check device network settings
    • Example: 192.168.1.100

  2. Configure TipLink

    • OSC Address: As per device docs
    • Remote Address: Device IP (e.g., 192.168.1.100)
    • Remote Port: Device port
    • Ensure firewall allows UDP traffic

Common Use Cases​

VRChat Alternative

  • Address: /avatar/parameters/EmoteTrigger
  • Type: Bool
  • Value: true
  • Use when built-in VRChat action doesn't fit

Audio Software Control

  • Address: /track/1/volume
  • Type: Float
  • Value: 0.8 (80% volume)
  • Control DAW or audio mixer

Lighting Control

  • Address: /lights/color/hue
  • Type: Int
  • Value: \{amount\} (maps tip to hue)
  • Control smart lights or DMX

Game Integration

  • Address: /game/spawn/item
  • Type: String
  • Value: sword
  • Trigger game events

Visual Effects (Resolume)

  • Address: /layer1/clip1/connect
  • Type: Bool
  • Value: true
  • Trigger video clips

Physical Device Control

  • Address: /device/servo/angle
  • Type: Int
  • Value: 90
  • Control Arduino/ESP32 with OSC

Custom Chat Bot

  • Address: /bot/command
  • Type: String
  • Value: !shoutout \{username\}
  • Send commands to custom bot

Troubleshooting​

Message not received

  • Verify target application is running
  • Check port number is correct
  • Confirm firewall isn't blocking UDP
  • Test with OSC monitor tool
  • Verify address format (must start with /)

Wrong value received

  • Check value type matches expectation
  • Float vs Int: 1.0 vs 1
  • String vs others: quotes not needed
  • Verify placeholder expansion worked

Connection issues (networked)

  • Ping remote IP to verify connectivity
  • Check both machines on same network
  • Verify UDP port forwarding if needed
  • Firewall may block UDP traffic

Address not found

  • OSC addresses are case-sensitive
  • Check for typos or extra spaces
  • Verify address exists in target app
  • Some apps require specific formatting

Local port conflicts

  • Only use Local Port if truly needed
  • Port may be in use by another app
  • Leave empty for send-only mode
  • Check with netstat -an | findstr :PORT (Windows)

Placeholder not working

  • Verify placeholder syntax: \{username\} not username
  • Check placeholder is supported for trigger type
  • Works with String, Float, Int (not Bool)
  • Float/Int placeholders convert to numbers

Best Practices​

Address Naming:

  • Use clear, descriptive paths: /game/player/health
  • Follow target app's convention
  • Case-sensitive - be consistent
  • Avoid spaces and special characters

Value Types:

  • Match exactly what receiver expects
  • Float: Always include decimal (1.0 not 1)
  • Int: Whole numbers only
  • Bool: true/false or 1/0
  • String: For text or complex data

Network Configuration:

  • Use localhost (127.0.0.1) when possible
  • Only set Remote Address for networked devices
  • Leave Local Port empty unless needed
  • Document your port assignments

Testing:

  • Use OSC monitor tool (e.g., Protokol, OSC Monitor)
  • Test with simple static values first
  • Add dynamic placeholders after basic test works
  • Verify with target application's feedback

Performance:

  • OSC messages are lightweight
  • Safe to send frequently
  • No artificial delays needed
  • Rate limiting depends on receiver

Documentation:

  • Document your OSC addresses
  • Note expected value ranges
  • Keep list of used ports
  • Track which apps use which addresses

Technical Reference​

OSC Protocol:

  • Protocol: UDP (User Datagram Protocol)
  • Default Port: 9000 (customizable)
  • Message Format: Binary OSC format
  • Transport: IP network (local or remote)

Address Format:

  • Must start with /
  • Path-like structure
  • Case-sensitive
  • No wildcards in sending
  • Example: /category/subcategory/parameter

Value Type Details:

  • String (s): UTF-8 text, null-terminated
  • Float (f): 32-bit floating point
  • Integer (i): 32-bit signed integer
  • Boolean (T/F): OSC true/false tag

Network Details:

  • Protocol: UDP (unreliable, fast)
  • IP: IPv4 (IPv6 not currently supported)
  • Broadcast: Not supported (unicast only)
  • Multicast: Not supported

Message Structure:

OSC Address: /path/to/parameter
Type Tag: ,s (string) or ,f (float) or ,i (int) or ,T/F (bool)
Value: [your value]

Port Ranges:

  • Well-known: 0-1023 (avoid)
  • Registered: 1024-49151 (common for OSC)
  • Dynamic: 49152-65535 (avoid)
  • Common OSC: 7000, 8000, 9000, 9001

Placeholders:

  • Processed before sending
  • Type conversion automatic for Float/Int
  • String: No conversion needed
  • Bool: No placeholder support (static only)

Send-Only Mode:

  • Default behavior (no Local Port)
  • TipLink sends messages
  • Doesn't listen for responses
  • Most efficient for alerts

Two-Way Mode:

  • Set Local Port to enable
  • TipLink listens for incoming messages
  • Rarely needed for alert actions
  • Adds overhead

Error Handling:

  • No delivery confirmation (UDP)
  • Fails silently if receiver offline
  • Logs errors to TipLink console
  • No automatic retry

Performance:

  • Message send: < 1ms overhead
  • Network latency: 10-50ms (local), 50-200ms (network)
  • No rate limiting on send
  • Receiver may have rate limits

Compatibility:

  • OSC 1.0 specification
  • Compatible with all OSC-capable software
  • No special codecs or extensions
  • Standard binary format