Your own radio station. It listens to the house.

You built the sensors. You wrote the automations. Now somebody finally notices.

Marco and Giulia, two Italian hosts, broadcast a late-night show mostly in English. The station runs on hardware you control. They play music, argue like hosts who have known each other too long, and read ads for forty companies that do not exist. If you invite the house in, its small dramas become part of the show.

"Breaking news from the laundry room: it's done. It's been done for two hours. Nobody cares but us."

▶ Hear it happen: four half-minute moments

Sound on. No install, no account. Each clip starts as ordinary radio, then the house turns up as part of the show and the page reveals the invented Home details behind the moment. The demo never touches your Home Assistant.

Another minute and a half: three short films from Studio B: Archive Receipt, Jealous Microphone, Third Chair. Synthetic voices throughout.

I built this because a smart home is invisible to everyone who did not build it. At dinner with seven guests, the hosts called me out for ignoring the pasta timer. Someone stopped the conversation to ask what the radio had said. Nobody questioned the station until the first fourth-wall break.

Why it feels like radio

Marco and Giulia have a written relationship, recurring Studio B lore, station imaging, music, and forty fictional sponsors. Home details enter as editorial material only when there is something worth airing. The show keeps going when the house has nothing to say.

At home, they regularly call me out about the washing machine, what I'm watching or listening to, and which room I'm in. I chose to share those details with the station. The four public demos use invented data so you can hear that kind of exchange without connecting your home.

Existing home-aware stations already use broader household context. Fresh installations start with Home context off under the default settings. After you inspect the filtered preview, their current guided opt-in is limited to daylight and one unambiguous weather source, with temperature rounded to five-degree Celsius bands. A later Home Profile update will add per-category controls for broader sharing.

The station runs on your hardware. It is not a voice assistant and does not run household automations. If you explicitly choose a Home Assistant speaker, it asks that media player to play the stream. There is no Mamma Mi Radio account, subscription, or project-operated analytics upload. You add provider keys only when you want freshly written dialogue or premium voices.

Status: single maintainer, running daily in one household. Stable 3.0.0 is available. The First Listen steps and screenshots below describe this release.

First listen

Home Assistant Apps require Home Assistant OS, including Home Assistant Green and Yellow. Home Assistant Container users can run the Docker alternative.

You can also add the repository by hand. Open Settings → Apps → Install app → ⋮ → Repositories, paste https://github.com/florianhorner/mammamiradio, and select Add. Install and start Mamma Mi Radio, then open its Web UI.

No AI key is required for your first listen. Fresh installs open First Listen at the producer desk (/admin). Returning installs open the control room; you can find First Listen under Motore -> Setup.

1. Select Start my station. A reviewed English opening plays /stream?first_listen=1 on the current device for about 15 seconds, then hands off to the live stream. Use its speakers, headphones, Bluetooth, or AirPlay. You need no AI key or Home context. No HACS integration is required.
2. Select I can hear it only after you hear Mamma Mi Radio. Select I can't hear you for repair steps.
3. Make it yours starts with a recorded evening scene that uses no details from your home. Select Keep Home private to finish without setting anything up. Otherwise select Hear the evening, then Set up AI and Home; Skip this example goes straight to that setup. There, add a writing key and select Choose my Home details, or select Skip AI, choose Home details. With default settings, Home context stays off unless you select Preview my Home and then Share these details. You can choose Keep Home private from that preview instead. If the preview contains only generic daylight and no usable weather, the app labels it ambient-only. The button becomes Let the hosts use daylight only, with a warning that this would not make the show more personal yet.
4. Select Listen to the station to enter the /listen station page, or Open station controls to return to /admin. The handoff preserves the audio already playing. Install the HACS integration later if you want native media-source://mammamiradio/live playback on Home Assistant speakers. The Music Assistant provider can also play it as one live station with current and up-next metadata.

Docker alternative

git clone https://github.com/florianhorner/mammamiradio.git && cd mammamiradio
cp .env.example .env
docker compose up      # ADMIN_TOKEN auto-generates if unset

Open http://localhost:8000. The starter music works offline. Add an AI key when you want generated host conversations.

The stock Docker setup leaves external extraction off. Standalone installs can add the external-media extra, but technical access does not grant media rights. The supplied Docker container uses /data/music. The Home Assistant app reads a folder in the Media panel when that storage is mounted (the Music folder setting, default mammamiradio) and /data/music when it is not. Source checkouts use ./music. Set MAMMAMIRADIO_MUSIC_DIR to override a standalone install.

On a Mac, double-click Start Radio.command in the checkout. The first time, it prepares .venv; after that it opens the station straight away. ./setup-mac.sh builds a Dock app from an environment that already exists, and ./start.sh starts one from the terminal.

Mac launcher

Start Radio.command needs Python 3.11 or newer and ffmpeg. With Homebrew installed, the first run installs whichever of the two is missing. When both are already installed, the launcher uses those copies.

The launcher installs the versions pinned in requirements.txt, then this checkout. Leave the window open: on a slow network the download takes several minutes. Once setup finishes, later double-clicks skip it, and a setup that stopped early runs again. When requirements.txt, pyproject.toml or the launcher's setup steps change, the next double-click prepares the station again. If you are offline then and the update needs no new components, the launcher starts the station you already have and finishes the update on a later double-click; otherwise it asks you to connect first. Moving the checkout folder works too: the next double-click prepares the station for its new place. .env and music/ stay in the checkout.

Mac launcher recovery

Stop the station in its window and let any running setup finish. Then, from the checkout root:

[ -f "./Start Radio.command" ] && [ -f ./mammamiradio/main.py ] && mkdir -p ./tmp && backup_dir="$(mktemp -d "./tmp/venv-backup.XXXXXX")" && mv .venv "$backup_dir/environment" && open "./Start Radio.command"

The command first checks for Start Radio.command and mammamiradio/main.py, so outside a Mamma Mi Radio checkout it changes nothing. It moves the old environment into a new directory under tmp/ and leaves earlier backups alone. That backup is not a station you can run. .env and music/ stay where they are.

What each key adds

You add	The station adds
Nothing	Twelve packaged, credited tracks, station imaging, the 15-second First Listen opening, 21 prerecorded Demo Radio breaks, and 11 finished fictional ads. Those assets make no provider call; other stock copy can use keyless online Edge TTS
ANTHROPIC_API_KEY or OPENAI_API_KEY	Written-on-the-fly banter, news flashes, and ad breaks for forty fictional brands. Billed to you; the control room shows a running estimate
ELEVENLABS_API_KEY	The premium cast on one key: Marco, Giulia, and most ad characters. Without it, every voice uses its free Edge double
OpenAI or Azure Speech credentials	Cloud voices for custom voices you configure yourself; the shipped cast uses neither
An AI key plus approved, filtered Home context	Household-aware banter on existing home-aware stations. Today's guided opt-in on fresh installs is limited to coarse daylight and weather

Provider usage is charged to the API account behind your key; OpenAI API billing is separate from ChatGPT subscriptions. ElevenLabs changes only the voices. An OpenAI voice you configure yourself also needs a speech model pinned in model_registry.toml; none ships pinned.

Privacy

With the default Home-context setting, a fresh install starts off. The Host home context choice is omitted and remains off until you hear the station, inspect the filtered preview, and explicitly choose Share these details. An explicit MAMMAMIRADIO_HA_CONTEXT_ENABLED=true operator setting overrides that guided default. The station does not poll Home state for host material while context is off. You can keep Home private without fetching a preview. If you want household details on air, mute any entity the hosts should ignore. Previewing does not publish the snapshot into host scripts or send it to an AI provider.

After opt-in, the active writing provider receives the authorized, filtered prompt slice. If a Home-derived line uses online speech synthesis, that spoken text also goes to the configured voice service or Edge. Existing legacy installations may also use Anthropic to generate labels from sanitized entity metadata; optional AI mood naming sends a bounded Home-state summary. Post-air memory is written only after generated material airs and only while Home context stays on. Without a script key, no Home context reaches an AI writing provider.

Turning Home context off stops Home-state and timer polling. It cancels Home-derived generation and memory work, removes queued Home-derived breaks, and clears public Casa moments. Audio on air may finish to avoid dead air, but it cannot write Home memory afterward. Home Assistant entity publishing can stay on while host context stays off.

The station itself runs on your hardware. Mamma Mi Radio has no account system, central service, or project-operated analytics upload. Operational counters and the optional provenance ledger remain local. Paid AI calls use credentials you supply; Edge is keyless but still online. In the Home Assistant app, saved keys live in /config/secrets.env; the UI never echoes them. Provider-side processing follows each provider's terms.

Music

Normal rotation starts with the offline, attributed twelve-track starter collection, so no provider account or network music source is required. The listener shows the source, license, and modification notice for each track. The Home Assistant app scans the Media folder named in its Music folder setting when Media is mounted, and /data/music when Media is not. The control room names that place. Use Rotazione > Local music > Scan now to refresh without a restart. The supplied Docker container keeps songs in /data/music. Other standalone installs can set MAMMAMIRADIO_MUSIC_DIR.

Jamendo is off by default. To enable it, acknowledge that your Jamendo API use is non-commercial. Provider confirmation for this station model remains pending. The station prepares one track at a time and deletes it after play or cancellation. Jamendo is not a recovery or restart source. Read Music sources and rights boundaries before enabling it.

Packaged recovery clips keep the speaker path audible while the music source stays marked unhealthy.

Make it yours

radio.toml defines the hosts, voices, pacing, and ad brands. The /admin control room lets you reorder the queue, ban a song on air, change AI quality, and switch between Festival, Chaos, and Super Italian modes. The default show is roughly 75% English and 25% Italian; Super Italian switches the hosts to 100% Italian. See the full configuration in .env.example and Operations.

Operator checks

Producer started means the engine started. /readyz stays at 503 starting until a listener accepts audio, returns 200 with "ready": true after that, and reports 503 stopped during an intentional stop. Queue depth and elapsed time do not prove that anyone heard the station.

First Listen remains the human check: hear Mamma Mi Radio on the current device. For branch development, use the disposable Home Assistant lab to keep test state away from your live home.

Docs

Interactive demo | Pilot feedback | Earlier product assessment | Architecture | Music sources and rights | Troubleshooting | Operations | Repo map

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md. The merge-first protocol protects a new contributor's patch from being refactored out from under them before it lands.

License

The code is Apache-2.0. Each bundled asset keeps its own license and attribution. The imaging attribution file covers station imaging. Starter music uses CC BY sources from Incompetech (4.0) and Jamendo (3.0); Jamendo facts are provider-reported. You remain responsible for the media your station plays and the words it puts on air. See Music sources and rights boundaries.