Recording & Audio

Capture and play audio during a session: recording configuration and storage, transcript output, and background-audio playback.

RecordingConfig

Configuration for capturing and storing session recordings.

Fields

enabled

bool

default:"False"

Whether recording is enabled.

auto_start

bool

default:"True"

Whether recording starts automatically with the session.

format

Literal['wav', 'ogg_opus', 'mp3', 'flac']

default:"ogg_opus"

Audio format for the recording, one of 'wav', 'ogg_opus', 'mp3' or 'flac'.

channel_mode

Literal['mixed', 'dual_channel']

default:"dual_channel"

Channel layout, either 'mixed' or 'dual_channel'.

sample_rate

int

default:"0"

Sample rate in Hz; 0 uses the default.

bitrate_kbps

int

default:"0"

Audio bitrate in kbps; 0 uses the default.

storage

S3StorageConfig | None

Storage destination configuration, or None for the default.

transcript

RecordingTranscriptConfig | None

Transcript generation configuration, or None to disable.

max_duration_seconds

int

default:"0"

Maximum recording duration in seconds; 0 is unlimited.

max_file_size_mb

int

default:"0"

Maximum recording file size in megabytes; 0 is unlimited.

recording_beep

bool

default:"False"

Whether to play a beep indicating recording is active.

redact_dtmf

bool

default:"False"

Whether to redact DTMF tones from the recording.

custom_metadata

Dict[str, str]

default:"…"

Custom metadata to associate with the recording.

recording_name

str

default:""

Name assigned to the recording.

recording_group

str

default:""

Group identifier the recording belongs to.

apply_denoise

bool

default:"False"

Whether to apply denoising to the recorded audio.

normalize_audio

bool

default:"False"

Whether to normalize the audio levels.

trim_silence

bool

default:"False"

Whether to trim silent segments from the recording.

record_video

bool

default:"False"

Whether to record video.

Whether to record shared screens.

record_screen_audio

bool

default:"False"

Whether to record screen-share audio.

S3StorageConfig

Configuration for uploading recordings to S3-compatible object storage.

Fields

bucket

str

default:""

Target bucket name.

region

str

default:""

Region of the bucket.

prefix

str

default:""

Key prefix prepended to uploaded objects.

access_key_id

str

default:""

Access key identifier for authentication.

secret_access_key

str

default:""

Secret access key for authentication.

session_token

str

default:""

Optional session token for temporary credentials.

endpoint_url

str

default:""

Custom endpoint URL for S3-compatible providers.

storage_class

str

default:""

Storage class to apply to uploaded objects.

server_side_encryption

str

default:""

Server-side encryption algorithm to use.

kms_key_id

str

default:""

KMS key identifier used when encryption requires one.

acl

str

default:""

Canned access control list to apply to uploaded objects.

multipart_upload

bool

default:"True"

Whether to use multipart uploads.

multipart_part_size_mb

int

default:"8"

Part size, in megabytes, for multipart uploads.

upload_timeout_seconds

int

default:"0"

Upload timeout in seconds; 0 uses the default.

max_retry_attempts

int

default:"3"

Maximum number of upload retry attempts.

RecordingTranscriptConfig

Configuration for generating transcripts alongside a recording.

Fields

enabled

bool

default:"False"

Whether transcript generation is enabled.

format

Literal['json', 'srt', 'vtt']

default:"json"

Transcript output format, one of 'json', 'srt' or 'vtt'.

include_word_timestamps

bool

default:"False"

Whether to include per-word timestamps.

include_confidence

bool

default:"False"

Whether to include confidence scores.

speaker_labels

bool

default:"True"

Whether to label speakers in the transcript.

language

str

default:""

Language hint for transcription; empty to auto-detect.

RecordingFormat

Audio container and codec formats available for recordings.

class RecordingFormat(Enum):
    WAV = 'wav'
    OGG_OPUS = 'ogg_opus'
    MP3 = 'mp3'
    FLAC = 'flac'

RecordingChannelMode

Channel layouts for recorded audio.

class RecordingChannelMode(Enum):
    MIXED = 'mixed'
    DUAL_CHANNEL = 'dual_channel'

RecordingTranscriptFormat

Output formats for recording transcripts.

class RecordingTranscriptFormat(Enum):
    JSON = 'json'
    SRT = 'srt'
    VTT = 'vtt'

RecordingState

Lifecycle states of a recording, from idle through completion or failure.

class RecordingState(Enum):
    IDLE = 'idle'
    RECORDING = 'recording'
    FINALIZING = 'finalizing'
    UPLOADING = 'uploading'
    COMPLETED = 'completed'
    FAILED = 'failed'

BackgroundAudioHandlerConfig

Configuration for background audio playback during an agent session.

Fields

file

str

default:""

Path to the audio file to play in the background.

volume

float

default:"1.0"

Playback volume multiplier, where 1.0 is the original level.

looping

bool

default:"False"

Whether the audio should loop continuously.

enabled

bool

default:"True"

Whether background audio is active.

mode

Literal['playback', 'mixing']

default:"mixing"

Playback strategy. 'mixing' blends the audio with agent output, while 'playback' plays it on its own.

chunk_size

int

default:"320"

Number of audio samples processed per chunk.

load_audio_file

def load_audio_file(path: str) -> bytes

Read the raw bytes of an audio file from disk.

path

str

required

Filesystem path to the audio file.

returns

bytes

The file contents as bytes, or an empty bytes object if the file does not exist, is a directory, or cannot be read due to permissions.

TTSAudioCache

In-memory cache mapping keys to synthesized audio byte payloads.

Constructor

TTSAudioCache(*args, **kwargs) -> None

add

def add(self, key: str, data: bytes) -> None

Store audio data under the given key.

key

str

required

Identifier under which to store the audio.

data

bytes

required

Raw audio bytes to cache.

clear

def clear(self) -> None

Remove all cached audio entries.

get

def get(self, key: str) -> Optional[bytes]

Retrieve cached audio data for a key.

key

str

required

Identifier of the cached audio.

returns

Optional

The cached audio bytes, or None if the key is not present.

Python SDK

Core

Speech-to-text

LLM

Text-to-speech

Realtime models

Avatars

Turn detection

Voice activity detection

Noise cancellation

RecordingConfig

Fields

S3StorageConfig

Fields

RecordingTranscriptConfig

Fields

RecordingFormat

RecordingChannelMode

RecordingTranscriptFormat

RecordingState

BackgroundAudioHandlerConfig

Fields

load_audio_file

TTSAudioCache

Constructor

add

clear

get

​RecordingConfig

​Fields

​S3StorageConfig

​Fields

​RecordingTranscriptConfig

​Fields

​RecordingFormat

​RecordingChannelMode

​RecordingTranscriptFormat

​RecordingState

​BackgroundAudioHandlerConfig

​Fields

​load_audio_file

​TTSAudioCache

​Constructor

​add

​clear

​get

RecordingConfig

Fields

S3StorageConfig

Fields

RecordingTranscriptConfig

Fields

RecordingFormat

RecordingChannelMode

RecordingTranscriptFormat

RecordingState

BackgroundAudioHandlerConfig

Fields

load_audio_file

TTSAudioCache

Constructor

add

clear

get