Inworld | Voximplant Voice AI

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.

OpenAI with Inworld TTS

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

Realtime TTS pattern

See where realtime speech synthesis fits into VoxEngine call flows.

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

Usage

Add the module before using the namespace:

require(Modules.Inworld);

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

Factory functions

createRealtimeAPIClient

Creates a new Inworld.RealtimeAPIClient instance.

createRealtimeAPIClient(parameters: {
  statistics?: boolean;
  trace?: boolean;
  privacy?: boolean;
  onWebSocketClose?: (event: object) => void;
  apiKey: string;
  sessionKey: string;
  authScheme?: string;
}): Promise<Inworld.RealtimeAPIClient>

The required parameters object is typed as Inworld.RealtimeAPIClientParameters.

Parameters

Parameter	Type	Req.	Description
`parameters`	`RealtimeAPIClientParameters`	✓	Inworld.RealtimeAPIClient parameters. Can be passed as arguments to the `Inworld.createRealtimeAPIClient` 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 investigate 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.
↳ `onWebSocketClose`	`(event: object) => void`	✗	A callback function that is called when the WebSocket connection is closed.
↳ `apiKey`	`string`	✓	The API key for the Inworld Realtime API.
↳ `sessionKey`	`string`	✓	The session key for the Inworld Realtime API.
↳ `authScheme`	`string`	✗	The authentication scheme (basic or bearer) for the Inworld Realtime API. The default value is bearer.

Returns

Type	Description
`Promise<Inworld.RealtimeAPIClient>`	Resolves to the `Inworld.RealtimeAPIClient` instance.

createRealtimeTTSPlayer

Creates a new Inworld.RealtimeTTSPlayer instance. You can attach media streams later via the Inworld.RealtimeTTSPlayer.sendMediaTo or VoxEngine.sendMediaBetween methods.

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

The optional parameters object is typed as Inworld.RealtimeTTSPlayerParameters.

Parameters

Parameter	Type	Req.	Description
`parameters`	`RealtimeTTSPlayerParameters`	✗	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 investigate 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.
↳ `createContextParameters`	`Object`	✗	Object to provide parameters directly to the Inworld provider Create Context message. Find more information in the documentation.
↳ `apiKey`	`string`	✗	Inworld API key. Use your Inworld API key if you have your own Inworld account.

Returns

Type	Description
`RealtimeTTSPlayer`	The requested `RealtimeTTSPlayer` value.

RealtimeTTSPlayer

Methods

clearBuffer

Clears an Inworld.RealtimeTTSPlayer buffer.

clearBuffer(): void

Parameters

This method does not accept parameters.

Returns

Type	Description
`void`	Does not return a value.

send

Send message object to the Inworld provider context.

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.

Returns

Type	Description
`void`	Does not return a value.

Example parameters:

{
  "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 page, and they emit PlayerEvents.

addEventListener

Inherited from the shared player base. See Player.addEventListener.

Adds a handler for the specified PlayerEvents event. Use only functions as handlers; anything except a function leads to the error and scenario termination when a handler is called.

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

Parameters

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

Returns

Type	Description
`void`	Does not return a value.

id

Inherited from the shared player base. See Player.id.

Returns the player’s id.

id(): string

Parameters

This method does not accept parameters.

Returns

Type	Description
`string`	The requested string value.

pause

Inherited from the shared player base. See Player.pause.

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

pause(): void

Parameters

This method does not accept parameters.

Returns

Type	Description
`void`	Does not return a value.

removeEventListener

Inherited from the shared player base. See Player.removeEventListener.

Removes a handler for the specified PlayerEvents event.

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

Parameters

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

Returns

Type	Description
`void`	Does not return a value.

resume

Inherited from the shared player base. See Player.resume.

Resumes playback after the Player.pause method is called.

resume(): void

Parameters

This method does not accept parameters.

Returns

Type	Description
`void`	Does not return a value.

sendMediaTo

Inherited from the shared player base. See Player.sendMediaTo.

Starts sending media from the player to the media unit.

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

Parameters

Parameter	Type	Req.	Description
`mediaUnit`	`VoxMediaUnit`	✓
`parameters`	`SendMediaParameters`	✗

Returns

Type	Description
`void`	Does not return a value.

stop

Inherited from the shared player base. See Player.stop.

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

stop(): void

Parameters

This method does not accept parameters.

Returns

Type	Description
`void`	Does not return a value.

stopMediaTo

Inherited from the shared player base. See Player.stopMediaTo.

Stops sending media from the player to the media unit.

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. 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.

Created

Triggered when Player created.

Event constant: PlayerEvents.Created

Payload

Field	Type	Req.	Description
`player`	`RealtimeTTSPlayer`	✓	The Inworld.RealtimeTTSPlayer instance that emitted the event.

PlaybackReady

Triggers by the createURLPlayer and createTTSPlayer methods when

the audio file download to the Voximplant cache is finished;
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`	`RealtimeTTSPlayer`	✓	The Inworld.RealtimeTTSPlayer instance that emitted the event.

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`	`RealtimeTTSPlayer`	✓	The Inworld.RealtimeTTSPlayer instance that emitted the event.
`duration`	`number`	✓	Playback duration

Stopped

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

Event constant: PlayerEvents.Stopped

Payload

Field	Type	Req.	Description
`player`	`RealtimeTTSPlayer`	✓	The Inworld.RealtimeTTSPlayer instance that emitted the event.

PlaybackFinished

Triggered when playback has finished successfully or with an error.

Event constant: PlayerEvents.PlaybackFinished

Payload

Field	Type	Req.	Description
`player`	`RealtimeTTSPlayer`	✓	The Inworld.RealtimeTTSPlayer instance that emitted the event.
`error`	`string`	✗	Error message

Error

Triggered when playback has finished with an error.

Event constant: PlayerEvents.Error

Payload

Field	Type	Req.	Description
`player`	`RealtimeTTSPlayer`	✓	The Inworld.RealtimeTTSPlayer instance that emitted the event.
`error`	`string`	✓	Error message

PlaybackMarkerReached

Triggered when Player.addMarker is reached.

Event constant: PlayerEvents.PlaybackMarkerReached

Payload

Field	Type	Req.	Description
`player`	`RealtimeTTSPlayer`	✓	The Inworld.RealtimeTTSPlayer instance that emitted the event.
`offset`	`number`	✓	The marker offset

PlaybackBuffering

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

Event constant: PlayerEvents.PlaybackBuffering

Payload

Field	Type	Req.	Description
`player`	`RealtimeTTSPlayer`	✓	The Inworld.RealtimeTTSPlayer instance that emitted the event.

AudioChunksPlaybackFinished

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

For VoxTTS.RealtimeTTSPlayer, the optional final field indicates whether the completed flush ends the current phrase or is an intermediate auto-flush.

Event constant: PlayerEvents.AudioChunksPlaybackFinished

Payload

Field	Type	Req.	Description
`player`	`RealtimeTTSPlayer`	✓	The Inworld.RealtimeTTSPlayer instance that emitted the event.
`timeToFirstByte`	`number`	✓	Time to first byte (TTFB) in milliseconds. Represents the delay between sending the request and receiving the first byte of audio data.
`final`	`boolean`	✗	Whether the completed flush ends the current phrase. Present only for VoxTTS.RealtimeTTSPlayer (`true` or `false`); omitted for other RealtimeTTS providers. - `true` — final (normal) flush; phrase playback is complete. - `false` — intermediate auto-flush; more audio is expected.

Related guides

Contents

Usage

Factory functions

createRealtimeAPIClient

createRealtimeTTSPlayer

RealtimeTTSPlayer

Methods

clearBuffer

send

Inherited Methods

addEventListener

id

pause

removeEventListener

resume

sendMediaTo

stop

stopMediaTo

PlayerEvents

Created

PlaybackReady

Started

Stopped

PlaybackFinished

Error

PlaybackMarkerReached

PlaybackBuffering

AudioChunksPlaybackFinished