RELAYCall

play

View as MarkdownOpen in Claude

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", "text": "Hello", "language": "en-US", "gender": "female"} — text-to-speech
  • {"type": "audio", "url": "https://example.com/audio.mp3"} — audio file URL
  • {"type": "silence", "duration": 2} — silence for a duration in seconds
  • {"type": "ringtone", "name": "us"} — play a standard ringtone
volume
Optional[float]

Volume adjustment in dB, from -40.0 to 40.0.

direction
Optional[str]

Audio direction. Valid values:

  • "listen" — play to the caller only
  • "speak" — play to the remote party only
  • "both" — play to both sides
loop
Optional[int]

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

control_id
Optional[str]

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

on_completed
Optional[Callable[[RelayEvent], Any]]

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

1from signalwire.relay import RelayClient
2
3client = RelayClient(
4    project="your-project-id",
5    token="your-api-token",
6    host="your-space.signalwire.com",
7    contexts=["default"],
8)
9
10@client.on_call
11async def handle_call(call):
12    await call.answer()
13    action = await call.play([{"type": "tts", "text": "Welcome to SignalWire!"}])
14    await action.wait()
15
16client.run()

Audio File with Loop

1from signalwire.relay import RelayClient
2
3client = RelayClient(
4    project="your-project-id",
5    token="your-api-token",
6    host="your-space.signalwire.com",
7    contexts=["default"],
8)
9
10@client.on_call
11async def handle_call(call):
12    await call.answer()
13    # Play hold music on loop
14    action = await call.play(
15        [{"type": "audio", "url": "https://example.com/hold-music.mp3"}],
16        loop=0,
17        direction="listen",
18    )
19    # Later, stop the music
20    await action.stop()
21
22client.run()

Multiple Media Items

1from signalwire.relay import RelayClient
2
3client = RelayClient(
4    project="your-project-id",
5    token="your-api-token",
6    host="your-space.signalwire.com",
7    contexts=["default"],
8)
9
10@client.on_call
11async def handle_call(call):
12    await call.answer()
13    action = await call.play([
14        {"type": "tts", "text": "Please hold while we connect you."},
15        {"type": "silence", "duration": 1},
16        {"type": "audio", "url": "https://example.com/hold-music.mp3"},
17    ])
18    await action.wait()
19
20client.run()