@e04/ft8ts 0.0.2 → 0.0.6

package/README.md

@@ -6,7 +6,9 @@ FT8 encoder and decoder in TypeScript. A port of the Fortran implementation from
 
 ## Overview
 
-FT8 is a digital amateur radio mode designed for weak-signal communication. This library provides pure TypeScript implementations of both encoding and decoding, suitable for use in Node.js or the browser.
+FT8 is a digital amateur radio mode designed for weak-signal communication, developed by Joe Taylor (K1JT) and Steve Franke (K9AN).
+
+This library provides pure TypeScript implementations of both encoding and decoding, suitable for use in Node.js or the browser.
 
 ## Demo
 
@@ -32,27 +34,27 @@ npx tsx example/decode-ft8-wav.ts ./src/__test__/190227_155815.wav [--low 200] [
 
 The benchmark below was compiled with reference to [Comparing PyFT8 with WSJT-x and FT8_lib](https://www.reddit.com/r/amateurradio/comments/1qt27ss/comparing_pyft8_with_wsjtx_and_ft8_lib/).
 
-| Call a | Call b | Message | WSJT-x (FAST) | [PyFT8](https://github.com/G1OJS/PyFT8) | [ft8_lib](https://github.com/kgoba/ft8_lib) | ft8ts (depth=1) | ft8ts (depth=2) | ft8ts (depth=3) |
-| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
-| W1FC | F5BZB | -8 | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ |
-| WM3PEN | EA6VQ | -9 | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ |
-| CQ | F5RXL | IN94 | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ |
-| N1JFU | EA6EE | R-07 | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ |
-| A92EE | F5PSR | -14 | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ |
-| K1BZM | EA3GP | -9 | ☑️ | ☑️ | | ☑️ | ☑️ | ☑️ |
-| W0RSJ | EA3BMU | RR73 | ☑️ | ☑️ | | ☑️ | ☑️ | ☑️ |
-| K1JT | HA0DU | KN07 | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ |
-| W1DIG | SV9CVY | -14 | ☑️ | ☑️ | | ☑️ | ☑️ | ☑️ |
-| K1JT | EA3AGB | -15 | ☑️ | ☑️ | | ☑️ | ☑️ | ☑️ |
-| XE2X | HA2NP | RR73 | ☑️ | ☑️ | ☑️ | | | ☑️ |
-| N1PJT | HB9CQK | -10 | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ |
-| K1BZM | EA3CJ | JN01 | ☑️ | | | | | |
-| KD2UGC | F6GCP | R-23 | ☑️ | | | | | |
-| WA2FZW | DL5AXX | RR73 | | | | | | |
-| N1API | HA6FQ | -23 | | | | | ☑️ | ☑️ |
-| N1API | F2VX | 73 | | | | | | |
-| K1JT | HA5WA | 73 | | | | | ☑️ | ☑️ |
-| CQ | EA2BFM | IN83 | | | | | | |
+| Call a | Call b | Message | WSJT-x(default) | WSJT-x (fast) | [PyFT8](https://github.com/G1OJS/PyFT8) | [ft8_lib](https://github.com/kgoba/ft8_lib) | ft8ts (depth=1) | ft8ts (depth=2) | ft8ts (depth=3) |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| W1FC | F5BZB | -8 | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ |
+| WM3PEN | EA6VQ | -9 | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ |
+| CQ | F5RXL | IN94 | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ |
+| N1JFU | EA6EE | R-07 | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ |
+| A92EE | F5PSR | -14 | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ |
+| K1BZM | EA3GP | -9 | ☑️ | ☑️ | ☑️ | | ☑️ | ☑️ | ☑️ |
+| W0RSJ | EA3BMU | RR73 | ☑️ | ☑️ | ☑️ | | ☑️ | ☑️ | ☑️ |
+| K1JT | HA0DU | KN07 | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ |
+| W1DIG | SV9CVY | -14 | ☑️ | ☑️ | ☑️ | | ☑️ | ☑️ | ☑️ |
+| K1JT | EA3AGB | -15 | ☑️ | ☑️ | ☑️ | | ☑️ | ☑️ | ☑️ |
+| XE2X | HA2NP | RR73 | ☑️ | ☑️ | ☑️ | ☑️ | | | ☑️ |
+| N1PJT | HB9CQK | -10 | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ |
+| K1BZM | EA3CJ | JN01 | ☑️ | ☑️ | | | | | |
+| KD2UGC | F6GCP | R-23 | ☑️ | ☑️ | | | | | |
+| WA2FZW | DL5AXX | RR73 | ☑️ | | | | | | |
+| N1API | HA6FQ | -23 | ☑️ | | | | | ☑️ | ☑️ |
+| N1API | F2VX | 73 | ☑️ | | | | | | |
+| K1JT | HA5WA | 73 | ☑️ | | | | | ☑️ | ☑️ |
+| CQ | EA2BFM | IN83 | ☑️ | | | | | | |
 
 At its maximum depth mode (Depth 3), it successfully decodes 14 messages, outperforming both `PyFT8` (12) and `FT8_lib` (8), and matching the total message count of `WSJT-x FAST mode`.
 
@@ -65,7 +67,7 @@ At its maximum depth mode (Depth 3), it successfully decodes 14 messages, outper
 ### API
 
 ```typescript
-import { encodeFT8, decodeFT8 } from "@e04/ft8ts";
+import { encodeFT8, decodeFT8, HashCallBook } from "@e04/ft8ts";
 
 // Encode a message to audio samples (Float32Array)
 const samples = encodeFT8("CQ JK1IFA PM95", {
@@ -73,11 +75,17 @@ const samples = encodeFT8("CQ JK1IFA PM95", {
   baseFrequency: 1000,
 });
 
+// Create a HashCallBook to resolve hashed callsigns.
+// Reuse the same instance across multiple decode calls so that
+// callsigns learned from earlier frames can resolve hashes in later ones.
+const book = new HashCallBook();
+
 // Decode audio samples to messages
 const decoded = decodeFT8(samples, 12000, {
   freqLow: 200,
   freqHigh: 3000,
   depth: 2,
+  hashCallBook: book,
 });
 
 for (const d of decoded) {
@@ -94,10 +102,11 @@ for (const d of decoded) {
 | `syncMin` | 1.2 | Minimum sync threshold |
 | `depth` | 2 | Decoding depth: 1=fast BP only, 2=BP+OSD, 3=deep |
 | `maxCandidates` | 300 | Maximum candidates to process |
+| `hashCallBook` | — | `HashCallBook` instance for resolving hashed callsigns |
 
 ## ToDo
 
-- [ ] Add save_hash_call-style hash tables to the TypeScript port so that h10/h12/h22 hash references can be resolved to callsigns (e.g. <YW18FIFA>) instead of always showing <...>.
+- [ ] FT4 Support
 
 ## Build
 

package/dist/ft8ts.cjs

@@ -686,7 +686,7 @@ function bitsToUint(bits, start, len) {
     }
     return val;
 }
-function unpack28(n28) {
+function unpack28(n28, book) {
     if (n28 < 0 || n28 >= 268435456)
         return { call: "", success: false };
     if (n28 === 0)
@@ -700,7 +700,6 @@ function unpack28(n28) {
         return { call: `CQ ${nqsy.toString().padStart(3, "0")}`, success: true };
     }
     if (n28 >= 1003 && n28 < NTOKENS) {
-        // CQ with 4-letter directed call
         let m = n28 - 1003;
         let chars = "";
         for (let i = 3; i >= 0; i--) {
@@ -714,7 +713,10 @@ function unpack28(n28) {
         return { call: "CQ", success: true };
     }
     if (n28 >= NTOKENS && n28 < NTOKENS + MAX22) {
-        // Hashed call – we don't have a hash table, so show <...>
+        const n22 = n28 - NTOKENS;
+        const resolved = book?.lookup22(n22);
+        if (resolved)
+            return { call: `<${resolved}>`, success: true };
         return { call: "<...>", success: true };
     }
     // Standard callsign
@@ -794,8 +796,11 @@ function unpackText77(bits71) {
 }
 /**
  * Unpack a 77-bit FT8 message into a human-readable string.
+ *
+ * When a {@link HashCallBook} is provided, hashed callsigns are resolved from
+ * the book, and newly decoded standard callsigns are saved into it.
  */
-function unpack77(bits77) {
+function unpack77(bits77, book) {
     const n3 = bitsToUint(bits77, 71, 3);
     const i3 = bitsToUint(bits77, 74, 3);
     if (i3 === 0 && n3 === 0) {
@@ -813,8 +818,8 @@ function unpack77(bits77) {
         const ipb = bits77[57];
         const ir = bits77[58];
         const igrid4 = bitsToUint(bits77, 59, 15);
-        const { call: call1, success: ok1 } = unpack28(n28a);
-        const { call: call2Raw, success: ok2 } = unpack28(n28b);
+        const { call: call1, success: ok1 } = unpack28(n28a, book);
+        const { call: call2Raw, success: ok2 } = unpack28(n28b, book);
         if (!ok1 || !ok2)
             return { msg: "", success: false };
         let c1 = call1;
@@ -832,6 +837,9 @@ function unpack77(bits77) {
                 c2 += "/R";
             if (ipb === 1 && i3 === 2 && c2.length >= 3)
                 c2 += "/P";
+            // Save the "from" call (call_2) into the hash book
+            if (book && c2.length >= 3)
+                book.save(c2);
         }
         if (igrid4 <= MAXGRID4) {
             const { grid, success: gridOk } = toGrid4(igrid4);
@@ -864,6 +872,7 @@ function unpack77(bits77) {
     }
     if (i3 === 4) {
         // Type 4: One nonstandard call
+        const n12 = bitsToUint(bits77, 0, 12);
         let n58 = 0n;
         for (let i = 0; i < 58; i++) {
             n58 = n58 * 2n + BigInt(bits77[12 + i] ?? 0);
@@ -871,7 +880,6 @@ function unpack77(bits77) {
         const iflip = bits77[70];
         const nrpt = bitsToUint(bits77, 71, 2);
         const icq = bits77[73];
-        // Decode n58 to 11-char string using C38 alphabet
         const c11chars = [];
         let remain = n58;
         for (let i = 10; i >= 0; i--) {
@@ -880,12 +888,15 @@ function unpack77(bits77) {
             c11chars.unshift(C38[j] ?? " ");
         }
         const c11 = c11chars.join("").trim();
-        const call3 = "<...>"; // We don't have a hash table for n12
+        const resolved = book?.lookup12(n12);
+        const call3 = resolved ? `<${resolved}>` : "<...>";
         let call1;
         let call2;
         if (iflip === 0) {
             call1 = call3;
             call2 = c11;
+            if (book)
+                book.save(c11);
         }
         else {
             call1 = c11;
@@ -920,6 +931,7 @@ function decode(samples, sampleRate = SAMPLE_RATE, options = {}) {
     const syncmin = options.syncMin ?? 1.2;
     const depth = options.depth ?? 2;
     const maxCandidates = options.maxCandidates ?? 300;
+    const book = options.hashCallBook;
     // Resample to 12000 Hz if needed
     let dd;
     if (sampleRate === SAMPLE_RATE) {
@@ -944,7 +956,7 @@ function decode(samples, sampleRate = SAMPLE_RATE, options = {}) {
     const decoded = [];
     const seenMessages = new Set();
     for (const cand of candidates) {
-        const result = ft8b(dd, cxRe, cxIm, cand.freq, cand.dt, sbase, depth);
+        const result = ft8b(dd, cxRe, cxIm, cand.freq, cand.dt, sbase, depth, book);
         if (!result)
             continue;
         if (seenMessages.has(result.msg))
@@ -1128,7 +1140,7 @@ function computeBaseline(savg, nfa, nfb, df, nh1) {
     }
     return sbase;
 }
-function ft8b(dd0, cxRe, cxIm, f1, xdt, _sbase, depth) {
+function ft8b(_dd0, cxRe, cxIm, f1, xdt, _sbase, depth, book) {
     const NFFT2 = 3200;
     const NP2 = 2812;
     const fs2 = SAMPLE_RATE / NDOWN;
@@ -1336,7 +1348,7 @@ function ft8b(dd0, cxRe, cxIm, f1, xdt, _sbase, depth) {
     if (i3v === 0 && n3v === 2)
         return null;
     // Unpack
-    const { msg, success } = unpack77(message77);
+    const { msg, success } = unpack77(message77, book);
     if (!success || msg.trim().length === 0)
         return null;
     // Estimate SNR
@@ -2203,6 +2215,113 @@ function encode(msg, options = {}) {
     return generateFT8Waveform(encodeMessage(msg), options);
 }
 
+/**
+ * Hash call table – TypeScript port of the hash call storage from packjt77.f90
+ *
+ * In FT8, nonstandard callsigns are transmitted as hashes (10-, 12-, or 22-bit).
+ * When a full callsign is decoded from a standard message, it is stored in this
+ * table so that future hashed references to it can be resolved.
+ *
+ * Mirrors Fortran: save_hash_call, hash10, hash12, hash22, ihashcall
+ */
+const MAGIC = 47055833459n;
+const MAX_HASH22_ENTRIES = 1000;
+function ihashcall(c0, m) {
+    const s = c0.padEnd(11, " ").slice(0, 11).toUpperCase();
+    let n8 = 0n;
+    for (let i = 0; i < 11; i++) {
+        const j = C38.indexOf(s[i] ?? " ");
+        n8 = 38n * n8 + BigInt(j < 0 ? 0 : j);
+    }
+    const prod = BigInt.asUintN(64, MAGIC * n8);
+    return Number(prod >> BigInt(64 - m)) & ((1 << m) - 1);
+}
+/**
+ * Maintains a callsign ↔ hash lookup table for resolving hashed FT8 callsigns.
+ *
+ * Usage:
+ * ```ts
+ * const book = new HashCallBook();
+ * const decoded = decodeFT8(samples, sampleRate, { hashCallBook: book });
+ * // `book` now contains callsigns learned from decoded messages.
+ * // Subsequent calls reuse the same book to resolve hashed callsigns:
+ * const decoded2 = decodeFT8(samples2, sampleRate, { hashCallBook: book });
+ * ```
+ *
+ * You can also pre-populate the book with known callsigns:
+ * ```ts
+ * book.save("W9XYZ");
+ * book.save("PJ4/K1ABC");
+ * ```
+ */
+class HashCallBook {
+    calls10 = new Map();
+    calls12 = new Map();
+    hash22Entries = [];
+    /**
+     * Store a callsign in all three hash tables (10, 12, 22-bit).
+     * Strips angle brackets if present. Ignores `<...>` and blank/short strings.
+     */
+    save(callsign) {
+        let cw = callsign.trim().toUpperCase();
+        if (cw === "" || cw === "<...>")
+            return;
+        if (cw.startsWith("<"))
+            cw = cw.slice(1);
+        const gt = cw.indexOf(">");
+        if (gt >= 0)
+            cw = cw.slice(0, gt);
+        cw = cw.trim();
+        if (cw.length < 3)
+            return;
+        const n10 = ihashcall(cw, 10);
+        if (n10 >= 0 && n10 <= 1023)
+            this.calls10.set(n10, cw);
+        const n12 = ihashcall(cw, 12);
+        if (n12 >= 0 && n12 <= 4095)
+            this.calls12.set(n12, cw);
+        const n22 = ihashcall(cw, 22);
+        const existing = this.hash22Entries.findIndex((e) => e.hash === n22);
+        if (existing >= 0) {
+            this.hash22Entries[existing].call = cw;
+        }
+        else {
+            if (this.hash22Entries.length >= MAX_HASH22_ENTRIES) {
+                this.hash22Entries.pop();
+            }
+            this.hash22Entries.unshift({ hash: n22, call: cw });
+        }
+    }
+    /** Look up a callsign by its 10-bit hash. Returns `null` if not found. */
+    lookup10(n10) {
+        if (n10 < 0 || n10 > 1023)
+            return null;
+        return this.calls10.get(n10) ?? null;
+    }
+    /** Look up a callsign by its 12-bit hash. Returns `null` if not found. */
+    lookup12(n12) {
+        if (n12 < 0 || n12 > 4095)
+            return null;
+        return this.calls12.get(n12) ?? null;
+    }
+    /** Look up a callsign by its 22-bit hash. Returns `null` if not found. */
+    lookup22(n22) {
+        const entry = this.hash22Entries.find((e) => e.hash === n22);
+        return entry?.call ?? null;
+    }
+    /** Number of entries in the 22-bit hash table. */
+    get size() {
+        return this.hash22Entries.length;
+    }
+    /** Remove all stored entries. */
+    clear() {
+        this.calls10.clear();
+        this.calls12.clear();
+        this.hash22Entries.length = 0;
+    }
+}
+
+exports.HashCallBook = HashCallBook;
 exports.decodeFT8 = decode;
 exports.encodeFT8 = encode;
 //# sourceMappingURL=ft8ts.cjs.map