play | SignalWire

Play audio content on the call. Supports TTS (text-to-speech), audio file URLs, silence, and ringtone. Returns a PlayAction that you can use to pause, resume, stop, adjust volume, or wait for completion.

This method emits calling.call.play events. See Call Events for payload details.

This method corresponds to the SWML play verb. See the SWML play reference for the full specification.

Parameters

media

list[dict]Required

List of media items to play. Each item is a dict with a type key and type-specific fields:

{"type": "tts", "params": {"text": "Hello", "language": "en-US", "gender": "female"}} — text-to-speech
{"type": "audio", "params": {"url": "https://example.com/audio.mp3"}} — audio file URL
{"type": "silence", "params": {"duration": 2}} — silence for a duration in seconds
{"type": "ringtone", "params": {"name": "us"}} — play a standard ringtone

volume

float | NoneDefaults to None

Volume adjustment in dB, from -40.0 to 40.0.

direction

str | NoneDefaults to None

Audio direction. Valid values:

"listen" — play to the caller only
"speak" — play to the remote party only
"both" — play to both sides

loop

int | NoneDefaults to None

Number of times to repeat the media. 0 loops indefinitely.

control_id

str | NoneDefaults to None

Custom control ID for this operation. Auto-generated if not provided.

on_completed

Callable[[RelayEvent], Any] | NoneDefaults to None

Callback invoked when playback reaches a terminal state. Can be a regular function or async coroutine.

Returns

PlayAction — An action handle with stop(), pause(), resume(), volume(), and wait() methods.

Examples

Text-to-Speech

from signalwire.relay import RelayClient
client = RelayClient(
    project="your-project-id",
    token="your-api-token",
    contexts=["default"],
)
@client.on_call
async def handle_call(call):
    await call.answer()
    action = await call.play([{"type": "tts", "params": {"text": "Welcome to SignalWire!"}}])
    await action.wait()
client.run()

Audio File with Loop

from signalwire.relay import RelayClient
client = RelayClient(
    project="your-project-id",
    token="your-api-token",
    contexts=["default"],
)
@client.on_call
async def handle_call(call):
    await call.answer()
    # Play hold music on loop
    action = await call.play(
        [{"type": "audio", "params": {"url": "https://example.com/hold-music.mp3"}}],
        loop=0,
        direction="listen",
    )
    # Later, stop the music
    await action.stop()
client.run()

Multiple Media Items

from signalwire.relay import RelayClient
client = RelayClient(
    project="your-project-id",
    token="your-api-token",
    contexts=["default"],
)
@client.on_call
async def handle_call(call):
    await call.answer()
    action = await call.play([
        {"type": "tts", "params": {"text": "Please hold while we connect you."}},
        {"type": "silence", "params": {"duration": 1}},
        {"type": "audio", "params": {"url": "https://example.com/hold-music.mp3"}},
    ])
    await action.wait()
client.run()