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.pyindex 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_docxfrom src.services.llm import client, chat_client, call_llm_completion, call_chat_completion, process_streaming_with_thinking, TokenBudgetExceededfrom src.services.embeddings import process_recording_chunksfrom 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, FFProbeErrorfrom src.utils.audio_conversion import convert_if_neededfrom src.services.storage import get_storage_servicefrom 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 extractionhas_video = codec_info.get('has_video', False) if codec_info else Falsediff --git a/src/utils/ffprobe.py b/src/utils/ffprobe.pyindex 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 jsonimport loggingimport os+import shutilimport subprocessfrom datetime import datetimefrom typing import Optional, Dict, Any, Tuplelogger = 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, Anreturn 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.jsindex 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-closeconst 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 informationdiff --git a/static/js/modules/db/recording-persistence.test.js b/static/js/modules/db/recording-persistence.test.jsindex 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.pynew file mode 100644index 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