FabienDanieau/reachy-mini-minimal-js-conversation-app

Reachy Mini · Minimal Conversation (JS)

A tiny TypeScript webapp that turns a Reachy Mini robot into a live voice companion powered by the OpenAI Realtime API - no Python backend, no transcript panel, no chat UI. Just one big central circle that walks you through login → connect → start.

Built on top of:

• —The `pollen-robotics/reachy_mini` JS SDK (loaded from jsDelivr, same approach as the official webrtc_example).
• —The OpenAI Realtime WebRTC API.
• —Vite + TypeScript for a zero-config dev server and a static build.

Audio routing (robot = hub)

 ┌────────┐   robot mic   ┌────────┐ input track ┌───────────┐
 │ Reachy │ ────────────► │ Browser│ ──────────► │  OpenAI   │
 │  Mini  │               │ (this  │             │ Realtime  │
 │ daemon │ ◄──────────── │  app)  │ ◄────────── │    API    │
 └────────┘  robot speaker └────────┘ output track └───────────┘

• —The robot's microphone track comes in on the WebRTC peer managed by the SDK. We pull it out via robot._pc.getReceivers() and feed it straight into a second RTCPeerConnection pointed at OpenAI.
• —OpenAI's synthesized voice comes back as a remote audio track. We replaceTrack() it onto the robot's audio sender so the voice plays through Reachy Mini's speakers.

Prerequisites

• —Node.js 18+
• —A Hugging Face account (for robot signaling)
• —A Reachy Mini robot online on the signaling server
• —An OpenAI API key with Realtime access (docs)

Hugging Face OAuth

Deployed on a Space, OAuth "just works" - HF auto-provisions an OAuth app from the hf_oauth: true flag in this README and injects the client ID into the page at serve time.

For local dev you need to register your own OAuth app once:

1. 1.Go to <https://huggingface.co/settings/applications/new>.
2. 2.Fill in:
3. 3.App name: Reachy Mini Minimal Conversation (local) (or whatever).
4. 4.Homepage URL: http://localhost:5173
5. 5.Logo URL: leave empty.
6. 6.Scopes: check at least openid and profile.
7. 7.Redirect URIs: http://localhost:5173
8. 8.Click Create application. Copy the Client ID (looks like a UUID).
9. 9.Open the app, click the gear icon, paste the client ID into the "Hugging Face OAuth client ID" field, then Save.
10. 10.Click the central circle to sign in.

Run

npm install
npm run dev

Then open the printed URL (usually <http://localhost:5173>). First-time setup on localhost:

1. 1.Click the gear icon (top right) → paste your HF OAuth client ID and your OpenAI API key → Save.
2. 2.Now walk through the three clicks on the central circle:
3. 3.Sign in with Hugging Face - OAuth redirect.
4. 4.Connect - opens the SSE signaling channel and lists robots.
5. 5.Click a robot in the list, then Start.

When deployed to a Hugging Face Space, the OAuth client ID is provided automatically by the Space runtime - you can leave that field empty.

The OpenAI key is stored in localStorage and sent only as a Bearer token to api.openai.com/v1/realtime. For public deployments, swap this for an ephemeral token minted by a tiny backend.

Once streaming, the circle animates:

• —cyan · listening (silent) or user speaking
• —purple · Reachy is answering
• —red · something went wrong (click to retry)

Settings

The gear icon lets you change:

• —OpenAI API key (stored locally, never leaves the browser except as Authorization header).
• —Model (default gpt-realtime).
• —Voice (cedar, alloy, verse, ...).
• —System instructions (short prompt that shapes the robot's personality).

Build

npm run build
npm run preview

This produces a fully static dist/ folder that can be served from any HTTP host (Hugging Face Space, Vercel, Cloudflare Pages, GitHub Pages behind a static server, ...).

Limitations

• —The app assumes the robot reports micSupported=true (bidirectional audio). Older daemon versions won't expose a send-receive audio section in their SDP and the OpenAI voice won't reach the speakers.
• —The OpenAI API key lives in the browser - fine for personal demos, not for public deployments.
• —There is no fallback to the browser's own microphone/speakers. If the robot session fails, the circle turns red and you can retry.

License

MIT for this glue code. The underlying SDKs keep their respective licenses - see the pollen-robotics and OpenAI projects.