Docs — troubleshooting

Troubleshooting

When something won't connect at a venue, it's almost always the network. Here are the fixes, in the order you hit them while setting up.

Phone can't reach the Mac after scanning the QR

• They're on different networks. The phone is on mobile data or another Wi-Fi. Put both devices on the same Wi-Fi, and turn mobile data off while pairing if the phone keeps switching.
• It's a guest network. Venue guest Wi-Fi routinely blocks devices from talking to each other — everything looks connected, nothing works. Use the venue's production network, or bring your own travel router.
• The Mac's firewall is blocking it. If the macOS firewall is set to block all incoming connections, cameras can't reach . In System Settings → Network → Firewall, allow incoming connections for .

Nothing connects after the Local Network prompt

macOS 15 and later asks whether may use the local network. If it was denied, phones cannot connect and nothing in the app can undo that. Open System Settings → Privacy & Security → Local Network, switch STAGEVIS on, then quit and reopen the app. Camera and Microphone are in the same place if you denied those.

The phone browser says the connection is not private

Expected: it appears the first time each phone opens this Mac's camera page, and again after the Mac's network address changes (another venue or router) or the phone's browser data is cleared. Browsers only allow camera access on secure pages, and the Mac serves the camera page with its own certificate. Safari: Show Details → visit this website → Visit Website. Chrome: Advanced → Proceed. If the page never loads, the phone is not on the Mac's network or port 8443 is blocked (see the ports table below).

The QR points at the wrong network (Ethernet, Wi-Fi, VPN)

The pairing QR carries one address for the Mac: the interface that carries the Mac's default route (otherwise the first of en0, en1, en2…), skipping VPN addresses (Tailscale and similar) and 169.254.x.x. A Mac on Ethernet and Wi-Fi at once, or with a VPN up, can put an address on the QR that the phones cannot reach. Open Settings → Network interface and pick the interface the phones are on (the default is Automatic); the QR and the web certificate follow immediately. Or turn off the other interface (or the VPN) while you pair, then reopen the pairing card. If the Mac is wired, put the phones on a Wi-Fi that bridges to that same wired network.

The network changed (new Wi-Fi, wake from sleep, IP changed)

When the Mac's network address or Bonjour name changes, refreshes the pairing codes and rebuilds the web camera certificate for the new address on its own. A small Rescan chip appears next to the code: scan the QR again on each phone, because the old code points at the old address. With no usable Wi-Fi or Ethernet connection the card shows No network instead of a code. If port 8443 is taken by another program, the dot turns red and retries by itself; Copy Diagnostics shows the reason.

Phone says the Mac certificate changed

The Android camera shows “Mac certificate changed - re-scan the QR” and stops retrying. The phone pins the Mac's TLS public key from the QR, and the Mac now presents a different one. This happens only if 's certificate key was deleted or corrupted (for example Application Support/StageVis/WebCamera/ was wiped), or the phone was paired with an older QR that pinned the whole certificate. An ordinary IP or Wi-Fi change keeps the key, so phones paired with a current QR reconnect on their own. Fix: tap Re-pair on the phone and scan the QR in again.

Android camera app

These notes are for phones running the STAGEVIS Camera app (the direct APK download, not the browser page). The app is not on Google Play.

• The notification.Android 13 and newer asks for permission to show notifications. Allow it. While the camera is paired, the app keeps a persistent “STAGEVIS Camera” notification (its second line is the connection status) because that is what lets Android keep the camera running with the screen off or the app in the background. If you refuse the permission the stream can still run, but Android may stop it sooner.
• Swipe-away stops the stream.Removing the app from the recent apps list means “I'm done streaming”: the stream and the notification stop. Reopen the app to go live again; it reconnects without a new scan.
• Battery optimisation and screen-off.While paired, the app holds a Wi-Fi lock and a wake lock so the stream survives the screen turning off. Some phones still stop background apps. If the status shows “Battery optimisation may stop the stream - tap to allow”, tap it and allow the app to ignore battery optimisation. Phones from some makers also have their own task killer or “app sleeping” list (Samsung, Xiaomi, Huawei, OnePlus and others); exclude STAGEVIS Camera there too. Plug the phone into a charger for a show.
• The phone gets hot and the picture gets smaller.When Android reports a severe thermal state, the app caps capture at 24 fps; at a critical state it also limits the long edge to 960 pixels. The cap lifts on its own after the phone has been cooler for about two minutes. Shade the phone, take it out of its case or put it on a charger that doesn't heat it.
• “Refused by the Mac: free-tier camera limit”.The free tier allows two cameras. Enter a license on the Mac (Help menu, Enter License...) or forget another camera, then reopen the app.
• “Update available: STAGEVIS Camera x.y.z”.The Mac is newer than the app. The hint appears in About / licenses. Install the new APK from stagevis.app/download/StageVisCamera.apk over the old one. A phone running an APK from before 0.9.1 cannot reach a Mac that has been updated to 0.9.1 or later; install the new APK, then re-pair (scan the Native QR again).
• “This code has expired”.The QR rotates about every 15 minutes. Show the current Native QR on the Mac and scan it again. If you opened a stagevis://pair link from another app and it fails, you get a dialog with the same advice; a link that is not a STAGEVIS pairing link says so.
• Re-pair.Tap Re-pair on the streaming screen and confirm. That clears the saved pairing and returns to the scanner. Use it after “Mac certificate changed”, after the Mac was reinstalled, or when the phone was forgotten.
• Guest Wi-Fi: 5 GHz and AP isolation.The phone and the Mac must be on the same network, and the venue Wi-Fi must not isolate clients (see “Phone can't reach the Mac after scanning the QR” above). Prefer 5 GHz for video, but make sure the Mac is on the same network; a 5 GHz network that is a separate segment from the Mac's Ethernet will not connect.
• Share diagnostics.In the app, open About / licenses and tap Share diagnostics. Android's share sheet opens with a text report (app and Android version, device model, connection status and the last crash, if any). Nothing is uploaded; you choose where it goes, for example an email to hello@stagevis.app. If the app crashed, the crash is stored on the phone only until you share it.

Too many cameras for the Wi-Fi

A browser phone on the default Balanced quality sends up to about 2.5 Mbps of video, so four phones need roughly 10 Mbps of upload from the Wi-Fi, in a room where the audience shares it. The Android app and a phone set to Native quality have no such ceiling. If rows stutter or drop, put phones on Balanced, use USB or the Mac's own camera for fixed shots (wired, no Wi-Fi), or run the show on its own router. On the free tier a third live camera is refused outright (“Camera limit — enter a license to go beyond 2”).

The phone page says “This QR code has changed” or “The operator removed this camera”

• This QR code has changed. Scan the one on the Mac now. The phone scanned a QR that has since changed. If it opened the bare address with no code, it says “Scan the QR code shown on the Mac to join.” instead. The web QR carries a join secret that is rotated about every 15 minutes, on relaunch and network changes, when an Android phone joins, and whenever you Forget a camera (guests who have not joined yet scan the new code; a guest who already joined keeps their camera). Camera access tokens last about 15 minutes and the phone renews them itself. Scan the code the Mac shows now: the preview shows it while no camera is on the program, otherwise open the pairing card (Cameras card → pair a camera). A phone that already joined doesn't need the QR again; clearing its browser data makes it a new guest that does.
• The operator removed this camera. Someone chose Forget Camera… on it. Right-click the blocked camera in the Cameras card and choose Re-admit, then tap Go live again on the phone.

QR scans but pairing errors or expires

The pairing QR (Android and Web) refreshes itself every few minutes. If the phone says the code is expired or invalid, scan again: the pairing card always shows the current one. If pairing fails on a Wi-Fi blip, scan the same code again.

Phone shows connected but the camera row says NO FRAMES

The phone joined but isn't sending video — almost always camera permission denied on the phone, or the camera app sitting in the background. Check the phone's camera permission, bring the app to the front, and keep the screen on while streaming.

Everything is black in the preview

• No camera is live — pair one, or turn on Demo Mode (the play-screen button on the Cameras card).
• The BLACK button in the header is lit red — click it to release.
• FREEZE (also in the header) is holding an old frame — click it to release.

Local LiveKit server keeps failing

restarts its built-in media server by itself, waiting a little longer each time. If it keeps failing, the app stops retrying and shows a Retry chip in the top bar of the main window and in Settings → LOCAL SERVER — usually the cause is another program occupying the same network port. Quit the other program (or reboot the Mac), then click Retry. The message reads “Port 7880 is used by another program”: run lsof -nP -iTCP:7880 -sTCP:LISTEN in Terminal to see which one. STAGEVIS only adopts a listener that identifies itself as livekit-server and accepts this install's key.

An orange dot appears in the preview's top bar

The orange dot is the persistence-health indicator: one of STAGEVIS's saved files (settings, paired cameras, presets) could not be read or written, so changes may not survive a relaunch. Hover the dot for the first problem; Settings → DIAGNOSTICS lists every persistence issue with its file name. A corrupt file is set aside and the app starts from defaults; a file written by a newer version is left untouched. Free disk space or fix folder permissions, then relaunch; if the dot stays, export a Support Bundle (see below).

Contact support

In the app: Help → Contact Support… opens an email to hello@stagevis.app with the app version and build in the subject. Then choose Help → Export Support Bundle…: it writes a zip (diagnostics report, the last 2000 lines of the server log, STAGEVIS crash logs, macOS crash reports of the last 30 days in macos-reports/, the last saved diagnostics snapshots in snapshots/ and the app event timeline in app-events-tail.log) and reveals it in Finder. Attach the zip to the email; nothing is sent automatically. After a crash or stall STAGEVIS also offers Send Report… (never during a live show); it builds the same bundle and opens an email, or copies the address when no mail app is set up.

Redacted automatically: hostnames, the names of web-guest cameras, your home folder path, public IP addresses, secrets, tokens and the per-Mac identifiers in crash reports. Not redacted: names of your own USB, RTSP and Android cameras, local network addresses (192.168.x.x and similar), app and macOS versions, and timestamps. Please do not attach the raw server log; the bundle already contains a redacted copy. If the export fails, Settings (DIAGNOSTICS) shows the reason; Help → Copy Diagnostics is the fallback.

Updates never interrupt a live show; install them afterwards from the Help menu or Settings. STAGEVIS must run from Applications, or updates can’t install. Versions and build dates: https://stagevis.app/releases/.

The wall stutters or the Mac gets hot

The output on the wall judders, lags the cameras, or the Mac's fans spin up hard (a MacBook Air has no fan and slows itself down when it gets hot).

• Read the header. The FPS dot is the render rate of the wall. Hover it for the render FPS, draw time, current render Scale, CPU and RAM load and the camera receive rate. Scale is the internal resolution the looks are rendered at: in Auto (the default) the app steps it down by itself when the Mac falls behind and back up when there is headroom; the lowest automatic step is 50%. On a base Mac (8 GB, or a plain M1/M2) Auto starts at 75%. Help → Copy Diagnostics has a Power: line (battery or AC, Low Power Mode, thermal state).
• Plug in the power adapter. A Mac on battery can be throttled, and the battery will not last a show.
• Turn Low Power Mode off (System Settings → Battery); it caps the Mac's performance.
• Use fewer live cameras. Every live camera is decoded and drawn all the time. Wired USB and the Mac's own camera save Wi-Fi, not CPU.
• Use lighter looks: fewer stacked Filters and Effects, and no heavy simulations on the program while the Mac is struggling. Effects that detect people or faces run at most 30 times a second.
• Force the Scale in Settings → RENDER SCALE: 75 or 50 instead of Auto. A forced Scale is never changed by Auto.
• Switch recording cameras off. Each camera recording is encoded while you play; output recording is limited to 30 frames a second.
• Give the Mac air. Hard surface, out of the sun, not under a stage light, nothing on the vents. A fanless MacBook Air cools only through its case.

The stage output is composed at the camera's resolution (720p or 1080p) and upscaled to the display, so a 4K wall shows an upscaled picture. How many cameras a given Mac carries has not been measured on every model yet: run the look you plan to use for five minutes at the venue before doors.

Wi-Fi says “no internet” on the phone

Phones often drop a Wi-Fi network that has no internet (a travel router with nothing plugged into it) and fall back to mobile data, which breaks the camera link. Stay connected when the phone asks, and turn mobile data off for the show. If the phone asks whether to stay on this network because it has no internet, say yes (on Android: Stay connected). The camera page and the video only need the Mac on the same Wi-Fi, not the internet.

Ports (for firewall rules / managed networks)

On a managed network, these ports need to be open between the Mac and the phones:

If UDP 7882 is blocked, video falls back to TCP with higher latency; if both are blocked, there is no video. Browser phones need 8443 plus 7881/7882. Port 7880 is bound to the Mac's loopback address only and is never reachable from the network.

UDP blocked (some venue and hotel networks): video then travels over TCP 7881. It still works, but expect more delay and more stutter with several cameras, and nothing at all if 7881 is blocked too. Ask the network tech to open UDP 7882 and TCP 7881 and 8443 between the Mac and the phones, or run the show on your own router, and test it at the venue before doors.

mDNS / hostname discovery fails

The pairing payload prefers the Mac's .local hostname; some networks drop mDNS between clients, so pairing works only sometimes. There is nothing to configure: the QR also carries the LAN address as a fallback. If it still fails, the network is isolating clients (see the guest network entry at the top).

· hello@stagevis.app · stagevis.app