# KeyBeam Studio User Manual

Version: 1.2 (current)
Audience: Installers, AV techs, bar/venue owners, mobile DJs, and professional AV teams running laser fixtures during live shows.

## What This App Is For

KeyBeam Studio gives you fast, live control over up to 4 compatible laser fixtures on one Art-Net universe.

This manual is written so both technical and non-technical operators can use it:
- Installers can use it for setup validation and handoff.
- AV techs can use it for daily operation and troubleshooting.
- Bar/venue owners can use it as a practical checklist for staff.
- Professional AV teams can use it for repeatable show workflow and reliability checks.

You can:
- Run a show live from one screen
- Save looks as cues
- Trigger cues from MIDI hardware
- Build timed playlists for hands-off playback
- Clone/link fixtures for quick setup

## Before You Start

## Safety First (Important)

- Never aim lasers into audience eye level.
- Follow venue and local laser safety rules.
- Test blackout and panic controls before doors open.
- Keep one physical emergency kill option available.

## System Checklist

- Fixtures addressed correctly (16CH or 20CH profile)
- Network connected to fixture subnet
- Art-Net target IP and universe confirmed
- MIDI controller connected (if used)

## Install and Launch

Double-click KeyBeam Studio.exe to launch the app.

After launch, confirm your output settings and run a quick fixture response test before showtime.

## First 5-Minute Setup

1. Open Settings / Output.
2. Set Target IP, Universe, Fixture Profile, and FPS.
3. Click Connect Output (or press F5).
4. Arm output.
5. Verify movement/color response on a single fixture.
6. Save Main Config.

Screenshot:
![Settings and Output Setup](docs/screenshots/01-settings-output.png)

## Main Screen Tour

The interface is built for show speed.

- Fixture tabs: Control Fixture 1 to Fixture 4
- Live controls: Pattern, position, color, effects, speed
- Master controls: Grand Master, arm state, output status
- Monitor/status bar: Running state, target, packet/send info

Screenshot:
![Main Live View](docs/screenshots/02-main-live-view.png)

## Core Show Workflow

## Pre-Show (10 to 20 minutes)

1. Load your saved main config.
2. Confirm profile mode (16CH or 20CH).
3. Test blackout and recovery.
4. Build or load cue list.
5. Run a 2-minute stress test with movement and color changes.

## During Show

1. Keep output Armed only when actively controlling.
2. Use cues for repeatable looks.
3. Use Grand Master for fast intensity control.
4. Use panic blackout (Space) if needed.

## Post-Show

1. Disarm output.
2. Save Main Config.
3. Save session cues if changed.
4. Disconnect output.

## Building and Using Cues

## Save a Cue

1. Create your look on the fixture tabs.
2. Click Add Current To Cues.
3. Rename cue to a clear show name (example: Intro Sweep Blue).

## Fire a Cue

1. Open Cue Player / Playlist popout (or use cue controls in the main view).
2. Click the cue name to fire.
3. Confirm fixture response.

Screenshot:
![Cue Builder and Cue Window](docs/screenshots/03-cue-builder-window.png)

## Playlist Mode (Hands-Off Sections)

1. Open Cue Player / Playlist.
2. Add cues from Available Cues.
3. Set per-entry Time (ms) and/or Beats.
4. Select playlist mode (`ms`, `bpm`, or `sound`).
5. Start playlist for timed or audio-peak-triggered playback.
6. Save playlist changes to Main Config and/or Save Playlist As for a standalone playlist file.

In Sound mode, install optional audio packages (`numpy`, `sounddevice`) and verify an input device is available.

Screenshot:
![Playlist Editor](docs/screenshots/04-playlist-editor.png)

## MIDI Controller Setup (Simple)

## MIDI Learn

1. Enable Learn MIDI.
2. Click the on-screen target control.
3. Move/press the hardware control.
4. Save MIDI config profile.

## MIDI Best Practice for Smooth Control

- Use Relative mode for endless knobs.
- Keep knob scale moderate first, then fine-tune.
- Test one bank before mapping full controller.

Screenshot:
![MIDI Mapping Screen](docs/screenshots/05-midi-mapping.png)

## Fixture Config (Link and Clone)

## Link Fixtures

Use when Fixture B should follow Fixture A in real time.

## Copy Once

Use when you want a one-time match, then independent control.

## Clone Cue Data

Use when cue snapshots should update with fixture clone operations.

Screenshot:
![Fixture Config (Link and Clone)](docs/screenshots/06-link-clone.png)

## Hotkeys You Should Memorize

- Space: Panic blackout
- A: Arm/Disarm output
- F5: Connect output
- F6: Disconnect output

## Diagnostics (When Something Feels Off)

Open Settings > Diagnostics and watch:
- Output state
- Configured FPS and effective FPS
- Loop jitter
- MIDI queue and dropped count
- Send errors
- Last send status / last send error
- Active file paths (main config, cues, MIDI config, playlist)

If dropped MIDI rises quickly, reduce controller traffic and simplify mappings.

Screenshot:
![Diagnostics Tab](docs/screenshots/07-diagnostics.png)

## Quick Troubleshooting

## No Light Output

1. Check Armed state.
2. Confirm output is connected.
3. Verify Target IP and Universe.
4. Confirm fixture mode/address (16CH or 20CH).

## MIDI Not Responding

1. Confirm controller is connected before app launch.
2. Re-open MIDI settings and verify mapped profile.
3. Re-run MIDI Learn for one test control.

## App Says Already Running

On Windows, a single-instance safety lock is enabled. If opened twice, the first app window is brought to front.

## File Locations (Where Your Data Is Saved)

Runtime data is saved in your Documents folder under `Keybeam`:

- `defaults/main_config_default.json`
- `config/j5_main_config.json`
- `config/j5_session_cues.json`
- `config/j5_playlist.json`
- `midi/midi_config_<profile>.json`

Use Diagnostics to confirm exact active file paths during a show.

## Licensing and Trial

- License and renewal are managed from the License Manager window.
- A 3-day trial is available on supported systems.
- Online verification is required periodically; cached validation supports short offline operation.

## Recommended Show Routine

- Keep one stable "base show" config file.
- Build separate cue sets per event type.
- Test panic and blackout every setup.
- Save after major changes, not every tiny tweak.

## Appendix: Operator Terms

- Arm: Allows live output transmission
- Cue: Saved snapshot of fixture settings
- Universe: Art-Net DMX universe number
- Grand Master: Overall intensity control
- Relative knob: Endless encoder that sends direction/step values

---

Need printable/PDF version?
Use your Markdown viewer export or print this file as PDF for booth binders.