WebSphere Liberty SIP Servlet – a retro-style speaking clock, named after the Spanish phrase „Al próximo pitido serán las tres horas…" — „At the next beep it will be three o’clock…"
The name is a nod to the analogue telephone speaking-clock services that existed in many countries before smartphones made them redundant. In Germany, it was the Zeitansage (dial 1191), in France l’horloge parlante (dial 3699). The caller would hear a recorded voice counting down to a beep, then announcing the current time to the second.
Próximo pitido is the Spanish version of that countdown phrase. This project brings that experience to a self-hosted SIP number on a home DSL line.
If exactly one language implementation is available on the classpath, an incoming call is answered immediately and the time announcement plays straight away — no menu, no waiting.
If two or more language implementations are present, the caller first hears the language-selection menu, cycling through the available options:
"Für Deutsch drücken Sie die 1." "Press 2 for English." "Para español marque el 3." ... (repeats from the beginning)
The caller can press the corresponding digit at any time — even mid-phrase — and playback stops immediately. The chosen language’s time announcement then plays.
The order in which languages appear in the menu can be configured.
If no explicit order is configured, a deterministic default order is used (defined by each LanguageFactory implementation via getDefaultOrder()), so the menu is always the same across restarts.
On startup the app performs a SIP REGISTER handshake with the configured registrar:
-
SipRegistrationServlet.init()schedules a 2-second deferred REGISTER (virtual thread) to allow the Liberty SIP container and DAR router to initialise first. -
If
SipFactoryis not yet available in the servlet context,SipRegistrationListenerretries startup registration with short backoff instead of failing with a startupNullPointerException. -
SipRegistrationListener.register()usesSrvDnsResolverto find the registrar’s actual host via a JNDI_sip._tcpSRV lookup, then sends an unauthenticated REGISTER over TCP. -
The registrar responds
401 Unauthorizedwith a Digest MD5 challenge. -
SipRegistrationListener.registerWithAuth()reuses the original request’s Call-ID (sipFactory.createRequest(origRequest, true)) — required by RFC 3261 §10.2 — and delegates Digest computation toDigestMd5Computer. -
A
200 OKconfirms successful registration; the state machine moves toREGISTERED.
-
Algorithm: MD5 with
qop=auth -
Digest URI:
sip:<registrar-domain>(the registrar domain — not the SRV-resolved hostname) -
HA1:
MD5(username:realm:password) -
HA2:
MD5(REGISTER:sip:<registrar-domain>) -
Why manual?: Liberty’s
addAuthHeader()uses the SRV-resolved hostname as the Digest URI, causing a hash mismatch.
The DAR is one of the trickiest parts of Liberty SIP Servlet development and a common source of hard-to-diagnose bugs.
Understanding it is essential before touching dar.properties.
Every SIP message that arrives at (or is sent from) a Liberty SIP application passes through the Default Application Router before it reaches any servlet.
The DAR decides which application — and which servlet within that application — should handle each message.
Its configuration lives in war/src/main/liberty/config/dar.properties.
Each line in dar.properties has the form:
METHOD: ("AppName", "RouteHeader", "Region", "Route", "Directive", "Order")
| Field | Meaning |
|---|---|
|
Name of the SIP application as declared in |
|
How the router identifies the target (usually |
|
Routing region: |
|
An additional SIP route to push onto the route set. Empty string |
|
What to do after this application handles the message.
|
|
Numeric position when multiple applications compete for the same method. |
This is a critical gotcha that is easy to miss.
When the app sends an outgoing REGISTER to the registrar, Liberty routes it through the DAR on the way out as well as on the way in.
If REGISTER is listed in dar.properties, the DAR matches the outgoing REGISTER, creates a server-side transaction for it inside the app, and routes it back as an incoming request.
The app has no doRegister() handler, so Liberty responds with 405 Method Not Allowed.
The registrar receives the 405 instead of the real REGISTER — registration never succeeds and the logs fill up with a 405 loop.
The fix: simply omit REGISTER from dar.properties.
Unlisted methods pass through Liberty to the network without triggering application composition.
SIP INFO messages are used to carry DTMF digits during a call (RFC 2976).
When a caller presses a key during the language-selection menu, the digit arrives as a SIP INFO request.
If INFO is not listed in dar.properties, Liberty will not route it to the application and the keypress is silently dropped.
# REGISTER intentionally omitted — see explanation above.
INVITE: ("Proximo Pitido", "DAR:From", "NEUTRAL", "", "NO_ROUTE", "0")
BYE: ("Proximo Pitido", "DAR:From", "NEUTRAL", "", "NO_ROUTE", "0")
ACK: ("Proximo Pitido", "DAR:From", "NEUTRAL", "", "NO_ROUTE", "0")
CANCEL: ("Proximo Pitido", "DAR:From", "NEUTRAL", "", "NO_ROUTE", "0")
INFO: ("Proximo Pitido", "DAR:From", "NEUTRAL", "", "NO_ROUTE", "0")
OPTIONS: ("Proximo Pitido", "DAR:From", "NEUTRAL", "", "NO_ROUTE", "0")| Env var | MP Config property | Description |
|---|---|---|
|
|
SIP domain of the registrar (e.g. |
|
|
Your SIP subscriber ID / phone number. Optional when registration is disabled. |
|
|
Auth username (often an e-mail address). Optional when registration is disabled. |
|
|
Auth password. Optional when registration is disabled. |
|
|
LAN IP Liberty binds the SIP endpoint to |
|
|
Public IP advertised in the Contact header (auto-detected if absent) |
|
|
Set to |
server.env is intentionally excluded from version control (contains secrets).
The announced time uses the JVM default timezone, which OpenJDK on Linux resolves in this order:
-
TZenvironment variable — the standard Docker mechanism. SetTZ=Europe/Berlinindocker-compose.ymlor pass-e TZ=Europe/Berlintodocker run. -
/etc/localtimeinside the container — stock Docker images default to UTC.
Without TZ, callers will hear the time in UTC.
Use IANA timezone IDs such as Europe/Berlin, Europe/London, America/New_York, or Asia/Tokyo.
|
Note
|
user.country and user.region are locale settings for language formatting (decimal separators, date order, etc.).
They have no effect on timezone resolution.
|
-
Liberty
sipEndpoint host="*"resolves to127.0.1.1on this system — bind to the LAN IP explicitly viaSIP_LOCAL_HOST. -
Fritz!Box SIP ALG intercepts UDP port 5060 — use TCP transport.
-
Liberty’s SIP stack does not follow SRV records;
SrvDnsResolveruses JNDIDnsContextFactoryinstead. -
Do not declare
<servlet>insip.xml— it overrides@SipServlet(loadOnStartup=1). -
Auth re-REGISTER must reuse the original Call-ID (
sipFactory.createRequest(origRequest, true)); a new Call-ID causes some registrars to returnstale=trueindefinitely. -
SipFactoryandSipProviderarenullif accessed directly ininit()— the 2-second virtual thread delay is necessary.
./mvnw liberty:run -am -pl warLogs: war/target/wlp-usr/servers/proximo-pitido/logs/messages.log
Some features require native shared libraries installed on the host OS. Without them the feature is silently unavailable at runtime and a pure-Java fallback (where one exists) is used instead.
| Library | Debian / Ubuntu | Arch Linux | RHEL / UBI 9 (Docker) | Feature |
|---|---|---|---|---|
|
|
|
|
OGG/Opus audio decoding — required for the bundled language packs (Opus is the only supported format for language plug-ins) |
|
|
|
Enable EPEL first, then: |
G.722 HD Voice (50–7 000 Hz) wideband codec.
|
|
|
|
not yet packaged in UBI |
High-quality stereo-to-mono channel mixing (sample-rate-aware resampling). Falls back to the built-in Java mixer when absent. The FFM binding is not yet implemented; the library is detected but the Java path is used unconditionally for now. |
A minimal docker-compose.yml example:
services:
proximo-pitido:
image: ghcr.io/bmarwell/proximo-pitido:latest
environment:
TZ: "Europe/Berlin"
SIP_REGISTRAR: "tel.t-online.de"
SIP_SIPID: "4915112345678"
SIP_USER_ID: "4915112345678@t-online.de"
SIP_USER_PASSWORD: "secret"
SIP_LOCAL_HOST: "192.168.1.100"
network_mode: hostTZ must be set to an IANA timezone ID.
Without it, the container defaults to UTC and callers hear the time in UTC.