BeamCommander - Laser Control System

💎 Free & Open Source | 🤝 Community Driven | ✨ Live Performance Ready

📚 Website | 💬 Discussions

BeamCommander is a free, open-source laser control system that bridges OSC (Open Sound Control) commands with laser hardware, providing real-time visual effects for performances and installations. Developed and supported by a passionate community of artists, developers, and laser enthusiasts.

Live Performance Ready: Control your lasers in real-time using an Akai APC40 MIDI controller and/or intuitive web interface. Designed specifically for live performances, VJ sets, and externally controlled laser shows via OSC commands. Perfect for artists, performers, and installation designers who need responsive, tactile control over complex laser visuals.

Demo

Real-time laser control demonstration showing Open Stage Control interface integration with BeamCommander

Live performance demonstration with Akai APC40 MIDI controller and iPad (Open Stage Control browser UI) controlling laser effects in real-time

Quick Start (Users)

How to Run BeamCommander

1. Download the Release Binary

   • Go to the Releases page
   • Download the latest release for Mac
   • Extract the downloaded archive

2. Run BeamCommander

   • Double-click BeamCommander.app or run it from terminal
   • The application will start listening for OSC commands on UDP port 9000

3. Initial Laser Setup (Required)

   • First Time: The application opens with a configuration interface
   • Add Laser Hardware: Click "Add Laser" to detect your DAC device
   • Zone Mapping: Create and configure at least one output zone
   • Test Output: Verify laser output is working before performance use
   • Save Configuration: Settings are automatically saved for future sessions

4. Control Options

   Option A: Akai APC40 MIDI Controller

   • Connect your Akai APC40 via USB
   • Use physical knobs and buttons for tactile laser control
   • See MIDI Controller Reference section below for button mappings

   Option B: Custom OSC Client

   • Use any OSC-compatible software or hardware
   • Send commands to localhost:9000 (or the machine's IP address)
   • See OSC API Reference section below for complete command list

   Option C: Open Stage Control Web Interface

   • Install Open Stage Control on your device
   • Use the provided configuration files:
     • open-stage-control-server.config - Server configuration
     • open-stage-control-session.json - Touch interface layout
   • Access the web interface from any device on your network

Prerequisites

• macOS 15.6.1 or later
• Compatible Laser DAC Hardware (see Compatible Hardware section below)
• Optional: Akai APC40 MIDI controller for physical control
• Optional: Open Stage Control for web-based touch interface

Compatible Hardware

BeamCommander supports a wide range of laser DAC (Digital-to-Analog Converter) hardware through the powerful ofxLaser framework:

Ethernet DACs

• EtherDream: Industry-standard Ethernet laser DAC ✅ Tested
• Laser Dock: USB and Ethernet laser projector system
• LaserCube: Compact wireless laser projector

USB DACs

• Helios: High-performance USB laser DAC
• Riya: USB laser DAC with multiple output channels
• LaserDock/LaserCube: USB connectivity options

ILDA Standard

• ILDA Test Patterns: Support for standard ILDA test patterns and protocols

Note: Only EtherDream DAC has been tested with BeamCommander. Other DACs are supported by the underlying ofxLaser framework but may require additional setup. BeamCommander automatically detects connected hardware during the initial laser setup process.

Control Methods

Web Browser (Open Stage Control)

• Access the touch-friendly web interface from any device on your network
• Control laser shapes, colors, movement patterns, and effects
• Perfect for performance control and remote operation

MIDI Controller (Akai APC40)

• Physical knobs and buttons for tactile control
• Pre-mapped controls for laser brightness, position, colors, and effects
• Momentary buttons for instant cue triggering
• See OSC API Reference section below for complete command details

Desktop Application

• Direct laser output configuration
• Zone setup and perspective correction
• Advanced mask management
• Preset system for different venues/setups

Features

• Multi-Laser Support: Control multiple laser outputs simultaneously
• Real-time OSC Control: Low-latency command processing
• Shape Generation: Lines, circles, triangles, squares, wave patterns
• Color Systems: Static colors, RGB control, rainbow effects
• Movement Patterns: Pan, tilt, circular, figure-8, random movement
• Visual Effects: Dotted patterns, brightness control, rotation
• Cue System: Pre-programmed sequences and momentary triggers
• Zone Mapping: Perspective correction and output transformation

OSC API Reference

BeamCommander listens for OSC commands on UDP port 9000. All commands support real-time control for live performance applications.

Core Laser Controls

Shape Generation

• /laser/shape <string> - Set laser shape
  • Values: line | circle | triangle | square | wave | staticwave

Color Control

• /laser/color <string|rgb> - Set laser color
  • Named colors: "blue" | "red" | "green" (disables custom RGB)
  • RGB values: r g b as floats [0..1] or bytes [0..255] (enables custom)
  • Note: Selecting static colors disables rainbow automation

Brightness & Visual Effects

• /laser/brightness <float|int> - Master brightness [0..1] or [0..255]
  • Alias: /laser/master/brightness
• /laser/dotted <float|int> - Dot pattern intensity [0..1] or [0..255]
  • 0 = no dots (invisible), 1 = solid line
• /laser/flicker <hz> - Visual flicker rate (gates brightness at 50% duty)
  • 0 = disabled, >0 = flicker frequency in Hz
  • Alias: /laser/scanrate <hz>

Positioning & Scaling

• /laser/position <x> <y> - Set laser position (both [-1..+1])
  • Individual: /laser/position/x <x>, /laser/position/y <y>
• /laser/shape/scale <float> - Shape scale factor [-1..+1]
• /laser/rotation/speed <float> - Rotation speed in rotations/sec
  • Negative = reverse, 0 = static

Wave Pattern Controls

• /laser/wave/frequency <float> - Wave cycles across width (min 0.1)
• /laser/wave/amplitude <float> - Wave height [0..1] as fraction of half-height
• /laser/wave/speed <float> - Wave phase rotation speed (rotations/sec)

Rainbow Effects

• /laser/rainbow/amount <float> - Spatial color distribution [0..1]
  • 0 = many cycles (short segments), 1 = whole shape one color
• /laser/rainbow/speed <float> - Rainbow animation speed [-1..+1]
  • 0 = stopped, positive = forward, negative = reverse
• /laser/rainbow/blend <float> - Color transition smoothness [0..1]
  • 0 = hard steps, 1 = smooth gradient

Movement Patterns

• /move/mode <string> - Set movement pattern
  • Values: none|off | circle | pan | tilt | eight|figure8|8 | random
• /move/size <float|int> - Movement amplitude [0..1] or [0..255]
  • 0 = no movement, 1 = full canvas range
• /move/speed <float> - Movement speed in cycles/sec
  • Negative = reverse direction

Flash Controls

• /flash <int> - Flash button control
  • 1 = press (force full brightness), 0 = release
• /flash/release_ms <int> - Flash release fade time [0..60000] milliseconds
  • 0 = instant return, >0 = fade to previous brightness over time

Cue System

• /cue/save - Arm cue saving mode (next /cue/<n> will save)
• /cue/<n> - Save or recall cue slot (n = 1..16)
  • If save armed: Store current state to slot n
  • If save not armed: Recall cue from slot n

Cue Parameters

Saved with cues: shape, color (named/RGB), movement, wave settings, rainbow effects, rotation, scale, position, dotted amount, flicker rate

Not saved with cues: master brightness, flash settings, flash button state

Usage Examples

# Set blue circle with medium brightness
/laser/shape circle
/laser/color blue  
/laser/brightness 0.5

# Create moving rainbow wave
/laser/shape wave
/laser/wave/frequency 2.0
/laser/rainbow/amount 0.8
/laser/rainbow/speed 0.5
/move/mode circle
/move/size 0.6
/move/speed 1.2

# Flash effect with 2-second fade
/flash/release_ms 2000
/flash 1
# ... (later)
/flash 0

# Save current state as cue 5
/cue/save
/cue/5

MIDI Controller Reference (Akai APC40)

Complete AKAI APC40 MK2 controller mapping for BeamCommander - showing all knobs, buttons, and their corresponding laser control functions

The Akai APC40 provides tactile hardware control over BeamCommander's laser parameters. All MIDI controls are mapped to corresponding OSC commands for seamless integration.

Setup Instructions

1. Connect the Controller: Plug your AKAI APC40 MK2 into your Mac via USB
2. Launch BeamCommander: The application will automatically detect and connect to the MIDI controller
3. Verify Connection: LED lights on the controller should illuminate, indicating active connection
4. Start Controlling: All knobs and buttons are immediat