# 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; retained static client |
| [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 existing Docker image still serves the retained static client. To build it,
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)