Announcer

v1.1 - Custom Control Drivers LLC

Turn your RTI processor into an audio-announcement server. The processor hosts a small library of audio clips and plays them on your Sonos or other UPnP/DLNA speakers on demand - no NAS, no extra hardware, no cloud. Any RTI event can trigger an announcement: a doorbell press plays "Someone is at the front door," a camera detects motion and a speaker says "Motion in the driveway," a gate contact announces an arrival. You supply the clips (paste your own, or pick a built-in), name your speakers, and wire the Announce function to whatever events you like.

What's new in v1.1

· The speaker is always handed back to the source it was on. Previously, if a speaker was idle (stopped) when an announcement played, it was left pointed at the clip instead of the station or playlist it had loaded. It now gets that source back every time, whether it was playing or not, and whether Resume After is on or off.

The handback is timed to the clip. The driver reads each clip's length and waits exactly that long before restoring, instead of a fixed eight seconds. Short chimes hand back in about two seconds instead of eight; long announcements are no longer cut off by their own restore.

The status page answers "did it fire?" Browse the processor on the HTTP port and you now get licence state, uptime, played and failed counts, anything queued, and a timestamped list of recent announcements including any the driver refused and why. If that list is empty, the driver was never called.

Faults always reach the processor System Log. Errors are written on a channel the Debug Level setting cannot switch off, key events are logged there too, long lines are wrapped instead of truncated, and the driver writes a short state summary every five minutes so the log is useful whenever you look at it.

Stop All now stops every speaker. It previously stopped only the last configured slot.

Stopping mid-announcement still restores the source rather than leaving the speaker on the clip.

Better behavior on non-Sonos renderers. If a renderer refuses to change source while it is playing, the driver now stops it and retries, which is what Denon/HEOS, MusicCast and WiiM units generally require.

Grouped Sonos speakers are detected, warned about by name, and have their grouping restored afterwards instead of being left out of the group.

Recovery. If the clip server cannot claim its port at startup it now retries automatically instead of staying dead until someone restarts it, and a stuck announcement can no longer block every later one.

Each new version gets a fresh evaluation period. If you ran out of trial time on an earlier version, installing this one gives you the full 120 minutes again so you can evaluate what changed.

New `history` console command, and Debug Level "Off" now actually means off for detail while still logging faults.

Requirements

· An RTI XP processor (firmware v24+).

One or more Sonos speakers, or other UPnP/DLNA renderers (Denon/HEOS, Yamaha MusicCast, WiiM, many AVRs).

The speakers and the processor must be able to reach each other on the network. The speaker fetches the clip *from* the processor, so this must work in both directions. Putting the speakers on the same subnet/VLAN as the processor is strongly recommended. If they are on a separate VLAN, you must allow traffic both ways (processor to speaker on port 1400, and speaker to the processor on the HTTP port you set below) on your firewall, and set the Advertised Host/IP option.

Setup

1. Server. Leave HTTP Port at 8080 (any free port above 1024 works). Leave Advertised Host/IP blank unless your speakers are on a different subnet (see Requirements).

2. Clips. Under Clips, name each clip you want (e.g. "Front Door"). For each named clip either pick a built-in Default Clip, or paste your own audio as base64 into Clip Audio (see "Preparing your own clips" below). Each new clip slot appears after you name the previous one.

3. Speakers. Under Speakers, name each target (e.g. "Family Room") and enter its IP Address. Find a Sonos IP in the Sonos app under System > [speaker] > About, or in your router's client list. Give each speaker a DHCP reservation so its IP doesn't change. Leave Resume After on to have the speaker return to what it was playing once the announcement finishes (best-effort - see notes).

4. Transfer the system. The clip server starts automatically.

5. Wire it up. In your macros, call Announce and pick a Clip and a Speaker from the dropdowns. Trigger it from a doorbell, camera, gate, alarm - anything.

Preparing your own clips (base64)

The Clip Audio field takes the base64 encoding of an MP3 file - that is, the encoded bytes of an actual .mp3, NOT base64 of typed text. Encoding a sentence like "Someone is at the front door" as text will NOT work; the speaker will reject it with "can't play, not encoded correctly". You must encode a real audio file.

How to prepare a clip:

1. Get or make a short MP3 (a few seconds; a doorbell chime or a spoken phrase). Keep it small - the field accepts roughly 32,000 characters of base64, which is about a 24 KB MP3 (more than enough for a short clip). Mono, 64 kbps is plenty.

2. Convert the MP3 file to base64 using any "file to Base64" encoder. A free one that works: base64.guru - go to Converter, set Datatype to Local File (or use the "File to Base64" tool), upload your .mp3, and choose Output Format = Plain text. (If you use a "Text to Base64" tool by mistake you'll encode the words, not the audio - that's the #1 reason a custom clip won't play.)

3. Copy the resulting base64 string and paste it into the Clip Audio field for that clip.

4. Transfer the system (or run the Reload Clips function). The clip's status shows "Ready" with its byte size, and it appears at its served URL.

Tip: to verify a clip without a speaker, browse to `http://<processor-ip>:<HTTP Port>/` for the status page, where each ready clip is downloadable for a quick listen.

What the driver gives you

The headline function - Announce(Clip, Speaker) - play any clip on any speaker. Plus Stop, Stop All, and Test Speaker.

Per-clip feedback - name, ready state, source (pasted vs built-in), byte size, the URL it's served at, and last-played info.

Per-speaker feedback - name, IP, reachable, currently playing, last result.

Aggregates - clips ready, speakers configured, any playing, plus a one-line System Health for a panel header.

Events - Announcement Played / Failed, per-speaker Played / Failed / Resumed, server started / failed, clips reloaded, plus trial/license events.

The signature automation: a UniFi Protect doorbell press fires a macro that calls Announce("Front Door", "Family Room"), and the whole house hears "Someone is at the front door" - then the music it interrupted comes back on.

Scope notes

· The speaker is always handed back to whatever it was on. When the clip finishes, the driver re-points the speaker at the source it was using before the announcement, whether or not it was playing at the time. A speaker that was sitting idle on a station keeps that station; it is not left holding the clip.

Resume After controls playback, not the handback. With it on, a speaker that was *playing* is started again where it left off. With it off, the source is still handed back but playback is not restarted. Live radio and streaming-service sources (Spotify, Pandora, TuneIn, etc.) restart the station rather than resuming mid-track - that is a limit of those services, not the driver, and it is what the Sonos app itself does.

Clip length sets the handback delay. The driver reads each clip's length and waits exactly that long (plus a moment for buffering) before handing the speaker back, so a half-second chime and a thirty-second message both behave correctly with nothing to configure.

Grouped speakers: target the group's coordinator. If you point a slot at a speaker that is following another one, the driver logs a warning naming the coordinator, and restores the grouping afterwards.

Clip size: keep clips short (a few seconds). Pasted clips are limited by the config field (about 32,000 base64 characters, roughly a 24 KB clip). Built-in defaults and short custom chimes are well within this.

Playback interrupts current audio to play the clip, then resumes (per above). That's the intended doorbell/alert behavior.

Troubleshooting

The announcement doesn't play and Last Result shows a connect failure.

Check the speaker's IP and that it's reachable from the processor. The most common cause is the speaker being on a different VLAN than the processor - put them on the same subnet, or open the firewall both ways (see Requirements).

Last Result shows the command succeeded (200) but you hear nothing.

The speaker accepted the command but couldn't fetch the clip from the processor. This is almost always a network-reachability problem in the speaker-to-processor direction (VLAN/firewall), or the speaker's volume is down. Confirm both devices are on the same subnet.

A clip shows "decode FAILED" or "not ready," or the speaker says "can't play, not encoded correctly."

Almost always this means you encoded *text* to base64 instead of an *MP3 file*. The Clip Audio field needs the base64 of a real .mp3 file (see "Preparing your own clips"). Re-encode using a "File to Base64" converter (e.g. base64.guru > Datatype: Local File), not a "Text to Base64" tool. Also re-copy the full string in case it was truncated; if you pasted a data: URI, the driver strips the "...base64," prefix automatically. Or just pick a built-in Default Clip.

Nothing happened at all, and you are not sure the driver was even asked.

Browse `http://<processor-ip>:<HTTP Port>/` and read the Recent announcements table. Every attempt is listed with a timestamp and its outcome, including ones the driver refused and why. If that table is empty, the driver was never called and the problem is upstream: check the macro or driver event that is supposed to run Announce. The same page shows the licence state, how many announcements have played or failed, and anything currently queued.

Diagnostic debug console.

Telnet the processor IP on port 12512 (configurable under Debug; enable Advanced settings to see that category). Commands: `status`, `history`, `clips`, `speakers`, `play <clip#> <speaker#>`, `stop <speaker#>`, `reload`, `log off|low|med|high`, `quit`. The console mirrors the driver's log live while you are connected, so you can watch a full announcement as it happens.

Reading the processor log.

In Integration Designer, connect to the processor and open the System Log. Faults and key events from this driver are always written there and are not affected by the Debug Level setting; raise Debug Level to Medium or High only while diagnosing something. The driver also writes a short state summary every five minutes, so the log is useful whenever you happen to look at it.

Licensing

A 120-minute trial is included for evaluation. The trial counts wall-clock time while the driver is loaded and it survives a reboot or a project download, so it does not restart every time you re-send the project.

Each new driver version gets its own fresh 120 minutes, so if you evaluated an earlier version you can still properly evaluate this one.

Paste your purchased licence key under Licensing to unlock permanently. The licence is bound to the processor's MAC address.

Questions or problems: support@customcontroldrivers.com