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

Version 2.1 builds on the foundation of v2.0 with a focused set of precision improvements centred on regional PI handling, special/wildcard PI pass-through, and enhanced fmdx.org frequency coverage display.

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 extends this by also handling regional PI codes that some networks use instead of a single national PI code, and by adding a clean pass-through path for special/wildcard PI codes that must never be stored.

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 since v2.1 also 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 (new in v2.1)
• 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 · Frequency Change and Pre-Cache

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

5.5 · Dynamic vs. Static Stations

5.6 · 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 entry as entry.af[] (sorted, deduplicated)
• Displayed in the panel's AF flag (shows count; tooltip lists all MHz values)
• Forwarded to the web server's dataHandler in Follow mode
• In v2.1: cross-referenced against the fmdx.org altFreqs list; the FMDX.ORG panel row shows an AF coverage percentage (how many of the database-listed frequencies have been received live)

5.7 · RDS Follow Mode

5.8 · Special / Wildcard PI Codes NEW in v2.1

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)

5.9 · Regional PI Codes (PIreg) NEW in v2.1

Some national radio networks – for example BBC Radio in the United Kingdom or Radio 1 in Slovenia – transmit a regional PI code (pireg) instead of a single primary national PI code. The regional code uniquely identifies the transmitter within the network but differs from the primary PI code listed in most databases.

Without PIreg support, the received regional PI would fail the fmdx.org lookup, producing no reference match even though the station is well-known. Version 2.1 solves this:

5.10 · 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 CHANGED in v2.1

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

Reference matching at runtime – two-priority lookup (v2.1)

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;
}

PS-aware AF lookup (v2.1)

When the PS is locked, getAltFreqsForPIAndPS() filters the fmdxByPI list to entries whose psVariants include the confirmed PS string. This prevents showing unrelated transmitters that happen to share the same PI:

function getAltFreqsForPIAndPS(pi, confirmedPS) {
  const all = getAltFreqsForPI(pi);
  if (!confirmedPS || confirmedPS.trim().length === 0) return all;
  const norm = confirmedPS.trim().toUpperCase();
  const filtered = all.filter(item =>
    item.psVariants?.some(v => {
      const nv = v.trim().toUpperCase();
      return nv === norm || norm.startsWith(nv) || nv.startsWith(norm);
    })
  );
  return filtered.length > 0 ? filtered : all;
}

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 · 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.5 · 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 (v2.1)

6.6 · PI Verification Pipeline CHANGED in v2.1

The pipeline now handles special PIs as a separate path and uses PIreg-aware confirmation thresholds:

6.7 · Special PI Pass-Through NEW in v2.1

The isSpecialPI() guard is applied at every point where a PI code could influence persistent state:

// v2.1: Special PI detection
const SPECIAL_PI_CODES = new Set(['FFFF', '0000']);
function isSpecialPI(pi) {
  return !pi || SPECIAL_PI_CODES.has(pi.toUpperCase());
}

6.8 · 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
}

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.9 · WebSocket Protocol CHANGED in v2.1

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.1)

{
  "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": [                             // NEW in v2.1: per-entry psVariants
    {
      "freq":       "89.5",
      "distKm":     88,
      "station":    "Antenne Bayern",
      "psVariants": ["Antenne "]        // NEW: variants for this transmitter
    },
    {
      "freq":       "94.1",
      "distKm":     142,
      "station":    "Antenne Bayern",
      "psVariants": ["Antenne "]
    }
  ],
  "psLocked":   true,
  "stats": {
    "freq":          "104.00",
    "seenCount":     847,
    "psVoteTotal":   312,
    "psIsDynamic":   false,
    "psLocked":      true,
    "refStation":    "Antenne Bayern",
    "refDistKm":     142,
    "refMatchScore": 95,
    "pireg":         null,        // NEW: regional PI code (if match via pireg)
    "piMain":        null         // NEW: primary PI (if match via pireg)
  },
  "ts": 1773556231184
}

For a PIreg-matched station (e.g. received PI = "9857", primary PI = "9201"):

  "stats": {
    ...
    "refStation":    "BBC Radio 1 / Radio 1 Ljubljana",
    "refDistKm":     312,
    "refMatchScore": 88,
    "pireg":         "9857",     // received PI is a regional code
    "piMain":        "9201"      // back-reference to the primary PI
  }

Example rdsm_freq payload (v2.1)

{
  "type":  "rdsm_freq",
  "freq":  "104.00",
  "reset": true,
  "pi":    null,
  "ps":    null,
  "stats": {
    "freq": "104.00", "seenCount": 0, "psVoteTotal": 0,
    "psIsDynamic": false, "psLocked": false,
    "refStation": null, "refDistKm": null, "refMatchScore": 0,
    "pireg": null,   // NEW in v2.1
    "piMain": null   // NEW in v2.1
  }
}

6.10 · 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) {
    // 2. Apply AI values
    applyFollowToDataHandler();

    // 3. Lock all RDS fields with no-op setters
    const locked = {};
    fields.forEach(f => {
      locked[f] = dh.dataToSend[f];
      Object.defineProperty(dh.dataToSend, f, {
        get: () => locked[f],
        set: () => {},
        configurable: true
      });
    });

    // 4. Run native decoder with full raw data
    const result = orig.call(this, wss, receivedData, rdsWss);

    // 5. Restore normal writable properties
    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.11 · FMDX.ORG Panel – Frequency Chips and AF Coverage NEW in v2.1

The FMDX.ORG row in the plugin panel is extended in v2.1 with two new elements rendered by the client plugin:

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

// Inside renderPSName() – client plugin
const dbFreqSet  = new Set(uniqueFreqs.map(i => parseFloat(i.freq).toFixed(1)));
let matched = 0;
for (const dbFreq of dbFreqSet)
  if (receivedFreqSet.has(dbFreq)) matched++;

const pct = Math.round((matched / dbFreqSet.size) * 100);
// Displayed as: "AF 3/5 (60%)"

Scrollable Frequency Chip Row

Each known fmdx.org frequency appears as a small chip. Chips are colour-coded:

• Blue (var(--color-main-bright)) – frequency has been received live (in st.af or is the current tuned frequency)
• Dark (#1c1c1c) – frequency not yet received this session

When there are more than 5 rows of chips (~25 entries), a scrollable container is shown with a maximum height of 5 rows. The scroll position is preserved across re-renders via _freqScrollTop. A custom wheel event handler prevents the page from scrolling while the chip list is being scrolled.

Each chip tooltip shows the frequency in MHz plus the known PS variants for that transmitter (from item.psVariants), e.g. "94.1 MHz – Radio 1 / RAD1".

Deduplication

Both the coverage calculation and the chip row deduplicate by frequency (rounded to 1 decimal place) before rendering, preventing duplicates when the same frequency appears in multiple fmdx.org transmitter entries.

6.12 · 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. In v2.1 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

In practice, bigram predictions are almost never visible because one of the higher-priority sources fills every slot within a few seconds of reception.

6.13 · 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)
      // from cached raw data with updated own location
      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.14 · Manual Link in the Panel Header NEW in v2.1

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 -->
<span style="display:flex;align-items:center;gap:5px">
  <a href="https://highpoint.fmdx.org/manuals/
           RDS-AI-Decoder-Documentation-v2.1.html"
     target="_blank"
     title="Open RDS AI Decoder Manual"
     style="color:#fff;opacity:.75;font-size:13px;
            text-decoration:none;line-height:1;
            transition:opacity .2s"
     onmouseover="this.style.opacity='1'"
     onmouseout="this.style.opacity='.75'">?</a>
  <span id="rdsm-dot" title="/data_plugins"></span>
  <button id="rdsm-close">✕</button>
</span>

The link opens in a new browser tab (target="_blank") and uses a subtle opacity transition on hover. It is styled to match the panel header's colour scheme and does not interfere with the drag behaviour of the header.

7 · REST API CHANGED in v2.1

The plugin registers one HTTP endpoint:

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

{
  "stationCount":  312,
  "fmdxFreqCount": 4872,        // unique frequencies in fmdx.org index
  "fmdxPICount":   5140,        // NEW: unique PI + PIreg codes indexed
  "rdsFollowMode": false,
  "aiExclusiveMode": false,
  "piConfirmed":   true,
  "psLocked":      true,
  "currentPI":     "D3C3",
  "currentFreq":   "104.00"
}

The new fmdxPICount field reflects the number of unique entries in the fmdxByPI reverse index, which includes both primary PI codes and regional PIreg codes as separate entries.

8 · Configuration Parameters

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