Announcer

v1.4 - 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.

The status page is the first place to look when something is wrong. Browse `http://<processor-ip>:8080/` from any browser on the LAN (or whatever you set HTTP Port to). It shows every recent announcement with its outcome including the ones the driver refused and why, the licence state, your clips with a link to play each one, and the control address the driver resolved for each speaker. It is the quickest way to tell "the driver was never called" apart from "the driver tried and the speaker refused."

What's new in v1.4

· Announcements now work on speakers that format their replies differently. A speaker's reply is packaged in a standard envelope, but the short name a device gives that envelope is its own choice, and every name is equally valid. The driver only recognised three of them. On a speaker using any other name the reply was never recognised as finished, so the driver waited for the rest of a message it already had, gave up, and reported a timeout against a speaker that had answered correctly and immediately. It then treated that speaker as unreliable and re-scanned for it after every announcement. The driver now works out where the reply ends the way the protocol defines it, rather than by looking for a name it recognises.

· A speaker that closes the connection when it has finished is now understood. That is a normal and complete way to end a reply, and it was previously ignored.

· Descriptions that arrive in pieces are read correctly. Some speakers send their device description split into small fragments. One of the two places that check whether the whole description has arrived was reading the fragmented form rather than the reassembled one, so on a speaker that both fragments its description and holds the connection open, the driver could conclude the speaker had no playback service at all.

· The clip server now always recovers from a failed start. If the port was busy at the moment the driver started, one particular failure could stop the automatic retry for good, leaving every announcement refused until the driver was re-sent. The retry can no longer be skipped.

· A wedged announcement now reports what went wrong. The safety net that clears a stuck announcement updated the result but not the error text, so the Last Error value could still show an older, unrelated message.

What's new in v1.3

· A clip is no longer reported as played until the speaker says it is playing. The driver used to start its hand-back countdown the moment a speaker acknowledged the play command. A speaker that has just been handed a new source has to connect, fetch the audio and fill a buffer before it makes a sound, and the first time it does that it is starting cold. On a slow start the previous source went back before anything was audible, and the announcement had already been recorded as successful. The driver now asks the speaker what it is doing and waits until it reports that it is playing, so both the timing and the Played event describe what actually happened. If a speaker will not answer that question the announcement still goes ahead, and the log says the result could not be confirmed rather than claiming success.

· A speaker advertising a newer version of the playback service is reported instead of ignored. A renderer that offers AVTransport version 2 rather than version 1 was previously described as having no playback service at all. The log now names the device and asks you to report it.

· Every build now identifies itself in the log. The recurring status line carries the version, the package it came from and whether it is a trial or licensed build, so a log tells us exactly which driver produced it.

What's new in v1.2

· Non-Sonos speakers now work. Earlier versions sent every command to the control address Sonos uses. Other UPnP/DLNA renderers publish the same service at a different address, so announcements to them failed with a timeout no matter how the speaker was configured. The driver now reads each speaker's real control address from the speaker itself when it starts up, which is how UPnP is meant to work. Confirmed against the published device descriptions of Denon/HEOS players on two firmware generations and a WiiM Pro, each of which uses a different address. That confirms the driver finds the right address on those brands; whether an announcement completes on one is a separate question and depends on the speaker.

· A clearer answer when a speaker will not play. Each speaker now reports a Control Endpoint value. `(discovered)` means the driver read that address off the speaker and proved it, `(manual)` means you set it yourself, and `(default)` means the driver could not reach the speaker for its address and is falling back to the Sonos one. If an announcement fails, that value tells you which problem you have.

· A speaker that is still booting no longer stays broken. If a speaker is not on the network when the processor starts, the driver retries in the background instead of leaving that slot misconfigured until the next reboot.

· Refusals now say why. When a speaker rejects a command the log records the UPnP error code, not just a generic 500, so the reason is visible rather than guessable.

· Manual override. A new Advanced: Control Endpoints category lets you set a speaker's control port and path by hand for the rare case where the driver cannot reach it to ask.

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 `http://<processor-ip>:8080/` 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 on your firewall and set the Advertised Host/IP option. The speaker must be able to reach the processor on the HTTP port you set below, and the processor must be able to reach the speaker on its UPnP control port. That port is not the same for every brand: Sonos uses 1400, Denon/HEOS publish on 60006, and many other renderers sit in the 49152-49155 range. The driver finds it automatically when it can reach the speaker, so the simplest arrangement by far is to keep the speakers and the processor on the same subnet.

Setup

1. Server. Leave HTTP Port at 8080 (any free port above 1024 works). That same port serves the status page at `http://<processor-ip>:8080/`, which is worth opening once now so you know where it is before you need it. 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

A speaker will not play, and it is not a Sonos. Look at that speaker's Control Endpoint variable first, before anything else.

· `(discovered)` - the driver found and proved the speaker's real control address. The address is not your problem; look at the log for the actual refusal, which now includes the UPnP error code.

· `(default)` - the driver could not reach the speaker to ask for its address and is falling back to the Sonos one. On a Sonos that is correct and everything will work. On anything else it means the speaker was unreachable when the driver looked. Check the IP, check the speaker is powered up and on the network, then reload the driver or wait for the automatic retry.

· `(cached)` - the address the driver proved on an earlier start and restored from its own memory, so the speaker works from the first announcement after a restart without waiting for a fresh search. It is trusted until an announcement fails.

· `(manual)` - you set the address yourself under Advanced. The driver will not second-guess it, so if it is wrong, nothing else will correct it. Clear both Advanced fields to hand the slot back to automatic discovery.

· A `, suspect` suffix means an announcement to that address failed recently. The driver keeps using it, because it may simply be that the speaker was switched off, but it will search again in the background and replace it if it finds something better.

Setting a control address by hand. Only necessary when the processor cannot reach the speaker for its description, for example across a firewalled VLAN. Browse to the speaker's device description in a web browser (Sonos publishes it at `http://<speaker-ip>:1400/xml/device_description.xml`, Denon/HEOS at `http://<speaker-ip>:60006/upnp/desc/aios_device/aios_device.xml`, many others at `http://<speaker-ip>:49152/description.xml`), find the `<service>` block whose `<serviceType>` ends in `AVTransport:1`, and take the `<controlURL>` from inside that same block. Put the port number in Control Port and the controlURL in Control Path. Both must be filled in for the override to apply. Take the path only, starting with a slash: do not paste a full `http://...` address.

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