# Wave Studio for macOS

## Startup and sequence follow

The latest browser studio opens with six evenly spaced fixtures, all selected.
Odd-numbered fixtures F01, F03 and F05 are inverted; even-numbered fixtures
are not. Its initial view is 100%; Fit view restores 55% for more flame headroom.
Saved layouts retain their own fixture counts and settings when loaded.
Previously downloaded Mac packages are not rebuilt by website updates.

A fresh launch starts at sequence 001 with playback and Auto-next on, advancing
through the catalog and wrapping from 088 to 001. Pause stops progression; turn
off Auto-next to stay on one sequence. Loading a saved layout still starts paused.

The library follows the active fixture's current sequence, scrolling only when
the newly active row is outside the visible list. Selecting a visible sequence
keeps the list in place. Search, family filters and Favorites remain respected;
use the unfiltered All sequences tab to follow the full catalog. Selected stage
fixtures retain their outline without a checkmark badge.

This Mac source package includes the current Wave Studio visualizer and receive-only sACN / Art-Net receiver. It contains multiple draggable fixtures, individual Invert and min/max angle settings, Copy angle limits to all, saved layouts and the 50–200% visual flame scale.

This is a prototype for visual rehearsal, not a firing controller, certified device emulator or safety-validation tool. Keep real flame hardware disconnected from the rehearsal network: Vista can still transmit to physical equipment even though Wave Studio does not send firing commands.

## Requirements and testing status

- **Runtime:** Python 3.10 or newer, with no additional pip packages. Install a currently supported stable release from [Python's macOS download page](https://www.python.org/downloads/macos/). Python.org's universal2 installers run natively on supported Intel and Apple Silicon Macs; check the installer's supported macOS versions ([Python macOS documentation](https://docs.python.org/3/using/mac.html)).
- **Browser:** Use a current Chrome, Edge or Safari. Chrome rendering was tested in a Linux environment; Safari and macOS browser behavior still need native testing.
- **Vista:** Required only for live controller input, with the necessary Vista output licensing. Check your Vista build's requirements; the current vendor FAQ lists macOS Monterey 12 through Tahoe 26 and Apple Silicon through Rosetta ([Vista FAQ](https://www.vistabychromaq.com/vista-by-chroma-q-faqs/)).
- **Package status:** Readable Python and shell source, not a signed/notarized `.app`, DMG or self-contained runtime. No Windows EXE is included.
- **Verification boundary:** Launcher logic, archive contents, browser UI and actual synthetic multicast reception can be tested outside macOS. Finder launch, Gatekeeper, macOS multicast loopback, Safari and native Vista interoperability have not been verified on a Mac. A successful first rehearsal on your machine is still required.

## Manual preview without installing Python

Extract the ZIP and open **Wave Studio Preview.html** in a current browser. It includes all artwork and code, uses system fonts, and does not need a receiver or an internet connection for manual playback. External documentation links need internet access.

For live Vista input, use the launcher instead of this standalone file.

## First live launch

1. Extract the complete ZIP into a normal folder, for example `Documents/Wave Studio macOS`. Keep every included file together.
2. Install Python if needed, then double-click **Start Wave Studio.command**. This opens a Terminal launcher; it is not an application installer.
3. **Terminal shows a numbered menu**: 1 preview, 2 sACN from Vista 3 (default — press Return), 3 Art-Net from Vista 3, 4 sACN from grandMA3, 5 sACN from grandMA2, 6 Art-Net from a grandMA, 7 sACN from another console. The choice sets the console preset (hints, status text and the tab the studio's Vista & MA Receiver dialog opens on); the receiver reads E1.31 Final and grandMA2 Draft packets, multicast or unicast. Select the local IPv4 interface matching Vista's network. The launcher lists interface names and IPv4 addresses rather than assuming that `en0` is your adapter. It cannot read Vista's adapter setting automatically, so an empty response will not guess a default route.
4. Universes **1,2,3,4** are preconfigured; no universe prompt is needed. For custom subscriptions, launch with `--universes 1,2,5`. The receiver supports up to 16 one-based sACN universes in the range 1–32768.
5. Keep Terminal open. The receiver opens the local app at `http://127.0.0.1:8765`. If it does not open automatically, type that address into your browser.
6. Stop the receiver with **Control+C** in its Terminal window before launching another copy. Do not run Art-Net and sACN receivers at the same time.

The launch script searches common Python.org and Homebrew locations. It deliberately avoids Apple's `/usr/bin/python3` developer-tools stub and does not install developer tools, download code or change security settings.

## Vista on the same Mac

Use a rehearsal copy of the show with real flame hardware disconnected. This package listens for sACN on UDP 5568 and leaves Art-Net UDP 6454 untouched.

1. In Vista's network settings, select the local adapter/IP you selected in Wave Studio.
2. In **Connect Universes**, add a **Streaming ACN / sACN** output. Start with universe **1**, priority **100**, assign your intended Vista universe and enable output. This multicast output workflow is described in the [Vista user guide](https://www.stars-europe.com/pdf/produits/LECONSOLE4+.pdf); wording can vary by Vista release.
3. Do not wait for Wave Studio to appear as an Art-Net node while using sACN.
4. On the local Wave Studio page, click **Live sACN**, then match each fixture's displayed universe and starting address to Vista. The model uses six channels per fixture, so addresses 1 and 7 are examples for two units.
5. Verify that the packet counter and channel monitor respond before rehearsing visual effects. Existing virtual arming, trigger reset and input-loss rules remain unchanged.

On macOS, local multicast delivery depends on the sender, selected interface and OS permissions. If same-Mac delivery fails, the package also supports receiving from Vista on a separate Windows PC or Mac on the same trusted network. That is an alternative topology, not a guaranteed fix for an unverified network.

## Vista on a separate computer

For sACN, choose **this Mac's local receiving IP** in the launcher, not the sending computer's IP. Both adapters must be on a network that permits the multicast traffic; subscribe to the universe Vista is sending.

For Art-Net, explicitly launch `python3 mac_launcher.py --mode artnet`, or use `--menu` and choose option **3**. This enables ArtPollReply discovery on UDP 6454 and defaults to zero-based port-addresses 0–3. Only discovery replies are sent; it never sends ArtDmx or firing commands. Do not use this mode when another program already owns UDP 6454 on the Mac.

## Settings, layouts and safety boundaries

Save your stage with **Save layout** before closing. Open the saved JSON through **Load layout** on Mac or Windows; current version-4 layouts preserve fixture positions, preset choices, Invert, per-fixture angle limits and patches. Older version-1–3 layouts load with full angle limits. Visual flame scale is not stored in a layout.

Angle limits are a rendering convention, not a verified firmware emulator: limits stay fixed after Invert, the visual head is clamped to them, and out-of-range flame is suppressed without retiming the preset. These settings never configure or protect a physical device.

The model supports standard Explo six-channel DMX512 with CH5 “new”: angle, speed, trigger, opening time, program, mode. It is not Easy DMX, legacy CH5 or Pyroemotions. See the [Explo manual](https://explo.at/wp-content/uploads/2025/06/X2-Wave-Flamer-v2.0-ENG-2.pdf) and [sequence value sheet](https://explo.at/wp-content/uploads/2025/06/X2-Wave-Flame-Sequences-DMX-Values.pdf).

## Troubleshooting

- **Python not found:** Install Python from the official download page, then relaunch. The guide and standalone preview remain available without Python.
- **macOS security warning:** This source package is not signed/notarized. Do not disable Gatekeeper or remove quarantine attributes. Review the files and follow your organization's policy and [Apple's guidance on safely opening software](https://support.apple.com/en-us/102445). If macOS reports malware or that the software will damage your computer, stop rather than override the warning.
- **No permission to execute:** If the issue is specifically a missing Unix executable bit after extraction, and you have reviewed the script, run `chmod u+x ` in Terminal followed by dragging **Start Wave Studio.command** into the window, then press Return. This changes only the file's executable permission; it does not resolve or bypass a security warning.
- **Local-network or firewall prompt:** Review and allow only the appropriate Python process on your trusted rehearsal network if permitted by your policy. Do not disable system protections. Native macOS permission behavior has not been tested here.
- **Address already in use:** Stop the previous receiver or the conflicting application. The receiver intentionally does not steal or share occupied UDP ports.
- **Packets remain at zero:** Check Vista output, chosen adapter, subscribed universe, OS permissions and network multicast delivery. Stop other sACN monitor tools that may occupy UDP 5568.
- **Packets arrive but no virtual flame:** Check the six-channel patch and the virtual arming/trigger state. The monitor explains receiver state; angle limits can also suppress out-of-range emission.
- **Lost input:** The receiver clears stale effects after 2.5 seconds. After reconnecting, reset the trigger low before raising it again.

## Advanced launch

From inside the extracted folder, with a working `python3`:

```sh
python3 mac_launcher.py --mode sacn --interface YOUR_MAC_LOCAL_IPV4 --universes 1,2
python3 mac_launcher.py --mode artnet --universes 0,1
python3 mac_launcher.py --mode preview
python3 mac_launcher.py --menu
```

Replace `YOUR_MAC_LOCAL_IPV4` with a real local IPv4 address. `--port` changes the loopback web port; `--no-browser` leaves browser opening to you. Close the receiver before switching modes. No administrator privileges are needed to run the receiver.