# 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)