> For a complete documentation index, fetch https://docs.voximplant.ai/llms.txt

# Inworld

Inworld provides a real-time TTS player that can send generated audio to calls, WebSockets, and other VoxEngine media units.

Use `Inworld.createRealtimeTTSPlayer(...)` to create a `RealtimeTTSPlayer` for the current scenario. After the player is created, call methods such as `send`, `sendMediaTo`, and `addEventListener` on that player instance.

## Related guides

Use Inworld as the realtime TTS layer in an OpenAI voice pipeline.

See where realtime speech synthesis fits into VoxEngine call flows.

## Contents

*  [Usage](#usage): required module import and basic flow.
*  [Factory functions](#factory-functions): create the realtime TTS player.
*  [RealtimeTTSPlayerParameters](#factory-functions): API key, provider context, and WebSocket options.
*  [RealtimeTTSPlayer](#realtimettsplayer): runtime player object returned by the factory.
*  [Methods](#methods): direct Inworld player methods.
*  [Inherited Methods](#inherited-methods): playback and media methods inherited from the shared player base.
*  [PlayerEvents](#playerevents): player event names and playback lifecycle events.

## Usage

Add the module before using the namespace:

```js
require(Modules.Inworld);
```

Create a player, send provider messages, and bridge playback with `sendMediaTo` or `VoxEngine.sendMediaBetween`.

## Factory functions

###  createRealtimeTTSPlayer

Creates a new [Inworld.RealtimeTTSPlayer](/api-reference/voxengine/inworld#realtimettsplayer) instance. You can attach media streams later via the `Inworld.RealtimeTTSPlayer.sendMediaTo` or `VoxEngine.sendMediaBetween` methods.

```ts
createRealtimeTTSPlayer(parameters?: {
  statistics?: boolean;
  trace?: boolean;
  privacy?: boolean;
  createContextParameters?: Object;
  apiKey?: string;
}): RealtimeTTSPlayer
```

The optional `parameters` object is typed as <code>Inworld.RealtimeTTS<wbr />Player<wbr />Parameters</code>.

**Parameters**

| Parameter                                            | Type                                                   | Req. | Description                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------------------------------------------------- | ------------------------------------------------------ | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters`                                         | <code>RealtimeTTS<wbr />Player<wbr />Parameters</code> | ✗    | [Inworld.RealtimeTTSPlayer](/api-reference/voxengine/inworld#realtimettsplayer) parameters. Can be passed as arguments to the `Inworld.createRealtimeTTSPlayer` method.                                                                                                                                                                                                                               |
| ↳ `statistics`                                       | `boolean`                                              | ✗    | Enables statistics functionality.                                                                                                                                                                                                                                                                                                                                                                     |
| ↳ `trace`                                            | `boolean`                                              | ✗    | Whether to enable the tracing functionality. If tracing is enabled, a URL to the trace file appears in the 'websocket.created' message. The file contains all sent and received WebSocket messages in the plain text format. The file is uploaded to the S3 storage. NOTE: enable this only for diagnostic purposes. You can provide the trace file to our support team to help investigating issues. |
| ↳ `privacy`                                          | `boolean`                                              | ✗    | Whether to enable the privacy functionality. If privacy is enabled, the logging for the WebSocket connection is disabled. NOTE: the default value is **false**.                                                                                                                                                                                                                                       |
| ↳ <code>create<wbr />Context<wbr />Parameters</code> | `Object`                                               | ✗    | Object to provide parameters directly to the Inworld provider Create Context message. Find more information in the `documentation`([https://docs.inworld.ai/api-reference/ttsAPI/texttospeech/synthesize-speech-websocket](https://docs.inworld.ai/api-reference/ttsAPI/texttospeech/synthesize-speech-websocket)).                                                                                   |
| ↳ `apiKey`                                           | `string`                                               | ✗    | Inworld API key. Use your Inworld API key if you have your own Inworld account.                                                                                                                                                                                                                                                                                                                       |

**Returns**

| Type                                  | Description                              |
| ------------------------------------- | ---------------------------------------- |
| <code>RealtimeTTS<wbr />Player</code> | The requested `RealtimeTTSPlayer` value. |

## RealtimeTTSPlayer

## Methods

### &#x20;clearBuffer

Clears an [Inworld.RealtimeTTSPlayer](/api-reference/voxengine/inworld#realtimettsplayer) buffer.

```ts
clearBuffer(): void
```

**Parameters**

This method does not accept parameters.

**Returns**

| Type   | Description              |
| ------ | ------------------------ |
| `void` | Does not return a value. |

### &#x20;send

Send message object to the Inworld provider context.

```ts
send(parameters: Object): void
```

**Parameters**

| Parameter    | Type     | Req. | Description                                                                                                                                                                                                                |
| ------------ | -------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | `Object` | ✓    | Inworld TTS WebSocket message. Common message shapes: send\_text, flush\_context, close\_context.  See the [partner API reference](https://docs.inworld.ai/api-reference/ttsAPI/texttospeech/synthesize-speech-websocket). |

**Returns**

| Type   | Description              |
| ------ | ------------------------ |
| `void` | Does not return a value. |

Example `parameters`:

```json
{
  "send_text": {
    "text": "Hello, what a wonderful day to be a text-to-speech model!",
    "flush_context": {}
  },
  "contextId": "ctx-1"
}
```

## Inherited Methods

`Inworld.RealtimeTTSPlayer` extends the shared player base (`BasePlayer` in the typings). Those base methods use the same playback contract documented on the public [Player](/api-reference/voxengine/player) page, and they emit [PlayerEvents](#playerevents).

#### &#x20;addEventListener

Inherited from the shared player base. See [Player.addEventListener](/api-reference/voxengine/player#addeventlistener).

Adds a handler for the specified [PlayerEvents](/api-reference/voxengine/player-events) event. Use only functions as handlers; anything except a function leads to the error and scenario termination when a handler is called.

```ts
addEventListener(event: PlayerEvents | string, callback: (event: object) => any): void
```

**Parameters**

| Parameter  | Type                                | Req. | Description                                   |
| ---------- | ----------------------------------- | ---- | --------------------------------------------- |
| `event`    | <code>PlayerEvents \| string</code> | ✓    | Event constant or event name to subscribe to. |
| `callback` | <code>(event: object) => any</code> | ✓    | Function called when the event is emitted.    |

**Returns**

| Type   | Description              |
| ------ | ------------------------ |
| `void` | Does not return a value. |

#### &#x20;id

Inherited from the shared player base. See [Player.id](/api-reference/voxengine/player#id).

Returns the player's id.

```ts
id(): string
```

**Parameters**

This method does not accept parameters.

**Returns**

| Type     | Description                 |
| -------- | --------------------------- |
| `string` | The requested string value. |

#### &#x20;pause

Inherited from the shared player base. See [Player.pause](/api-reference/voxengine/player#pause).

Pauses playback. To continue the playback use the `Player.resume` method.

```ts
pause(): void
```

**Parameters**

This method does not accept parameters.

**Returns**

| Type   | Description              |
| ------ | ------------------------ |
| `void` | Does not return a value. |

#### &#x20;removeEventListener

Inherited from the shared player base. See [Player.removeEventListener](/api-reference/voxengine/player#removeeventlistener).

Removes a handler for the specified [PlayerEvents](/api-reference/voxengine/player-events) event.

```ts
removeEventListener(event: PlayerEvents | string, callback?: (event: object) => any): void
```

**Parameters**

| Parameter  | Type                                | Req. | Description                                   |
| ---------- | ----------------------------------- | ---- | --------------------------------------------- |
| `event`    | <code>PlayerEvents \| string</code> | ✓    | Event constant or event name to subscribe to. |
| `callback` | <code>(event: object) => any</code> | ✗    | Function called when the event is emitted.    |

**Returns**

| Type   | Description              |
| ------ | ------------------------ |
| `void` | Does not return a value. |

#### &#x20;resume

Inherited from the shared player base. See [Player.resume](/api-reference/voxengine/player#resume).

Resumes playback after the `Player.pause` method is called.

```ts
resume(): void
```

**Parameters**

This method does not accept parameters.

**Returns**

| Type   | Description              |
| ------ | ------------------------ |
| `void` | Does not return a value. |

#### &#x20;sendMediaTo

Inherited from the shared player base. See [Player.sendMediaTo](/api-reference/voxengine/player#sendmediato).

Starts sending media from the player to the media unit.

```ts
sendMediaTo(mediaUnit: VoxMediaUnit, parameters?: SendMediaParameters): void
```

**Parameters**

| Parameter    | Type                                    | Req. | Description |
| ------------ | --------------------------------------- | ---- | ----------- |
| `mediaUnit`  | `VoxMediaUnit`                          | ✓    |             |
| `parameters` | <code>SendMedia<wbr />Parameters</code> | ✗    |             |

**Returns**

| Type   | Description              |
| ------ | ------------------------ |
| `void` | Does not return a value. |

#### &#x20;stop

Inherited from the shared player base. See [Player.stop](/api-reference/voxengine/player#stop).

Stops playback. The current player's instance is destroyed.

```ts
stop(): void
```

**Parameters**

This method does not accept parameters.

**Returns**

| Type   | Description              |
| ------ | ------------------------ |
| `void` | Does not return a value. |

#### &#x20;stopMediaTo

Inherited from the shared player base. See [Player.stopMediaTo](/api-reference/voxengine/player#stopmediato).

Stops sending media from the player to the media unit.

```ts
stopMediaTo(mediaUnit: VoxMediaUnit): void
```

**Parameters**

| Parameter   | Type           | Req. | Description |
| ----------- | -------------- | ---- | ----------- |
| `mediaUnit` | `VoxMediaUnit` | ✓    |             |

**Returns**

| Type   | Description              |
| ------ | ------------------------ |
| `void` | Does not return a value. |

## PlayerEvents

These are inherited [PlayerEvents](/api-reference/voxengine/player-events). Event callbacks receive the shared player event object; `player` is the `Inworld.RealtimeTTSPlayer` instance that emitted the event. Some events include additional playback fields noted below.

<a id="-created" />

Triggered when [Player](/api-reference/voxengine/player) created.

Event constant: `PlayerEvents.Created`

**Payload**

| Field    | Type                                  | Req. | Description                                                                          |
| -------- | ------------------------------------- | ---- | ------------------------------------------------------------------------------------ |
| `player` | <code>RealtimeTTS<wbr />Player</code> | ✓    | The [Inworld.RealtimeTTSPlayer](#realtimettsplayer) instance that emitted the event. |

<a id="-playbackready" />

Triggers by the `createURLPlayer` and `createTTSPlayer` methods when

1. the audio file download to the Voximplant cache is finished;
2. the audio file is found in the cache (i.e., it is in the cache before).

Event constant: `PlayerEvents.PlaybackReady`

**Payload**

| Field    | Type                                  | Req. | Description                                                                          |
| -------- | ------------------------------------- | ---- | ------------------------------------------------------------------------------------ |
| `player` | <code>RealtimeTTS<wbr />Player</code> | ✓    | The [Inworld.RealtimeTTSPlayer](#realtimettsplayer) instance that emitted the event. |

<a id="-started" />

Triggered when playback is started. Note that if the `createURLPlayer` method is called with the **onPause** parameter set to true, the event is not triggered; it is triggered after the `Player.resume` method call.

Event constant: `PlayerEvents.Started`

**Payload**

| Field      | Type                                  | Req. | Description                                                                          |
| ---------- | ------------------------------------- | ---- | ------------------------------------------------------------------------------------ |
| `player`   | <code>RealtimeTTS<wbr />Player</code> | ✓    | The [Inworld.RealtimeTTSPlayer](#realtimettsplayer) instance that emitted the event. |
| `duration` | `number`                              | ✓    | Playback duration                                                                    |

<a id="-stopped" />

Triggers as a result of the `Player.stop` method call.

Event constant: `PlayerEvents.Stopped`

**Payload**

| Field    | Type                                  | Req. | Description                                                                          |
| -------- | ------------------------------------- | ---- | ------------------------------------------------------------------------------------ |
| `player` | <code>RealtimeTTS<wbr />Player</code> | ✓    | The [Inworld.RealtimeTTSPlayer](#realtimettsplayer) instance that emitted the event. |

<a id="-playbackfinished" />

Triggered when playback has finished successfully or with an error.

Event constant: `PlayerEvents.PlaybackFinished`

**Payload**

| Field    | Type                                  | Req. | Description                                                                          |
| -------- | ------------------------------------- | ---- | ------------------------------------------------------------------------------------ |
| `player` | <code>RealtimeTTS<wbr />Player</code> | ✓    | The [Inworld.RealtimeTTSPlayer](#realtimettsplayer) instance that emitted the event. |
| `error`  | `string`                              | ✗    | Error message                                                                        |

<a id="-error" />

Triggered when playback has finished with an error.

Event constant: `PlayerEvents.Error`

**Payload**

| Field    | Type                                  | Req. | Description                                                                          |
| -------- | ------------------------------------- | ---- | ------------------------------------------------------------------------------------ |
| `player` | <code>RealtimeTTS<wbr />Player</code> | ✓    | The [Inworld.RealtimeTTSPlayer](#realtimettsplayer) instance that emitted the event. |
| `error`  | `string`                              | ✓    | Error message                                                                        |

<a id="-playbackmarkerreached" />

Triggered when `Player.addMarker` is reached.

Event constant: `PlayerEvents.PlaybackMarkerReached`

**Payload**

| Field    | Type                                  | Req. | Description                                                                          |
| -------- | ------------------------------------- | ---- | ------------------------------------------------------------------------------------ |
| `player` | <code>RealtimeTTS<wbr />Player</code> | ✓    | The [Inworld.RealtimeTTSPlayer](#realtimettsplayer) instance that emitted the event. |
| `offset` | `number`                              | ✓    | The marker offset                                                                    |

<a id="-playbackbuffering" />

Triggered when an audio file is playing faster than it is being loaded.

Event constant: `PlayerEvents.PlaybackBuffering`

**Payload**

| Field    | Type                                  | Req. | Description                                                                          |
| -------- | ------------------------------------- | ---- | ------------------------------------------------------------------------------------ |
| `player` | <code>RealtimeTTS<wbr />Player</code> | ✓    | The [Inworld.RealtimeTTSPlayer](#realtimettsplayer) instance that emitted the event. |

<a id="-audiochunksplaybackfinished" />

Triggered when an audio chunk playback is finished. Note that this event is triggered only for RealtimeTTSPlayer instances.

Event constant: `PlayerEvents.AudioChunksPlaybackFinished`

**Payload**

| Field                               | Type                                  | Req. | Description                                                                                                                             |
| ----------------------------------- | ------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `player`                            | <code>RealtimeTTS<wbr />Player</code> | ✓    | The [Inworld.RealtimeTTSPlayer](#realtimettsplayer) instance that emitted the event.                                                    |
| <code>timeToFirst<wbr />Byte</code> | `number`                              | ✓    | Time to first byte (TTFB) in milliseconds. Represents the delay between sending the request and receiving the first byte of audio data. |