alvaro
abd03ed07d
Rename the project directories, Python distribution and import package, and npm package. Update launcher, Docker, tooling, tests, lockfiles, and documentation while preserving existing API contracts. Make AGENTS.md self-contained and remove external skill and workflow references.
60 lines
2.8 KiB
Markdown
60 lines
2.8 KiB
Markdown
# Vocero speech-to-speech
|
|
|
|
Vocero provides a browser voice interface, a FastAPI integration server, and a
|
|
Python speech pipeline. The interface defaults to Spanish;
|
|
documentation, source identifiers, comments, and internal instructions use English.
|
|
|
|
| Component | Purpose |
|
|
|---|---|
|
|
| [vocero-frontend](vocero-frontend) | React, TypeScript, and Tailwind browser UI, served by Vite with hot reload |
|
|
| [vocero-api](vocero-api) | FastAPI backend, realtime WebSocket proxy, search and ApiPilot bridges |
|
|
| [speech_to_speech](speech_to_speech) | Queue-driven VAD, speech recognition, language model, and speech synthesis pipeline |
|
|
|
|
Start with [client setup and usage](docs/client/usage.md), then read the
|
|
[architecture](docs/client/architecture.md) and [documentation index](docs/README.md).
|
|
The speech backend needs its own installed model and runtime dependencies;
|
|
The uv project in `vocero-api/` installs only the UI server dependencies.
|
|
|
|
## Run the browser client
|
|
|
|
From the repository root, point the client at an existing realtime backend:
|
|
|
|
```bash
|
|
S2S_PROXY_TARGET=ws://localhost:8765/v1/realtime ./start_ui.sh
|
|
```
|
|
|
|
Open <http://localhost:8420/> and allow microphone access. The launcher creates
|
|
`vocero-api/.venv`, syncs locked Python and frontend dependencies,
|
|
and loads the root `.env` if present. Vite listens on `UI_PORT` (default `8420`)
|
|
and forwards HTTP/WebSocket backend routes to FastAPI on `127.0.0.1:8421`.
|
|
Both servers reload during development; stopping the launcher stops both.
|
|
Leave `SPEECH_TO_SPEECH_URL` unset to use the same-origin speech proxy.
|
|
|
|
The launcher requires uv 0.12.5 (which provisions Python 3.12), Node.js 22.18+ on the 22.x
|
|
line or Node.js 24+, npm, Bash 4.4+, `setsid`, and `curl`. For staging hostnames,
|
|
set `S2S_DEV_ALLOWED_HOSTS` and forward the Vite HMR WebSocket through the existing
|
|
HTTPS reverse proxy. See [development setup](vocero-frontend/README.md).
|
|
|
|
The Docker image serves backend routes and shared documentation. The React
|
|
frontend runs separately through Vite. To build the backend image, use the
|
|
repository root as the Docker build context so documentation is included:
|
|
|
|
```bash
|
|
docker build -f vocero-api/Dockerfile -t vocero-api .
|
|
docker run --rm -p 7860:7860 \
|
|
-e SPEECH_TO_SPEECH_URL=ws://localhost:8765/v1/realtime vocero-api
|
|
```
|
|
|
|
The direct WebSocket URL is resolved by the user's browser. For a server-side
|
|
proxy deployment, supply a backend address reachable from the container instead.
|
|
|
|
## Project references
|
|
|
|
- [Change history](vocero-api/CHANGELOG.md)
|
|
- [Backend development and compatibility](docs/client/development.md)
|
|
- [Realtime protocol and pipeline](docs/speech/realtime-api.md)
|
|
- [Context injection](docs/client/context-injection.md)
|
|
- [Tool calling](docs/client/tool-calling.md)
|
|
- [Troubleshooting](docs/client/troubleshooting.md)
|
|
- [Historical architecture proposal](docs/proposals/vocero-architecture.html)
|