> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Recording & Audio
> Python API reference for 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
Whether recording is enabled.
Whether recording starts automatically with the session.
Audio format for the recording, one of `'wav'`, `'ogg_opus'`, `'mp3'` or `'flac'`.
Channel layout, either `'mixed'` or `'dual_channel'`.
Sample rate in Hz; `0` uses the default.
Audio bitrate in kbps; `0` uses the default.
Storage destination configuration, or `None` for the default.
Transcript generation configuration, or `None` to disable.
Maximum recording duration in seconds; `0` is unlimited.
Maximum recording file size in megabytes; `0` is unlimited.
Whether to play a beep indicating recording is active.
Whether to redact DTMF tones from the recording.
Custom metadata to associate with the recording.
Name assigned to the recording.
Group identifier the recording belongs to.
Whether to apply denoising to the recorded audio.
Whether to normalize the audio levels.
Whether to trim silent segments from the recording.
Whether to record video.
Whether to record shared screens.
Whether to record screen-share audio.
***
## S3StorageConfig
Configuration for uploading recordings to S3-compatible object storage.
### Fields
Target bucket name.
Region of the bucket.
Key prefix prepended to uploaded objects.
Access key identifier for authentication.
Secret access key for authentication.
Optional session token for temporary credentials.
Custom endpoint URL for S3-compatible providers.
Storage class to apply to uploaded objects.
Server-side encryption algorithm to use.
KMS key identifier used when encryption requires one.
Canned access control list to apply to uploaded objects.
Whether to use multipart uploads.
Part size, in megabytes, for multipart uploads.
Upload timeout in seconds; `0` uses the default.
Maximum number of upload retry attempts.
Object tags to attach to uploaded files.
Custom user metadata to attach to uploaded objects.
Explicit content type to set instead of the inferred one.
***
## RecordingTranscriptConfig
Configuration for generating transcripts alongside a recording.
### Fields
Whether transcript generation is enabled.
Transcript output format, one of `'json'`, `'srt'` or `'vtt'`.
Whether to include per-word timestamps.
Whether to include confidence scores.
Whether to label speakers in the transcript.
Language hint for transcription; empty to auto-detect.
***
## RecordingFormat
Audio container and codec formats available for recordings.
```python theme={null}
class RecordingFormat(Enum):
WAV = 'wav'
OGG_OPUS = 'ogg_opus'
MP3 = 'mp3'
FLAC = 'flac'
```
***
## RecordingChannelMode
Channel layouts for recorded audio.
```python theme={null}
class RecordingChannelMode(Enum):
MIXED = 'mixed'
DUAL_CHANNEL = 'dual_channel'
```
***
## RecordingTranscriptFormat
Output formats for recording transcripts.
```python theme={null}
class RecordingTranscriptFormat(Enum):
JSON = 'json'
SRT = 'srt'
VTT = 'vtt'
```
***
## RecordingState
Lifecycle states of a recording, from idle through completion or failure.
```python theme={null}
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
Path to the audio file to play in the background.
Playback volume multiplier, where `1.0` is the original level.
Whether the audio should loop continuously.
Whether background audio is active.
Playback strategy. `'mixing'` blends the audio with agent output, while `'playback'` plays it on its own.
Number of audio samples processed per chunk.
***
## load\_audio\_file
```python theme={null}
def load_audio_file(path: str) -> bytes
```
Read the raw bytes of an audio file from disk.
Filesystem path to the audio file.
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
```python theme={null}
TTSAudioCache(*args, **kwargs) -> None
```
### add
```python theme={null}
def add(self, key: str, data: bytes) -> None
```
Store audio data under the given key.
Identifier under which to store the audio.
Raw audio bytes to cache.
### clear
```python theme={null}
def clear(self) -> None
```
Remove all cached audio entries.
### get
```python theme={null}
def get(self, key: str) -> Optional[bytes]
```
Retrieve cached audio data for a key.
Identifier of the cached audio.
The cached audio bytes, or `None` if the key is not present.