How OpenWhispr Guarantees Cleanup of Temporary Audio Files: 5 Mechanisms Explained

Temporary audio files in OpenWhispr are guaranteed to be cleaned up through bounded lifecycle management, including explicit disposal methods, automatic stream release, and fail-open error handling that removes artifacts immediately after transcription or on any error.

OpenWhispr handles sensitive voice data by ensuring that temporary audio files never persist longer than a single transcription pass. The application uses a combination of in-memory Blobs and short-lived filesystem buffers that are explicitly deleted after use. According to the OpenWhispr source code, five distinct mechanisms work together to prevent orphaned audio recordings from accumulating on disk.

Explicit Cleanup via AudioManager and Prepared Capture

Disposing Prepared Microphone Captures

The AudioManager class maintains a PreparedMicCapture instance to handle pre-roll buffering. When recording ends or is cancelled, the manager invokes _disposePrepared, which releases the MediaStream and clears temporary buffers through disposePreparedCapture.

// src/helpers/audioManager.js
_disposePrepared(prepared) {
  if (!prepared) return;
  disposePreparedCapture(prepared);   // ↩︎ releases stream & clears temp data
  this._markCaptureStreamReleased();
}

This explicit disposal pattern ensures that any prepared capture state is reset before new recordings begin.

Post-Transcription File Deletion

Merging and Deleting Segment Files

After dictation completes, the renderer calls mergeAudioSegments in the main process. This utility concatenates recorded chunks into a single Blob and deletes the source temporary files before returning the result. The test suite confirms this behavior through explicit assertions on the deletion list.

// test/services/uploadDiarizationPersistence.test.js
assert.deepEqual(calls.deletedTempFiles, ["/tmp/ow-url-download.m4a"]);

By removing source files immediately after merging, OpenWhispr ensures that raw audio segments never outlive their single transcription pass.

Stale Buffer Management

Discarding Expired Pre-Roll Data

Pre-roll buffers that exceed PRE_ROLL_MAX_AGE_MS are automatically discarded via discardPreRoll. This function, implemented in src/helpers/preparedMicCapture.js, drops captured chunks and frees any associated temporary storage.

// src/helpers/preparedMicCapture.js (via discardPreRoll)
discardPreRoll(prepared);

Time-based expiration prevents stale audio data from accumulating in memory when recording sessions are interrupted or abandoned.

Automatic Resource Release

MediaStream and File Handle Cleanup

When the browser's MediaRecorder stops, the underlying MediaStream tracks are stopped, causing the browser to close associated file handles. The AudioManager method _markCaptureStreamReleased timestamps the mic-warm state and triggers an idle-hold countdown via micStreamHold.touch(), ensuring streams do not remain open indefinitely.

// src/helpers/audioManager.js
_markCaptureStreamReleased() {
  this._stampMicWarm();
  this.micStreamHold.touch();
}

This automatic release mechanism complements explicit file deletion by ensuring OS-level resources are freed promptly.

Error-Resilient Cleanup

Fail-Open Guards for Error Conditions

All code paths that create temporary files are wrapped in try/catch blocks. On any error, the implementation discards temporary data rather than persisting it. This fail-open design guarantees that even during unexpected failures—such as transcription crashes or permission denials—no stray temporary audio files remain on disk.

The combination of these layers ensures that temporary audio artifacts exist only for the duration of their immediate utility.

Summary

• Prepared capture disposal: AudioManager._disposePrepared explicitly clears pre-roll buffers and releases streams via disposePreparedCapture.
• Post-merge deletion: mergeAudioSegments deletes source files immediately after concatenating audio chunks.
• Time-based expiration: discardPreRoll removes stale buffers exceeding PRE_ROLL_MAX_AGE_MS.
• Automatic stream release: _markCaptureStreamReleased ensures MediaStream resources are freed and idle timeouts are triggered.
• Error handling: Try/catch blocks ensure temporary files are discarded rather than preserved when errors occur.

Frequently Asked Questions

How long do temporary audio files persist in OpenWhispr?

Temporary audio files exist only for the duration of a single transcription pass. According to the source code in src/helpers/audioManager.js, files are deleted immediately after mergeAudioSegments completes, or discarded via discardPreRoll when pre-roll buffers expire based on PRE_ROLL_MAX_AGE_MS.

What happens to temporary audio files if transcription fails?

OpenWhispr implements fail-open guards where all file-creation paths are wrapped in error handling. If any error occurs during recording or transcription, the catch blocks explicitly discard temporary data rather than persisting it, ensuring no orphaned files remain on disk.

Where does OpenWhispr store temporary audio files?

Temporary audio files are stored in system temporary directories, such as /tmp/ow-url-download.m4a as shown in the test suite at test/services/uploadDiarizationPersistence.test.js. These paths are created by the main process for short-term concatenation before being deleted post-transcription.

How does OpenWhispr prevent memory leaks from audio streams?

The application prevents memory leaks through _markCaptureStreamReleased in src/helpers/audioManager.js, which stops MediaStream tracks when recording ends and triggers micStreamHold.touch() to manage idle timeouts. This ensures browser file handles and memory buffers are released immediately.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}