Sound¶

This page shows how to play sounds on your clock: MP3 files, melodies, songs and speech. It also shows how loud each kind of sound plays, and what happens when two sounds meet.

See and hear it:

A few words this page uses:

• Alert: a sound you ask for from outside the clock. A notification's sound, a request to /api/v1/audio/play, the boot sound and the answer of Home Assistant Voice are alerts.
• App sound: a sound a script plays.
• Radio: an internet radio station. See Internet radio.
• Master volume: the volume of the whole clock. Every other volume is a share of it.
• RTTTL: a short text format for ringtones, from old mobile phones.

How it behaves¶

Every sound is described the same way, whether you play it with a request, over MQTT, with a notification or from a script. It plays at the master volume times the share of its group: alerts, app sounds or the radio. Several sounds can play at once: a script's music and effects get quieter under an alert, and the radio pauses while an alert or a script's sound plays (What plays over what). A new alert replaces the one that plays. A sound plays once, unless you add "loop": true, and a station plays until you stop it.

What your clock can play¶

Which sounds your clock can play depends on its hardware. The web UI shows only what your clock can play. To see it yourself, look at audio in GET /api/v1/capabilities:

{"audio":{"mp3":true,"rtttl":true,"song":true,"speech":true,"track":false,
          "radio":true,"url":true,"effect":true,"clip":true}}

Every flag is always there, true or false. track is always false on this clock.

Play a sound¶

The quickest test plays three rising notes:

curl -X POST http://<awtrix-ip>/api/v1/audio/play \
  -H 'Content-Type: application/json' \
  -d '{"rtttl":"beep:d=4,o=5,b=120:c,e,g"}'

The answer is:

{"ok":true}

The body says what to play. It is called the sound, and a notification's sound takes the same value.

A stored sound is played by its name:

curl -X POST http://<awtrix-ip>/api/v1/audio/play \
  -H 'Content-Type: application/json' \
  -d '{"file":"ding"}'

A plain name in quotes is short for the same thing. "ding" and {"file":"ding"} play the same sound:

curl -X POST http://<awtrix-ip>/api/v1/audio/play \
  -H 'Content-Type: application/json' \
  -d '"ding"'

A sound has exactly one of these keys. The key says what plays:

Next to the key, "loop": true repeats the sound until you stop it. See Repeat a sound.

Give the clock a choice¶

A sound can also be a list of 1 to 4 sounds. The clock plays the first one it can play. It skips an entry when it lacks the hardware for it, or when a file is not stored.

This notification speaks on a clock with a voice, and plays ding on every other clock:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"text":"Door","sound":[{"speech":"The front door is open."},"ding"]}'

The display shows Door while the sound plays. A clock that can play none of the entries shows the notification without sound.

How a name is found¶

A plain name such as "ding" is looked up in this order:

1. the MP3 /MP3/ding.mp3;
2. the melody /MELODIES/ding.txt.

A script asks its own folder first. See Sounds for your script.

A name with a slash, such as "Racer/boost", plays the sound boost of the script Racer. It is looked up in that script's folder only.

Names are 1 to 32 characters of A-Z, a-z, 0-9, _ and -.

MP3s¶

Upload an MP3¶

1. Open the web UI and go to the Audio tab.
2. In the MP3s section, drag the file onto ⬆ Upload, or click it to choose the file.

You play an MP3 by its file name without .mp3, so name the file the way you want to call it.

• Use normal MP3 files, the kind any converter makes. A file that is not an MP3 is refused.
• MP3s share the storage with icons, melodies and scripts, so keep them to a few seconds. The line above the list in the MP3s section shows how much space is left.
• An MP3 and a melody never share a name. If a melody called ding is stored, an MP3 called ding.mp3 is refused, and the other way round. Rename one of them first.

Play an MP3¶

1. Open the Audio tab.
2. Press ▶ next to the MP3.

Or use the file name without .mp3:

curl -X POST http://<awtrix-ip>/api/v1/audio/play \
  -H 'Content-Type: application/json' \
  -d '{"file":"ding"}'

The same name works as "sound":"ding" in a notification, and in a script.

MP3s from the internet¶

The clock can play an MP3 straight from a web address. You do not upload it first.

curl -X POST http://<awtrix-ip>/api/v1/audio/play \
  -H 'Content-Type: application/json' \
  -d '{"file":"https://example.com/doorbell.mp3"}'

• The clock downloads the whole file first, then plays it. It does not keep the file.
• A file can be up to 4 MB. The clock also needs enough free memory for it.
• The answer comes at once. If you hear nothing, ask the clock why: GET /api/v1/audio shows the reason under alert.error, for example HTTP 404 (wrong address) or not enough memory.
• With "loop": true, a file that cannot be downloaded is not tried again.

Rename an MP3¶

Click the pen next to it on the Audio tab, type the new name and press Enter, or send:

curl -X POST http://<awtrix-ip>/api/v1/audio/mp3/rename \
  -H 'Content-Type: application/json' \
  -d '{"from":"ding","to":"bell"}'

Alarms, notifications and scripts that play the old name stay silent until you change them. A script's own MP3s keep their names.

Delete an MP3¶

Click the bin next to it on the Audio tab, or send:

curl -X DELETE http://<awtrix-ip>/api/v1/audio/mp3/ding

MP3s that come with a script¶

A script can bring its own MP3s. They live in the script's folder. The Audio tab lists them below your own MP3s, in a group for each script. From outside the script, play one as "Racer/boost":

curl -X POST http://<awtrix-ip>/api/v1/audio/play \
  -H 'Content-Type: application/json' \
  -d '{"file":"Racer/boost"}'

A script's sounds may have the same name as a melody or as an MP3 in /MP3. See Sounds for your script.

Deleting a script with sounds asks what happens to them: Delete with sounds, or Keep sounds. Kept sounds stay on the Audio tab, in a group marked script removed. They come back into use when a script of the same name is installed again. Delete them there one by one when you do not need them any more.

Melodies¶

A melody is a short tune in RTTTL text. You can send it with each request, or store it on the clock and play it by name.

Writing RTTTL¶

An RTTTL melody has three parts, separated by colons. All three are required:

name:defaults:notes

beep:d=4,o=5,b=120:c,e,g
└─┬─┘ └──────┬─────┘ └─┬─┘
name    defaults     notes

• name: 1 to 24 characters. It is not played, but it must not be empty.
• defaults: d is the default note length, o the default octave, b the beats per minute. Each may appear once at most, in any order, and each may be left out.
• notes: separated by commas. Each note is an optional length, a letter a to g (p is a pause), an optional #, an optional . for a dotted note, and an optional octave. 16c6 is a 16th note C in octave 6. A note without a length or octave uses the defaults.

Allowed values:

Anything else is refused, including b#, e#, a pause with # and a length such as 3. The answer names the reason and the position in the text:

curl -X POST http://<awtrix-ip>/api/v1/audio/play \
  -H 'Content-Type: application/json' \
  -d '{"rtttl":"d=4,o=5,b=120:c,e,g"}'

{"error":{"code":"validationFailed",
          "message":"missing ':' (at offset 19)",
          "field":"rtttl"}}

The status is 422.

A melody is at most 512 characters, sent in the request or stored in a file. See Limits.

Some melodies to try:

# Two-tone doorbell
curl -X POST http://<awtrix-ip>/api/v1/audio/play -H 'Content-Type: application/json' \
  -d '{"rtttl":"bell:d=4,o=5,b=100:e,c"}'

# Falling "something went wrong"
curl -X POST http://<awtrix-ip>/api/v1/audio/play -H 'Content-Type: application/json' \
  -d '{"rtttl":"lose:d=8,o=5,b=120:16c,16b,16a,4g"}'

# Jackpot fanfare
curl -X POST http://<awtrix-ip>/api/v1/audio/play -H 'Content-Type: application/json' \
  -d '{"rtttl":"jackpot:d=8,o=5,b=120:16c,16e,16g,c6,16p,16c6,16e6,4g6"}'

Store a melody¶

1. Open the Audio tab and go to Melodies.
2. Press + New melody.
3. Enter a name and the notes, then save.

The editor checks the text while you type, plays it in your browser, and plays it on the clock when you want to hear it there. See Melodies.

Or save one with a request:

curl -X PUT http://<awtrix-ip>/api/v1/audio/melodies/doorbell \
  -H 'Content-Type: application/json' \
  -d '{"rtttl":"d=4,o=5,b=100:e,c"}'

The answer is 201 for a new melody and 200 when it replaced one. A text with a mistake answers 422.

• The melody is stored as /MELODIES/doorbell.txt. Its name part is always the name you saved it under. Send d=4,o=5,b=100:e,c and the file holds doorbell:d=4,o=5,b=100:e,c.
• Names are 1 to 24 characters of A-Z, a-z, 0-9, _ and -.
• A melody never takes the name of a stored MP3. Saving doorbell while /MP3/doorbell.mp3 exists answers 409, name taken.

Play a stored melody¶

Use the name without .txt:

curl -X POST http://<awtrix-ip>/api/v1/audio/play \
  -H 'Content-Type: application/json' \
  -d '{"file":"doorbell"}'

If nothing is called doorbell, the answer is 404:

{"error":{"code":"notFound","message":"nothing called \"doorbell\""}}

List the stored melodies¶

curl http://<awtrix-ip>/api/v1/audio/melodies

{"melodies":[{"name":"doorbell","rtttl":"doorbell:d=4,o=5,b=100:e,c",
              "bytes":26,"notes":2,"durationMs":2400,"valid":true}],
 "usedBytes":41216,"totalBytes":1048576}

• notes and durationMs tell you how long a melody is without playing it.
• A melody with a mistake is still listed, with valid:false, error and index. So you can find and fix it in the editor.
• usedBytes and totalBytes are for the whole storage. Melodies share it with icons, palettes and scripts.

Delete or rename a melody¶

curl -X DELETE http://<awtrix-ip>/api/v1/audio/melodies/doorbell

The answer is 404 notFound if there is no such melody. To rename a melody, save it under the new name and delete the old one.

Songs¶

The synthesizer plays music written as text: a few instruments and the notes they play. You send the text in the request. Nothing is uploaded or stored. How to write a song: Song text.

curl -X POST http://<awtrix-ip>/api/v1/audio/play \
  -H 'Content-Type: application/json' \
  -d '{"song":"bpm 120; inst lead wave=pulse volume=75; lead: c4 e g c5"}'

• The song plays once. Add "loop": true to repeat it until you stop it.
• Song text with a mistake is refused with 422 validationFailed, field song. The message names the line and column.
• Scripts can play a song as music and add effects over it. See the scripting guide.

Speech¶

A clock with a voice reads English text aloud. Your clock has a voice when speech is true under audio in GET /api/v1/capabilities.

curl -X POST http://<awtrix-ip>/api/v1/audio/play \
  -H 'Content-Type: application/json' \
  -d '{"speech":"Good morning. It is 7:30 and 21° outside."}'

A notification can speak too. The text on the display and the spoken text are separate:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"text":"Door open","sound":{"speech":"The front door is open."}}'

The display shows Door open, and the clock says the whole sentence.

On a clock without a voice, that notification shows without sound. To play a sound there instead, give a list: "sound":[{"speech":"The front door is open."},"ding"].

How the clock reads the text:

• Up to 512 bytes of text. A plain letter is one byte. A letter with an accent, or a sign like °, is two or three.
• Letters with accents are read without them: Café sounds like cafe.
• Numbers are read as words: 23.5 is "twenty three point five", -5 is "minus five".
• Times are read as times: 7:05 is "seven oh five", 12:00 is "twelve o'clock".
• %, & and ° are read as "percent", "and" and "degrees".
• ., ,, ?, !, ;, : and a new line make a short pause.
• Anything else, emoji for example, is skipped.
• A very long text stops after the last word that fits.

While Home Assistant Voice uses the speaker, the clock does not speak.

If the clock does not speak, check that the text contains words and fits within 512 bytes. The clock also needs speech support and an available speaker. The exact responses are listed in Audio playback errors.

Repeat a sound¶

Add "loop": true to a sound to repeat it until you stop it:

curl -X POST http://<awtrix-ip>/api/v1/audio/play \
  -H 'Content-Type: application/json' \
  -d '{"rtttl":"siren:d=8,o=5,b=200:c,g,c,g","loop":true}'

• It repeats until you stop it, or until a new alert takes its place.
• The radio stays paused while it repeats and comes back once it has stopped.
• In a notification it repeats while the notification is shown. See Notifications.
• loop does not work with station. A station plays until you stop it anyway.

Volume¶

The clock has one master volume and three groups. Each group is a share of the master volume:

What you hear is the master volume times the group's share. With volume at 50 and alertVolume at 60, an alert plays at 30.

MP3s, melodies, songs and speech play about equally loud at the same volume. A script's music plays a little quieter, under its effects.

In the web UI¶

1. Open the Audio tab.
2. Move the sliders in the Mixer section at the top: Master, Radio, Apps and Alerts.

A change applies at once, also to sounds that are playing.

The knob also sets the master volume.

With the API¶

curl -X PATCH http://<awtrix-ip>/api/v1/settings \
  -H 'Content-Type: application/json' \
  -d '{"volume":50,"alertVolume":60}'

• 0 is silence. "volume": 0 silences every sound, the radio included.
• A value outside 0 to 100 is refused with 422.

All four settings: Sound settings.

What plays over what¶

The clock can play several sounds at once.

Stop a sound¶

On the Audio tab, press ■ in the bar that shows what is playing. Or send:

curl -X POST http://<awtrix-ip>/api/v1/audio/stop

This stops everything, the radio too. Add group to stop less:

curl -X POST http://<awtrix-ip>/api/v1/audio/stop \
  -H 'Content-Type: application/json' \
  -d '{"group":"alert"}'

Any other value answers 422, must be alert, app or radio.

Over MQTT¶

The same sound goes to <prefix>/cmd/audio/play:

mosquitto_pub -h <broker> -t 'awtrixNG/cmd/audio/play' -m '{"file":"ding"}'
mosquitto_pub -h <broker> -t 'awtrixNG/cmd/audio/stop' -m '{"group":"alert"}'

• An empty payload on cmd/audio/stop stops everything.
• Errors come back on <prefix>/cmd/audio/play/result as {"ok":false,"error":{…}}.
• <prefix>/state/audio shows what is playing. It is kept by the broker, and it is sent again on every change.
• Storing and listing melodies works over HTTP only.

See Command topics.

When it goes wrong¶

Every status code and message: Audio playback errors.

Good to know¶

• An rtttl without a name in front is refused with 422. Write any name and a colon before the defaults: beep:d=4,o=5,b=120:c,e,g. Only a stored melody may leave the name out.
• A stored sound is played by its name alone. {"file":"ding.mp3"} is refused with 422, invalid name. Send {"file":"ding"}.
• An MP3 whose file name has spaces or other signs is refused. Names may only use A-Z, a-z, 0-9, _ and -, up to 32 characters. Rename My Song (2024).mp3 to my-song-2024.mp3 first.
• station works only on its own. In a list or in a notification's sound it is refused with 422, not here. Start the radio with a request of its own.

Details¶

• Audio: every audio route, field and status code
• Song text: how to write a song
• Sound settings: the four volumes

Related¶

• Internet radio: stations and streams
• Audio tab: the mixer, MP3s and the melody editor
• Notifications: a sound with a notification