wsjtx-lib 1.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2025 wsjtx-lib-nodejs
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+The full text of the GNU General Public License v3 can be found at:
+https://www.gnu.org/licenses/gpl-3.0.txt 

package/README.md

@@ -0,0 +1,390 @@
+# WSJTX Library for Node.js
+
+A high-performance Node.js C++ extension for digital amateur radio protocols, providing TypeScript support and async/await interfaces for WSJTX library functionality.
+
+## Features
+
+- 🚀 **High Performance**: Native C++ implementation with multi-threading support
+- 📡 **Multiple Modes**: Support for FT8, FT4, JT4, JT65, JT9, FST4, Q65, FST4W, and WSPR
+- 🔧 **TypeScript Support**: Full TypeScript definitions and modern ES modules
+- ⚡ **Async/Await**: Promise-based API for non-blocking operations
+- 🎵 **Audio Processing**: Support for both Float32Array and Int16Array audio formats
+- 🌍 **Cross-Platform**: Works on Windows, macOS, and Linux
+- 📊 **WSPR Decoding**: Specialized support for WSPR IQ data processing
+
+## Supported Modes
+
+| Mode | Encoding | Decoding | Sample Rate | Duration | Bandwidth |
+|------|----------|----------|-------------|----------|-----------|
+| FT8  | ✅       | ✅       | 48 kHz      | 12.6s    | ~50 Hz    |
+| FT4  | ✅       | ✅       | 48 kHz      | 6.0s     | ~80 Hz    |
+| JT4  | ❌       | ✅       | 11.025 kHz  | 47.1s    | Variable  |
+| JT65 | ❌       | ✅       | 11.025 kHz  | 46.8s    | ~180 Hz   |
+| JT9  | ❌       | ✅       | 12 kHz      | 49.0s    | ~16 Hz    |
+| FST4 | ❌       | ✅       | 12 kHz      | 60.0s    | Variable  |
+| Q65  | ❌       | ✅       | 12 kHz      | 60.0s    | Variable  |
+| FST4W| ❌       | ✅       | 12 kHz      | 120.0s   | Variable  |
+| WSPR | ❌       | ✅       | 12 kHz      | 110.6s   | ~6 Hz     |
+
+## Installation
+
+### Prerequisites
+
+- Node.js 16+ 
+- CMake 3.15+
+- C++ compiler with C++17 support
+- FFTW3 library
+- Boost libraries
+- Fortran compiler (gfortran)
+
+### macOS
+
+```bash
+# Install dependencies using Homebrew
+brew install cmake fftw boost gcc
+
+# Clone and install
+git clone --recursive https://github.com/boybook/wsjtx_lib_nodejs.git
+cd wsjtx-lib-nodejs
+npm install
+```
+
+### Linux (Ubuntu/Debian)
+
+```bash
+# Install dependencies
+sudo apt-get update
+sudo apt-get install cmake libfftw3-dev libboost-all-dev gfortran build-essential
+
+# Clone and install
+git clone --recursive https://github.com/boybook/wsjtx_lib_nodejs.git
+cd wsjtx-lib-nodejs
+npm install
+```
+
+### Windows
+
+```bash
+# Install dependencies using vcpkg or manually
+# Ensure CMake, FFTW3, Boost, and MinGW-w64 are available
+
+# Clone and install
+git clone --recursive https://github.com/boybook/wsjtx_lib_nodejs.git
+cd wsjtx-lib-nodejs
+npm install
+```
+
+## Quick Start
+
+```typescript
+import { WSJTXLib, WSJTXMode } from 'wsjtx-lib';
+
+async function example() {
+    // Create library instance
+    const lib = new WSJTXLib();
+    
+    // Encode an FT8 message
+    const encodeResult = await lib.encode(
+        WSJTXMode.FT8,
+        'CQ TEST K1ABC FN20',
+        1000  // Audio base frequency in Hz (typically 500-3000 Hz)
+    );
+    
+    console.log(`Generated ${encodeResult.audioData.length} audio samples`);
+    console.log(`Message: "${encodeResult.messageSent}"`);
+    
+    // Decode audio data
+    const audioData = new Float32Array(48000 * 13); // 13 seconds at 48kHz
+    // ... fill audioData with actual audio samples ...
+    
+    const decodeResult = await lib.decode(
+        WSJTXMode.FT8,
+        audioData,
+        1000  // Same audio base frequency used for encoding
+    );
+    
+    // Get decoded messages
+    const messages = lib.pullMessages();
+    messages.forEach(msg => {
+        console.log(`Decoded: "${msg.text}" (SNR: ${msg.snr} dB)`);
+    });
+}
+```
+
+## API Reference
+
+### WSJTXLib Class
+
+#### Constructor
+
+```typescript
+new WSJTXLib(config?: WSJTXConfig)
+```
+
+Creates a new WSJTX library instance.
+
+**Parameters:**
+- `config` (optional): Configuration options
+  - `maxThreads`: Maximum number of threads (1-16, default: 4)
+  - `debug`: Enable debug logging (default: false)
+
+#### Methods
+
+##### `decode(mode, audioData, frequency, threads?): Promise<DecodeResult>`
+
+Decode digital radio signals from audio data.
+
+**Parameters:**
+- `mode`: WSJTXMode enum value
+- `audioData`: Float32Array or Int16Array of audio samples
+- `frequency`: Audio base frequency in Hz (typically 500-3000 Hz for FT8)
+- `threads`: Number of threads to use (optional, default: 4)
+
+**Returns:** Promise resolving to DecodeResult with success status
+
+##### `encode(mode, message, frequency, threads?): Promise<EncodeResult>`
+
+Encode a message into audio waveform for transmission.
+
+**Parameters:**
+- `mode`: WSJTXMode enum value
+- `message`: Message text to encode (1-22 characters)
+- `frequency`: Audio base frequency in Hz (typically 500-3000 Hz for FT8)
+- `threads`: Number of threads to use (optional, default: 4)
+
+**Returns:** Promise resolving to EncodeResult with audio data and actual message sent
+
+##### `decodeWSPR(iqData, options?): Promise<WSPRResult[]>`
+
+Decode WSPR signals from IQ data.
+
+**Parameters:**
+- `iqData`: Float32Array of interleaved I,Q samples
+- `options`: WSPRDecodeOptions (optional)
+
+**Returns:** Promise resolving to array of WSPR decode results
+
+##### `pullMessages(): WSJTXMessage[]`
+
+Retrieve decoded messages from the internal queue.
+
+**Returns:** Array of decoded messages
+
+##### Utility Methods
+
+- `isEncodingSupported(mode): boolean` - Check if encoding is supported for a mode
+- `isDecodingSupported(mode): boolean` - Check if decoding is supported for a mode
+- `getSampleRate(mode): number` - Get required sample rate for a mode
+- `getTransmissionDuration(mode): number` - Get transmission duration for a mode
+- `getAllModeCapabilities(): ModeCapabilities[]` - Get capabilities for all modes
+
+##### Static Methods
+
+- `convertAudioFormat(audioData, targetFormat): AudioData` - Convert between Float32Array and Int16Array
+
+### Enums and Types
+
+#### WSJTXMode
+
+```typescript
+enum WSJTXMode {
+    FT8 = 0,
+    FT4 = 1,
+    JT4 = 2,
+    JT65 = 3,
+    JT9 = 4,
+    FST4 = 5,
+    Q65 = 6,
+    FST4W = 7,
+    WSPR = 8
+}
+```
+
+#### WSJTXMessage
+
+```typescript
+interface WSJTXMessage {
+    text: string;           // Decoded message text
+    snr: number;            // Signal-to-noise ratio in dB
+    deltaTime: number;      // Time offset in seconds
+    deltaFrequency: number; // Frequency offset in Hz
+    timestamp: number;      // Unix timestamp
+    sync: number;           // Sync quality metric
+}
+```
+
+#### EncodeResult
+
+```typescript
+interface EncodeResult {
+    audioData: Float32Array;  // Generated audio waveform
+    messageSent: string;      // Actual message encoded
+}
+```
+
+#### WSPRResult
+
+```typescript
+interface WSPRResult {
+    frequency: number;    // Signal frequency in Hz
+    sync: number;         // Sync quality
+    snr: number;          // Signal-to-noise ratio in dB
+    deltaTime: number;    // Time offset in seconds
+    drift: number;        // Frequency drift in Hz/minute
+    jitter: number;       // Jitter metric
+    message: string;      // Decoded message
+    callsign: string;     // Decoded callsign
+    locator: string;      // Decoded grid locator
+    power: string;        // Decoded power in dBm
+    cycles: number;       // Number of decode cycles
+}
+```
+
+## Examples
+
+### Basic FT8 Encoding and Decoding
+
+```typescript
+import { WSJTXLib, WSJTXMode } from 'wsjtx-lib';
+
+const lib = new WSJTXLib();
+
+// Encode a message
+const result = await lib.encode(WSJTXMode.FT8, 'CQ DX K1ABC FN20', 1500);
+console.log(`Audio samples: ${result.audioData.length}`);
+
+// Decode audio (replace with actual audio data)
+const audioData = new Float32Array(48000 * 13);
+const decodeResult = await lib.decode(WSJTXMode.FT8, audioData, 1500);
+
+// Get messages
+const messages = lib.pullMessages();
+console.log(`Found ${messages.length} messages`);
+```
+
+> **Important Note**: The `frequency` parameter is the **audio base frequency** (typically 500-3000 Hz), not the RF frequency. For example, if you're operating on 20m FT8 (14.074 MHz RF), you might use 1500 Hz as the audio frequency within your transceiver's passband.
+
+### WSPR Decoding
+
+```typescript
+import { WSJTXLib } from 'wsjtx-lib';
+
+const lib = new WSJTXLib();
+
+// IQ data (interleaved I,Q samples)
+const iqData = new Float32Array(2 * 12000 * 120); // 2 minutes
+// ... fill with actual IQ data ...
+
+const options = {
+    dialFrequency: 14095600,  // RF dial frequency for WSPR (this is different from audio frequency)
+    callsign: 'K1ABC',
+    locator: 'FN20',
+    quickMode: false,
+    passes: 2
+};
+
+const results = await lib.decodeWSPR(iqData, options);
+results.forEach(result => {
+    console.log(`${result.callsign} ${result.locator} ${result.power}dBm`);
+});
+```
+
+### Audio Format Conversion
+
+```typescript
+import { WSJTXLib } from 'wsjtx-lib';
+
+// Convert Float32Array to Int16Array
+const floatData = new Float32Array([0.5, -0.5, 0.25]);
+const intData = WSJTXLib.convertAudioFormat(floatData, 'int16');
+
+// Convert back to Float32Array
+const backToFloat = WSJTXLib.convertAudioFormat(intData, 'float32');
+```
+
+## Error Handling
+
+The library throws `WSJTXError` for all operation failures:
+
+```typescript
+import { WSJTXError } from 'wsjtx-lib';
+
+try {
+    await lib.decode(WSJTXMode.FT8, audioData, 1500);
+} catch (error) {
+    if (error instanceof WSJTXError) {
+        console.error(`WSJTX Error [${error.code}]: ${error.message}`);
+    } else {
+        console.error('Unexpected error:', error);
+    }
+}
+```
+
+## Building from Source
+
+```bash
+# Clone with submodules
+git clone --recursive https://github.com/your-repo/wsjtx-lib-nodejs.git
+cd wsjtx-lib-nodejs
+
+# Install dependencies
+npm install
+
+# Build native module and TypeScript
+npm run build
+
+# Run tests
+npm test
+
+# Run example
+node examples/basic_usage.js
+```
+
+## Development
+
+### Project Structure
+
+```
+wsjtx-lib-nodejs/
+├── src/                 # TypeScript source files
+├── native/              # C++ wrapper code
+├── wsjtx_lib/          # Git submodule (wsjtx_lib C library)
+├── test/               # Test files
+├── examples/           # Usage examples
+├── dist/               # Compiled TypeScript output
+└── build/              # CMake build directory
+```
+
+### Scripts
+
+- `npm run build` - Build both native module and TypeScript
+- `npm run build:native` - Build only the native C++ module
+- `npm run build:ts` - Build only TypeScript
+- `npm test` - Run all tests
+- `npm run clean` - Clean build artifacts
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass
+6. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Based on the excellent [wsjtx_lib](https://github.com/original-repo/wsjtx_lib) C library
+- WSJT-X development team for the original algorithms
+- Amateur radio community for protocol specifications
+
+## Support
+
+- 📧 Email: support@example.com
+- 🐛 Issues: [GitHub Issues](https://github.com/your-repo/wsjtx-lib-nodejs/issues)
+- 📖 Documentation: [Wiki](https://github.com/your-repo/wsjtx-lib-nodejs/wiki)
+- 💬 Discussions: [GitHub Discussions](https://github.com/your-repo/wsjtx-lib-nodejs/discussions) 

package/dist/src/index.d.ts

@@ -0,0 +1,180 @@
+/**
+ * WSJTX Digital Radio Protocol Library for Node.js
+ *
+ * High-level TypeScript wrapper around the native C++ WSJTX library bindings.
+ * Provides async/await support, input validation, and convenient utilities
+ * for working with digital amateur radio protocols.
+ *
+ * @example
+ * ```typescript
+ * import { WSJTXLib, WSJTXMode } from 'wsjtx-lib';
+ *
+ * const lib = new WSJTXLib();
+ *
+ * // Decode FT8 audio data
+ * const audioData = new Float32Array(48000 * 13); // 13 seconds at 48kHz
+ * const result = await lib.decode(WSJTXMode.FT8, audioData, 1500);
+ *
+ * // Get decoded messages
+ * const messages = lib.pullMessages();
+ * console.log('Decoded messages:', messages);
+ * ```
+ */
+import { WSJTXMode, DecodeResult, EncodeResult, WSPRResult, WSPRDecodeOptions, WSJTXMessage, AudioData, IQData, WSJTXError, WSJTXConfig, VersionInfo, ModeCapabilities } from './types.js';
+/**
+ * Main WSJTX library class providing digital radio protocol processing
+ *
+ * This class wraps the native C++ implementation and provides a convenient
+ * TypeScript/JavaScript interface with proper error handling, validation,
+ * and async/await support.
+ */
+export declare class WSJTXLib {
+    private native;
+    private config;
+    /**
+     * Create a new WSJTX library instance
+     *
+     * @param config Optional configuration options
+     * @throws {WSJTXError} If the native library fails to initialize
+     */
+    constructor(config?: WSJTXConfig);
+    /**
+     * Decode digital radio signals from audio data
+     *
+     * This method processes audio samples and attempts to decode digital
+     * messages using the specified protocol mode. The operation is performed
+     * asynchronously to avoid blocking the Node.js event loop.
+     *
+     * @param mode The digital mode to use for decoding
+     * @param audioData Audio samples (Float32Array or Int16Array)
+     * @param frequency Center frequency in Hz
+     * @param threads Number of threads to use (1-16, default: 4)
+     * @returns Promise that resolves when decoding is complete
+     *
+     * @throws {WSJTXError} If parameters are invalid or decoding fails
+     *
+     * @example
+     * ```typescript
+     * const audioData = new Float32Array(48000 * 13); // 13 seconds
+     * await lib.decode(WSJTXMode.FT8, audioData, 1500);
+     * const messages = lib.pullMessages();
+     * ```
+     */
+    decode(mode: WSJTXMode, audioData: AudioData, frequency: number, threads?: number): Promise<DecodeResult>;
+    /**
+     * Encode a message into audio waveform for transmission
+     *
+     * Generates the audio waveform that represents the specified message
+     * using the given digital mode. The resulting audio can be fed to
+     * a radio transmitter or audio interface.
+     *
+     * @param mode The digital mode to use for encoding
+     * @param message The message text to encode (mode-specific format)
+     * @param frequency Center frequency in Hz
+     * @param threads Number of threads to use (1-16, default: 4)
+     * @returns Promise that resolves with encoded audio data and actual message sent
+     *
+     * @throws {WSJTXError} If parameters are invalid or encoding fails
+     *
+     * @example
+     * ```typescript
+     * const result = await lib.encode(WSJTXMode.FT8, 'CQ DX K1ABC FN20', 1500);
+     * console.log('Generated audio samples:', result.audioData.length);
+     * console.log('Actual message sent:', result.messageSent);
+     * ```
+     */
+    encode(mode: WSJTXMode, message: string, frequency: number, threads?: number): Promise<EncodeResult>;
+    /**
+     * Decode WSPR signals from IQ data
+     *
+     * WSPR (Weak Signal Propagation Reporter) is a specialized protocol
+     * for studying radio propagation. This method takes IQ (complex)
+     * samples and attempts to decode WSPR transmissions.
+     *
+     * @param iqData Interleaved I,Q samples as Float32Array
+     * @param options Decoder options (frequency, callsign, etc.)
+     * @returns Promise that resolves with array of decoded WSPR results
+     *
+     * @throws {WSJTXError} If parameters are invalid or decoding fails
+     *
+     * @example
+     * ```typescript
+     * const iqData = new Float32Array(2 * 12000 * 111); // 2 minutes of IQ data
+     * const options = {
+     *   dialFrequency: 14095600, // 20m WSPR frequency
+     *   callsign: 'K1ABC',
+     *   locator: 'FN20'
+     * };
+     * const results = await lib.decodeWSPR(iqData, options);
+     * ```
+     */
+    decodeWSPR(iqData: IQData, options?: WSPRDecodeOptions): Promise<WSPRResult[]>;
+    /**
+     * Retrieve decoded messages from the internal queue
+     *
+     * Messages are added to an internal queue as they are decoded.
+     * This method retrieves and removes all pending messages from the queue.
+     *
+     * @returns Array of decoded messages
+     *
+     * @example
+     * ```typescript
+     * const messages = lib.pullMessages();
+     * messages.forEach(msg => {
+     *   console.log(`${msg.text} (SNR: ${msg.snr} dB, ΔT: ${msg.deltaTime}s)`);
+     * });
+     * ```
+     */
+    pullMessages(): WSJTXMessage[];
+    /**
+     * Check if encoding is supported for a specific mode
+     *
+     * @param mode The mode to check
+     * @returns True if encoding is supported
+     */
+    isEncodingSupported(mode: WSJTXMode): boolean;
+    /**
+     * Check if decoding is supported for a specific mode
+     *
+     * @param mode The mode to check
+     * @returns True if decoding is supported
+     */
+    isDecodingSupported(mode: WSJTXMode): boolean;
+    /**
+     * Get the required sample rate for a specific mode
+     *
+     * @param mode The mode to query
+     * @returns Sample rate in Hz
+     */
+    getSampleRate(mode: WSJTXMode): number;
+    /**
+     * Get the transmission duration for a specific mode
+     *
+     * @param mode The mode to query
+     * @returns Duration in seconds
+     */
+    getTransmissionDuration(mode: WSJTXMode): number;
+    /**
+     * Get capabilities for all supported modes
+     *
+     * @returns Array of mode capability information
+     */
+    getAllModeCapabilities(): ModeCapabilities[];
+    /**
+     * Convert audio format between Float32Array and Int16Array
+     *
+     * @param audioData Input audio data
+     * @param targetFormat Target format ('float32' or 'int16')
+     * @returns Converted audio data
+     */
+    static convertAudioFormat(audioData: AudioData, targetFormat: 'float32' | 'int16'): AudioData;
+    private validateMode;
+    private validateFrequency;
+    private validateThreads;
+    private validateMessage;
+    private validateAudioData;
+    private validateIQData;
+}
+export { WSJTXMode, WSJTXError, };
+export type { DecodeResult, EncodeResult, WSPRResult, WSPRDecodeOptions, WSJTXMessage, AudioData, IQData, WSJTXConfig, VersionInfo, ModeCapabilities };
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACL,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,YAAY,EACZ,SAAS,EACT,MAAM,EACN,UAAU,EACV,WAAW,EACX,WAAW,EACX,gBAAgB,EAIjB,MAAM,YAAY,CAAC;AAoEpB;;;;;;GAMG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,MAAM,CAAc;IAE5B;;;;;OAKG;gBACS,MAAM,GAAE,WAAgB;IAiBpC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,MAAM,CACV,IAAI,EAAE,SAAS,EACf,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,MAAoC,GAC5C,OAAO,CAAC,YAAY,CAAC;IA+BxB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,MAAM,CACV,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,MAAoC,GAC5C,OAAO,CAAC,YAAY,CAAC;IA8BxB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,UAAU,CACd,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,UAAU,EAAE,CAAC;IAkCxB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,IAAI,YAAY,EAAE;IAW9B;;;;;OAKG;IACH,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO;IAI7C;;;;;OAKG;IACH,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO;IAI7C;;;;;OAKG;IACH,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM;IAItC;;;;;OAKG;IACH,uBAAuB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM;IAIhD;;;;OAIG;IACH,sBAAsB,IAAI,gBAAgB,EAAE;IAY5C;;;;;;OAMG;IACH,MAAM,CAAC,kBAAkB,CACvB,SAAS,EAAE,SAAS,EACpB,YAAY,EAAE,SAAS,GAAG,OAAO,GAChC,SAAS;IA6BZ,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,cAAc;CAcvB;AAGD,OAAO,EACL,SAAS,EACT,UAAU,GACX,CAAC;AAEF,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,YAAY,EACZ,SAAS,EACT,MAAM,EACN,WAAW,EACX,WAAW,EACX,gBAAgB,EACjB,CAAC"}