Troubleshooting

Model not found

Download the checkpoint to the documented Application Support directory, or set CONFUCIUS_MODEL_PATH to a directory containing config.json, tokenizer files, and the model safetensors. See First-run model setup.

Port 8765 is already in use

The app shows a native error and exits. It never searches for or kills the process using the port. Quit the owning app or stop the other or legacy process yourself, then reopen Confucius Captions.

macOS blocks the app

Public artifacts are ad-hoc signed, not Developer ID signed or notarized. Control-click the app, choose Open, and confirm. A production release needs maintainer signing and notarization credentials.

Microphone or shared audio is unavailable

Open System Settings → Privacy & Security and check Microphone and Screen & System Audio Recording. Quit and reopen the app after changing a permission. Shared-tab audio depends on the WebKit/macOS share picker; Chrome remains available for source development.

A file will not decode

Install FFmpeg with brew install ffmpeg. The app expects the Apple Silicon Homebrew binaries under /opt/homebrew/bin.

Windows

Windows packaging is on hold because MLX has no Windows inference backend.