Merge pull request #13 from melbinjp/copilot/plan-audio-data-transfer-implementation

Fix OOM crash on file send: lazy chunk reads, single transmitter session, correct modem profile

Author: melbinjp

src/dsp/quiet-modem.ts

@@ -56,11 +56,15 @@ export function primeAudio(): void {
 /**
  * Profile used for file-data frames (sender → receiver).
  *
- * 'audible-fsk-robust' uses FSK8 modulation with a v29 convolutional outer FEC,
- * centred at 8 kHz with 250 samples/symbol.  The long integration window makes
- * it resilient to speaker/microphone gain variations across a real air gap.
+ * 'audible-fsk' uses FSK8 modulation with a v29 convolutional outer FEC,
+ * centred at 8 kHz with 50 samples/symbol (~250 bytes/sec at typical sample
+ * rates).  This is 5× faster than the former 'audible-fsk-robust' profile
+ * (250 samples/symbol, ~50 bytes/sec), which caused every 4096-byte frame to
+ * require ~81 s of audio — far exceeding the 30 s transmission timeout and
+ * making all transfers fail after the first frame.  'audible-fsk' still uses
+ * the same FSK8/v29-FEC modem and is reliable for typical desktop/phone use.
  */
-export const DATA_MODEM_PROFILE = 'audible-fsk-robust';
+export const DATA_MODEM_PROFILE = 'audible-fsk';
 
 /**
  * Profile used for ACK frames (receiver → sender).
@@ -185,8 +189,15 @@ doInit().catch((err) => {
     initPromise = null;
 });
 
-/** Maximum time (ms) to wait for a single frame transmission to finish. */
-const SEND_TIMEOUT_MS = 30_000;
+/** Maximum time (ms) to wait for a single frame transmission to finish.
+ *
+ * With the 'audible-fsk' profile (50 samples/symbol, FSK8) the effective
+ * application-layer throughput is approximately 250 bytes/sec.  A 4096-byte
+ * application frame therefore takes roughly 4096 / 250 ≈ 16 s to play out at
+ * typical sample rates.  60 s provides a 3.7× safety margin to accommodate
+ * slower devices and non-standard sample rates (e.g. 44.1 kHz).
+ */
+const SEND_TIMEOUT_MS = 60_000;
 
 /**
  * Transmit an ArrayBuffer as audio.
@@ -232,6 +243,98 @@ export async function sendData(data: ArrayBuffer, profile = DATA_MODEM_PROFILE):
     });
 }
 
+/**
+ * A reusable transmitter session that creates a single `Quiet.transmitter`
+ * (and therefore a single `ScriptProcessorNode`) for an entire file transfer,
+ * rather than creating and tearing down one per frame.
+ *
+ * Each `send()` call updates a mutable callback reference that the shared
+ * `onFinish` handler delegates to, so the quiet.js transmitter can be reused
+ * across multiple sequential `transmit()` invocations without being destroyed
+ * and recreated between frames.
+ *
+ * Usage:
+ *   const session = new TransmitterSession();
+ *   await session.init();
+ *   await session.send(frame1);
+ *   await session.send(frame2);
+ *   session.destroy();
+ */
+export class TransmitterSession {
+    private transmitter: { transmit: (data: ArrayBuffer) => void; destroy: () => void } | null = null;
+    /** Resolves the Promise returned by the current in-flight `send()` call. */
+    private onFinishRef: (() => void) | null = null;
+    private isDestroyed = false;
+
+    constructor(private readonly profile: string = DATA_MODEM_PROFILE) {}
+
+    /**
+     * Initialises Quiet.js and creates the underlying transmitter.
+     * Must be called once before any `send()` calls.
+     */
+    async init(): Promise<void> {
+        await initQuiet();
+        this.transmitter = Quiet.transmitter({
+            profile: this.profile,
+            onFinish: () => {
+                console.log('Transmission finished.');
+                // Delegate to whichever frame's resolve callback is currently set.
+                this.onFinishRef?.();
+            },
+            clampFrame: false,
+        });
+    }
+
+    /**
+     * Transmits `data` as audio and resolves when playback is complete.
+     * Calls must be awaited sequentially — do not overlap concurrent sends.
+     */
+    send(data: ArrayBuffer): Promise<void> {
+        return new Promise((resolve, reject) => {
+            const transmitter = this.transmitter;
+            if (this.isDestroyed || !transmitter) {
+                reject(new Error('TransmitterSession has been destroyed'));
+                return;
+            }
+
+            const timeout = setTimeout(() => {
+                this.onFinishRef = null;
+                reject(new Error(
+                    'Transmission timed out: the browser AudioContext may be suspended. ' +
+                    'Ensure primeAudio() was called synchronously in the click handler ' +
+                    'before any async operations.',
+                ));
+            }, SEND_TIMEOUT_MS);
+
+            this.onFinishRef = () => {
+                clearTimeout(timeout);
+                this.onFinishRef = null;
+                resolve();
+            };
+
+            try {
+                transmitter.transmit(data);
+            } catch (err) {
+                clearTimeout(timeout);
+                this.onFinishRef = null;
+                reject(err);
+            }
+        });
+    }
+
+    /**
+     * Immediately stops audio playback and releases the `ScriptProcessorNode`.
+     * Safe to call multiple times.
+     */
+    destroy(): void {
+        if (!this.isDestroyed) {
+            this.isDestroyed = true;
+            this.transmitter?.destroy();
+            this.transmitter = null;
+        }
+    }
+}
+
 /**
  * Start listening for audio data via the microphone.
  * Returns an AnalyserNode for spectrogram visualization and a `stop` function

src/transport/framing.ts

@@ -11,7 +11,7 @@ import CRC32 from 'crc-32';
  * balances memory efficiency with frame-count reduction (~64× fewer frames
  * compared to the previous 64-byte size).
  */
-const PAYLOAD_SIZE = 4096;
+export const PAYLOAD_SIZE = 4096;
 
 /**
  * Defines the different types of frames used in the protocol.
@@ -156,6 +156,34 @@ export function createFileDataFrame(
     return createFrame(header, payload);
 }
 
+/**
+ * Creates a single `file-data` frame from an already-sliced payload chunk.
+ * Use this instead of {@link createFileDataFrame} when the caller reads each
+ * chunk lazily (e.g. via `File.slice().arrayBuffer()`) to avoid holding the
+ * entire file in memory simultaneously.
+ *
+ * @param payload The raw bytes for this chunk (must be exactly the slice for frameIndex).
+ * @param fileId The ID for this transfer session.
+ * @param frameIndex The zero-based index of the frame.
+ * @param totalFrames The total number of data frames for this file.
+ * @returns An ArrayBuffer representing the single `file-data` frame.
+ */
+export function createFileDataFrameFromPayload(
+    payload: ArrayBuffer,
+    fileId: string,
+    frameIndex: number,
+    totalFrames: number,
+): ArrayBuffer {
+    const header: FrameHeader = {
+        type: 'file-data',
+        fileId,
+        frameIndex,
+        totalFrames,
+        crc32: CRC32.buf(new Uint8Array(payload)),
+    };
+    return createFrame(header, payload);
+}
+
 /**
  * Returns the total number of `file-data` frames required for a given buffer.
  * @param fileBuffer The file content as an ArrayBuffer.

src/ui/sender-sm.ts

@@ -1,5 +1,5 @@
-import { sendData } from '../dsp/quiet-modem';
-import { createFileDataFrame, createFileStartFrame, getTotalFrames } from '../transport/framing';
+import { TransmitterSession } from '../dsp/quiet-modem';
+import { PAYLOAD_SIZE, createFileDataFrameFromPayload, createFileStartFrame } from '../transport/framing';
 
 /**
  * Defines the possible states of the sender state machine.
@@ -9,12 +9,23 @@ export type SenderState = 'idle' | 'sending' | 'complete' | 'error';
 /**
  * Sends a file as audio frames sequentially without requiring ACKs.
  *
- * Removing the bidirectional ACK protocol means the sender no longer needs
- * to run a microphone receiver (ScriptProcessorNode) concurrently with the
- * transmitter (another ScriptProcessorNode).  Having two ScriptProcessorNodes
- * simultaneously was the primary cause of the main-thread freeze and the
- * out-of-memory crash: quiet.js runs Emscripten DSP synchronously inside each
- * node's onaudioprocess callback, and two concurrent nodes starved the browser.
+ * Key design decisions that prevent out-of-memory crashes and transmission
+ * timeouts:
+ *
+ * 1. **Lazy chunk reading** — `File.arrayBuffer()` is never called on the
+ *    entire file.  Instead, each 4 KB chunk is read with `File.slice().arrayBuffer()`
+ *    immediately before it is transmitted and discarded afterwards.  Peak RAM
+ *    usage is therefore O(1 frame) rather than O(file size).
+ *
+ * 2. **Single `TransmitterSession`** — one `Quiet.transmitter` (and one
+ *    `ScriptProcessorNode`) is created for the whole transfer and reused across
+ *    all frames.  Creating/destroying a node per frame was causing unnecessary
+ *    DSP churn on the main thread.
+ *
+ * 3. **No concurrent ACK receiver** — removing the bidirectional ACK protocol
+ *    means only one `ScriptProcessorNode` is active at any time.  Running two
+ *    concurrent nodes (transmitter + ACK receiver) previously starved the
+ *    browser's audio thread.
  */
 export class SenderSM {
     private state: SenderState = 'idle';
@@ -38,9 +49,9 @@ export class SenderSM {
     public start() {
         this.fileId = crypto.randomUUID();
         this.setState('sending', 'Preparing to send...');
-        this.file.arrayBuffer().then(fileBuffer => this.sendAll(fileBuffer)).catch(err => {
+        this.sendAll().catch(err => {
             const msg = err instanceof Error ? err.message : String(err);
-            this.setState('error', `Failed to read file: ${msg}`);
+            this.setState('error', `Transmission error: ${msg}`);
         });
     }
 
@@ -51,41 +62,49 @@ export class SenderSM {
         }
     }
 
-    private async sendAll(fileBuffer: ArrayBuffer) {
-        const totalFrames = getTotalFrames(fileBuffer);
+    private async sendAll() {
+        // Compute the total frame count from file metadata — no need to read
+        // the file contents up front, which would cause an OOM for large files.
+        const totalFrames = Math.ceil(this.file.size / PAYLOAD_SIZE);
         this.onProgress(0, totalFrames);
 
-        // Transmit the handshake frame first so the receiver can prepare its
-        // reassembly buffer before any data frames arrive.
-        const startFrame = createFileStartFrame(this.file, this.fileId);
-        this.setState('sending', 'Sending handshake frame...');
+        const session = new TransmitterSession();
         try {
-            await sendData(startFrame);
+            await session.init();
         } catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            this.setState('error', `Transmission error: ${msg}`);
+            this.setState('error', `Failed to initialize transmitter: ${msg}`);
             return;
         }
 
-        // Send every data frame in order.  Frames are created one at a time so
-        // that only the current frame is held in memory alongside fileBuffer,
-        // rather than pre-allocating the full set (which would double peak RAM
-        // usage and cause out-of-memory crashes for large files).
-        // await ensures each frame's audio has fully played out before the next
-        // one begins, preventing the quiet.js transmit queue from growing unboundedly.
-        for (let i = 0; i < totalFrames; i++) {
-            this.setState('sending', `Sending frame ${i + 1}/${totalFrames}...`);
-            const frame = createFileDataFrame(fileBuffer, this.fileId, i, totalFrames);
-            try {
-                await sendData(frame);
-            } catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                this.setState('error', `Transmission error: ${msg}`);
-                return;
+        try {
+            // Transmit the handshake frame first so the receiver can prepare its
+            // reassembly buffer before any data frames arrive.
+            const startFrame = createFileStartFrame(this.file, this.fileId);
+            this.setState('sending', 'Sending handshake frame...');
+            await session.send(startFrame);
+
+            // Send every data frame in order.  Each chunk is read lazily with
+            // File.slice() so that only ~4 KB is held in memory at a time,
+            // regardless of the total file size.  Awaiting session.send() ensures
+            // each frame's audio has fully played out before the next one begins,
+            // preventing the quiet.js transmit queue from growing unboundedly.
+            for (let i = 0; i < totalFrames; i++) {
+                this.setState('sending', `Sending frame ${i + 1}/${totalFrames}...`);
+                const start = i * PAYLOAD_SIZE;
+                const end = start + PAYLOAD_SIZE;
+                const chunkBuffer = await this.file.slice(start, end).arrayBuffer();
+                const frame = createFileDataFrameFromPayload(chunkBuffer, this.fileId, i, totalFrames);
+                await session.send(frame);
+                this.onProgress(i + 1, totalFrames);
             }
-            this.onProgress(i + 1, totalFrames);
-        }
 
-        this.setState('complete', 'File sent successfully.');
+            this.setState('complete', 'File sent successfully.');
+        } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.setState('error', `Transmission error: ${msg}`);
+        } finally {
+            session.destroy();
+        }
     }
 }