Upload, Play, and Delete an Audio File

Upload, Play, and Delete an Audio File API

This API supports the following combined actions:

Upload a WAV (recommended) or MP3 audio file.
Play or multicast the audio.
Delete the file after playback completes.

Notes About This API

Playback latency varies depending on the target device’s status and the audio file size. When the device is idle, the typical latency is:
- 15-second audio file: approximately 60 seconds
- 60-second audio file: approximately 90 seconds

The POST /api/controls/tone/upload-play API supports two upload methods. Each method uses a different request format and HMAC signature (if the standard authentication method is used).

Upload Method	Description	Request Format	HMAC String	Required Headers
Raw file	Upload the binary data of an audio file directly	--data-binary "@<file_name>"	[request_method]:[request_uri]:[content_md5]:[content_type]:[timestamp]:[nonce]	Authorization Content-Md5 Content-Type Date
Multipart (File + JSON)	Upload an audio file with optional playback and multicast settings	-F "tone=@<file_name>" -F "data={...}"	[request_method]:[request_uri]:[timestamp]:[nonce]	Authorization Date

Upload Method

Description

Request Format

HMAC String

Required Headers

Raw file

Upload the binary data of an audio file directly

--data-binary "@<file_name>"

[request_method]:[request_uri]:[content_md5]:[content_type]:[timestamp]:[nonce]

Authorization
Content-Md5
Content-Type
Date

Multipart (File + JSON)

Upload an audio file with optional playback and multicast settings

-F "tone=@<file_name>"

-F "data={...}"

[request_method]:[request_uri]:[timestamp]:[nonce]

Authorization
Date

API Specifications

Applicable Products: All IP Speakers, Paging Adapters, IP Intercoms, IP Visual Alerters, IP Displays, IP Clocks

Minimum Firmware Version: 5.7

URI

POST /api/controls/tone/upload-play

Multipart Payload

Element	Description	Type	Required	Notes
data	Multipart payload to specify the audio file playback and multicast settings.		Optional	The multipart `data` field is optional. However, when provided, you must specify the Content-Type as “application/json”. For example: `-F "data={\"loop\":true};type=application/json"`
duration	How long the audio plays (in seconds).	Integer	Optional
interval	When the audio file loop plays (`loop` set to `true`), set the pause time (in seconds) between each playback.	Integer	Optional
loop	Set the audio file to loop.	Boolean	Optional	Valid values: “true” “false”
mcast	Configure the device as a multicast transmitter.	Boolean	Optional	Valid values: “true” “false” If multicast is turned on via `/mcast/update` at any time, this call will default to these settings. If multicast is only configured via the web interface, this call will default to the web interface settings.
playback	Whether the device plays the uploaded audio file locally.	String	Optional	Valid values: “true” “false”
state	The multicast parameters.	String	Optional
mode	The multicast mode of the device	String	Optional	Valid values: “sender”
address	The IP address of the multicast zone.	String	Optional
port	The port of the multicast zone.	String	Optional
type	The multicast transfer type.	String	Optional	Valid values: “poly” “rtp“
group	The Poly group being used.	Integer	Optional	Valid values: numbers 1 through 25. Applicable only when “type” is set as “poly”.
tone	The audio file to play back or multicast.		Required	Note: All uploaded files are converted to 16kHz single-channel (Mono). When using MP3 files, the Content-Type must be set as “audio/mpeg”
file	The binary data of the audio file.		Required	File format: WAV with 16kHz sample rate (recommended) MP3 with 16kHz sample rate

Sample Request 1: Upload a WAV audio file, play it, then delete it.

curl -X POST "http://10.11.12.123/api/controls/tone/upload-play" \
  -H "Authorization: hmac admin:<nonce>:<hex_digest>" \
  -H "Content-Md5: <hex_md5>" \
  -H "Content-Type: audio/wav" \
  -H "Date: <RFC1123_date>" \
  --data-binary "@alert-lockdown.wav"

Sample Request 2: Upload a WAV file to the device, continuously play the file locally for 60 seconds with a 2-second pause between playbacks, multicast the audio to a specified zone, and then delete the file after playback completes.

curl -X POST \
  -H "Authorization: hmac admin:<nonce>:<digest>" \
  -H "Date: <date>" \
  -F "tone=@alert-lockdown.wav;type=audio/wav" \
  -F 'data={"loop":true,"interval":2,"duration":60,"mcast":true,"playback":true,"state":{"mode":"sender","address":"20.21.22.234","port":"50000","type":"rtp"}};type=application/json' \
  http://10.11.12.123/api/controls/tone/upload-play

Sample Request 3: Upload an MP3 file, play locally, multicast to a specified zone, then delete it.

curl -X POST \
  -H "Authorization: hmac admin:<nonce>:<digest>" \
  -H "Date: <date>" \
  -F "tone=@alert-lockdown.mp3;type=audio/mpeg" \
  -F 'data={"loop":false,"mcast":true,"playback":true,"state":{"mode":"sender","address":"20.21.22.234","port":"50002","type":"rtp"}};type=application/json' \
  http://10.11.12.123/api/controls/tone/upload-play

Example Response

On success, the device plays the audio and (if configured) multicasts it.