Skip to content

About

WebSphere Liberty SIP Servlet – Retro-Zeitansage auf Spanisch: ‚Al próximo pitido es…‘

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Próximo Pitido – time announcement

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…"

Why "Próximo Pitido"?

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.

Concept and call flow

Single language

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.

Multiple languages

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.

Language ordering

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.

Extensibility

Languages are provided as CDI beans implementing LanguageFactory (SPI module). Adding a new language means adding a new CDI-visible implementation — no changes to the core or war modules are required.

SIP Registration

On startup the app performs a SIP REGISTER handshake with the configured registrar:

  1. SipRegistrationServlet.init() schedules a 2-second deferred REGISTER (virtual thread) to allow the Liberty SIP container and DAR router to initialise first.

  2. If SipFactory is not yet available in the servlet context, SipRegistrationListener retries startup registration with short backoff instead of failing with a startup NullPointerException.

  3. SipRegistrationListener.register() uses SrvDnsResolver to find the registrar’s actual host via a JNDI _sip._tcp SRV lookup, then sends an unauthenticated REGISTER over TCP.

  4. The registrar responds 401 Unauthorized with a Digest MD5 challenge.

  5. SipRegistrationListener.registerWithAuth() reuses the original request’s Call-ID (sipFactory.createRequest(origRequest, true)) — required by RFC 3261 §10.2 — and delegates Digest computation to DigestMd5Computer.

  6. A 200 OK confirms successful registration; the state machine moves to REGISTERED.

Digest auth details

  • 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.

Default Application Router (DAR)

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.

What the DAR does

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

AppName

Name of the SIP application as declared in @SipServlet(applicationName = "…​").

RouteHeader

How the router identifies the target (usually "DAR:From" — route based on the From header).

Region

Routing region: "ORIGINATING", "TERMINATING", or "NEUTRAL". For a simple UAS (like this app) "NEUTRAL" is correct.

Route

An additional SIP route to push onto the route set. Empty string "" for none.

Directive

What to do after this application handles the message. "NO_ROUTE" means stop routing here — do not forward the message further. "CONTINUE" would pass it to the next application in the chain.

Order

Numeric position when multiple applications compete for the same method. "0" = first.

Why REGISTER must not appear in dar.properties

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.

INFO (DTMF) must be listed

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.

Full current dar.properties

# 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")

Configuration (server.env)

Env var MP Config property Description

SIP_REGISTRAR

sip.registrar

SIP domain of the registrar (e.g. tel.t-online.de, sip.sipgate.de). Optional when registration is disabled.

SIP_SIPID

sip.sipid

Your SIP subscriber ID / phone number. Optional when registration is disabled.

SIP_USER_ID

sip.user.id

Auth username (often an e-mail address). Optional when registration is disabled.

SIP_USER_PASSWORD

sip.user.password

Auth password. Optional when registration is disabled.

SIP_LOCAL_HOST

sip.local.host

LAN IP Liberty binds the SIP endpoint to

SIP_PUBLIC_HOST

sip.public.host

Public IP advertised in the Contact header (auto-detected if absent)

SIP_REGISTRATION_ENABLED

sip.registration.enabled

Set to false to skip REGISTER entirely and accept direct calls only (softphone / dev mode). Default: true.

server.env is intentionally excluded from version control (contains secrets).

Timezone

The announced time uses the JVM default timezone, which OpenJDK on Linux resolves in this order:

  1. TZ environment variable — the standard Docker mechanism. Set TZ=Europe/Berlin in docker-compose.yml or pass -e TZ=Europe/Berlin to docker run.

  2. /etc/localtime inside 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.

Known quirks

  • Liberty sipEndpoint host="*" resolves to 127.0.1.1 on this system — bind to the LAN IP explicitly via SIP_LOCAL_HOST.

  • Fritz!Box SIP ALG intercepts UDP port 5060 — use TCP transport.

  • Liberty’s SIP stack does not follow SRV records; SrvDnsResolver uses JNDI DnsContextFactory instead.

  • Do not declare <servlet> in sip.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 return stale=true indefinitely.

  • SipFactory and SipProvider are null if accessed directly in init() — the 2-second virtual thread delay is necessary.

Running

./mvnw liberty:run -am -pl war

Logs: war/target/wlp-usr/servers/proximo-pitido/logs/messages.log

Optional system libraries

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

libopus.so.0

sudo apt install libopus0

sudo pacman -S opus

microdnf install opus

OGG/Opus audio decoding — required for the bundled language packs (Opus is the only supported format for language plug-ins)

libspandsp.so.2

sudo apt install libspandsp2

sudo pacman -S spandsp

Enable EPEL first, then:
rpm -i https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
microdnf install spandsp

G.722 HD Voice (50–7 000 Hz) wideband codec. G722RtpCodec.isAvailable() returns false when absent and the call falls back to PCMA.

libsoxr0

sudo apt install libsoxr0

sudo pacman -S libsoxr

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.

Running with Docker

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: host

TZ must be set to an IANA timezone ID. Without it, the container defaults to UTC and callers hear the time in UTC.

About

WebSphere Liberty SIP Servlet – Retro-Zeitansage auf Spanisch: ‚Al próximo pitido es…‘

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages