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.
2.8 KiB
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 | React, TypeScript, and Tailwind browser UI, served by Vite with hot reload |
| vocero-api | FastAPI backend, realtime WebSocket proxy, search and ApiPilot bridges |
| speech_to_speech | Queue-driven VAD, speech recognition, language model, and speech synthesis pipeline |
Start with client setup and usage, then read the
architecture and documentation index.
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:
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.
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:
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.