| name | gradium-sdk |
| description | Teaches the agent how to use the Gradium AI real-time speech-to-text WebSocket API from TypeScript/JavaScript. Use when wiring voice transcription directly against the Gradium protocol. For browser use in this project, prefer the `@agsk/lib-gradium` wrapper — this skill documents the underlying protocol. |
Gradium AI (raw WebSocket protocol)
Use this skill when implementing a Gradium STT client from scratch, or when debugging one. In this repo the browser-side SDK at libs/lib-gradium/ already implements this — prefer importing it (@agsk/lib-gradium) unless you specifically need to talk to Gradium directly.
Endpoint
wss://us.api.gradium.ai/api/speech/asr
Authentication
Gradium requires an HTTP header on the WebSocket upgrade:
x-api-key: <GRADIUM_API_KEY>
Important: browser WebSocket cannot set custom headers. Only Node or native clients can. From a browser, you must route through a Node proxy that accepts a local WebSocket and re-opens to Gradium with the header — see libs/lib-gradium/demo/vite.config.ts for a 40-line reference proxy.
Verified as the only working auth method — query param, subprotocol, and setup-message payloads are all rejected with "No authentication provided".
Audio format
- PCM 16-bit signed little-endian, mono, 24 kHz
- Frames must be exactly 1920 samples = 3840 bytes = 80 ms
- Each frame is base64-encoded and wrapped in a JSON message
Do not use MediaRecorder — it only emits containerized opus/webm, never raw PCM. Use AudioContext + AudioWorklet to capture Float32 samples and convert to Int16.
