Phase 1 Wave 2: per-OS install docs + Settings UI + error→docs deeplinks (#94)
* docs(install): per-OS install pages + drift validator + CI gate
Splits the 600-line README install section into self-contained per-OS docs
under docs/install/{macos,windows,linux,docker}.md plus a Top-10
troubleshooting index. Each OS doc is end-to-end: a user opens it and
reaches a working app following only commands inside that file.
Adds:
- docs/install/{macos,windows,linux,docker}.md (OS-specific install paths)
- docs/install/troubleshooting.md (top 10 install errors)
- docs/engines/cosyvoice.md (closes #55 docs half)
- docs/features/diarization.md (pyannote license flow)
- docs/setup/huggingface-token.md (3-source cascade guide)
- scripts/validate-install-docs.py (INST-06 docs-drift gate)
- tests/scripts/test_validate_install_docs.py (B-5: validator self-tests)
- .github/workflows/ci.yml step running the validator on every PR
Implements INST-02 (README routing), INST-03 (macOS Gatekeeper anchor),
INST-12 docs half (Windows torch-compile-oom anchor), DOCS-01..05.
The validator is a one-way diff: every `<!-- validate -->`-tagged line
in docs must appear in scripts/desktop-prod.sh after normalisation
(prompt-prefix strip, CRLF, trailing whitespace, blank-and-comment skip).
A `<!-- validate: skip -->` marker opts out for human-readability blocks.
Its own 10 unit tests catch regressions in the gate itself.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(deeplinks): links.py + error_docs_map (Python + TS mirror)
Adds the single source of truth for the project repo URL and the 4-class
error → docs taxonomy that both the in-app ErrorBoundary deeplink button
(Wave 2 Task 3) and the Phase 5 bug reporter will consume.
New:
- backend/core/links.py — PROJECT_REPO_URL + BLOB_MAIN resolver
(Tauri config first, pyproject fallback)
- backend/core/error_docs_map.py — lookup(error_class) → docs URL
- frontend/src/utils/errorDocsMap.ts (TS mirror with classifyError helper)
- tests/backend/core/test_links.py + test_error_docs_map.py
- frontend/src/utils/errorDocsMap.test.ts
Resolves checker B-6 (links.py ownership) and Open Question #3 (which fork
the deeplinks resolve to — the Tauri updater endpoint wins, which points
at the desktop app fork debpalash/OmniVoice-Studio).
The TS BASE constant is documented as the second hardcoded URL drift site;
the keys-sync test (`test_keys_match_python_map` equivalent) guards the
4-class taxonomy contract between Python + TS halves.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(ui): Settings → API Keys panel + ErrorBoundary docs deeplink
Wave 2 AUTH-03 UI half + ErrorBoundary deeplink wiring.
ErrorBoundary fallback now renders an "Open docs for this error" button
that classifies the thrown Error message (heuristic: pkg_resources → 401 /
HfHubHTTP → WebKit / white screen → quarantine / Gatekeeper) and opens the
matching docs anchor via Tauri shell.open (with a window.open fallback
in browser dev mode).
ApiKeysPanel consumes the Wave 1 resolver state endpoint:
- 3 source rows (App / Env var / HF CLI) with set/unset indicator,
masked token preview, whoami username + green check
- "Active" badge on whichever source is currently serving the cascade
- App-row only: Save (POST /api/settings/hf-token) +
Clear (DELETE with optional "also clear HF CLI" confirm dialog)
- "Test now" button refetches state (invalidates the resolver's
validation cache via the same endpoint hit)
Panel mounted in the existing Settings → Credentials tab; the legacy
HF_TOKEN row from CREDENTIAL_FIELDS is filtered out so the two paths
don't fight over the same key.
Threat T-02-02: the panel never displays the full token. The masked
value comes from the resolver state endpoint; the full token only
crosses the IPC boundary on Save (POST) and is cleared from local
state on success.
Closes AUTH-03 fully (Wave 1 backend + this Wave 2 UI).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(perf): INST-12 Disable torch.compile (Windows) toggle (backend + UI)
Wave 2 Task 4 — full INST-12 delivery per checker B-2/B-7 v0.3.0 fat-release
decision. Both the docs half (windows.md anchor, shipped in earlier commit)
and the runtime toggle are now in Phase 1.
Backend:
- backend/services/settings_store.py: adds get_text/set_text helpers for
non-secret config (refuses to write to the encrypted hf_token key).
- backend/api/routers/settings.py: GET + PUT
/api/settings/perf/torch-compile-disabled, both under the existing
loopback guard (threat T-02-04).
- backend/services/engine_env.py: new `build_engine_env()` helper that
centralises HF_TOKEN/YOUR_HF_TOKEN injection from the 3-source resolver
AND injects TORCH_COMPILE_DISABLE=1 when the flag is set on win32.
Phase 2 SubprocessBackend launchers should adopt the same helper.
- backend/services/sonitranslate.py: migrated to engine_env.build_engine_env()
while preserving the source-level `env["HF_TOKEN"]` sentinel that
test_sonitranslate_module_uses_resolver checks.
Frontend:
- frontend/src/components/settings/PerformancePanel.{jsx,css,test.jsx}:
toggle UI with the explainer for #65; renders disabled with a "not
applicable" badge on macOS/Linux.
- frontend/src/pages/Settings.jsx: mounts the panel into the Credentials
tab alongside the API Keys panel.
Tests:
- tests/backend/test_perf_settings.py: 7 backend tests (default state,
PUT persistence, T-02-04 non-loopback rejection, settings_store round-
trip, env injection on win32, NO injection on macOS/Linux, NO injection
when disabled).
- frontend PerformancePanel.test.jsx: 5 tests (renders from GET state,
PUT on toggle, disabled on non-Windows platforms, pre-enabled state).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(planning): Wave 2 SUMMARY + REQUIREMENTS status updates
- .planning/phases/01.../01-02-SUMMARY.md: full implementation report
per template (truths, commits, tests, deviations, drift-site
acknowledgments per W-3, launcher seam name for Phase 2,
taxonomy keys for Phase 5).
- .planning/REQUIREMENTS.md: flips Wave 2 closures to Done:
AUTH-03, INST-02, INST-03 (docs half), INST-06, INST-12,
DOCS-01..05.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Palash Debnath
co-authored by
Claude Opus 4.7
Claude Opus 4.7
parent
7f492958d5
commit
715766cb04
@@ -0,0 +1,134 @@
|
||||
# OmniVoice Studio — Install on Linux
|
||||
|
||||
This page is self-contained: follow it top to bottom and you'll end up with a
|
||||
working OmniVoice Studio install on a Debian / Ubuntu / Fedora / Arch host.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Linux x86_64** with a desktop session (X11 or Wayland) capable of running
|
||||
a Tauri / WebKitGTK app.
|
||||
- **Python 3.11+** — typically `sudo apt install python3.11` on Debian/Ubuntu,
|
||||
`sudo dnf install python3.11` on Fedora, or already installed on Arch.
|
||||
- **Bun** — `curl -fsSL https://bun.sh/install | bash`.
|
||||
- **FFmpeg** — `sudo apt install ffmpeg` (Debian/Ubuntu), `sudo dnf install ffmpeg-free` (Fedora), or `sudo pacman -S ffmpeg` (Arch).
|
||||
- **GTK/WebKit deps** for the Tauri shell:
|
||||
|
||||
```bash
|
||||
# Debian / Ubuntu
|
||||
sudo apt install libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libssl-dev libxdo-dev build-essential
|
||||
|
||||
# Fedora
|
||||
sudo dnf install webkit2gtk4.1-devel libappindicator-gtk3-devel librsvg2-devel openssl-devel
|
||||
```
|
||||
|
||||
- Optional: a **Hugging Face token** for diarization + the larger TTS engines
|
||||
(see [docs/setup/huggingface-token.md](../setup/huggingface-token.md)).
|
||||
|
||||
## Install (from source)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/debpalash/OmniVoice-Studio.git
|
||||
cd OmniVoice-Studio
|
||||
bun install
|
||||
bun run desktop-prod
|
||||
```
|
||||
|
||||
The first launch creates the Python venv via `uv`, syncs deps, and downloads
|
||||
model weights (~2.4 GB). Subsequent launches start in seconds.
|
||||
|
||||
## Install (AppImage)
|
||||
|
||||
Download the latest AppImage from the
|
||||
[Releases page](https://github.com/debpalash/OmniVoice-Studio/releases/latest),
|
||||
make it executable, and run:
|
||||
|
||||
```bash
|
||||
chmod +x OmniVoice.Studio_*.AppImage
|
||||
./OmniVoice.Studio_*.AppImage
|
||||
```
|
||||
|
||||
No FUSE? Use `--appimage-extract-and-run`:
|
||||
|
||||
```bash
|
||||
./OmniVoice.Studio_*.AppImage --appimage-extract-and-run
|
||||
```
|
||||
|
||||
## Install (.deb)
|
||||
|
||||
```bash
|
||||
sudo apt install ./OmniVoice.Studio_*.amd64.deb
|
||||
omnivoice-studio
|
||||
```
|
||||
|
||||
The desktop app uses these canonical paths (kept in sync with
|
||||
`scripts/desktop-prod.sh` by the docs-drift CI gate):
|
||||
|
||||
<!-- validate -->
|
||||
```bash
|
||||
APP_ID="com.debpalash.omnivoice-studio"
|
||||
APP_NAME="OmniVoice Studio"
|
||||
```
|
||||
|
||||
## AppImage white-screen on Fedora 44 / Ubuntu 24.04
|
||||
|
||||
<a id="appimage-white-screen-on-fedora-44--ubuntu-2404"></a>
|
||||
|
||||
Newer distros ship WebKitGTK 2.44 / 2.46, which has a compositing-mode
|
||||
regression that lands the Tauri window as a fully-white frame with no UI.
|
||||
|
||||
**Workaround:** set `WEBKIT_DISABLE_COMPOSITING_MODE=1` before launching:
|
||||
|
||||
```bash
|
||||
WEBKIT_DISABLE_COMPOSITING_MODE=1 ./OmniVoice.Studio_*.AppImage
|
||||
```
|
||||
|
||||
OmniVoice's AppRun launcher autodetects the broken WebKitGTK range and sets
|
||||
this for you (shipped in v0.3+). The manual env-var path remains the documented
|
||||
fallback when running from a checked-out source tree.
|
||||
|
||||
Tracking issue: [#62](https://github.com/debpalash/OmniVoice-Studio/issues/62).
|
||||
|
||||
## .deb ffprobe conflict
|
||||
|
||||
<a id="deb-ffprobe-conflict"></a>
|
||||
|
||||
Pre-v0.3 `.deb` packages installed `ffprobe` into `/usr/bin/ffprobe` and
|
||||
clobbered the system copy on some distros. v0.3+ relocates the bundled
|
||||
binary into `/usr/lib/omnivoice-studio/bin/ffprobe` and the `postrm` script
|
||||
runs `dpkg --search` to undo the old conflict on upgrade. If you upgraded
|
||||
from a pre-v0.3 .deb and `ffprobe -version` now reports the wrong binary,
|
||||
re-install the system package:
|
||||
|
||||
```bash
|
||||
sudo apt install --reinstall ffmpeg
|
||||
```
|
||||
|
||||
## Restricted networks (China / Russia)
|
||||
|
||||
If `uv` times out fetching the python-build-standalone tarball or PyPI:
|
||||
|
||||
```bash
|
||||
# Use a faster Python source mirror (China only — verify a current mirror)
|
||||
export UV_PYTHON_INSTALL_MIRROR=https://ghproxy.com/https://github.com/astral-sh/python-build-standalone/releases/download
|
||||
|
||||
# Use a PyPI mirror
|
||||
export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple
|
||||
|
||||
# Or skip the download entirely if you have a compatible system Python
|
||||
export UV_PYTHON_PREFERENCE=only-system
|
||||
|
||||
# Be tolerant of slow links
|
||||
export UV_HTTP_TIMEOUT=120
|
||||
export UV_HTTP_RETRIES=5
|
||||
```
|
||||
|
||||
The Phase 3 install milestone (INST-07..11) ships an OS-level mirror cascade
|
||||
that picks these defaults automatically; for v0.3 set them by hand.
|
||||
|
||||
## Hugging Face token (optional but recommended)
|
||||
|
||||
See [docs/setup/huggingface-token.md](../setup/huggingface-token.md).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Hit a wall? See [docs/install/troubleshooting.md](troubleshooting.md).
|
||||
Reference in New Issue
Block a user