🆘 When things break (troubleshooting)

"Wait, it's not working?" — look it up by symptom 🆘 Details link to each chapter.

⬛ Black screen / nothing shows

• First, reload the page (the initial load sometimes fails)
• You denied the mic permission at first 👉 VJam can keep running in No Mic mode. For how to allow the mic again, see You denied the mic by mistake
• An old browser or power-saving mode can disable WebGL 👉 try the latest Chrome
• Turn off extensions (ad blockers, etc.) for a moment

🔇 Not reacting to sound

• Visuals move but nothing reacts / sound's playing but no reaction 👉 the mic isn't coming in, or the input source is off. Check the mic permission → reload. If it's an audio file, is [AUDIO] set to playing? (→ 🔊 Audio input chapter)
• You can't find where to allow the mic again 👉 check the 🔒 / mic icon in the address bar, Chrome Site settings, or Safari's aA / Website Settings on iPhone. If you're in an in-app browser, reopen VJam in Safari / Chrome
• Only one kind of sound seems missing 👉 you cannot tell from the look alone which band a preset uses. First switch to a preset with a strong obvious reaction to confirm input is working. If you're on mic, do a quiet-place voice check 🎤

🚫 Buttons / taps do nothing

• Tap / click the screen once first (sound needs a user interaction to start)
• Audio-file actions only work after you've loaded a file

📂 Can't load / drop a file

• Check the format (image = PNG/JPG/GIF, video = MP4, audio = MP3/WAV)
• On mobile, don't drag & drop — pick from IMPORT / AUDIO
• If it won't work, reload the page and try again

📱 Not working on iPhone / Safari

• Sound not coming in / not playing 👉 iOS is strict. Tap the screen once before starting (autoplay block)
• If the Home Screen / PWA version feels unstable, open https://vjam.art directly in Safari (→ 📲 PWA / App install chapter)
• Still stuck 👉 try PC + Chrome / Edge. MIDI and external output are PC-oriented features

🐢 Heavy / stuttering

• Avoid heavy presets and text effects (the 3D ones)
• Close other heavy apps / tabs
• If streaming/recording, lower the resolution / FPS
• If the Cockpit FPS reads red (under 45), that's a warning 🚥

🔴 Can't record / no audio

• No audio 👉 recording with audio needs an audio file playing. On mic/demo it won't capture. Pick Silent or load an audio file (→ 🔴 Recording chapter)
• Not saving (mobile) 👉 tap the "save" link before you close it

🎹 MIDI won't connect

• Use Chrome / Edge (Safari often doesn't support WebMIDI)
• Reload / replug the USB / check that another app (a DAW) isn't holding the MIDI device (→ 🎹 MIDI chapter)

📺 External monitor / stream shows nothing

• Projector shows nothing 👉 check the cable / that your OS sees the monitor / that it's set to extend (→ 📺 Projector chapter)
• Black in the stream 👉 switch the OBS capture method (window → display capture). PROJ window capture is the most stable (→ 📡 Streaming chapter)

🔄 When in doubt

• Reload the page (hard reload) fixes a lot
• Still stuck? Try the latest Chrome

🔗 Related

• Audio, mic, and BPM → 🔊 Audio input
• Loading images / video / audio files → 🖼️ Images / 🎬 Video
• Recording saves and audio → 🔴 Recording
• External output / OBS → 📺 Projector / 📡 Streaming
• MIDI not responding → 🎹 MIDI
• Check ahead before a show → ✅ Pre-show checklist