---
title: "Start audio playback"
method: POST
path: "/speakers/{speaker_id}/play/"
tags: ["speakers"]
---

# Start audio playback

`POST /speakers/{speaker_id}/play/`

## Request

- Base URL: `https://api.angelcam.com/v1`
- URL: `https://api.angelcam.com/v1/speakers/{speaker_id}/play/`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://my.angelcam.com/oauth/authorize/`, token URL `https://my.angelcam.com/oauth/token/`
    - Password, token URL `https://api.angelcam.com/oauth/token/`
    - Scopes: `audio_messages_play`
  - API key in header `Authorization`
- TypeScript: <https://skmtc.dev/angelcam/apis/angelcam-api/docs/speakers/:speaker_id/play/post.ts> (a function with typed inputs; its response is checked against the schema)

Play a given audio message or return a WebRTC signaling URL if no message ID is given.

### Live audio playback using WebRTC

Every [WebRTC signaling](#section/Angelcam-API/WebRTC-signaling) session for live audio playback starts by sending an SDP offer from the client to the corresponding Angelcam server followed by one or more local ICE candidates. The server then responds with an SDP answer followed by one or more of its local ICE candidates. The candidate exchange should conclude by sending a `null` candidate by each side to the other peer to signal that there are no more local ICE candidates. There is no lock-step mechanism for sending the ICE candidates. All available local candidates should be sent to the other peer immediately after sending the SDP offer/answer.

#### STUN/TURN servers

No external STUN or TURN servers are required as all Angelcam servers have a public IP address and, therefore, the `host` ICE candidates on the server side are always reachable. The client's server-reflexive candidates, if needed, are then discovered once the client contacts the server via the server's `host` candidates.

## Request body

- object
  - `message` integer, nullable: audio message ID
  - `repeat` boolean: repeat the audio message
  - `stop_after` integer, nullable: Duration in seconds after which the playback will automatically stop. This is required when repeat is `true` to prevent infinite playback.

## Response `200`

WebRTC signaling URL.

- object
  - `webrtc_signaling_url` string, url, required: WebRTC signaling URL

## Other responses

- `204`: Empty response.
- `401`: Missing or invalid authorization.
- `403`: Missing permission.
- `404`: The specified resource was not found
- `503`: Service unavailable

---

[API](https://skmtc.dev/angelcam/apis/angelcam-api.md) - [All operations](https://skmtc.dev/angelcam/apis/angelcam-api/llms.txt) - [OpenAPI document](https://skmtc.dev/angelcam/apis/angelcam-api/revisions/a3b9b1d3e96a?raw)