{"id":50607088,"url":"https://github.com/arach/vox","last_synced_at":"2026-06-06T00:03:30.177Z","repository":{"id":344964877,"uuid":"1183849314","full_name":"arach/vox","owner":"arach","description":"Local-first macOS transcription runtime with Swift services, a Bun CLI, and a TypeScript SDK.","archived":false,"fork":false,"pushed_at":"2026-06-03T19:17:09.000Z","size":37718,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-03T20:10:18.117Z","etag":null,"topics":["bun","developer-tools","local-first","macos","speech-to-text","swift","transcription","typescript"],"latest_commit_sha":null,"homepage":"https://voxd.cc/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arach.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-17T02:22:00.000Z","updated_at":"2026-06-03T19:17:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/arach/vox","commit_stats":null,"previous_names":["arach/vox"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/arach/vox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arach%2Fvox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arach%2Fvox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arach%2Fvox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arach%2Fvox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arach","download_url":"https://codeload.github.com/arach/vox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arach%2Fvox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33964367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","developer-tools","local-first","macos","speech-to-text","swift","transcription","typescript"],"created_at":"2026-06-06T00:03:29.719Z","updated_at":"2026-06-06T00:03:30.169Z","avatar_url":"https://github.com/arach.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vox\n\nVox is a local-first voice stack for Apple platforms. This repo brings together the Hudson-powered menu bar app, the Swift runtime, the companion daemon, the TypeScript clients, and the CLI.\n\n- `VoxCore`, `VoxEngine`, `VoxService`, and `VoxBridge`: embeddable Swift packages for macOS and iOS apps.\n- `voxd`: Vox Companion, the Swift daemon for web-facing, shared-process, and operator integrations.\n- `@voxd/sdk`: TypeScript SDK. Typed JSON-RPC client for Vox Companion integrations.\n- `@voxd/client`: Browser SDK. HTTP bridge client for local web integrations.\n- `vox`: Node CLI. Health checks, benchmarks, warm-up scheduling, dashboards.\n- `Vox.app`: Hudson-based macOS menu bar app, packaged as a signed and notarized DMG by release automation.\n\nApple apps can embed Vox directly. Bun and Node tools can connect to `voxd` over local WebSocket JSON-RPC. Browser clients can connect through the companion HTTP bridge with `@voxd/client`.\n\n## Pick a surface\n\n- Build a native Apple app: start with `VoxCore`, `VoxEngine`, `VoxService`, and `VoxBridge`.\n- Build a local tool or companion-connected service: start with `voxd` plus `@voxd/sdk`.\n- Build a browser integration: start with `@voxd/client` plus the local bridge path.\n- Operate or benchmark Vox itself: start with the `vox` CLI.\n\n## Get Going Fast\n\nRequirements:\n\n- macOS 14+ for the Swift transcription packages; macOS 26+ for the Hudson menu app and demo flows that use Apple Intelligence\n- Bun 1.2+\n- Node 22+\n- Swift 6.2+\n- `uv` for the MLX-backed demo paths\n\n### a. dev\n\nTo work on Vox:\n\n```bash\ngit clone https://github.com/arach/vox.git\ncd vox\nbun install\nbun run build\nbun run test\n```\n\nUseful loops:\n\n```bash\nbun run site:dev\nbun run docs:build\nswift build --package-path swift\n```\n\n### b. client\n\nTo use Vox Companion locally from the CLI or SDK:\n\n```bash\ngit clone https://github.com/arach/vox.git\ncd vox\nbun install\nbun run build\n```\n\nStart the daemon, verify health, then transcribe:\n\n```bash\nnode packages/cli/dist/index.js daemon start\nnode packages/cli/dist/index.js doctor\nnode packages/cli/dist/index.js models preload parakeet:v3\nnode packages/cli/dist/index.js transcribe file /path/to/audio.wav\n```\n\nIf you are writing a local client, start here:\n\n- `packages/client/` for the TypeScript SDK\n- `packages/web-client/` for the browser SDK\n- `swift/` for direct Apple embed mode\n\n### c. demo\n\nTo run the standalone macOS demo app:\n\n```bash\ngit clone https://github.com/arach/vox.git\ncd vox\nbun install\nswift run --package-path examples/macos-minimal VoxMinimalExample\n```\n\nWhat the demo does:\n\n- records locally from the mic\n- transcribes with Parakeet\n- replies with Apple Intelligence when available\n- falls back to local Qwen 0.6B when Apple Intelligence is not ready\n- speaks back with Kokoro through the MLX audio provider\n\nNotes:\n\n- The first run may download Parakeet, Kokoro, or the Qwen fallback model.\n- The app will ask for microphone access.\n- Apple Intelligence is optional for the demo, not required.\n\nThe current standalone demo lives in `examples/macos-minimal/` and is a good reference app for direct embed mode.\n\n## Layout\n\n- `swift/` contains `VoxCore`, `VoxEngine`, `VoxService`, and the `voxd` daemon.\n- `packages/client` contains the TypeScript SDK for talking to `voxd` over local WebSocket JSON-RPC.\n- `packages/web-client` contains the browser SDK for talking to the local HTTP bridge.\n- `packages/cli` contains the `vox` CLI.\n- `docs/` contains Dewey source docs.\n- `site/` contains the marketing site, docs route, and OG generation.\n\n## Commands\n\n```bash\nbun install\nbun run dev\nbun run build\nbun run build:all\nbun run test\nbun run test:e2e\nbun run site:build\nbun run site:og\nbun run docs:generate\n```\n\n## Telemetry\n\nEach transcription or synthesis request appends a tagged sample to `~/.vox/performance.jsonl` with `clientId`, `route`, `modelId`, and `voiceId` when applicable.\n\nThis lets you answer a few practical questions: is the hot model fast, which integration is regressing, and whether latency is in inference, audio prep, or cold runtime work.\n\n### CLI\n\n```bash\nvox daemon start\nvox doctor\nvox models list\nvox models install\nvox warmup start\nvox warmup schedule 500\nvox logs daemon --tail 80\nvox transcribe status\nvox transcribe cancel\nvox transcribe file --timestamps /path/to/audio.wav\nvox transcribe bench /path/to/audio.wav 5\nvox perf dashboard\nvox transcribe live --timestamps\n```\n\n## Companion Runtime\n\n- Runtime discovery: `~/.vox/runtime.json`\n- Latency samples: `~/.vox/performance.jsonl`\n- Daemon logs: `~/.vox/logs/voxd.log` (written even when `voxd` is auto-started by the CLI)\n\n`voxd` is Vox Companion: the shared-process and web-facing transport for Vox. `bun run test:e2e` is an opt-in macOS integration suite that boots `voxd`, preloads the model, synthesizes speech with `say`, and checks `transcribe file` output against keyword expectations.\n\nSpeech synthesis supports Apple system voices locally and OpenAI TTS (`gpt-4o-mini-tts`, `tts-1`, and `tts-1-hd`) when `OPENAI_API_KEY` is configured. The packaged app bundles `voxd` and `voxttsd` so the menu bar app and CLI share the same companion runtime.\n\n## Docs and site\n\n- Dewey source docs: `docs/`\n- Generated handoff files: `AGENTS.md`, `llms.txt`, `docs.json`, `install.md`\n- Website and `/docs` route: `site/`\n- OG image template: `site/og-template.html`\n\n## Release automation\n\n- GitHub Pages deploys from `.github/workflows/deploy-pages.yml` to `https://voxd.cc`\n- npm publishing runs from `.github/workflows/publish-packages.yml` on `v*` tags and publishes `@voxd/sdk`, `@voxd/client`, and `@voxd/cli`\n- DMG builds run from `.github/workflows/release-dmg.yml`. Tag builds create or update the matching GitHub Release and upload `Vox.dmg`.\n- Manual DMG releases can be started from the workflow page with a version. The workflow validates the repo versions, builds the DMG, signs and notarizes it, creates `v\u003cversion\u003e` when needed, creates the GitHub Release, and uploads the installer.\n\nRequired release secrets:\n\n- `DEVELOPER_ID_APPLICATION_CERT_BASE64`\n- `DEVELOPER_ID_APPLICATION_CERT_PASSWORD`\n- `KEYCHAIN_PASSWORD`\n- `APP_STORE_CONNECT_API_KEY_P8`\n- `APP_STORE_CONNECT_KEY_ID` and `APP_STORE_CONNECT_ISSUER_ID` as repository variables, or secrets if needed\n- `HUDSON_READ_TOKEN` for the private SwiftPM dependency used by the macOS app bundle\n- `NPM_TOKEN` in the `PRODUCTION` environment for package publishing\n\nThe DMG workflow also accepts the older Apple ID notarization secrets (`APPLE_ID`, `APPLE_APP_PASSWORD`, and `APPLE_TEAM_ID`) as a fallback, plus the legacy certificate names (`APPLE_SIGNING_CERT_BASE64` and `APPLE_SIGNING_CERT_PASSWORD`).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farach%2Fvox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farach%2Fvox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farach%2Fvox/lists"}