Imported from trongnguyen24/CatVoice (AGENTS.md). Install upstream with npx skills add trongnguyen24/CatVoice. Copyright stays with the author.

AGENTS.md

Shape

• Root package.json is the command hub; package manager is bun@1.3.11 and the only workspace is frontend/.
• Python backend lives in backend/ and imports the copied model package from root omnivoice/; run backend commands from repo root so pyproject.toml and uv.lock are in scope.
• Frontend is Svelte 5 + Vite in frontend/src; Tauri v2 app lives in frontend/src-tauri.
• reference/ and docs/ are implementation references/blueprints; trust current manifests and source when they differ from prose.

Commands

• Install/sync Python deps: bun run setup:api or uv sync.
• Backend only: bun run dev:api starts FastAPI at 127.0.0.1:3900 with --app-dir backend --reload.
• Web dev: bun run dev runs uv sync, kills ports 3900/3901, starts backend, waits for /system/info, then starts Vite on strict port 1420.
• Desktop dev: bun run desktop does the same backend startup, then runs bun run --cwd frontend desktop (tauri dev).
• Frontend build check: bun run --cwd frontend build.
• Tauri dev direct from frontend/: bun run tauri dev; note tauri.conf.json runs beforeDevCommand: bun run dev, so this only starts the Vite dev server when launched from frontend/.

Verification

• No lint/typecheck/test scripts are defined in manifests; use focused checks instead of inventing commands.
• Backend health checks: GET http://127.0.0.1:3900/health, GET /system/info, GET /api/ext/engines.
• The expensive model path is triggered by POST /api/ext/engines/omnivoice/preload or POST /api/ext/generate; avoid using these as casual smoke tests unless model download/load is intended.

Runtime Quirks

• Python version is pinned by .python-version and Tauri bootstrap to 3.11.
• Backend env knobs: OMNIVOICE_PORT default 3900, OMNIVOICE_MODEL default k2-fsa/OmniVoice, OMNIVOICE_DATA_DIR default ~/.catvoice, OMNIVOICE_CACHE_DIR, OMNIVOICE_OUTPUTS_DIR, OMNIVOICE_IDLE_TIMEOUT_SECONDS, CORS via OMNIVOICE_ALLOWED_ORIGINS/OMNIVOICE_ALLOWED_ORIGIN_REGEX.
• backend/core/paths.py sets HF_HOME, HF_HUB_CACHE, TORCH_HOME, HF_HUB_DISABLE_XET=1, TORCHAUDIO_USE_TORCHCODEC=0, and PYTHONUNBUFFERED=1 before runtime dirs are used.
• Frontend API base is hardcoded to http://127.0.0.1:3900 in frontend/src/lib/api.ts; keep it aligned with backend/Tauri port behavior if changing ports.
• Tauri skips spawning the backend when TAURI_SKIP_BACKEND is set; otherwise it refuses to start if the configured port is already occupied by a non-healthy service.

Tauri Packaging

• frontend/src-tauri/tauri.conf.json bundles ../../pyproject.toml, ../../uv.lock, ../../README.md, ../../backend, and ../../omnivoice; keep this list current when moving backend/model files.
• First-run bootstrap resolves uv from PATH or installs uv version 0.8.5, creates .venv with Python 3.11, then runs uv sync --frozen --no-dev when uv.lock is present.
• In production, backend resources are copied into app-local project/; clean_and_retry_bootstrap deletes that copied project and retries setup.
• Backend logs are written by Tauri to ~/Library/Logs/CatVoice/backend.log on macOS, or local data CatVoice/logs/backend.log elsewhere; stderr tail uses backend_err.log.

Frontend Conventions

• Svelte code uses Svelte 5 runes ($state, $derived, $props, $bindable) and event attributes like onclick, not Svelte 4 on: syntax.
• Tailwind CSS v4 is configured through @tailwindcss/vite and theme tokens in frontend/src/app.css, not a separate tailwind.config.*.
• body has min-width: 960px; desktop window min width is also 960, so mobile responsiveness is not currently a verified target.

Git/Generated Files

• .gitignore ignores the uv.lock, bun.lock, and frontend/bun.lock, but those files are present and used by local/Tauri workflows; do not delete or regenerate them casually.
• Ignore and do not preserve __pycache__/, .venv/, node_modules/, frontend/dist/, and frontend/src-tauri/target/ changes.