Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python

Fix malformed browser WebM uploads (#340): serialize IndexedDB recording-session writes so crash-recovered chunks keep order, and auto-trim a .webm to its EBML header server-side when the leading bytes are corrupt

Murtaza Nasir6ab390bf6902
diff --git a/src/api/recordings.py b/src/api/recordings.py
index f4957b16..3c5fdc5c 100644
--- a/src/api/recordings.py
+++ b/src/api/recordings.py
@@ -48,7 +48,7 @@ from src.services.document import process_markdown_to_docx
from src.services.llm import client, chat_client, call_llm_completion, call_chat_completion, process_streaming_with_thinking, TokenBudgetExceeded
from src.services.embeddings import process_recording_chunks
from src.file_exporter import export_recording, mark_export_as_deleted
-from src.utils.ffprobe import get_codec_info, get_creation_date, get_duration, FFProbeError
+from src.utils.ffprobe import get_codec_info, get_creation_date, get_duration, try_repair_malformed_webm, FFProbeError
from src.utils.audio_conversion import convert_if_needed
from src.services.storage import get_storage_service
from src.utils.file_hash import compute_file_sha256
@@ -2514,6 +2514,15 @@ def upload_file():
except FFProbeError as e:
current_app.logger.warning(f"Failed to probe {original_filename} (timeout={probe_timeout}s): {e}. Will attempt conversion.")
codec_info = None
+ # #340: a browser MediaRecorder can produce a .webm whose EBML header
+ # isn't at the front (chunk-order artifact, seen on crash-recovered
+ # recordings). If so, trim to the real header and re-probe before we
+ # fall through to a conversion that would just fail again.
+ if os.path.splitext(original_filename)[1].lower() in ('.webm', '.mkv', '.mka'):
+ repaired_info = try_repair_malformed_webm(filepath, timeout=probe_timeout)
+ if repaired_info is not None:
+ codec_info = repaired_info
+ current_app.logger.info(f"Recovered malformed WebM header for {original_filename}; probe succeeded after trim")
# Video retention/passthrough: skip conversion for videos, processing pipeline handles extraction
has_video = codec_info.get('has_video', False) if codec_info else False
diff --git a/src/utils/ffprobe.py b/src/utils/ffprobe.py
index 4cd33105..33dbbf96 100644
--- a/src/utils/ffprobe.py
+++ b/src/utils/ffprobe.py
@@ -8,12 +8,18 @@ structured information about their codecs, streams, and formats.
import json
import logging
import os
+import shutil
import subprocess
from datetime import datetime
from typing import Optional, Dict, Any, Tuple
logger = logging.getLogger(__name__)
+# Every valid WebM/Matroska file begins with this 4-byte EBML magic. A browser
+# MediaRecorder can occasionally hand us a .webm whose header is not at the
+# front (chunk-assembly artifact — see try_repair_malformed_webm / issue #340).
+_EBML_MAGIC = b'\x1a\x45\xdf\xa3'
+
class FFProbeError(Exception):
"""Raised when ffprobe fails to analyze a file."""
@@ -184,6 +190,86 @@ def get_codec_info(filename: str, timeout: Optional[int] = None) -> Dict[str, An
return result
+def try_repair_malformed_webm(filename: str, timeout: Optional[int] = None,
+ max_scan_bytes: int = 8 * 1024 * 1024) -> Optional[Dict[str, Any]]:
+ """Repair a WebM/Matroska file whose EBML header is not at the front.
+
+ A browser's MediaRecorder can assemble chunks such that the leading bytes of
+ the uploaded .webm are not the EBML magic (``1A 45 DF A3``) — the real header
+ appears further in. ffprobe/ffmpeg then reject the file ("EBML header parsing
+ failed"). This is most often seen on crash-recovered recordings whose chunk
+ order was scrambled in client storage (issue #340).
+
+ When the file does not start with the EBML magic but contains it within the
+ first ``max_scan_bytes``, this trims the leading bytes so the file starts at
+ the real header. The trimmed candidate is written to a temp file and probed;
+ the original is replaced ONLY if the trimmed file probes cleanly, so a false
+ positive (the magic appearing by chance inside media data) never destroys the
+ upload.
+
+ Args:
+ filename: Path to the file to repair in place.
+ timeout: Optional probe timeout in seconds.
+ max_scan_bytes: How far into the file to search for the header.
+
+ Returns:
+ The codec-info dict for the repaired file if the repair succeeded and the
+ file now probes cleanly, otherwise None (file left untouched).
+ """
+ try:
+ with open(filename, 'rb') as f:
+ head = f.read(max_scan_bytes)
+ except OSError as e:
+ logger.warning(f"WebM repair: could not read {filename}: {e}")
+ return None
+
+ if head[:4] == _EBML_MAGIC:
+ return None # already well-formed at the front — nothing to repair
+
+ offset = head.find(_EBML_MAGIC)
+ if offset <= 0:
+ # Header not found ahead of the current start (or already at 0): either
+ # this isn't a recoverable WebM or the header is missing entirely.
+ return None
+
+ tmp_path = f"{filename}.repair.tmp"
+ try:
+ with open(filename, 'rb') as src, open(tmp_path, 'wb') as dst:
+ src.seek(offset)
+ shutil.copyfileobj(src, dst, length=1024 * 1024)
+ except OSError as e:
+ logger.warning(f"WebM repair: could not write trimmed candidate for {filename}: {e}")
+ _quiet_remove(tmp_path)
+ return None
+
+ # Only commit the repair if the trimmed file actually probes as valid media.
+ try:
+ codec_info = get_codec_info(tmp_path, timeout=timeout)
+ except FFProbeError as e:
+ logger.warning(f"WebM repair: trimmed candidate for {filename} still not probeable: {e}")
+ _quiet_remove(tmp_path)
+ return None
+
+ try:
+ os.replace(tmp_path, filename)
+ except OSError as e:
+ logger.warning(f"WebM repair: could not replace {filename} with trimmed file: {e}")
+ _quiet_remove(tmp_path)
+ return None
+
+ logger.info(f"WebM repair: trimmed {offset} leading bytes to reach EBML header in {filename}")
+ return codec_info
+
+
+def _quiet_remove(path: str) -> None:
+ """Best-effort removal of a temp file; never raises."""
+ try:
+ if os.path.exists(path):
+ os.remove(path)
+ except OSError:
+ pass
+
+
def is_video_file(filename: str, timeout: Optional[int] = None, codec_info: Optional[Dict[str, Any]] = None) -> bool:
"""
Check if a file contains video streams.
diff --git a/static/js/modules/db/recording-persistence.js b/static/js/modules/db/recording-persistence.js
index 6b315078..d68f4b37 100644
--- a/static/js/modules/db/recording-persistence.js
+++ b/static/js/modules/db/recording-persistence.js
@@ -19,6 +19,28 @@ const promisifyRequest = (request) => {
});
};
+/**
+ * Serialize read-modify-write mutations of the single 'current' session record.
+ *
+ * saveChunk/updateRecordingMetadata/pruneOldChunks each do get -> mutate -> put
+ * with awaits in between. Without serialization, two that overlap (common at
+ * startup, where the first chunk's write is still opening the DB when the next
+ * chunk arrives) clobber each other's writes — dropping or REORDERING chunks in
+ * IndexedDB. On crash recovery the scrambled order yields a WebM whose EBML
+ * header isn't first, which ffmpeg then rejects (issue #340). Chaining every
+ * mutation through one promise guarantees they apply in call order, one at a
+ * time. Order is fixed at call time because the .then() is attached
+ * synchronously, so callers enqueue in the order MediaRecorder emits chunks.
+ */
+let _sessionWriteChain = Promise.resolve();
+const serializeSessionWrite = (task) => {
+ const result = _sessionWriteChain.then(task, task);
+ // Keep the chain alive after a rejection so one failed write doesn't wedge
+ // every later write; callers still see their own rejection via `result`.
+ _sessionWriteChain = result.catch(() => {});
+ return result;
+};
+
/**
* Initialize IndexedDB
*/
@@ -58,7 +80,7 @@ export const initDB = () => {
/**
* Save recording metadata and initialize session
*/
-export const startRecordingSession = async (recordingData) => {
+export const startRecordingSession = (recordingData) => serializeSessionWrite(async () => {
try {
const db = await initDB();
const transaction = db.transaction([STORE_NAME], 'readwrite');
@@ -88,12 +110,12 @@ export const startRecordingSession = async (recordingData) => {
console.error('[RecordingDB] Failed to start session:', error);
throw error;
}
-};
+});
/**
* Save a recording chunk to IndexedDB
*/
-export const saveChunk = async (chunkBlob, chunkIndex) => {
+export const saveChunk = (chunkBlob, chunkIndex) => serializeSessionWrite(async () => {
try {
// Do async prep work BEFORE creating transaction to avoid auto-close
const db = await initDB();
@@ -126,12 +148,12 @@ export const saveChunk = async (chunkBlob, chunkIndex) => {
console.error('[RecordingDB] Failed to save chunk:', error);
// Don't throw - recording should continue even if persistence fails
}
-};
+});
/**
* Update recording metadata (notes, duration, etc.)
*/
-export const updateRecordingMetadata = async (updates) => {
+export const updateRecordingMetadata = (updates) => serializeSessionWrite(async () => {
try {
const db = await initDB();
const transaction = db.transaction([STORE_NAME], 'readwrite');
@@ -151,7 +173,7 @@ export const updateRecordingMetadata = async (updates) => {
} catch (error) {
console.error('[RecordingDB] Failed to update metadata:', error);
}
-};
+});
/**
* Prune the IndexedDB buffer to the last `keepLast` chunks.
@@ -164,7 +186,7 @@ export const updateRecordingMetadata = async (updates) => {
* than keepLast, so a not-yet-uploaded chunk is never dropped from the local
* fallback. Non-fatal on error — pruning is an optimization, not correctness.
*/
-export const pruneOldChunks = async (keepLast = 5) => {
+export const pruneOldChunks = (keepLast = 5) => serializeSessionWrite(async () => {
try {
const db = await initDB();
const transaction = db.transaction([STORE_NAME], 'readwrite');
@@ -178,7 +200,7 @@ export const pruneOldChunks = async (keepLast = 5) => {
} catch (error) {
// Pruning is best-effort; recording continues regardless.
}
-};
+});
/**
* Check if there's a recoverable recording
@@ -267,7 +289,7 @@ export const recoverRecording = async () => {
/**
* Clear recording session (after successful upload or discard)
*/
-export const clearRecordingSession = async () => {
+export const clearRecordingSession = () => serializeSessionWrite(async () => {
try {
const db = await initDB();
const transaction = db.transaction([STORE_NAME], 'readwrite');
@@ -278,7 +300,7 @@ export const clearRecordingSession = async () => {
} catch (error) {
console.error('[RecordingDB] Failed to clear session:', error);
}
-};
+});
/**
* Get database size information
diff --git a/static/js/modules/db/recording-persistence.test.js b/static/js/modules/db/recording-persistence.test.js
index 80513d62..dd4f958b 100644
--- a/static/js/modules/db/recording-persistence.test.js
+++ b/static/js/modules/db/recording-persistence.test.js
@@ -218,6 +218,27 @@ describe('recording-persistence', () => {
await expect(mod.saveChunk(bad, 0)).resolves.toBeUndefined();
expect(console.error).toHaveBeenCalled();
});
+
+ it('preserves chunk order when writes overlap (issue #340)', async () => {
+ await mod.startRecordingSession({ mode: 'm' });
+
+ // Chunk 0's arrayBuffer resolves AFTER chunk 1's. Without
+ // serialization the two get->modify->put cycles interleave and the
+ // slower (header) chunk loses the race, so it lands out of order —
+ // which is what leaves a recovered WebM's EBML header off the front.
+ const slow = { size: 10, arrayBuffer: () => new Promise(r => setTimeout(() => r(new ArrayBuffer(10)), 25)) };
+ const fast = { size: 20, arrayBuffer: () => new Promise(r => setTimeout(() => r(new ArrayBuffer(20)), 0)) };
+
+ // Issue both without awaiting the first, mirroring rapid
+ // ondataavailable events firing while the DB is still opening.
+ const p0 = mod.saveChunk(slow, 0);
+ const p1 = mod.saveChunk(fast, 1);
+ await Promise.all([p0, p1]);
+
+ const chunks = mock.stores.get(STORE_NAME).get('current').chunks;
+ expect(chunks.map(c => c.index)).toEqual([0, 1]);
+ expect(chunks.map(c => c.size)).toEqual([10, 20]);
+ });
});
describe('updateRecordingMetadata', () => {
diff --git a/tests/test_webm_header_repair.py b/tests/test_webm_header_repair.py
new file mode 100644
index 00000000..6df157c9
--- /dev/null
+++ b/tests/test_webm_header_repair.py
@@ -0,0 +1,92 @@
+"""Server-side repair of WebM files whose EBML header isn't at the front (#340).
+
+A browser MediaRecorder can hand us a .webm whose leading bytes are not the EBML
+magic (chunk-assembly artifact, usually on crash-recovered recordings). ffmpeg
+then rejects the file. try_repair_malformed_webm trims the leading garbage to the
+real header, but only commits the trim if the result actually probes as valid —
+so a false-positive match never destroys the upload.
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+
+import pytest
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from src.utils.ffprobe import try_repair_malformed_webm, get_codec_info, _EBML_MAGIC, FFProbeError
+
+
+def _ffmpeg_available():
+ return shutil.which('ffmpeg') is not None and shutil.which('ffprobe') is not None
+
+
+pytestmark = pytest.mark.skipif(not _ffmpeg_available(), reason="ffmpeg/ffprobe not installed")
+
+
+def valid_webm(tmp_path):
+ """A tiny real Opus/WebM file produced by ffmpeg."""
+ path = str(tmp_path / "good.webm")
+ subprocess.run(
+ ['ffmpeg', '-y', '-f', 'lavfi', '-i', 'anullsrc=r=48000:cl=mono',
+ '-t', '1', '-c:a', 'libopus', path],
+ check=True, capture_output=True,
+ )
+ # Sanity: a freshly-muxed webm really does start with the EBML magic.
+ with open(path, 'rb') as f:
+ assert f.read(4) == _EBML_MAGIC
+ return path
+
+
+def test_repairs_webm_with_leading_garbage(valid_webm):
+ good_bytes = open(valid_webm, 'rb').read()
+ broken = valid_webm.replace('good', 'broken')
+ with open(broken, 'wb') as f:
+ f.write(b'\x43\xc3\x81\x13' * 64) # bogus prefix like the one reported
+ f.write(good_bytes)
+
+ # Precondition: it does NOT probe before repair.
+ with pytest.raises(FFProbeError):
+ get_codec_info(broken)
+
+ info = try_repair_malformed_webm(broken)
+ assert info is not None
+ assert info['has_audio'] is True
+ # File now starts at the real header and probes cleanly.
+ with open(broken, 'rb') as f:
+ assert f.read(4) == _EBML_MAGIC
+ assert get_codec_info(broken)['has_audio'] is True
+
+
+def test_wellformed_file_is_left_untouched(valid_webm):
+ before = open(valid_webm, 'rb').read()
+ assert try_repair_malformed_webm(valid_webm) is None
+ assert open(valid_webm, 'rb').read() == before
+
+
+def test_file_without_ebml_header_is_not_touched(tmp_path):
+ garbage = str(tmp_path / "no_header.webm")
+ payload = b'\x00\x01\x02\x03' * 4096 # no EBML magic anywhere
+ with open(garbage, 'wb') as f:
+ f.write(payload)
+ assert try_repair_malformed_webm(garbage) is None
+ assert open(garbage, 'rb').read() == payload # untouched
+
+
+def test_false_positive_match_does_not_destroy_original(tmp_path):
+ """If the EBML magic appears by chance but the trimmed file still won't
+ probe, the original must be preserved (repair returns None)."""
+ path = str(tmp_path / "chance.webm")
+ payload = b'\x11\x22\x33\x44' * 32 + _EBML_MAGIC + b'\x99' * 4096
+ with open(path, 'wb') as f:
+ f.write(payload)
+ assert try_repair_malformed_webm(path) is None
+ assert open(path, 'rb').read() == payload # original intact, not clobbered
+
+
+def test_missing_file_returns_none(tmp_path):
+ assert try_repair_malformed_webm(str(tmp_path / "nope.webm")) is None