Table of Contents

1 · What is RDS?

RDS (Radio Data System) is a digital communication standard that transmits data as an inaudible signal modulated onto FM broadcasts (87.5–108 MHz). It was standardised under ETSI EN 50067 and has been in use across Europe since the 1980s.

RDS carries among others the following information:

RDS transmits at 1,187.5 bit/s as a BPSK signal on a 57 kHz subcarrier. A complete PS transmission takes approximately 0.35 seconds under error-free conditions.

2 · Why an AI Plugin?

During long-distance FM reception (DX) – especially via tropospheric ducting or Sporadic-E propagation – signals are often weak and affected by multipath interference or co-channel interference. This results in:

• Packet loss: Entire RDS groups are lost in transit
• Bit errors: Individual bits are decoded incorrectly
• Incomplete PS names: Only 2–3 of the 8 characters are received correctly
• Unknown PI codes: Block A contains errors, PI unreadable

3 · What's New in Version 2.2

Version 2.2 builds on the precision improvements of v2.1 with a focused user-facing enhancement: a live status indicator that communicates the decoder's confidence journey from initial reception through to a fully verified, locked PS name.

4 · Architecture – The Two Plugin Components

5 · Simple Explanation – How the Plugin Works

Imagine listening to an announcement in a busy train station with a lot of background noise. The first time you might only catch "...NR...", the second time "...NRJ...". After hearing it 10 times, you can say with high confidence: the announcement said "NRJ".

That is exactly what the plugin does with RDS data: it listens to many erroneous packets, collects them all, and votes statistically on which character at which position is most likely the correct one. In v2.0 it additionally consults the online fmdx.org transmitter database to cross-check and immediately confirm the station name. Version 2.1 extended this with regional PI codes and special PI pass-through. Version 2.2 makes this entire confidence journey visible in the panel through the new Provisional → Locked status display.

5.1 · Learning by Voting

The station name (PS) consists of 8 character positions. Each position is voted on separately:

After enough votes, a reliable station name emerges. Through its database the plugin already knows thousands of stations – for recognised ones, the full name is available immediately.

5.2 · fmdx.org Reference Database

On startup (and every 6 hours) the plugin downloads the full FM transmitter database from maps.fmdx.org/api/?qth={lat},{lon} centred on the receiver's own location. All transmitters within a radius of 3000 km are indexed into two in-memory lookup tables: one keyed by frequency (fmdxByFreq), and one keyed by PI code (fmdxByPI).

Each fmdx.org entry provides:

• PI code – primary programme identification code
• PIreg – optional regional PI code used by some national networks
• PS name variants – one or more 8-character PS strings the station is known to broadcast
• Station name – the human-readable full name
• Distance – computed via Haversine formula

5.3 · PS Lock Engine and Hybrid Case

Once a PS name has been determined with high confidence, it is locked – the displayed name stops changing until the frequency or PI code changes. This eliminates the flickering that occurs when weak reception alternately produces correct and incorrect characters.

The lock is achieved through three priority levels:

After a lock is set, the dynamic jump engine handles stations with multiple PS variants. When the live buffer matches a different known variant at ≥ 75%, the locked PS jumps to the new variant without unlocking.

5.4 · Provisional → Locked Status Display NEW in v2.2

Before a PS name is fully locked, the decoder goes through an intermediate provisional stage. In v2.2 this state is communicated to the user via the new STATUS row in the panel, located directly below the PI Code row.

The STATUS row cycles through three visual states:

The status is rendered by the client-side renderStatus() function, which reads the st.psProvisional, st.psProvisionalConf, st.psStableMs, st.psLockReason, and st.psLocked fields – all populated from the server via rdsm_ai WebSocket messages.

5.5 · Frequency Change and Pre-Cache

When tuning to a new frequency, the following sequence runs:

5.6 · Dynamic vs. Static Stations

5.7 · Alternate Frequency (AF) Decoding

RDS Group 0A Block C carries up to two AF codes per group. The plugin decodes these codes according to the ETSI EN 50067 formula:

function decodeAFCode(code) {
  // code 1–204 → frequency in MHz: (code + 875) / 10
  // e.g. code 1 → 87.6 MHz, code 204 → 107.9 MHz
  if (code >= 1 && code <= 204) return (code + 875) / 10;
  return null;   // 205–255 are special codes (filler, LF/MF, ...)
}

Decoded frequencies are stored in the DB, displayed in the AF flag, forwarded to the dataHandler in Follow mode, and cross-referenced against the fmdx.org altFreqs list for the coverage badge in the FMDX.ORG panel row.

5.8 · RDS Follow Mode

5.9 · Special / Wildcard PI Codes

Certain PI codes are reserved and must never be treated as real station identifiers:

When isSpecialPI(pi) returns true, the plugin enters a pass-through mode:

• No voting, no DB writes, no PS lock
• Raw PS characters from the live buffer are forwarded directly to the AI prediction and, in Follow mode, to the dataHandler
• The FMDX.ORG section remains empty (no reference lookup)
• PI is confirmed immediately with threshold = 1
• freqRefs is set to an empty array (no fmdx.org gate applied)
• STATUS row remains at WAIT (no locking occurs)

5.10 · Regional PI Codes (PIreg)

Some national radio networks transmit a regional PI code (pireg) instead of a single primary national PI code. Without PIreg support, the received regional PI would fail the fmdx.org lookup. The plugin's two-priority lookup handles this transparently: primary PI is checked first, then pireg. When a match is found via pireg, the stats object carries both pireg (the received code) and piMain (the primary PI back-reference).

5.11 · The Panel – Display Elements

6 · Technical Deep Dive

6.1 · RDS Group Structure and Error Correction

An RDS group consists of 4 blocks of 26 bits each (16 bits payload + 10 bits CRC checksum). The error correction code is a shortened cyclic code capable of detecting up to 5 bit errors and correcting up to 2 bit errors per block.

The plugin receives these error levels as the array errB[0..3] and converts them into confidence weights:

Group types and their relevance to the plugin

6.2 · fmdx.org Bulk Index, Distance Filter and PIreg

After downloading the bulk transmitter data from maps.fmdx.org/api/?qth={lat},{lon}, the plugin builds two in-memory indexes. The pipeline indexes both the primary PI and the optional regional PIreg:

Reference matching at runtime – two-priority lookup

function findBestRefEntry(pi) {
  if (isSpecialPI(pi)) return null;
  const refs  = fmdxByFreq[roundFreq(currentFreq)] || [];
  const piUp  = pi.toUpperCase();

  // Priority 1: exact primary PI match on current frequency
  const exact = refs.filter(r => r.pi === piUp);
  if (exact.length === 1) return exact[0];
  if (exact.length > 1)
    return exact.sort((a,b) => (a.distKm??99999)-(b.distKm??99999))[0];

  // Priority 2: regional PI (pireg) match on current frequency
  const piRegMatches = refs.filter(r => r.pireg && r.pireg === piUp);
  if (piRegMatches.length === 1) return piRegMatches[0];
  if (piRegMatches.length > 1)
    return piRegMatches.sort((a,b) => (a.distKm??99999)-(b.distKm??99999))[0];

  return null;
}

6.3 · PS Lock Engine – Priority Ladder

The PS lock is managed by checkAndLockPS(pi), called after every complete PS round (all 4 segments received). Special PIs are never locked – they bypass this function entirely.

6.4 · Provisional → Locked Status Engine NEW in v2.2

Before a PS is fully locked, the server tracks a provisional candidate – the best current guess with its associated confidence and how long it has been stable. This state is broadcast in every rdsm_ai message and rendered by the client as the STATUS row.

Server-side: building the provisional state

The server computes the provisional PS and its metadata in buildAIPrediction(). The key fields populated are:

Client-side: renderStatus()

function renderStatus() {
  const el = document.getElementById('rdsm-status');
  if (!el) return;

  if (st.psLocked) {
    const reason = st.psLockReason ? ` – ${st.psLockReason}` : '';
    el.innerHTML = `
      <span class="rf on" style="background:#1b3b2a;color:#44ff88;
        border:1px solid #44ff88;padding:3px 7px;line-height:1.6;">LOCKED</span>
      <span style="color:#777;font-size:11px;">${reason}</span>`;
    return;
  }

  const confPct = Math.round((st.psProvisionalConf || 0) * 100);
  if (st.psProvisional && confPct >= 55) {
    const stableS = (st.psStableMs || 0) / 1000;
    el.innerHTML = `
      <span class="rf on" style="background:#2a2331;color:#c8a020;
        border:1px solid #c8a020;padding:3px 7px;line-height:1.6;">PROVISIONAL</span>
      <span style="color:#888;font-size:11px;">
        ${confPct}% · stable ${stableS.toFixed(1)}s</span>`;
  } else {
    el.innerHTML = `
      <span class="rf" style="border:1px solid #2a2a2a;">WAIT</span>
      <span style="color:#555;font-size:11px;">collecting…</span>`;
  }
}

Integration points

• onAI(d) – updates all five fields from the incoming message, then calls renderStatus() and renderAll()
• reset() – sets psProvisional = null, psProvisionalConf = 0, psStableMs = 0, psLockReason = null, psLocked = false, then calls renderStatus()

CSS

#rdsm-status { overflow: visible; line-height: 1.8; }

The overflow: visible rule ensures the coloured badge border does not get clipped by the parent row's layout, and line-height: 1.8 provides comfortable vertical spacing between the badge and the secondary text.

6.5 · Voting Engine – Compact Aggregation Format

A compact aggregated format is used instead of a list of individual timestamps. Votes are never cast for special PIs.

Format per character position (JSON)

// db[pi].ps[position][character]
{
  "w":         147.3,         // current weighted score (lazy-decayed)
  "count":     18,            // raw number of votes received
  "firstSeen": 1773554046944, // Unix timestamp of first vote (ms)
  "lastSeen":  1773554677188  // Unix timestamp of last vote (ms)
}

Lazy Exponential Decay

function applyDecay(v, now) {
  const ageMs  = now - v.lastSeen;
  const halfMs = 7 * 86400000;
  v.w        = v.w * Math.pow(0.5, ageMs / halfMs);
  v.lastSeen = now;
}

Values below 0.1 weight with fewer than 3 votes are deleted on the next write access (noise suppression).

Consistency Boost

When a character already clearly dominates (weight > 2× all competitors combined), the new vote receives a multiplier of 1.5×.

6.6 · Confidence Calculation

conf = share      * 0.5   // winner's share of total weight
     + dominance  * 0.3   // gap between winner and runner-up
     + voteFactor * 0.2   // experience factor (saturates at 30+ votes)

// Upper bound: 0.97

Confidence Scale – Colour Mapping in the Panel

Normal: rgb(v) where v = 20 + conf × 220  ·  ref-match: warm gold  ·  ref-seed: amber  ·  bigram: v = 15 + conf × 30

PS source types

6.7 · PI Verification Pipeline

6.8 · Special PI Pass-Through

6.9 · Database Format and Storage Management

File structure (rdsm_memory.json)

{
  "_meta": {
    "rdsFollowMode": false,
    "savedAt": 1773556231184,
    "dbVersion": 1
  },
  "D3C3": {
    "freq":           "104.00",
    "ps": { "0": { "N": {w,count,firstSeen,lastSeen}, ... }, ... },
    "psResolved":    "NRJ     ",
    "psConf":        [0.97,0.95,0.93,0,0,0,0,0],
    "psVerifiedRaw": "NRJ     ",
    "psVerifiedRawTs": 1773554677188,
    "psIsDynamic":   false,
    "psLastRaw":     ["N","R","J"," "," "," "," "," "],
    "psLastRawTs":   1773554677188,
    "pty":           10,
    "tp":            true,
    "ta":            false,
    "ms":            1,
    "stereo":        true,
    "ecc":           "E1",
    "af":            [89.5, 94.1, 98.0],
    "seen":          1773554677188,
    "seenCount":     847
  }
  // Note: special PI codes (FFFF, 0000) are NEVER stored here
}

psVerifiedRaw integrity check

On load and before every save, isPSStringClean() validates any stored psVerifiedRaw. Strings containing characters outside printable ASCII (0x20–0x7E) or extended Latin (0xA0–0xFF) are discarded. This prevents corrupt blocks from a previous errLevel-2 decode session from poisoning future sessions.

DB Version Migration

When the server starts and finds a database without _meta.dbVersion === 1, it performs a one-time automatic wipe. The rdsFollowMode setting is preserved across the wipe.

Retention periods and limits

6.10 · WebSocket Protocol CHANGED in v2.2

Communication between the server plugin and the browser runs over WebSocket on the path /data_plugins. All messages are JSON.

Example rdsm_ai payload (v2.2)

{
  "type":       "rdsm_ai",
  "pi":         "D3C3",
  "ps": [
    { "char": "A", "conf": 0.97, "src": "ref-match" },
    { "char": "n", "conf": 0.95, "src": "ref-match" },
    // ... 6 more slots
  ],
  "rt": { "text": "Dua Lipa - Levitating", "score": 0.72, "src": "raw-rt" },
  "af":         [89.5, 94.1, 98.0],
  "psName":     "Antenne Bayern",
  "psNameSrc":  "fmdx",
  "psVariants": ["Antenne ", "ANTENNE "],
  "altFreqs": [
    {
      "freq":       "89.5",
      "distKm":     88,
      "station":    "Antenne Bayern",
      "psVariants": ["Antenne "]
    }
  ],

  // ── NEW in v2.2: Provisional → Locked state fields ──────────
  "psProvisional":     "Antenne ",   // candidate PS before lock
  "psProvisionalConf": 0.87,          // average slot confidence
  "psStableMs":        4800,          // ms this candidate has been stable
  "psLockReason":      "FMDX match 95%", // null until locked
  "psLocked":          true,

  "stats": {
    "freq":          "104.00",
    "seenCount":     847,
    "psVoteTotal":   312,
    "psIsDynamic":   false,
    "psLocked":      true,
    "refStation":    "Antenne Bayern",
    "refDistKm":     142,
    "refMatchScore": 95,
    "pireg":         null,
    "piMain":        null
  },
  "ts": 1773556231184
}

PROVISIONAL example (before locking):

  "psProvisional":     "NRJ     ",
  "psProvisionalConf": 0.62,
  "psStableMs":        1200,
  "psLockReason":      null,
  "psLocked":          false
  // → Panel shows: [PROVISIONAL]  62% · stable 1.2s

6.11 · dataHandler Patch – Property Locking

The native decoder receives the complete raw stream in all modes. In Follow mode, all writes to the protected fields are intercepted via JavaScript property descriptors and restored after the native decoder returns.

dh.handleData = function(wss, receivedData, rdsWss) {
  // 1. AI parsing runs first (always)
  interceptLines(receivedData);

  if (aiExclusiveMode) return;

  if (rdsFollowMode && piConfirmed) {
    applyFollowToDataHandler();

    const locked = {};
    fields.forEach(f => {
      locked[f] = dh.dataToSend[f];
      Object.defineProperty(dh.dataToSend, f, {
        get: () => locked[f],
        set: () => {},
        configurable: true
      });
    });

    const result = orig.call(this, wss, receivedData, rdsWss);

    fields.forEach(f => {
      Object.defineProperty(dh.dataToSend, f, {
        value: locked[f], writable: true, configurable: true
      });
    });
    return result;
  }

  return orig.call(this, wss, receivedData, rdsWss);
};

Locked fields: pi, ps, ps_errors, pty, tp, ta, ms, rt0, rt1, rt0_errors, rt1_errors, rt_flag, ecc, country_iso, country_name, af.

6.12 · FMDX.ORG Panel – Frequency Chips and AF Coverage

The FMDX.ORG row shows the station name, variant chips, an AF coverage badge, and a scrollable chip row of all known fmdx.org frequencies for this PI.

AF Coverage Badge

Counts how many of the fmdx.org-listed alternative frequencies (altFreqs) have been received during the current session (present in st.af or equal to the current frequency). Displayed as: AF m/n (x%).

Scrollable Frequency Chip Row

Each known fmdx.org frequency appears as a chip. Chips are colour-coded: blue when received live, dark when not yet received. When more than ~25 entries are present, a scrollable container is shown (max 5 rows visible). The scroll position is preserved across re-renders via _freqScrollTop. Each chip tooltip shows the frequency in MHz plus the known PS variants for that transmitter.

6.13 · Bigram Predictor

The bigram predictor is a fallback of last resort. It is only reached when no raw data, no DB vote above 30% confidence, and no fmdx.org reference seed is available for a position. It is also bypassed entirely for special PIs.

// Excerpt from bigram table:
BIGRAM = {
  ' ': { 'R':25, 'S':20, 'M':18, 'F':15, ... },
  'F': { 'M':40, 'R':12, ... },
  // 26 letter rows + digit rows
}
// Confidence of a bigram guess: max. ~10% – clearly a placeholder

6.14 · GPS WebSocket Listener

The server plugin connects as a WebSocket client to its own /data_plugins endpoint to receive live GPS position updates:

ws.on('message', (raw) => {
  const msg = JSON.parse(raw);
  if (msg.type === 'GPS' && msg.value.status === 'active') {
    if (lat !== ownLat || lon !== ownLon) {
      ownLat = lat; ownLon = lon;
      // Rebuild fmdx.org index (both fmdxByFreq and fmdxByPI)
      if (fmdxLoadedAt > 0) buildFmdxIndex(cachedRaw);
    }
  }
});

Reconnection is attempted every 15 seconds on disconnect. Starts 5 seconds after plugin initialisation. Falls back to static config.json coordinates if no GPS message is received.

6.15 · Manual Link in the Panel Header

A small documentation link is rendered in the panel header bar, immediately to the left of the connection status dot:

<!-- Inside the rdsm-hdr flex bar -->
<a id="rdsm-manual-link"
   href="https://highpoint.fmdx.org/manuals/RDS-AI-Decoder-Documentation-v2.2.html"
   target="_blank"
   title="Open RDS AI Decoder Manual">?</a>

The link opens in a new browser tab and is styled to match the panel header colour scheme. The drag handler explicitly excludes this element to prevent conflicts with header dragging.

6.16 · _aiTimer – Module-Level Broadcast Timer NEW in v2.2

In v2.2 the AI broadcast debounce timer is promoted to module scope:

// rds-ai-decoder_server.js – top of module
let _aiTimer = null;

Previously the timer was managed locally within the functions that needed it. By declaring it at module scope, all code paths that schedule or cancel a deferred rdsm_ai broadcast share a single handle. This prevents a race condition where two concurrent paths (e.g. checkAndLockPS() and the dynamic jump engine) could each schedule their own setTimeout, resulting in duplicate or out-of-order broadcasts.

Usage pattern

// Cancel any pending broadcast before scheduling a new one
if (_aiTimer) { clearTimeout(_aiTimer); _aiTimer = null; }
_aiTimer = setTimeout(() => {
    _aiTimer = null;
    broadcast({ type: 'rdsm_ai', ...prediction, ts: Date.now() });
    if (rdsFollowMode) applyFollowToDataHandler();
}, AI_BROADCAST_DELAY);

The pattern is used in both checkAndLockPS() (on lock commit and dynamic jump) and in the main scheduleBroadcast() helper, ensuring the 80 ms batching window is always respected regardless of which code path triggers the broadcast.

7 · REST API

The plugin registers one HTTP endpoint:

Example response for /api/rdsm/stats (v2.2)

{
  "stationCount":  312,
  "fmdxFreqCount": 4872,
  "fmdxPICount":   5140,
  "rdsFollowMode": false,
  "aiExclusiveMode": false,
  "piConfirmed":   true,
  "psLocked":      true,
  "currentPI":     "D3C3",
  "currentFreq":   "104.00"
}

8 · Configuration Parameters

RDS AI Decoder · Documentation v2.2 · Author: Highpoint · March 2026
github.com/Highpoint2000/RDS-AI-Decoder  ·  Online Manual