# Voice SDK

Source: https://docs.gryt.chat/docs/build/voice

The Gryt voice engine as an npm package

`@gryt/voice` is Gryt's voice engine published on its own. It handles signalling with the SFU, ICE, track management, capture, the audio graph, and the connection state machine. The Gryt client uses it, and so can anything else that runs React.

```bash
npm install @gryt/voice
```

The package is `0.4.2`, AGPL-3.0-only, ESM only, with no runtime dependencies. React 18 or newer is the one peer dependency a web app needs. `react-native-webrtc` 124 or newer is optional, and only the `@gryt/voice/native` entry point uses it.

<Callout type="warn" title="Two things that will cost you an afternoon">
`<VoiceSingletonHooks />` has to be mounted above anything that calls a voice hook, or every hook returns its initial value forever and nothing tells you why. The package also can't be pre-bundled: Vite needs `optimizeDeps: { exclude: ["@gryt/voice"] }`. Both are covered in [Getting started](https://docs.gryt.chat/docs/build/voice-getting-started).
</Callout>

## What it doesn't do

The engine reports and the app decides. That split is what makes the rest of the API legible, so it's worth stating plainly.

It plays no sounds. It raises no toasts and sends no notifications. It doesn't know that servers exist, which ones you have, or which one is on screen. When a call drops after retrying, the engine sets `connectionError` to `"reconnect-failed"` and stops there. Whether that's worth interrupting somebody is a question the engine can't answer.

The Gryt client does all of those things itself, in two small hooks sitting on top of the package. They're worth reading before writing your own: see the [reference implementation](https://docs.gryt.chat/docs/build/voice-getting-started#the-reference-implementation).

## The seams

Five interfaces cover everything the engine can't work out for itself. None of them are guessable from the export list, so they get [a page of their own](https://docs.gryt.chat/docs/build/voice-seams).

`VoiceConfig` is what the person has chosen: device ids, mute state, gain, noise gate, camera quality, STUN hosts. It arrives through `VoiceConfigProvider` and the engine never reaches up for it.

`VoiceHost` answers two questions about the runtime. Is native capture available, and is a plain `ws://` connection to a private address allowed.

`RoomCoordinator` is Gryt's half of joining a channel: asking permission, saying what is being published, reporting peers. You supply it alongside a connection target.

`VoicePlatform` is per-platform capture and peer construction, and the engine uses it. Each entry point registers its own on the way in. The barrel registers the web one, `@gryt/voice/native` registers the React Native one, and `setVoicePlatform` overrides either. A web or Electron embedder supplies nothing and gets the web platform.

`SfuTransport` describes signalling and is still a type nothing consumes. The engine opens its own WebSocket to the SFU, so there's nothing to hand it.

## Where the code is

The package lives at [Gryt-chat/voice](https://github.com/Gryt-chat/voice). The Gryt client is the reference implementation, under `packages/client/src/packages/webRTC/src/adapters`.