# Vocero speech-to-speech

Vocero provides a browser voice interface, a Python speech pipeline, and an
optional Node-RED reasoning service. The interface defaults to Spanish;
documentation, source identifiers, comments, and internal instructions use English.

| Component | Purpose |
|---|---|
| [s2s-frontend](s2s-frontend) | React, TypeScript, and Tailwind browser UI, served by Vite with hot reload |
| [s2s-client](s2s-client) | 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 |
| [s2s-reasoning-engine](s2s-reasoning-engine) | Optional Node-RED HTTP reasoning and conversation logging flows |

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;
`s2s-client/requirements.txt` 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
`.venv`, installs missing Python requirements and locked 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 Python 3 with venv support, 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](s2s-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 s2s-client/Dockerfile -t s2s-client .
docker run --rm -p 7860:7860 \
  -e SPEECH_TO_SPEECH_URL=ws://localhost:8765/v1/realtime s2s-client
```

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](s2s-client/CHANGELOG.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)