Thanks for your interest in improving VoiceStudio! This guide covers everything you need to get started.
| 💬 Chat | Discord |
| 🐛 Bugs | GitHub Issues |
| 🏷️ Good First Issues | Filtered list |
| 📋 Roadmap | docs/ROADMAP.md |
Before your first pull request: sign the CLA first. Unless exempt under the CLA checker’s policy, sign the Contributor License Agreement once. It takes a minute: post the line in Contribution licensing on the signing issue (#2586), and your signature covers your future contributions. A pull request opened before you sign is converted to a draft, its heavy CI is skipped and the review bots wait; when you sign, CI re-runs automatically and the pull request is marked ready (one you made a draft yourself stays a draft until you mark it). An unsigned pull request cannot merge unless a maintainer applies the
cla-overridelabel after manual review. Every other non-exempt human commit author and co-author must also sign before the check passes.Using an AI coding agent? Give it the agent pull-request guide first.
New engines are hired for a named job, not added to a list — the bar, the current job map, and the out-of-tree path are in docs/engine-acceptance.md. Read it before opening a proposal; the licence check in particular ends most of them.
- Git
curl(used by the Bun / uv / rustup install one-liners on macOS and Linux)- Node.js 22, 22.12.0 or newer (Electron development and validation scripts). CI runs Node 22 and
.nvmrcpins it for nvm, fnm and Volta; newer majors change some error messages and fail tests that pass on CI. - Bun (frontend package manager)
- uv (Python environment manager)
- ffmpeg (audio/video processing)
- Rust / Cargo (
native/desktop-bridgeand its imported Rust modules) - Python 3.11+ (
requires-pythoninpyproject.toml; managed automatically byuv)
Linux desktop development needs the native helper libraries. On Debian or Ubuntu, install the same packages used by CI:
sudo apt-get update
sudo apt-get install -y \
libasound2-dev libxdo-dev libxtst-dev libx11-dev libxkbcommon-dev \
libwayland-dev libssl-dev pkg-config build-essential curlSee the Linux source-build guide for Fedora and Arch packages.
git clone https://github.com/debpalash/VoiceStudio.git
cd VoiceStudio
bun run devThis installs the source dependencies (skipping local API setup for an external backend or Intel Mac) and launches Electron with hot reload. The supervisor manages backend startup; do not launch a second backend. See Electron setup.
For screenshots, use the maintained Electron capture script described in
README media. To share a runnable app, use
the release installers or bun run dist; source users should clone the
repository with its lockfiles and follow the setup commands above.
CPU-only Linux/Windows hosts automatically select CPU wheels; see
CPU setup and overrides.
When regenerating uv.lock for compute variants, preserve unrelated package
versions: NumPy remains 2.0.2 on Python 3.12 Linux/Windows and 2.2.6 elsewhere.
Validate both frozen CPU/CUDA exports with tests/test_cpu_install.py; a NumPy
upgrade needs its own compatibility review.
bun run build # build Electron
bun run start # launch the built Electron app
bun run dist # package locally without publishing
bun run smoke-test # packaged startup, first-run consent, and native bridge
bun run smoke-test -- --install # also install and start the managed backend
bun run dev:web # maintained Electron renderer in a browser + backendbun run dev:web starts both services:
| Service | URL | What it does |
|---|---|---|
| Backend | localhost:3900 |
FastAPI server — TTS, ASR, diarization, dubbing pipeline |
| Frontend | localhost:3901 |
Electron renderer served by Vite in a browser |
bun run dev keeps one desktop dev instance per checkout: starting it again
stops the earlier dev app and its dev server (only this checkout's, never an
installed VoiceStudio or another project) instead of failing with "Port 3902 is
already in use". To run two side by side, start the second one with
VOICESTUDIO_ALLOW_MULTIPLE_INSTANCES=1 plus its own ports, for example
VOICESTUDIO_UI_PORT=3912 VOICESTUDIO_ELECTRON_PROXY_PORT=3913.
On macOS, development launches coordinate bundle preparation and retain each
active dev server’s branded Electron bundle across main-process restarts.
Unused bundles are removed on later launches; cleanup failures do not prevent
a valid cached bundle from starting. Native OS locks release automatically when
all holders exit, including after a crash. The launcher calls /bin/cp,
/usr/bin/plutil and /usr/bin/codesign by full path, so GNU coreutils ahead
of /bin on PATH does not break it, and the app asks the Keychain only when a
saved account sign-in exists or account features are on.
Editing a main-process file restarts Electron. Each dev instance records its process ID in its user-data folder, and the replacement waits up to 20 seconds for the previous one to exit before taking the single-instance lock, so the restart does not end the dev session. Packaged builds never wait.
Product builds read the app name, application ID, and the backend/web/Electron
development ports from config/app.json. Change that manifest instead of
copying new defaults into launchers or runtime modules.
The backend runs through scripts/dev-backend.mjs (the dev:api script): the
uvicorn command is unchanged, but if the backend dies (OOM kill, hard
crash), the wrapper prints a boxed exit banner with the exit code/signal and
the last 20 lines of omnivoice.log before the dev stack shuts down — so the
cause doesn't scroll away with the terminal. The same death is also reported
as a crash notice in the UI the next time the backend starts (see
docs/install/troubleshooting.md §14c).
Close VoiceStudio and its backend/dev servers before cleaning. From the checkout:
bun clean --dry-run # list exact paths without deleting
bun clean # permanently delete the listed state
bun run clean:all # equivalent command
make clean:all DRY_RUN=1 # Make preview; omit DRY_RUN=1 to deletePlain make still starts the release flow; cleanup must be selected explicitly.
For Make, any non-empty DRY_RUN value enables preview mode unless it is
exactly one of 0, false or no; true, yes, unfamiliar values and
several words (such as false 0) all preview.
The script needs Git and Node, but no installed project dependencies. It removes
project node_modules, Python virtual environments (including custom names
identified by pyvenv.cfg), tool caches, Electron/native/mobile build outputs,
test reports, logs and checkout-local runtime data. It also removes the default
VoiceStudio Electron profile, OmniVoice backend data and persisted settings.
This deletes saved voices, projects, generated audio, account sessions and
managed engines in those locations.
These default profiles are shared with installed VoiceStudio and other source checkouts.
Tracked files, root .env files, Git metadata, agent configuration, research
clones and nested Git repositories are preserved. Symlink targets are never
followed. Shared Hugging Face caches (including Windows' %LOCALAPPDATA%/OmniVoice/hf_cache),
global package-manager caches, other apps' profiles, installed applications,
phone/simulator data and OS keychain entries are excluded. Custom external
data/runtime/model locations are also excluded; inspect and remove those
separately if needed. The preview lists exactly what will be removed.
Failed deletions return a nonzero exit code. Run bun run dev to reinstall
project dependencies afterwards.
Tauri is sunset after v0.5.3 and receives no further development or backports. Use Electron for desktop contributions and reproduce desktop bugs there. Existing users should follow the migration guide. The Tauri shell and its legacy UI entry points have been removed. Shared modules and native helpers used by Electron remain maintained.
VoiceStudio/
├── backend/ # Python FastAPI server
│ ├── api/ # Route handlers
│ ├── core/ # Config, prefs, constants
│ ├── engines/ # Engines in their own module (lazy-registered)
│ └── services/ # TTS engines, ASR, dubbing, audio DSP
│ └── tts_backend.py # ← Multi-engine TTS registry
├── electron/ # The only desktop and web UI
│ └── src/
│ ├── main/ # Electron main process (IPC, updater, runtime)
│ ├── preload/ # Narrow renderer bridges
│ ├── renderer/src/ # App shell, features, shadcn ui/, i18n catalog
│ └── shared/ # Legacy modules the renderer still imports (being retired, #2603)
├── native/ # Rust desktop helper used by Electron
├── deploy/ # Dockerfile, compose, install worker
├── docs/ # User, install, release and design docs
├── scripts/ # Build, release and CI helper scripts
└── tests/ # Repo-wide pytest suite (CI: tests/ + backend/tests/)
Open an issue with:
- What happened vs what you expected
- Steps to reproduce
- OS, GPU, and Python version (find in Settings → Logs)
- Error logs (Settings → Logs → copy relevant lines)
- Fork the repo and create a branch from
main - Keep PRs focused — one feature or fix per PR
- Run tests before pushing:
# Packaging tests use Electron dependencies, including electron-builder. bun install --frozen-lockfile # Backend tests (the same two runs as CI; -n auto runs tests/ in parallel, # optional locally, it is about 4x faster on 4 cores) uv run pytest tests/ -q -n auto uv run pytest backend/tests/ -q # Frontend build check bun run check:electron
- Write a clear PR title — it becomes the squash-merge commit message
- Add a changelog fragment if users will notice the change: one line in
changelog.d/<PR#>.<type>.md(seechangelog.d/README.md). Don't editCHANGELOG.mddirectly, so your PR never conflicts with others - Don't include local machine stats, file paths, or private system info in PR descriptions
VoiceStudio's TTS backend is a plugin registry. Adding a new engine takes ~50 lines:
- Open
backend/services/tts_backend.py - Create a class extending
TTSBackend:
class MyEngineBackend(TTSBackend):
id = "my-engine"
display_name = "My Engine (description)"
@classmethod
def is_available(cls) -> tuple[bool, str]:
try:
import my_engine # noqa: F401
return True, "ready"
except ImportError:
return False, "my_engine not installed. pip install my-engine"
@property
def sample_rate(self) -> int:
return 24000
@property
def supported_languages(self) -> list[str]:
return ["en", "zh"]
def generate(self, text: str, **kw) -> torch.Tensor:
# ... call your engine, return [1, num_samples] tensor- Register it at the bottom of the file: in-file classes go in
_REGISTRY; an engine that lives in its ownbackend/engines/<name>module goes in_LAZY_REGISTRYas"id": ("engines.<name>", "ClassName") - Add the same id under
tts_enginesindocs/features.yamlwith its README string (readme:) or a doc page (doc:) — the Python suite and relevant documentation PRs runpython scripts/check-docs-drift.pyto flag missing registry ids in a read-only job; only the daily/manual maintenance job gets issue-write permission to maintain the rolling docs-drift issue - It then appears in Settings → TTS Engine
- Formatter: We don't enforce one globally — match the style of the file you're editing
- Logging: Use
logger.warning()/logger.error(), never bareprint() - Exceptions: Avoid bare
except: pass— catch specific exceptions - Type hints: Use them for public API functions and class methods
- Components: Functional components with hooks
- State: Zustand slices in
electron/src/shared/store/ - Brand assets: Reuse the canonical mark, palette, naming, and compatibility rules in
docs/branding.md; do not redraw or rename runtime identifiers ad hoc - CSS: Tailwind v4 utilities + the shadcn/ui primitives in
electron/src/renderer/src/components/ui/, themed by the tokens inelectron/src/renderer/src/styles/(globals.css,t3-theme.css). Prefer utilities; add or extend a co-located.cssfile only for what utilities cannot express (@keyframes, pseudo-elements, styling hooks on library-generated DOM). - Naming:
PascalCasefor components,camelCasefor hooks and utils
- Format:
cargo fmtbefore committing - Scope:
native/desktop-bridgeand modules it imports; do not revive the archived Tauri shell.
Frontend code stays modular so an edit loads one small file, not a 1900-line one. The rules:
- Size caps: soft 300 lines, hard 500 lines per component file
(
.jsx/.tsx). Anything over 500 lines must be split. - Pages are thin orchestrators. A page in
electron/src/renderer/src/features/<feature>/(routed fromelectron/src/renderer/src/routes/) is just layout + routing + state wiring that composes feature components — no inline sub-component over ~50 lines. - One component per file. Co-locate
foo.tsx+foo.test.tsxtogether in the feature folder underelectron/src/renderer/src/features/(e.g.features/settings/,features/dub/). Style with utilities + shadcn first (see the CSS rule above). - Shared bits go in a subfolder inside the feature folder, or in
electron/src/renderer/src/components/when several features use them. New UI never goes inelectron/src/shared/. - Enforced in review, not by lint:
bun run lint(oxlint) has nomax-linesrule, so reviewers apply the caps.
Write clear, concise messages. The PR title becomes the squash-merge commit.
good: fix: prevent CUDA OOM during concurrent transcription + TTS
good: feat: add CosyVoice 3 TTS backend adapter
good: docs: add platform compatibility matrix to README
bad: fixed stuff
bad: update
bad: WIP
Commit with a real identity (your GitHub noreply address works). The
commit-identity PR check (scripts/check_commit_identities.py) fails when a
PR commit's author, committer, or Co-authored-by:/Signed-off-by: email is
a placeholder (test@local, you@example.com, mergetest, hostname-style
*.local), an AI agent, or on the hashed block list, or when a commit message
or the PR description credits an AI agent. Fix an identity on the listed
commits only: git rebase -i origin/main, mark each listed commit edit, and
at each stop run git commit --amend --no-edit --reset-author and
git rebase --continue (a blanket --exec would also take over other
people's commits); fix agent credit by rewording the commit messages (git rebase -i, then
reword) and editing the PR description.
Native-call timeout tests should synchronize with confirmed worker entry before starting their short test deadline, and join released workers during cleanup. Cover delayed startup separately so runner scheduling does not masquerade as a native-call timeout or leak work into later tests.
Shared React tests await cleanupReact() before resetting persistence and
disposing JSDOM. Keep deferred focus restoration in that same realm; advance
only the current fake-timer tick rather than flushing unrelated future timers.
# Packaging tests in tests/ load the installed Electron tooling.
bun install --frozen-lockfile
# Run the backend suites CI runs (kept separate: backend/tests is isolated)
uv run pytest tests/ -q
uv run pytest backend/tests/ -q
# Run a specific test file
uv run pytest tests/test_app_version.py -q
# Electron desktop validation, from the repository root
bun run check:electron
# Desktop UI tests: launch the real (unpackaged) app against a fake backend.
# CI runs these on macOS, Windows and Linux. On Linux without a display,
# prefix the last command with `xvfb-run -a`. Failures leave a Playwright
# trace and screenshot in electron/test-results/.
bun run --cwd electron build
bun run --cwd electron test:desktop-ui
# The bundled `voicestudio` command, built as installers build it (needs uv).
# CI runs this on all three systems (Release smoke on macOS and Linux, Desktop UI on Windows).
node electron/tests/cli-bundle-smoke.mjs
# Offline renderer smokes (what CI runs): start the smoke server, then the runner.
# New *-smoke.mjs files are classified automatically (chromium = runs here,
# *-real-smoke = needs a live backend, _electron = drives the real app);
# `node --test electron/tests/smoke-inventory.test.mjs` fails on an unclassified one.
OMNIVOICE_PORT=3999 bun run --cwd electron smoke:server &
OMNIVOICE_PORT=3999 VOICESTUDIO_UI_URL=http://localhost:3912 PLAYWRIGHT_CHANNEL=chromium \
node electron/tests/run-renderer-smokes.mjs [name-filter ...]
# UI crawler (the "UI crawler (n/3)" CI jobs, VOICESTUDIO_CRAWL_SHARD=n/3), against the same smoke server:
# clicks every enabled button on every route, then the buttons a filled-in form
# enables, then one level into each dialog, while API writes answer normally,
# with 500, with a network error, or with broken JSON. It fails on a spinner
# left after requests settle, a button still greyed out after its write failed,
# a failed write with no visible feedback, an uncaught error, or a
# console.error. Fix the button; KNOWN_FINDINGS stays empty. A request pending
# for 30 s (a hung backend or dev server) stops that fault mode at once with one
# "stalled" finding naming the click or screen that started it.
OMNIVOICE_PORT=3999 VOICESTUDIO_UI_URL=http://localhost:3912 \
VOICESTUDIO_CRAWL_MODES=http-500 VOICESTUDIO_CRAWL_ROUTES=/clone \
node electron/tests/ui-crawler.mjs
# Shared native helper, when changed
cargo check --manifest-path native/desktop-bridge/Cargo.tomlDagger runs the frontend tests, the mobile
token check and both backend pytest suites in containers whose steps are cached
by content, so a re-run after an unrelated edit takes seconds. It needs Docker.
The first run downloads container images and dependencies (as CI does); after
that your code and results stay on your machine. CI is unchanged: ci.yml
stays the gate.
The module has its own dependency lockfile, .dagger/uv.lock; the root Python
lockfile does not update it. When refreshing module dependencies, use the SDK
matching dagger.json's engine version and keep the generated .dagger/sdk/
directory untracked. tests/test_dependency_security_floors.py checks both
lockfiles against reviewed security fixes.
dagger call check # all of the above, in parallel
dagger call check --git=.git # also run tests that read real git history
# (in a linked worktree: --git=$(git rev-parse --git-common-dir))
dagger call frontend-tests # or: mobile-tokens, python-testsEvery PR is reviewed by two AI reviewers before a human looks at it:
- CodeRabbit posts a short collapsed summary (no diagrams), inline
findings, and warning-mode pre-merge checks against the project's hard
rules (configured in
.coderabbit.yaml). Finishing-touch repair prompts for findings, failing CI, and merge conflicts are disabled. - Greptile reviews with the same project rubrics and learns from 👍/👎 reactions on its comments — react to train it.
Both are advisory, not gating: CI and the maintainer's approval decide. Don't be surprised by detailed bot comments minutes after you open a PR — address what's right, push back (in a reply) on what's wrong.
Commit & PR conventions: conventional-commit style with a scope
(fix(dub): …, feat(setup): …) and link the issue (Closes #N / Refs #N)
in the title or body.
Plenty of contributions here are built with Claude Code, Cursor, and similar agents — welcome, with the same quality bar as hand-written PRs (real bug, correct fix, regression test; see the quality gates below).
You submit agent-assisted work as your own, under your own git identity. Don't
credit agents in commits or the PR description: no Co-authored-by: trailer
for an AI agent, no "Generated with …" line, no agent session or share links
(claude.ai, chatgpt.com) and no Claude-Session: trailer. The
commit-identity check fails PRs that carry them. Co-authors who are people
are welcome, including people with first names that also name an agent, such
as Claude, Jules, or Devin. Known agent email addresses remain blocked. The
identity workflow runs the base branch's policy and publishes Commit identity policy; changing the checker or workflow in your PR does not bypass it.
Keep one open PR per head commit. CLA checks reject duplicate heads because
GitHub commit statuses are shared by SHA, even when PR descriptions or authors
differ. Close duplicates and comment recheck on the survivor, then rerun its
trusted identity workflow.
One practical tip: this codebase is large, and re-explaining it to your agent
every session burns context and tokens fast. A persistent memory layer fixes
that — the agent recalls the architecture, conventions, and your past findings
instead of re-reading the tree each time. memxt
(100% local, MCP-based, built by this project's maintainer) exists for exactly
this; any MCP memory server works. Pair it with the repo's agent skill —
npx skills add debpalash/VoiceStudio — so your agent knows the project's
hard rules from the first prompt.
Documentation-only and test-only changes skip runtime tests, desktop/mobile builds
and Docker image rebuilds on pull requests and pushes to main. The required
Tests (backend + frontend) check reports the explicit skip so branch protection
still works. Mixed changes, workflow/build configuration, dependencies and bundled
app icons still run their normal checks, as do changes to the UI crawler's
harness (CI_HARNESS in .github/scripts/ci_scope.py), so the crawler job checks
its own changes; unknown or truncated change lists run
all checks. Manual runs and scheduled audits remain full runs. CLA, commit identity
and secret scanning still run. The same skip applies while a pull request's
opener has not signed the CLA (see Contribution licensing). Run changed tests locally before submitting a
test-only PR. Docker Hub overview edits still publish through the small
dockerhub-description.yml workflow without rebuilding images.
-
Gallery pin: a PR that changes the
omnivoice-gallerysubmodule must move it forward along the gallery'smain(.github/workflows/gallery-pin.yml). If it fails on a PR that never meant to touch the gallery, the checkout had a stale submodule: rungit submodule update omnivoice-galleryand drop that change from the commit. -
First CI run from a fork: a pull request from a fork waits for a maintainer to approve it (the
external-prenvironment) before CI starts. Branches in this repository start at once. -
Required check:
Tests (backend + frontend)is the one CI statusmainrequires. It waits for every job inci.ymland fails if any of them failed, so a red UI crawler, Desktop UI or release smoke blocks the merge too. -
Release smoke: every pull request that can affect the desktop app packages it on Linux and macOS the way a release does, without installers or signing credentials:
electron-builder --dir(which builds the bundledvoicestudiocommand and the native helper), the release's packaging contract, glibc floor and bundle signature checks, the packaged startup smoke test (on Linux through thevoicestudioentry, as the AppImage starts it) andelectron/tests/cli-bundle-smoke.mjs. -
CI scope: the Electron-only jobs (UI crawler, Desktop UI, Linux native package, release smoke,
Tests (Electron)andElectron renderer smokes) are skipped on a pull request whose every changed file is an edit or addition underbackend/(exceptbackend/assets/),omnivoice/,docs/ormobile/, a Python file undertests/orscripts/(except the scripts the desktop build runs or ships:freeze_cli.py,smoke_windows_rocm.py,check_glibc_floor.py), a root*.md,Makefile, or a workflow other thanci.ymlandelectron-*.yml. Any other path (includingpyproject.toml,uv.lock,package.json,bun.lockand shared test fixtures), any file that is not a plain edit or addition (deleted, renamed, copied or type-changed), 3,000 or more files, and every push tomainrun the full matrix; so does a failed detection. Skipped jobs show as skipped in the PR. If the merge queue is ever turned on (it needs an organization-owned repository; seedocs/RELEASING.md→ Merge queue), a queue run applies the same rule to the queue commit against its base (300 files or more run everything). The rule is thechangesjob in.github/workflows/ci.yml. -
Nix build scope: the optional flake workflow uses the shared
.github/scripts/ci_scope.pydetector on pull requests, main pushes and merge groups. Documentation and test-only edits, including inline tests anddocs/install/nix.md, produce an explicit successful skip. Runtime/mixed changes, flake/config/lockfiles, bundled logos, license data and the shared runtime CI harness still build; unknown, failed or truncated change detection runs the build. Merge groups retain the package's mobile and unrelated.github/exclusions; the Nix workflow itself always qualifies. Explicit manual/release events remain full, and the existing unsigned-CLA hold remains. -
Mobile artifacts: uploads retry once after ten seconds when the first attempt fails and the run is not cancelled. Both attempts use the same artifact name and inputs; a failed retry still fails the job, and pass-cache markers remain after the terminal upload. Native tests are never skipped because an upload failed.
-
Pass cache: the heavy jobs in
ci.yml(Python tests, the Electron jobs, UI crawler, Desktop UI, release smoke, smokes) and inmobile.yml(iOS, Android and their inference tests) skip their steps, and still pass, when their exact inputs already passed. Each job hashes the git entries (mode, content and path) of the files it reads, plus its workflow file and.github/actions/ci-pass; a green run saves an empty cache marker under that key as its last step. Only pull-request and merge-queue runs skip; pushes tomain, manual runs, releases and the CLA, identity and security checks always run in full, andmain's runs save the markers pull requests reuse. Each job lists its inputs next to itsci-passstep; when a job starts reading a new file outside them, add it there. To force a full run, use Run workflow on the branch.tests/test_ci_pass_cache.pychecks the gating. Mobile pass keys also include the shared diagnostics policy, destination and golden event fixture. The two iOS pass keys exclude only Android implementation/build subtrees; iOS, shared contracts, native pins and resource-generator inputs still invalidate them. This reuses a prior green result only for pull-request and merge-group runs; the cache never skips main pushes, manual verification or release builds. The iOS screenshot tour waits for a hittable native tab, its selected state and its destination before capturing a screen. A failed navigation records a test failure and stops that tour, rather than collecting screenshots of the previous page; it never retries the tap. TheSecurityworkflow works the same way: CodeQL, bandit and the dependency audits are skipped for a PR that only edits files underdocs/ormobile/or Markdown, while the secret scan always runs (rule: its ownchangesjob). The Docker image build onmainskips merges that only touchdocs/,mobile/,changelog.d/orCHANGELOG.md. -
Closed PRs stop their CI: merging or closing a PR cancels its queued and running pull-request workflows (
.github/workflows/cancel-closed-pr-runs.yml); the repository is capped at 20 concurrent jobs, so they would only delay others. Maintainers can run the same cleanup for the whole repository from the Actions tab (cancel-closed-pr-runs, dry run by default). The sweep requests cancellation incrementally within a four-minute work budget, leaving time for its final bounded request before the five-minute job limit. Accepted requests are not proof of completed cancellation; HTTP 409 refusals are reported as skipped. Capped searches use a bounded 30-day recovery window. Saturated or truncated discovery, lookup failures and failed cancellation requests return a nonzero result after preserving eligible partial progress; no force-cancel is issued. Short searches with missing rows get one bounded rescan for delayed cancellations; the retry's own count must cover its reported total even when new arrivals increase the combined ID count. Unresolved totals remain incomplete. Each day window is checked against its own reported total, so new arrivals elsewhere cannot hide a truncated window; its retry counts toward the window budget. Both close-event cleanup and the repository sweep freshly paginate the repository's open PRs before each otherwise eligible cancellation: the commit-association API can omit an open PR whose SHA is already on the default branch. An open head/merge SHA, associated PR number, or matching head repository and branch keeps the run, including a reopened PR whose head has advanced. Each refresh needs two consecutive complete matching ownership inventories, bounded to three reads of at most ten pages each; duplicate PR numbers or an unstable inventory preserve that candidate and report incomplete inspection while later candidates remain inspectable. Cosmetic PR updates do not affect this identity comparison. Missing ownership evidence or an incomplete open/closure lookup keeps the run. A positive open-PR match can preserve a run without branch metadata; otherwise its head repository and branch are required, even when it lists a PR number. Cached closures never bypass this refresh. A run must predate the earliest initially known associated PR closure, protecting work started by either close event. Direct cleanup uses the requested PR's own closure for empty commit associations only when its API response explicitly says closed andmerged: false. A merged or unknown merge state cannot supply that fallback; an empty result alone never authorizes repository-wide cleanup. -
Cross-platform parity (hard rule): anything that ships in default mode must behave identically on macOS, Windows, and Linux. Platform-specific implementation is fine; platform-divergent default behavior is a P0. Platform-only features go behind an explicit opt-in (Settings toggle, env var, or CLI flag).
-
i18n — every locale (hard rule): every user-facing string goes through
t('...')and the key must exist in every file of the catalog:electron/src/renderer/src/i18n/locales/(checked bytests/test_locale_parity.pyandbun run --cwd electron locale:check, which also fails on anen.jsonkey no code references; delete it from every locale, or add a prefix toALLOWED_PREFIXESinelectron/tests/locale-source-keys.mjsif code builds it dynamically). Translate; don't copy English into non-English locales. CI fails on hardcoded CJK outside the allowlist intests/test_no_hardcoded_cjk.py(extend_ALLOWED_FILESwith a justification for legitimate functional CJK). -
DB schema changes go through an alembic migration with a tested upgrade path — existing
omnivoice_data/must keep working with no manual steps. -
Engine back-compat: already-installed engines (model weights on disk) must not require reinstall or re-download.
-
Local-first: no new outbound calls, and the app must work fully offline with every prompt declined. The only sanctioned ones are:
- First-run setup the user starts: the pinned, SHA-256-verified
ffmpeg/ffprobe download from GitHub (
zackees/ffmpeg_bins) when no usable copy is found (backend/services/media_tools.py); the huggingface.co vs hf-mirror.com reachability probe that picks a download endpoint on restricted networks, skipped when the user set an endpoint (backend/services/endpoint_race.py); the dependency install's download of the packages pinned inuv.lock, from their locked URLs or the regional mirror the user chose or the Auto region selected (including a hash-preserving PyPI failover after a confirmed transient origin failure), including the parallel multi-connection wheel prefetch (electron/src/main/wheel-prefetch.ts; owner-approved 2026-10-27); the Auto region's speed check, which reads the start of one locked wheel from files.pythonhosted.org and mirrors.aliyun.com (one ranged request each, timed out, no retries) and keeps PyPI on any doubt (electron/src/main/pypi-mirror.ts); a user-clicked setup connection check requesting 256 KiB from the affected package's pinned URL through the setup proxy, bounded to 15 seconds, with no upload; and Hugging Face model downloads (gated on install state or an explicit user action). - Windows ROCm setup the user explicitly selects (owner-approved
2026-10-26; extended 2026-11-09): the matched AMD SDK and PyTorch wheels
from
repo.radeon.comandstable.repo.amd.com/rocm/whl-next/, the pinned HIP CTranslate2 archive from OpenNMT/CTranslate2 GitHub Releases, and the HIP CTranslate2 wheels this repository builds with.github/workflows/ct2-rocm-windows.ymland publishes on its own GitHub Releases. Every artifact is SHA-256 pinned inscripts/windows-rocm-recipe.jsonand verified before use. This opt-in installer keeps every other package at its installed (locked) version and uses the usual package indexes only for anything new; verification and the optional local-model smoke test never acquire models or use the network. The VC++ Redistributable is a manual prerequisite; opted-in Windows ROCm source setup checks it locally and stops when it is missing. - Dependency repair for an existing Python the user selected
(owner-approved 2026-11-09): after the user reviews the plan and confirms,
pip installof the listed missing packages from PyPI into that interpreter (electron/src/main/ipc.ts). - Optional engine installs the user starts (owner-approved 2026-11-07):
clicking Install or Repair on an optional engine fetches its upstream
source from GitHub (a shallow clone of the branch tip, then the reviewed
commit, or that commit's source archive when the clone or checkout fails),
plus any helper sources the engine needs as GitHub archives at pinned
commits (CosyVoice: Matcha-TTS, PyWorld and World); a uv-managed Python from
astral-sh/python-build-standaloneGitHub Releases (or the regional mirror) when the engine needs a version that is not installed; its Python packages from PyPI or the user's chosen mirror; the host's PyTorch build fromdownload.pytorch.org(cu128orcpu; on Linux AMD hosts, engines with ROCm support use the ROCm index that publishes their Torch version, which a user-setOMNIVOICE_TORCH_INDEXreplaces), where uv may also resolve other packages that index carries; and, for engines that fetch them during install, their Hugging Face weights at a reviewed revision (backend/services/sidecar_install.py). Engines that skip that step download weights on first use, under the Hugging Face model downloads above. Torch is pinned to an exact version; other packages follow the engine's own requirements (exact, ranged or unpinned). Nothing is hash-pinned. Checking whether an engine is installed downloads nothing. - Galleries the user opens or enables: the community gallery manifest
from jsDelivr plus its GitHub-hosted previews
(
backend/api/routers/community.py); the voice-preview gallery's signed downloads fromomnivoice-galleryGitHub Releases, only after it is turned on in Settings (backend/services/gallery.py). - Packaged-app update checks against GitHub Releases, and the background
download of a found update from the same release (on by default; Settings
→ Updates → Download updates automatically turns it off, so downloads wait
for the user) (
electron/src/main/updater.ts). - yt-dlp updates from PyPI, only when the user clicks update
(
backend/services/media_tools.py). - VoiceStudio Cloud account features, only after the user turns them on
(first-run setup or Settings → Account; off by default, skipping = off):
browser sign-in that starts on
app.voicestudio.sh/auth/app(the dashboard handles login and approval), the one-time code exchange atapp.voicestudio.sh/auth/app/token, token refresh and revocation atid.voicestudio.sh, and the account API atappapi.voicestudio.sh, all from Electron main (electron/src/main/account/, endpoints and client ID inconfig/account.json), and, only after the user also turns cloud sync on, settings sync withappapi.voicestudio.sh/v1/syncfrom the backend (backend/services/cloud_sync/), which can call only with a token main hands out. Turning either off stops every request at once; signing out or switching account features off sends one best-effort token revocation and always forgets the session on this device, even offline (sign-out waits at most 5 seconds for the network). While signed in with account features on, the app also sends a periodic check-in (POST appapi.voicestudio.sh/v1/account/app-check: app name, app version and operating system only) so the server knows which app and version you use; it grants nothing, and it stops at once on sign-out or when account features are switched off. - Bug reports as prefilled GitHub Issue URLs opened in the user's browser.
- Phone content reports, only when the user taps Send in a generated
result's Report sheet:
appapi.voicestudio.sh/v1/content-reportswith the reason, optional note and typed text, app version and model; no audio, account or device identifier (mobile/contract/SPEC.md→ Reporting generated content; required by Google Play's AI-generated content policy). - Supermetry analytics only after a yes at the first-run consent prompt, asked before
runtime setup on a fresh install so setup stage and failure code can be counted
(
backend/core/analytics.py, allowlisted content-free metadata). - Automatic failure reports to Supermetry's app intake
(
https://app.supermetry.com/api/public/v1/app-events, or the owner-configured packaged destinationhttps://app.voicestudio.sh/api/public/v1/app-events, owner-set 2026-11-16) when build/runtime app credentials are configured, otherwise the same existing public events endpoint, only after the separate Automatic error reports opt-in (owner-approved 2026-11-14). Off by default, including for existing analytics users; metadata followsconfig/diagnostics.json. Electron main owns desktop uploads even when setup/backend fails; source/Docker and both native phones own their respective consent. Release CI receives the app ID and ingest key only from GitHub Actions Secrets, never public repository variables or logged values; fork builds receive no upstream app credentials.SUPERMETRY_APP_HOSTis an explicit, default-unset operator override; any other production host needs owner approval and documentation. The separatediagnostics.sessionPingsbuild flag remains off by default and still requires diagnostics consent. Withdrawal stops delivery and invalidates queued reports. No audio, text, exception messages, logs, user paths, credentials, screenshots or crash dumps are uploaded; seedocs/electron-privacy.md. - The GitHub star count (no credentials or referrer, refreshed every 20 minutes while shown).
Adding to this list needs owner approval. Never log or persist secrets or absolute home paths.
- First-run setup the user starts: the pinned, SHA-256-verified
ffmpeg/ffprobe download from GitHub (
-
Security posture: the backend serves loopback HTTP — treat every query/path/form parameter as hostile. User-chosen filesystem destinations are authorized in Electron main (native save dialog), never via HTTP params.
-
CI supply chain: every remote action in
.github/workflows/is pinned to a full 40-char commit SHA with a trailing# vX.Y.Zcomment (tests/test_actions_pinned.py); Dependabot bumps the pins weekly.
VoiceStudio is AGPL-3.0-only, and the maintainer also offers a commercial license (see LICENSE-NOTICE.md). Before a pull request can merge, every non-exempt human contributor — the opener, commit authors and co-authors — signs the Contributor License Agreement once. The checker exempts its configured maintainer and bot account IDs. You keep your copyright. The agreement lets Yupcha Softwares Private Limited, the company that maintains VoiceStudio, ship your work in both the AGPL-3.0 app and commercial builds. In return, the company commits that while your contribution is in the public VoiceStudio repository, it stays available there under AGPL-3.0 or another OSI-approved licence (CLA section 4). AI agents can't be co-authors (see Contributing with AI agents); the person submitting the work signs for it.
For an unsigned pull request, the daily CLA reminder starts a 3-day waiting period, displays its UTC deadline, and sends one reminder halfway through. Signing takes a minute. After the deadline maintainers may independently address the underlying issue without using the contribution. The pull request stays open and signatures remain welcome after the deadline. The timer begins when the reminder first detects an unsigned contributor; a deadline already shown on a pull request (14 days, before this changed) keeps its date.
While the person who opened a pull request has not signed, the CLA check holds
it: it converts the pull request to a draft (CodeRabbit and Greptile skip
drafts) and says so in its comment, with the signing step and a prompt for your
AI coding agent. CI skips its heavy jobs, and the required
Tests (backend + frontend) check reports "CLA not signed yet". The CLA, CLA
gate, commit identity and secret scan checks still run. Once you sign, on the
pull request or the signing issue, the check marks the pull request ready for
review (unless you made it a draft yourself) and re-runs the CI it skipped.
Marking it ready before you sign puts it back to draft. If CI cannot be
restarted yet (a run still in progress), the comment says so; comment
recheck later to retry. Maintainers, bots, and signed openers are never held.
The CLA check comments on your pull request when someone still needs to sign. To sign, post this as a new comment, on its own line:
I have read the VoiceStudio CLA 1.0 and I hereby sign it.
The signature covers your earlier and future contributions. The CLA check
identifies other required signers or cases needing manual review.
New contributors can sign first: post the same line on the
signing issue (#2586)
before opening a pull request, or on the pull request itself if you prefer. The
same signature applies if a maintainer folds your pull request into another one.
If a pull request contains Supersedes #N, its CLA check also covers the
non-exempt human opener, commit authors and co-authors of pull request #N.
Contributed before and have no open pull request? Post
the same line on the issue labelled cla. If it lists a commit it cannot link to a GitHub
account, either add that commit email to your account (Settings → Emails), or
rewrite the commits with an email that is on it (git commit --amend --reset-author, or an interactive rebase) and push again. Comment recheck to
run the check without pushing. Contributing as part of your job? Your employer
signs the Corporate CLA first, and you still sign the CLA
yourself. Adding a Signed-off-by: line (DCO) is appreciated but does not
replace the CLA.
- Stuck on setup? Ask in Discord #help
- Not sure where to start? Check good first issues
- Want to discuss a big change? Open a discussion or Discord thread before coding
Thank you for contributing! 🎙️