Labyricorn/voicebox
1
0
Fork 0
mirror of https://github.com/jamiepine/voicebox.git synced 2026-09-16 13:20:39 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs: refresh contributor docs and drop root requirements.txt

Browse Source 
CONTRIBUTING.md caught up with reality: ruff not Black, Python 3.12,
sh.voicebox.app, the routes/services/backends layout, the actual
pytest + CI story, and a working autoupdater link. SECURITY.md now
says 0.5.x and describes what CI actually enforces. The root
requirements.txt was vestigial (unpinned, included torchvision,
referenced by nothing) — deleted, with two stale doc references
repointed at backend/requirements.txt. backend/pyproject.toml is now
covered by bumpversion; its version was stuck at 0.2.3 and is synced
to 0.5.0.
This commit is contained in:
Jamie Pine
2026-07-26 23:17:34 -07:00
parent f2e55ba50f
commit 827ce2bf0a
8 changed files with 40 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.bumpversion.cfg
+4
View File
@@ -37,3 +37,7 @@ replace = "version": "{new_version}"
[bumpversion:file:backend/__init__.py]
search = __version__ = "{current_version}"
replace = __version__ = "{new_version}"
[bumpversion:file:backend/pyproject.toml]
search = version = "{current_version}"
replace = version = "{new_version}"
CONTRIBUTING.md
+24 -26
View File
@@ -18,9 +18,9 @@ Thank you for your interest in contributing to Voicebox! This document provides
curl -fsSL https://bun.sh/install | bash
```
- **[Python 3.11+](https://python.org)** - For backend development
- **[Python 3.12+](https://python.org)** - For backend development
```bash
python --version # Should be 3.11 or higher
python --version # Should be 3.12 or higher
```
- **[Rust](https://rustup.rs)** - For Tauri desktop app (installed automatically by Tauri CLI)
@@ -91,7 +91,7 @@ On Windows, to build with CUDA support for local testing:
just build-local # Build CPU + CUDA server binaries + Tauri installer
```
This builds the CPU sidecar (bundled with the app), the CUDA binary (placed in `%APPDATA%/com.voicebox.app/backends/` for runtime GPU switching), and the installable Tauri app.
This builds the CPU sidecar (bundled with the app), the CUDA binary (placed in `%APPDATA%/sh.voicebox.app/backends/` for runtime GPU switching), and the installable Tauri app.
Creates platform-specific installers (`.dmg`, `.msi`, `.AppImage`) in `tauri/src-tauri/target/release/bundle/`.
@@ -115,14 +115,6 @@ just build-server
This makes PyInstaller use your local qwen-tts version instead of the pip-installed package.
### Generate OpenAPI Client
After starting the backend server:
```bash
./scripts/generate-api.sh
```
This downloads the OpenAPI schema and generates the TypeScript client in `app/src/lib/api/`
### Convert Assets to Web Formats
To optimize images and videos for the web, run:
@@ -212,7 +204,7 @@ export const ProfileCard = (props) => { ... }
- Follow PEP 8 style guide
- Use type hints
- Use async/await for I/O operations
- Format with Black (if configured)
- Format and lint with ruff (configured in `backend/pyproject.toml`)
```python
# Good
@@ -242,9 +234,12 @@ voicebox/
│ ├── lib/ # Utilities and API client
│ └── hooks/ # React hooks
├── backend/ # Python FastAPI server
│ ├── main.py # API routes
│ ├── tts.py # Voice synthesis
│ └── ...
│ ├── main.py # Entry point (FastAPI app assembled in app.py)
│ ├── routes/ # API routers, one per domain
│ ├── services/ # Business logic (generation, transcription, profiles, ...)
│ ├── backends/ # TTS engine implementations
│ ├── database/ # SQLAlchemy models, sessions, migrations
│ └── tests/ # pytest suite
├── tauri/ # Desktop app wrapper
│ └── src-tauri/ # Rust backend
└── scripts/ # Build scripts
@@ -289,23 +284,26 @@ voicebox/
When adding new API endpoints:
1. **Add route in `backend/main.py`**
1. **Add the route to the relevant router in `backend/routes/`** (new routers get registered in `backend/routes/__init__.py`)
2. **Create Pydantic models in `backend/models.py`**
3. **Implement business logic in appropriate module**
4. **Update OpenAPI schema** (automatic with FastAPI)
5. **Regenerate TypeScript client:**
```bash
bun run generate:api
```
5. **Update the TypeScript client** — add matching types to `app/src/lib/api/types.ts` and a method to `app/src/lib/api/client.ts`
6. **Update `backend/README.md`** with endpoint documentation
## Testing
Currently, testing is primarily manual. When adding tests:
Backend tests live in `backend/tests/` and run with pytest:
- **Backend**: Use pytest for Python tests
- **Frontend**: Use Vitest for React component tests
- **E2E**: Use Playwright for end-to-end tests (future)
```bash
cd backend
venv/bin/python -m pytest tests
```
CI runs the backend test suite on every PR, along with frontend lint and typecheck (`bun run lint`, `bun run typecheck`) and a `cargo check` of the Tauri app (see `.github/workflows/ci.yml`). Add backend tests alongside your changes where it makes sense.
- **Frontend**: Vitest for React component tests (coverage is still sparse — contributions welcome)
- **E2E**: Playwright for end-to-end tests (future)
## Pull Request Process
@@ -363,7 +361,7 @@ See [docs/content/docs/overview/troubleshooting.mdx](docs/content/docs/overview/
**Quick fixes:**
- **Backend won't start:** Check Python version (3.11+), ensure venv is activated, install dependencies
- **Backend won't start:** Check Python version (3.12+), ensure venv is activated, install dependencies
- **Tauri build fails:** Ensure Rust is installed, clean build with `cd tauri/src-tauri && cargo clean`
- **OpenAPI client generation fails:** Ensure backend is running, check `curl http://localhost:17493/openapi.json`
@@ -379,7 +377,7 @@ See [docs/content/docs/overview/troubleshooting.mdx](docs/content/docs/overview/
- [README.md](README.md) - Project overview
- [backend/README.md](backend/README.md) - API documentation
- [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md) - Living engineering roadmap: architecture, shipped vs in-flight work, prioritized open issues, candidate TTS engines under evaluation, architectural bottlenecks. Keep this updated when you ship significant features, close or backlog a model integration, or identify new bottlenecks.
- [docs/AUTOUPDATER_QUICKSTART.md](docs/AUTOUPDATER_QUICKSTART.md) - Auto-updater setup
- [docs/content/docs/developer/autoupdater.mdx](docs/content/docs/developer/autoupdater.mdx) - Auto-updater setup (published at [voicebox.sh docs](https://voicebox.sh/docs/developer/autoupdater))
- [SECURITY.md](SECURITY.md) - Security policy
- [CHANGELOG.md](CHANGELOG.md) - Version history
SECURITY.md
+4 -4
View File
@@ -6,8 +6,8 @@ We release patches for security vulnerabilities. Which versions are eligible for
| Version | Supported |
| ------- | ------------------ |
| 0.3.x | :white_check_mark: |
| < 0.3 | :x: |
| 0.5.x | :white_check_mark: |
| < 0.5 | :x: |
## Reporting a Vulnerability
@@ -39,7 +39,7 @@ We will:
### For Developers
- **Dependencies** - Keep all dependencies up to date
- **Code review** - All PRs require review before merging
- **CI checks** - Every PR must pass typecheck, lint, backend tests, and `cargo check` before merging
- **Secrets** - Never commit API keys or signing keys
- **Signing** - All releases are cryptographically signed
@@ -82,7 +82,7 @@ Timeline may vary based on severity and complexity.
## Security Updates
Security updates will be:
- Released as patch versions (e.g., 0.3.2)
- Released as patch versions (e.g., 0.5.1)
- Documented in CHANGELOG.md
- Announced via GitHub releases
- Automatically delivered via auto-updater
docs/content/docs/developer/contributing.mdx
+2 -14
View File
@@ -258,20 +258,8 @@ When adding new API endpoints:
```
</Step>
<Step title="Regenerate Client">
```bash
just generate-api
```
This updates the TypeScript client with type-safe bindings.
</Step>
<Step title="Update Docs">
The API documentation is automatically generated from the OpenAPI schema. Ensure your endpoint has proper docstrings and type hints, then regenerate the docs:
```bash
just generate-api
```
<Step title="Update the Frontend Client">
The TypeScript client is hand-written. Add matching types to `app/src/lib/api/types.ts` and a method to `app/src/lib/api/client.ts`. The backend's live schema at `http://localhost:17493/docs` is the reference.
</Step>
</Steps>
docs/content/docs/developer/setup.mdx
+5 -12
View File
@@ -32,7 +32,7 @@ Ensure you have these installed:
curl -fsSL https://bun.sh/install | bash
```
</Card>
<Card title="Python 3.11+" icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12 2L2 7l10 5 10-5-10-5z"/><path d="M2 17l10 5 10-5"/><path d="M2 12l10 5 10-5"/></svg>}>
<Card title="Python 3.12+" icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12 2L2 7l10 5 10-5-10-5z"/><path d="M2 17l10 5 10-5"/><path d="M2 12l10 5 10-5"/></svg>}>
[Download Python](https://python.org)
```bash
python --version
@@ -111,7 +111,6 @@ Run `just --list` to see all available commands. Highlights:
| Command | Description |
|---------|-------------|
| `just generate-api` | Generate TypeScript API client from the backend's OpenAPI schema |
| `just docs` | Open `http://localhost:17493/docs` in your browser |
| `just logs` | Tail backend logs |
| `just clean` | Remove build artifacts |
@@ -184,15 +183,9 @@ See [Model Management](/developer/model-management) for the full list.
First-time usage will be slower due to model downloads, but subsequent runs will use cached models.
</Callout>
## Generate OpenAPI Client
## Frontend API Client
After starting the backend server, generate the TypeScript API client:
```bash
just generate-api
```
This downloads the OpenAPI schema and generates the TypeScript client in `app/src/lib/api/`.
The TypeScript API client is hand-written: request/response types live in `app/src/lib/api/types.ts` and the fetch wrapper in `app/src/lib/api/client.ts`. When you add or change a backend endpoint, update both to match. The backend's live schema at `http://localhost:17493/docs` is the reference.
## Manual Setup (Advanced)
@@ -277,9 +270,9 @@ bun run tauri dev
<AccordionGroup>
<Accordion title="Backend won't start">
- Check Python version (must be 3.11+)
- Check Python version (must be 3.12+)
- Ensure virtual environment is activated: `source backend/venv/bin/activate`
- Verify all dependencies are installed: `pip install -r requirements.txt`
- Verify all dependencies are installed: `pip install -r backend/requirements.txt`
- Check if port 17493 is available
</Accordion>
docs/content/docs/overview/troubleshooting.mdx
-33
View File
@@ -355,39 +355,6 @@ cd ../..
bun run tauri build
```
### OpenAPI Client Generation Fails
**Symptoms:**
- `./scripts/generate-api.sh` fails
- "Failed to fetch schema" error
**Solutions:**
<Steps>
<Step title="Ensure Backend is Running">
```bash
curl http://localhost:17493/openapi.json
```
Should return JSON. If not, start the backend.
</Step>
<Step title="Check Port">
Ensure nothing else is using port 17493
</Step>
<Step title="Regenerate Manually">
```bash
cd backend
source venv/bin/activate
uvicorn main:app --reload --port 17493
# In another terminal
./scripts/generate-api.sh
```
</Step>
</Steps>
## Database Issues
### "Database is locked" Error
docs/plans/DOCKER_DEPLOYMENT.md
+1 -1
View File
@@ -90,7 +90,7 @@ RUN apt-get update && apt-get install -y \
# Copy application
COPY backend/ /app/backend/
COPY requirements.txt /app/
COPY backend/requirements.txt /app/
# Install Python dependencies
RUN pip install --no-cache-dir -r requirements.txt
requirements.txt
-9
View File
@@ -1,9 +0,0 @@
uvicorn
fastapi
sqlalchemy
torch
torchvision
soundfile
librosa
python-multipart
huggingface_hub