Repository navigation
Getting Started Home Assistant
This page explains how to install Sonorium as a Home Assistant app (an add-on), from the add-on store to the Sonorium web UI open in Home Assistant's sidebar. When you're done, What's next links to Sonorium's documentation for turning on speakers and playing your first channel.
The Home Assistant app runs inside Home Assistant, the way an app runs on a phone. It plays on the speakers Home Assistant already knows (its media_player entities), uses Home Assistant's floors and areas, lets every Home Assistant user in with the role they have there, and gives Home Assistant switches, selects and dashboard cards for every channel.
Other ways to run Sonorium: Docker · Windows · Compare them
| Home Assistant OS or Supervised | Apps (add-ons) need Home Assistant's Supervisor. Home Assistant Container and Core installs don't have it: use Docker there and link it to Home Assistant. |
| A 64-bit machine | amd64 (x86-64) or aarch64 (64-bit ARM, such as a Raspberry Pi 4 or 5, or Home Assistant Green and Yellow). |
| The Mosquitto broker app | Sonorium sends its controls to Home Assistant over MQTT and does not start without a broker. The next section installs it. |
| Speakers in Home Assistant | Any media_player entity: Google Cast (Chromecast, Nest, Google Home), Sonos, Music Assistant players and most smart speakers with a Home Assistant integration. |
| Virtual machines | If Home Assistant runs in a virtual machine (Proxmox and others), set the VM's CPU type to host. See Requirements. |
Skip this if Mosquitto broker is already installed and running.
- In Home Assistant, open Settings › Add-ons and click Add-on Store at the bottom right.
- Search for "Mosquitto" and click Mosquitto broker.
- Click Install and wait for it to finish.
- Turn on Start on boot.
- Click Start.
- Open Settings › Devices & services. Home Assistant shows the MQTT integration as discovered. Click Configure, then Submit.
Sonorium finds this broker automatically.
Using another MQTT broker? Leave Mosquitto out and fill in the sonorium__mqtt_host options in Configuration instead.
Home Assistant's store lists apps from repositories. Sonorium's repository has to be added once.
With the button: click this button, which opens your Home Assistant with the repository filled in, then click Add:
By hand:
- Open Settings › Add-ons › Add-on Store.
- Click the ⋮ menu at the top right and pick Repositories.
- Paste
https://github.com/synssins/sonoriumand click Add. - Click Close.
The store now has a Sonorium section. If it doesn't show, reload the page.
- In Settings › Add-ons › Add-on Store, find the Sonorium section and click Sonorium.
- Click Install. Home Assistant downloads a ready-made image for your machine; this takes a few minutes.
- Turn on Start on boot, so Sonorium starts with Home Assistant.
- Leave Show in sidebar on: the sidebar entry signs Home Assistant users in to Sonorium (see Open the web UI).
Don't start it yet if you want to change an option first; the defaults work for most homes.
The add-on's Configuration tab holds Sonorium's start-up options. After changing one, click Save and restart the add-on (Info tab › Restart).
| Option | Default | What it does |
|---|---|---|
log_level |
info |
How much the log says. info shows a start-up summary, warnings and errors. debug adds detail per theme and per speaker, and library versions. The other choices are trace, notice, warning, error and fatal. |
sonorium__stream_url |
auto |
The address speakers fetch the sound from. auto uses Home Assistant's address on your network with port 8008. Set it only when speakers can't reach that address, for example http://192.0.2.5:8008. |
sonorium__path_audio |
/media/sonorium |
The folder that holds the themes, one folder per theme. It is inside Home Assistant's media folder. |
sonorium__max_channels |
6 |
How many channels can play (or be listened to in a browser) at the same time, from 1 to 10. Each playing channel uses some processor time, which matters on a Raspberry Pi. See Channels. |
sonorium__mqtt_host |
auto |
auto uses the Mosquitto broker app. Type a host name or address only for another broker. |
sonorium__mqtt_port |
0 |
That broker's port. 0 means 1883. |
sonorium__mqtt_username, sonorium__mqtt_password
|
empty | That broker's login. |
web_ui_only_through_ha |
false |
true keeps the web UI in Home Assistant's sidebar only. Ports 8008 and 8808 then serve the audio streams, linked phones and keys, but not the web UI. |
bypass_login |
false |
Recovery only. true opens the web UI on the direct ports without a sign-in. See Forgotten password. |
The Network section of the Configuration tab maps Sonorium's ports to the Home Assistant machine:
| Container port | Host port | Serves |
|---|---|---|
8080/tcp |
8008 | The web UI, the API and the audio streams, over HTTP. Speakers fetch the sound here, so this port must stay mapped. |
8808/tcp |
8808 | The web UI and the API over HTTPS, for the Sonorium app for Android. The certificate is made by Sonorium, so a browser warns about it; the app checks its fingerprint instead. |
Change a host port only if another app already uses it. Home Assistant's sidebar reaches Sonorium on a separate internal port that is never mapped.
- On the add-on's Info tab, click Start.
- Open the Log tab and click Refresh after a few seconds.
A good start includes lines like these:
Starting Sonorium addon...
Auto-detecting MQTT from Supervisor services...
MQTT auto-detected: core-mosquitto:1883
Configuration:
Stream URL: auto
Audio Path: /media/sonorium
Max Channels: 6
Python imports OK
Launching Sonorium...
Users: new install, an admin account is made on the first visit
MQTT connected successfully
Sonorium 1.7.1 (HA App) ready: 3 themes, 12 speakers detected, 0 channels, MQTT connected
- 3 themes are the bundled ones: Sleigh Ride, Tavern and A Rainy Day... Or is it?
-
speakers detected is the number of
media_playerentities Sonorium found in Home Assistant. - MQTT connected means the broker was found. Within a few seconds a Sonorium device appears in Home Assistant under Settings › Devices & services › MQTT.
If the log says No MQTT broker is registered with the Supervisor yet. Waiting up to 2 minutes for the Mosquitto broker add-on to start..., Sonorium is waiting for Mosquitto, which is normal while Home Assistant boots. If Mosquitto never comes, the log says what to check, Sonorium doesn't start, and its sidebar page shows 502: Bad Gateway.
Click Sonorium in Home Assistant's sidebar. Every Home Assistant user sees it there and is signed in already: Home Assistant told Sonorium who they are. The Open Web UI button on the add-on's Info tab opens the same web UI on port 8008 in a new tab.
Sonorium opens on the Channels page. The bottom left of its menu shows the version and HA App.
Home Assistant's users are Sonorium's users, with the role they have in Home Assistant:
| In Home Assistant | In Sonorium |
|---|---|
| Owner, or in the Administrators group | Admin: everything, including settings, users and keys |
| User, Read-only | User: plays and changes channels, playlists and sequences; sees themes and speakers |
| Switched off ("Can log in" off) or removed | Signed out; their phones and keys stop working |
A role change in Home Assistant applies within a minute. Passwords stay in Home Assistant: Sonorium keeps no password for these users. See Sign-in and Users.
On any device on your network, http://<Home Assistant's address>:8008 opens Sonorium directly, for example http://192.0.2.5:8008. On a new install this asks for a sign-in: use your Home Assistant username and password. Sonorium passes them to Home Assistant to check and never keeps them.
After an update from a version before 1.7.0, the direct port stays open without a sign-in until an admin turns on Require login with the banner at the top of the page. See Require login.
To keep the web UI in the sidebar only, set web_ui_only_through_ha to true.
-
Speakers: every
media_playerin Home Assistant is listed on Settings › Speakers, by Home Assistant's floors and areas, and switched off. Sonorium uses only the ones you turn on: How to turn a speaker on. - Floors and areas come from Home Assistant and are read-only in Sonorium; change them in Home Assistant. See Floors and areas.
- Home Assistant's controls: each channel gets entities over MQTT (play switch, theme, preset and playlist selects, volume, announcements), and Sonorium's dashboard cards are added to Home Assistant automatically. See Home Assistant Integration, MQTT Entities and Dashboard Cards.
- Announcements: each channel also gets a notify entity that speaks a message with Home Assistant's text to speech. See Announcements.
The Connection settings page is not in the Home Assistant app: Home Assistant and the broker are found automatically.
| What | Where | Reach it from |
|---|---|---|
| Themes and sound files | /media/sonorium |
The media share of the Samba share app, or the upload in Sonorium's Theme Editor. |
| Settings, channels, playlists, plugins, keys | addon_configs/<id>_sonorium/sonorium |
The addon_configs share of the Samba share app. |
Home Assistant backups include the add-on's settings when the add-on is in the backup, and the themes when the Media folder is.
When a new version is out, Home Assistant shows an update for Sonorium under Settings (and on the add-on's Info tab). Click Update. Its release notes are on the add-on's Changelog tab.
The update replaces the program only: themes, channels, settings and accounts stay. Playing channels stop during the update; press Play to start them again.
- Open Settings › Add-ons › Sonorium.
- Click Uninstall.
When Home Assistant offers to delete the add-on's data as well, choosing it removes Sonorium's settings folder (channels, playlists, accounts, keys). The themes in /media/sonorium are your files and stay; delete that folder yourself if you no longer want them. The Sonorium device stays in Home Assistant as unavailable; delete it under Settings › Devices & services › MQTT.
| Problem | What to check |
|---|---|
| The sidebar shows 502: Bad Gateway | Sonorium isn't running. Read the add-on's Log tab: most often the Mosquitto broker app isn't started, or Start on boot is off for it. |
Segmentation fault, or FAILED: numpy import and a line about SSE4.2 |
Home Assistant runs in a VM with a basic CPU type. Set it to host: Requirements. |
| No speakers in the channel editor | Speakers are listed on Settings › Speakers but switched off: turn them on. |
| A speaker is picked but stays silent | The speaker must reach Home Assistant's address on port 8008. On a network with several subnets or VLANs, set sonorium__stream_url. See Troubleshooting. |
| No Sonorium entities in Home Assistant | The MQTT integration is set up (step 6 of Install the Mosquitto broker), and the log's start-up line ends with MQTT connected. |
| Port 8008 doesn't open | The Network section still maps 8080/tcp to a host port. |
| Anything else | Settings › Logs in Sonorium, or the add-on's Log tab. See Troubleshooting. |
Sonorium is running. The rest happens in the web UI and is the same on every install:
- Turn on your speakers: Sonorium lists every speaker Home Assistant has, but uses only the ones you turn on.
- Make your first channel and play it.
- Themes: the bundled themes, making your own and adding sound files.
- Presets, Sequences and Playlists: different versions of a theme, and channels that change over time.
- Home Assistant Integration and Automation Examples: control Sonorium from Home Assistant.
All of Sonorium's documentation starts at Home.