Troubleshooting — the most common stumbling blocks.

Audio analysis supports MP3, WAV, FLAC, M4A (AAC) and OGG Vorbis. Other formats (WMA, AIFF, Opus in OGG containers) are not reliably detected.

• Check the file format. If needed, convert to MP3 / WAV with Audacity or fre:ac.
• For tracks stuck on "Analysis pending" in the library: right-click → "Restart analysis".
• For very short files (< 30 s) the BPM result is unreliable — the model needs enough bars to recognise a pattern.
• For ambient tracks without a clear beat you can set the BPM estimate by hand via the edit dialog (track drawer → pencil icon).

Dropouts are usually caused by an overloaded CPU, a too-small audio buffer or competing audio apps.

• Close other audio applications (Spotify, browser videos, DAWs). They tap into the same audio stack.
• Check CPU load in Task Manager (Ctrl+Shift+Esc). Continuously > 80 % → the machine is under load.
• In Hypnotika: raise Settings → Audio → Buffer size from 256 to 512 or 1024 samples. Larger buffer = more stable, minimal extra latency.
• Set the Windows power plan to "High performance" — on laptops in particular, "Balanced" throttles the CPU under load.
• Update the audio drivers (Realtek, Intel SST). Outdated drivers are a classic cause.

The symptom "library empty after app start" points to a hydration problem with the local database.

• Check the contents of %APPDATA%\Hypnotika\library.db. The file should be at least a few KB in size.
• If the file is missing or 0 bytes: Hypnotika doesn't have write access in the folder. Right-click the folder → Properties → Security → enable "Full control" for your user.
• If in doubt, launch the app once with admin rights — that creates the DB cleanly, afterwards a normal start is enough.
• Antivirus software may quarantine library.db. Add the path as an exception.
• Backup: back up the whole folder %APPDATA%\Hypnotika before larger experiments.

If the six hotkeys fall into the void, another application has usually already taken the same combination.

• Check that Settings → Stream Deck / macro controller → Global hotkeys is really enabled.
• Test the hotkeys on a normal keyboard (Ctrl+Alt+F1 to F6). Does the app respond? If yes, the issue is in the Stream Deck software configuration.
• Shortcut conflicts: graphics drivers (NVIDIA GeForce Experience, Intel Graphics Command Center) often claim Ctrl+Alt+F1–F4. Disable those hotkeys in the respective tool.
• Windows permissions: Hypnotika can't register global hotkeys if it runs without admin rights in a protected context. A one-time start as admin helps — afterwards the permission is set.
• USB issues: plug the Stream Deck into another USB port, restart the Elgato software.

• Windows microphone permission: Windows Settings → Privacy & Security → Microphone. Make sure "Allow apps to access your microphone" is on and "Desktop apps" too.
• Right device chosen? In Hypnotika check Settings → Microphone → Microphone device. Headset mics sometimes show up as two entries (Bluetooth HFP vs. HSP) — one of the two is the right one.
• Test system-wide: Windows Settings → System → Sound → Input. The input level should react when you speak into it. If it doesn't, the problem is at Windows level, not Hypnotika.
• Interface users: turn on phantom power (48 V) if using a condenser mic.
• For USB mics: try another port. Some USB hubs don't deliver enough power.

• Check whether recording is enabled in the settings — it may be deliberately off if an external tool (e.g. OBS) handles the recording. See audio setup.
• Recording folder: %USERPROFILE%\Documents\Hypnotika\Sessions or the path set in the settings. Explorer can hide hidden folders — enable "Show hidden items".
• Recordings only start if music was actually played. If you just previewed and didn't play, there's nothing to record.
• Disk full? The recording stops without an error message if less than 500 MB is free.

Hypnotika uses SoundTouchJS for pitch shift without tempo change. It's a CPU-friendly library, but hits its limits on extreme shifts.

• Recommended range: ±3 semitones. Up to ±5 semitones still acceptable. Above ±7, artefacts become clearly audible (phasing, metallic chirping).
• For heavily vocal tracks (choir, singing) the pitch limit is lower than for instrumental music. Vocal formants get warped.
• Alternative: pitch-shift the original audio in an external tool (Audacity, Adobe Audition) and import it as a new track. Better algorithms are available there (Élastique Pro, Rubber Band).
• For precise key adjustment: enter manual pitch values instead of the automatic Camelot Wheel correction.

• Windows SmartScreen may block the EXE. "More info" → "Run anyway".
• Antivirus (Windows Defender, Kaspersky, Norton) sometimes mistakes new, not-yet-widespread apps for malware. Add an exception for Hypnotika TranceDeck.
• Missing WebView2 runtime: the UI framework needs Microsoft Edge WebView2. If it isn't installed, grab the "Evergreen Standalone Installer" from developer.microsoft.com.
• VC++ redistributable: the audio modules need Visual C++ 2019+. Installer: aka.ms/vs/17/release/vc_redist.x64.exe.
• Check the log file: %APPDATA%\Hypnotika\logs\latest.log. The last lines often show the cause directly (missing module, path error).

• Clear the internal WebView browser cache: close Hypnotika, delete the folder %LOCALAPPDATA%\Hypnotika\EBWebView. The cache is recreated on next launch.
• Hard reload inside the UI: enable developer mode (Settings → Advanced → DevTools), then Ctrl+Shift+R.
• The language is saved per session. If you land on the old language again on the next launch, that probably points to a write-permission issue on %APPDATA%\Hypnotika\settings.json — see "Tracks disappear".
• The website language switch (DE/EN in the top right) is independent of the app language. Both are stored separately.