Documentation

Complete guide to using and controlling BeamCommander.

Quick Start

1. Install BeamCommander for macOS
2. Launch the application
3. Configure your laser hardware (EtherDream, Helios, etc.)
4. Set up output zones
5. Start sending OSC commands or connect MIDI controller

OSC API Reference

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

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"
• RGB values: r g b as floats [0..1] or bytes [0..255]

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 = invisible, 1 = solid line

/laser/flicker <hz>

Visual flicker rate. 0 = disabled, >0 = flicker frequency in Hz. Alias: /laser/scanrate

Positioning & Scaling

/laser/position <x> <y>

Set laser position. Both values [-1..+1]. Individual: /laser/position/x, /laser/position/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, 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 (full brightness), 0 = release

/flash/release_ms <int>

Flash release fade time [0..60000] milliseconds. 0 = instant return

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. Otherwise: recall cue.

Saved Parameters

• Shape, color (named/RGB)
• Movement patterns and settings
• Wave parameters
• Rainbow effects
• Rotation, scale, position
• Dotted amount, flicker rate

Not Saved

• Master brightness
• Flash settings and button state

MIDI Controller Reference (Akai APC40)

Complete hardware control mapping for Akai APC40 MK2.

Setup

1. Connect Akai APC40 MK2 via USB
2. Launch BeamCommander
3. Controller is automatically detected
4. LED lights confirm active connection

Knobs (Continuous Controllers)

Top Row - Shape & Color Controls

• Knob 1: Master brightness [0..1]
• Knob 2: Shape scale [-1..+1]
• Knob 3: Rotation speed (rotations/sec)
• Knob 4: Horizontal position [-1..+1]
• Knob 5: Vertical position [-1..+1]
• Knob 6: Dot pattern intensity [0..1]
• Knob 7: Visual flicker rate (Hz)
• Knob 8: RGB color mixing

Bottom Row - Wave & Movement Controls

• Knob 9: Wave frequency
• Knob 10: Wave amplitude [0..1]
• Knob 11: Wave phase rotation speed
• Knob 12: Movement amplitude [0..1]
• Knob 13: Movement speed (cycles/sec)
• Knob 14: Rainbow spatial distribution

Grid Buttons

The 8x5 grid provides 16 cue memory slots (using bottom 4 rows, first 4 columns):

• Press: Recall saved cue
• Save Mode: Hold designated save button, then press slot to save

Side Buttons

• Shape Selection: Trigger different shape types
• Movement Patterns: Activate movement modes
• Effect Toggles: Enable/disable visual effects

Examples

Example 1: Blue Circle with Medium Brightness

/laser/shape circle
/laser/color blue
/laser/brightness 0.5

Example 2: 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

Example 3: Flash Effect with Fade

/flash/release_ms 2000
/flash 1
# ... wait ...
/flash 0

Example 4: Save and Recall Cue

# Set up your desired look
/laser/shape triangle
/laser/color red
/move/mode figure8

# Save as cue 5
/cue/save
/cue/5

# Later: recall cue 5
/cue/5

Troubleshooting

No Laser Output

• Verify DAC hardware is connected and powered
• Check laser safety interlock is closed
• Ensure laser projector is powered on
• Verify zone configuration in BeamCommander
• Check brightness is not at 0

MIDI Controller Not Detected

• Reconnect USB cable
• Restart BeamCommander
• Check MIDI device appears in macOS Audio MIDI Setup
• Try a different USB port

OSC Commands Not Working

• Verify sending to localhost:9000
• Check firewall settings allow UDP port 9000
• Confirm OSC message format matches documentation
• Use OSC debugging tool to verify messages are sent

Performance Tips

• Use MIDI controller for tactile, real-time control
• Pre-program cues for complex sequences
• Test your setup before live performance
• Keep spare cables and USB connections
• Monitor CPU usage for complex patterns

Safety

• Never point lasers at people, aircraft, or vehicles
• Follow local laser safety regulations
• Use appropriate safety equipment
• Ensure audience safety at all times
• Have emergency stop procedures in place