Troubleshooting

Troubleshooting

"App is damaged / can't be opened" (macOS)

The released builds are unsigned. Clear the quarantine attribute:

xattr -dr com.apple.quarantine "/Applications/Zegplayer.app"

Or right-click the app → Open → confirm.

SmartScreen blocks the app (Windows)

Click More info → Run anyway. The build is unsigned.

A tool shows as "not installed" but I installed it

Zegplayer finds tools on your PATH plus a few known locations. If a tool is installed somewhere non-standard:

• Make sure it's on the PATH of the environment the app launches in (GUI apps don't always inherit your shell's PATH on macOS/Linux).
• For whisper-cli, use the Choose binary override in Connected Services to point at it directly.

Note: executable discovery beyond PATH is still macOS/Homebrew-leaning — see issue #7.

LM Studio / Ollama shows "Server off" (or offline)

Detection is reachability-based: Zegplayer probes the local server port (LM Studio :1234, Ollama :11434).

• "Server off" — the app is installed but the local server isn't running. Start the server in LM Studio / run ollama serve.
• Offline / download link — not detected on disk. On Windows/Linux, on-disk detection is still limited (issue #5); install it and start the server.

Install button does nothing

On macOS the button shells out to Homebrew. On Windows it downloads the binary directly from the tool's GitHub release into %APPDATA%\Zegplayer\bin\. On Linux the in-app installer isn't wired up yet — install manually via your package manager (issue #1).

Getting Whisper installed

• Windows: whisper-cli.exe (plus ggml.dll / whisper.dll) is fetched from the whisper.cpp GitHub release into %APPDATA%\Zegplayer\bin\ on first launch. No user action needed.
• macOS: install it from Connected Services → Install next to Whisper, which runs brew install whisper-cpp. There is no silent auto-download: whisper.cpp no longer publishes a macOS arm64 release archive, so the app asks brew rather than failing on a missing asset.
• Linux / Intel macOS: build or download whisper-cli from whisper.cpp and put it on your PATH (issue #2).

On any platform you can instead use openai-whisper (pip install -U openai-whisper) — the app drives both flavors and prefers whisper-cli when it finds one.

The speech model download

Separate from the binary, whisper.cpp needs a ggml-*.bin model. The app pre-fetches the ~466 MB small model in the background on launch — but only once a whisper-cli exists on your machine, so on macOS/Linux the download starts after you install whisper.cpp (restart the app to trigger it). Progress appears in the status bar as a setup job.

If you already have a ggml model from another app, it's reused instead of downloading: the app scans ~/Library/Application Support/…, ~/.cache/whisper, and the Homebrew whisper.cpp share directories. Python openai-whisper users are skipped entirely — it keeps its own .pt cache.

YouTube import fails with SSL: CERTIFICATE_VERIFY_FAILED

An antivirus (AVG, Avast, Kaspersky, ESET) or corporate proxy is intercepting HTTPS with its own root certificate that Python's bundled certifi doesn't trust. On Windows the app now passes --no-check-certificates to yt-dlp unconditionally to work around this. If you still see the error, delete any stale yt-dlp.exe under %APPDATA%\Zegplayer\bin\ and restart — the app will re-download the standalone build on next launch.

YouTube import fails with spawn EFTYPE

An earlier pip install --force-reinstall yt-dlp was interrupted and left a 0-byte yt-dlp.exe on your Python Scripts PATH. The app now bundles its own known-good copy under %APPDATA%\Zegplayer\bin\ and prefers it, so a fresh install should just work. To clean the stale one:

Remove-Item "C:\Users\<you>\AppData\Local\Programs\Python\Python*\Scripts\yt-dlp.exe.deleteme" -ErrorAction SilentlyContinue
pip install --force-reinstall yt-dlp

"Failed to connect" to the MCP server (packaged build)

This is almost always a missing unpacked native dependency. The packaged build must asarUnpack better-sqlite3 and its transitive deps bindings and file-uri-to-path, plus dist-mcp. Verify the asarUnpack list in package.json.

My projects disappeared after updating

The app was renamed from Agentic Video Player to Zegplayer. On first launch the packaged app migrates the old …/Agentic Video Player/ data directory to …/Zegplayer/ automatically — but only if the new directory doesn't already exist. If you launched once before updating, your data is still safe in the old directory; copy agentic-video.sqlite (and any media folders) from …/Application Support/Agentic Video Player/ into …/Application Support/Zegplayer/.

Dev changes to main/preload don't take effect

HMR only covers the renderer. Restart npm run dev after editing main or preload code.