play | SignalWire

Add a play verb to the main section. Plays audio from a URL or a list of URLs.

Exactly one of url or urls must be provided. Calling play() without either raises a ValueError.

Parameters

url

str | NoneDefaults to None

Single URL to play. Supports audio file URLs and the say: prefix for text-to-speech (e.g., "say:Hello world"). Mutually exclusive with urls.

urls

list[str] | NoneDefaults to None

List of URLs to play in sequence. Mutually exclusive with url.

volume

float | NoneDefaults to None

Volume adjustment level, from -40 to 40 dB.

say_voice

str | NoneDefaults to None

Voice name for text-to-speech playback.

say_language

str | NoneDefaults to None

Language code for text-to-speech (e.g., "en-US").

say_gender

str | NoneDefaults to None

Gender for text-to-speech voice selection.

auto_answer

bool | NoneDefaults to None

Whether to automatically answer the call before playing audio.

Returns

Self — The builder instance for method chaining.

Example

from signalwire import SWMLService, SWMLBuilder
service = SWMLService(name="player")
builder = SWMLBuilder(service)
# Single audio file
doc = (
    builder
    .answer()
    .play(url="https://example.com/welcome.mp3")
    .build()
)
print(doc)
# Multiple files in sequence
builder.reset()
doc = (
    builder
    .answer()
    .play(urls=[
        "https://example.com/greeting.mp3",
        "https://example.com/menu.mp3"
    ])
    .build()
)
print(doc)
# Text-to-speech via say: prefix
builder.reset()
doc = (
    builder
    .answer()
    .play(url="say:Welcome to our service.", say_voice="rime.spore")
    .build()
)
print(doc)