Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
Recording sessions: segment-aware stitch assembly, dispatch stitch jobs, auto-finalize abandoned sessions, set title/meeting_date at finalize
Murtaza Nasir10e1d577d5ed
diff --git a/src/api/recording_sessions.py b/src/api/recording_sessions.pyindex 62a11c9c..ababcd6d 100644--- a/src/api/recording_sessions.py+++ b/src/api/recording_sessions.py@@ -32,7 +32,10 @@ Per-user storage of in-progress sessions is bounded by``RECORDING_SESSION_MAX_BYTES_PER_USER`` (default 5 GB). Sessions whose``last_seen_at`` is older than ``RECORDING_SESSION_TTL_HOURS`` (default24) are reaped by :func:`cleanup_expired_sessions` from an APScheduler-job; cleanup flips status to ``expired`` before removing the directory.+job. To avoid losing audio from users who disappear mid-recording,+cleanup AUTO-FINALIZES abandoned sessions that have chunks (assembling+what was uploaded into the user's library) and only deletes sessions that+have nothing to recover. See that function for the full policy."""import json@@ -135,6 +138,65 @@ def _write_session_manifest(session):current_app.logger.warning(f"Could not write session manifest for {session.id}: {e}")+def _remove_session_dir(session_id, app=None):+ """Best-effort removal of a session's on-disk chunk directory."""+ logger = (app.logger if app is not None else current_app.logger)+ try:+ dir_path = _session_dir(session_id)+ if os.path.isdir(dir_path):+ shutil.rmtree(dir_path, ignore_errors=True)+ except Exception as e:+ logger.warning(f"Could not remove session dir {session_id}: {e}")+++def _finalize_session_into_stitch(session, *, user_id, title, notes=None,+ resolved_folder_id=None, metadata=None):+ """Create the placeholder Recording, flip the session to ``finalizing``,+ and enqueue the stitch job.++ This is the single code path used by BOTH the user-initiated finalize+ endpoint and the abandoned-session auto-finalize in cleanup, so the two+ behave identically (same Recording shape, same job, same downstream+ transcription kickoff). Returns ``(recording, enqueue_error)`` where+ ``enqueue_error`` is ``None`` on success.+ """+ recording = Recording(+ user_id=user_id,+ title=(title or 'Recording')[:200],+ status='STITCHING',+ notes=notes,+ folder_id=resolved_folder_id,+ processing_source='recording_session',+ mime_type=session.mime_type,+ # Set meeting_date up front (= when recording started) so the+ # sidebar sorts it into the right position the instant it appears,+ # instead of sorting as null until the stitch worker fills it in+ # (which left newly-finalized recordings at the bottom of "Today").+ meeting_date=session.created_at,+ )+ db.session.add(recording)+ db.session.flush()++ session.status = 'finalizing'+ session.finalize_metadata = json.dumps(metadata or {})+ session.finalized_recording_id = recording.id+ session.last_seen_at = datetime.utcnow()+ db.session.commit()++ try:+ job_queue.enqueue(+ user_id=user_id,+ recording_id=recording.id,+ job_type='stitch',+ params={'session_id': session.id},+ is_new_upload=True,+ )+ return recording, None+ except Exception as e:+ current_app.logger.error(f"Could not enqueue stitch job for session {session.id}: {e}")+ return recording, e++# --- Endpoints --------------------------------------------------------------@recording_sessions_bp.route('/upload/session', methods=['POST'])@@ -359,43 +421,26 @@ def finalize_session(session_id):return jsonify({'error': 'No access to target folder'}), 403resolved_folder_id = target.id- recording = Recording(+ # Create the placeholder Recording, flip the session to finalizing, and+ # enqueue the async stitch job — shared with the cleanup auto-finalize+ # path so both behave identically. The worker dispatches to _run_stitch+ # which assembles the audio, writes it into UPLOAD_FOLDER, and enqueues a+ # downstream 'transcribe' job.+ recording, enqueue_error = _finalize_session_into_stitch(+ session,user_id=current_user.id,- title=title[:200],- status='STITCHING',+ title=title,notes=notes,- folder_id=resolved_folder_id,- processing_source='recording_session',- mime_type=session.mime_type,+ resolved_folder_id=resolved_folder_id,+ metadata=metadata,)- db.session.add(recording)- db.session.flush()-- session.status = 'finalizing'- session.finalize_metadata = json.dumps(metadata)- session.finalized_recording_id = recording.id- session.last_seen_at = datetime.utcnow()- db.session.commit()-- # Enqueue the async stitch job. The job-queue worker dispatches to- # _run_stitch which performs the ffmpeg concat, writes the final file- # into UPLOAD_FOLDER, and then enqueues a downstream 'transcribe' job.- try:- job_queue.enqueue(- user_id=current_user.id,- recording_id=recording.id,- job_type='stitch',- params={'session_id': session.id},- is_new_upload=True,- )- except Exception as e:- current_app.logger.error(f"Could not enqueue stitch job for session {session_id}: {e}")+ if enqueue_error is not None:# Leave the session in `finalizing` so the client can retry; the# placeholder recording stays in STITCHING so the user can see it.return jsonify({'recording_id': recording.id,'status': session.status,- 'queue_error': str(e),+ 'queue_error': str(enqueue_error),}), 500return jsonify({@@ -426,12 +471,7 @@ def abort_session(session_id):# Best-effort directory cleanup; if the dir is already gone or the FS# complains, the periodic cleanup job will catch it.- try:- dir_path = _session_dir(session_id)- if os.path.isdir(dir_path):- shutil.rmtree(dir_path, ignore_errors=True)- except Exception as e:- current_app.logger.warning(f"Could not remove session dir for {session_id}: {e}")+ _remove_session_dir(session_id)return ('', 204)@@ -441,9 +481,20 @@ def abort_session(session_id):def cleanup_expired_sessions(app=None):"""Reap sessions whose ``last_seen_at`` is older than the TTL.- Called from APScheduler. Flips status to ``expired`` (so the client- can detect that a resume-on-reload attempt missed the window) before- removing the directory.+ Called from APScheduler. The policy prioritises NOT losing a user's+ audio when they disappear mid-recording (crash, closed laptop, dropped+ connection):++ - ``recording`` with chunks on the books → **auto-finalize**: assemble+ what was uploaded and land it in the user's library (same path as a+ manual finalize), rather than discarding it.+ - ``recording`` with no chunks → expire and delete the empty directory.+ - ``finalizing`` (already has a placeholder recording) but never reached+ a terminal stitch state → **re-enqueue** the stitch to unstick it+ (enqueue dedupes an already-active job). Bumping ``last_seen_at`` here+ naturally rate-limits this to once per TTL window.++ Returns the number of sessions acted on."""if app is None:from flask import current_app as _ca@@ -455,15 +506,52 @@ def cleanup_expired_sessions(app=None):RecordingSession.last_seen_at < cutoff,RecordingSession.status.in_(('recording', 'finalizing')),).all()++ finalized = rekicked = expired = 0for s in candidates:- s.status = 'expired'try:- dir_path = _session_dir(s.id)- if os.path.isdir(dir_path):- shutil.rmtree(dir_path, ignore_errors=True)+ if s.status == 'recording' and (s.chunk_count or 0) > 0:+ when = s.created_at.strftime('%Y-%m-%d %H:%M') if s.created_at else ''+ title = f"Recovered recording {when}".strip()+ _finalize_session_into_stitch(+ s, user_id=s.user_id, title=title,+ metadata={'recovered': True},+ )+ finalized += 1+ app.logger.info(+ f"Auto-finalized abandoned recording session {s.id} "+ f"({s.chunk_count} chunks) for user {s.user_id}"+ )+ elif s.status == 'finalizing' and s.finalized_recording_id:+ s.last_seen_at = datetime.utcnow()+ db.session.commit()+ try:+ job_queue.enqueue(+ user_id=s.user_id,+ recording_id=s.finalized_recording_id,+ job_type='stitch',+ params={'session_id': s.id},+ is_new_upload=True,+ )+ rekicked += 1+ app.logger.info(f"Re-enqueued stitch for stalled session {s.id}")+ except Exception as e:+ app.logger.warning(f"Could not re-enqueue stitch for {s.id}: {e}")+ else:+ # No chunks to save (or finalizing without a recording):+ # nothing recoverable — expire and remove the directory.+ s.status = 'expired'+ db.session.commit()+ _remove_session_dir(s.id, app)+ expired += 1except Exception as e:- app.logger.warning(f"Cleanup could not remove session dir {s.id}: {e}")- if candidates:- db.session.commit()- app.logger.info(f"Reaped {len(candidates)} expired recording session(s)")- return len(candidates)+ app.logger.error(f"Cleanup failed for session {s.id}: {e}", exc_info=True)+ db.session.rollback()++ total = finalized + rekicked + expired+ if total:+ app.logger.info(+ f"Recording-session cleanup: {finalized} auto-finalized, "+ f"{rekicked} re-enqueued, {expired} expired"+ )+ return totaldiff --git a/src/services/job_queue.py b/src/services/job_queue.pyindex a3b5eba8..7710e015 100644--- a/src/services/job_queue.py+++ b/src/services/job_queue.py@@ -26,8 +26,16 @@ SUMMARY_WORKERS = int(os.environ.get('SUMMARY_QUEUE_WORKERS', '2'))MAX_RETRIES = int(os.environ.get('JOB_MAX_RETRIES', '3'))POLL_INTERVAL = 1.0 # seconds between checking for new jobs-# Job type categories-TRANSCRIPTION_JOBS = ['transcribe', 'reprocess_transcription']+# Job type categories.+#+# 'stitch' (server-side recording-session assembly, #287 c/d) lives in the+# transcription category on purpose: it is the local ffmpeg concat step that+# gates the recording's transcription, and putting it here means the existing+# transcription workers claim it, get_queue_status counts it, and+# get_position_in_queue places it — no separate worker pool or queue needed.+# Every consumer routes via "SUMMARY_JOBS if ... else TRANSCRIPTION_JOBS", so+# membership in this list is the single source of truth for the whole pipeline.+TRANSCRIPTION_JOBS = ['transcribe', 'reprocess_transcription', 'stitch']SUMMARY_JOBS = ['summarize', 'reprocess_summary']@@ -731,6 +739,14 @@ class FairJobQueue:'summarize': 'recording.summary.failed','reprocess_transcription': 'recording.transcription.failed','reprocess_summary': 'recording.summary.failed',+ # A permanent stitch failure means the recording will never reach+ # transcription, so subscribers should hear about it under the+ # transcription.failed event (the follow-up transcribe job that would+ # normally emit this is never enqueued on a stitch failure, so there+ # is no double-emit). Stitch deliberately has NO started/completed+ # mapping: those fire from the real transcribe job after a successful+ # stitch.+ 'stitch': 'recording.transcription.failed',}# No `summary.started` in the vocabulary today; if one is added later,diff --git a/src/services/recording_stitch.py b/src/services/recording_stitch.pyindex 37678d15..25d815a2 100644--- a/src/services/recording_stitch.py+++ b/src/services/recording_stitch.py@@ -4,13 +4,29 @@ The :func:`stitch_recording_session` function is called from the``stitch`` job_queue dispatch. It1. Reads the session row + on-disk chunks.-2. Builds an ffmpeg concat-demux input file listing the chunks in order.-3. Runs ``ffmpeg -f concat -safe 0 -i list.txt -c copy <out>`` to assemble- the final audio file. Stream-copy keeps the codec parameters intact- and avoids re-encoding; the concat demuxer correctly handles- pause/resume across MediaRecorder restarts (where each restart- produces a fresh container header, which a naive ``cat`` would- corrupt).+2. Partitions the chunks into *segments*. A segment is the output of one+ continuous ``MediaRecorder`` instance: its first chunk carries the+ container initialization header (WebM/Matroska EBML, or fMP4 ftyp) and+ every later chunk is a headerless continuation. A normal recording is a+ single segment; a recording that was resumed after a page reload (a new+ MediaRecorder appended to the same session) has one segment per+ MediaRecorder. Segment boundaries are detected from the bytes+ themselves (header magic at a chunk's start), so no client-side+ bookkeeping or schema change is required.+3. Assembles the audio:+ - WITHIN a segment, the chunks are **byte-joined** (raw concatenation in+ index order). This is the correct reassembly for MediaRecorder+ timeslice fragments — only the first fragment has a header, so the+ joined stream is a valid container. (Feeding the fragments to ffmpeg's+ concat *demuxer* instead would decode only the first headered fragment+ and silently drop the rest — the bug this design replaces.)+ - ACROSS segments (resume case only), the per-segment byte-joined files+ are each independently valid, so they are combined with ffmpeg's+ concat demuxer ``-c copy`` — the right tool at this granularity.+ - A single-segment recording is finished with a stream-copy remux pass+ so the output gets a seekable container with proper duration metadata+ (raw MediaRecorder output is "live": no SeekHead/Cues, unknown+ duration, which trips players, the duration probe, and some ASR).4. Moves the stitched file into UPLOAD_FOLDER with a deterministic name.5. Updates the placeholder Recording row with the resulting path, size,and a status transition to PENDING (so the downstream transcribe job@@ -75,52 +91,132 @@ def _mime_to_extension(mime_type: str) -> str:return mapping.get((mime_type or '').lower(), 'webm')-def _run_ffmpeg_concat(chunk_paths: list, output_path: str, mime_type: str) -> None:- """Stream-copy concat via ffmpeg's concat demuxer.+# Container initialization-segment signatures. A chunk that STARTS a fresh+# MediaRecorder stream begins with one of these; a timeslice continuation+# chunk does not. Ogg/WAV are intentionally absent: Ogg pages all start with+# 'OggS' (so it can't delimit segments) but Ogg is self-framing and chains+# losslessly under a plain byte-join, and WAV is single-shot — both are+# handled correctly as one byte-joined segment.+_WEBM_EBML_MAGIC = b'\x1a\x45\xdf\xa3' # Matroska/WebM EBML header, offset 0+_MP4_FTYP_MAGIC = b'ftyp' # ISO-BMFF ftyp box type, offset 4- The concat demuxer reads a text manifest and assembles container- elements correctly across restart boundaries. Stream-copy (``-c copy``)- avoids re-encoding so this is fast even on long recordings.- """- if not chunk_paths:- raise StitchError('no chunks to stitch')- # Write the manifest next to the output file.- manifest_path = output_path + '.concat.txt'+def _chunk_starts_segment(chunk_path: str) -> bool:+ """True if this chunk begins a new container (a fresh MediaRecorder)."""+ try:+ with open(chunk_path, 'rb') as f:+ head = f.read(12)+ except OSError:+ return False+ return head[0:4] == _WEBM_EBML_MAGIC or head[4:8] == _MP4_FTYP_MAGIC+++def _partition_into_segments(chunk_paths: list) -> list:+ """Group ordered chunk paths into segments by header detection.++ Returns a list of lists; each inner list is the chunks of one segment in+ order. The first chunk always opens a segment; later chunks open a new+ segment only when they carry a container header (i.e. a resumed+ recording started a new MediaRecorder)."""+ segments = []+ for i, p in enumerate(chunk_paths):+ if i == 0 or _chunk_starts_segment(p):+ segments.append([p])+ else:+ segments[-1].append(p)+ return segments+++def _byte_join(chunk_paths: list, output_path: str) -> None:+ """Raw byte concatenation in order, streamed for flat memory use."""+ with open(output_path, 'wb') as out:+ for p in chunk_paths:+ with open(p, 'rb') as src:+ shutil.copyfileobj(src, out, length=1024 * 1024)+++def _remux_copy(src_path: str, output_path: str) -> None:+ """Stream-copy remux ``src`` → ``output`` for a seekable container with+ duration metadata. On any ffmpeg problem, fall back to using the raw+ byte-joined stream directly (it is already valid audio) rather than+ losing the recording — logged loudly so it can be investigated."""+ cmd = [+ 'ffmpeg', '-hide_banner', '-loglevel', 'error', '-y',+ '-i', src_path, '-c', 'copy', output_path,+ ]+ try:+ result = subprocess.run(cmd, capture_output=True, timeout=600)+ except FileNotFoundError:+ logger.warning("ffmpeg not found; using raw byte-joined stream without remux")+ os.replace(src_path, output_path)+ return+ except subprocess.TimeoutExpired:+ raise StitchError('ffmpeg remux timed out after 10 minutes')+ if result.returncode != 0:+ stderr = (result.stderr.decode('utf-8', errors='replace') or '').strip()+ logger.warning(+ f"Remux failed (exit {result.returncode}): {stderr[:300]}; "+ "falling back to raw byte-joined stream"+ )+ os.replace(src_path, output_path)+++def _concat_demux(segment_files: list, output_path: str, work_dir: str) -> None:+ """Combine multiple independently-valid segment files via ffmpeg's+ concat demuxer (the correct tool once each input is a complete+ container). Used only for resumed recordings (>1 segment)."""+ manifest_path = os.path.join(work_dir, 'segments.concat.txt')+ with open(manifest_path, 'w') as f:+ for p in segment_files:+ safe = p.replace("'", "'\\''")+ f.write(f"file '{safe}'\n")+ cmd = [+ 'ffmpeg', '-hide_banner', '-loglevel', 'error', '-y',+ '-f', 'concat', '-safe', '0', '-i', manifest_path,+ '-c', 'copy', output_path,+ ]try:- with open(manifest_path, 'w') as f:- for p in chunk_paths:- # The concat demuxer requires the directive prefix; we- # quote single quotes inside paths defensively.- safe = p.replace("'", "'\\''")- f.write(f"file '{safe}'\n")-- cmd = [- 'ffmpeg',- '-hide_banner', '-loglevel', 'error',- '-y',- '-f', 'concat',- '-safe', '0',- '-i', manifest_path,- '-c', 'copy',- output_path,- ]- logger.info(f"Running ffmpeg concat with {len(chunk_paths)} chunks → {output_path}")result = subprocess.run(cmd, capture_output=True, timeout=600)- if result.returncode != 0:- stderr = (result.stderr.decode('utf-8', errors='replace') or '').strip()- raise StitchError(f'ffmpeg concat failed (exit {result.returncode}): {stderr[:500]}')except FileNotFoundError:raise StitchError('ffmpeg binary not found on server PATH')except subprocess.TimeoutExpired:- raise StitchError('ffmpeg concat timed out after 10 minutes')+ raise StitchError('ffmpeg segment concat timed out after 10 minutes')+ if result.returncode != 0:+ stderr = (result.stderr.decode('utf-8', errors='replace') or '').strip()+ raise StitchError(f'ffmpeg segment concat failed (exit {result.returncode}): {stderr[:500]}')+++def _assemble_session_audio(chunk_paths: list, output_path: str, mime_type: str) -> None:+ """Assemble MediaRecorder chunks into one playable file.++ Byte-joins within each detected segment, then either remuxes the single+ segment or concat-demuxes multiple segments (resume case). See the module+ docstring for the rationale.+ """+ if not chunk_paths:+ raise StitchError('no chunks to stitch')++ segments = _partition_into_segments(chunk_paths)+ work_dir = output_path + '.parts'+ os.makedirs(work_dir, exist_ok=True)+ try:+ segment_files = []+ for i, seg_chunks in enumerate(segments):+ seg_path = os.path.join(work_dir, f'segment-{i:04d}.bin')+ _byte_join(seg_chunks, seg_path)+ segment_files.append(seg_path)++ if len(segment_files) == 1:+ logger.info(f"Assembling {len(chunk_paths)} chunks (1 segment) → byte-join + remux → {output_path}")+ _remux_copy(segment_files[0], output_path)+ else:+ logger.info(+ f"Assembling {len(chunk_paths)} chunks across {len(segment_files)} segments "+ f"(resume detected) → byte-join per segment + concat → {output_path}"+ )+ _concat_demux(segment_files, output_path, work_dir)finally:- # Clean up the manifest regardless of outcome.- try:- if os.path.exists(manifest_path):- os.remove(manifest_path)- except OSError:- pass+ shutil.rmtree(work_dir, ignore_errors=True)def stitch_recording_session(session_id: str) -> Tuple[int, str]:@@ -154,7 +250,7 @@ def stitch_recording_session(session_id: str) -> Tuple[int, str]:final_filename = f'{timestamp}_recording-{session_id[:8]}.{extension}'final_path = os.path.join(upload_folder, final_filename)- _run_ffmpeg_concat(chunk_paths, final_path, session.mime_type)+ _assemble_session_audio(chunk_paths, final_path, session.mime_type)file_size = os.path.getsize(final_path)@@ -183,8 +279,25 @@ def stitch_recording_session(session_id: str) -> Tuple[int, str]:'been killed mid-write or run out of disk space')- # Update the recording row in place. We don't change the title - the- # finalize endpoint set it.+ # Parse the user's finalize metadata up front: it drives both the title+ # and the downstream transcribe-job options (tags, ASR settings, etc.).+ metadata = {}+ if session.finalize_metadata:+ try:+ metadata = json.loads(session.finalize_metadata) or {}+ except json.JSONDecodeError:+ metadata = {}++ # Update the recording row in place. Resolve the title through the SAME+ # shared helper as drag-drop upload and the PWA share target+ # (src/utils/titles.py): a real user-supplied title is kept, otherwise we+ # set a recognised placeholder so generate_title_task gives it an AI+ # title — instead of a fabricated default being mistaken for a user+ # choice and AI titling getting skipped (the same class of bug fixed for+ # the share target in 482614c).+ from src.utils.titles import resolve_upload_title+ user_title = (metadata.get('title') or '').strip()+ recording.title = resolve_upload_title(user_title, final_filename)recording.audio_path = final_pathrecording.original_filename = final_filenamerecording.file_size = file_size@@ -204,16 +317,9 @@ def stitch_recording_session(session_id: str) -> Tuple[int, str]:except Exception as e:logger.warning(f"Could not remove session dir for {session_id}: {e}")- # Parse the user's finalize metadata so the downstream transcribe job- # picks up tags, ASR options, hotwords, etc. as if they had been on a- # regular upload form.- metadata = {}- if session.finalize_metadata:- try:- metadata = json.loads(session.finalize_metadata) or {}- except json.JSONDecodeError:- metadata = {}-+ # metadata (parsed above) carries tags, ASR options, hotwords, etc. for+ # the downstream transcribe job, as if they had been on a normal upload+ # form.return recording.id, final_path, metadatadiff --git a/tests/test_recording_sessions.py b/tests/test_recording_sessions.pyindex a279e3fd..c3dd1705 100644--- a/tests/test_recording_sessions.py+++ b/tests/test_recording_sessions.py@@ -390,50 +390,106 @@ def test_ownership_enforced_other_user_gets_404():shutil.rmtree(upload_folder, ignore_errors=True)-def test_cleanup_reaps_expired_sessions():+def test_cleanup_auto_finalizes_with_chunks_expires_empty_and_rekicks_stalled():+ """Cleanup policy (#287 unification):+ - stale 'recording' WITH chunks → auto-finalize (don't lose audio)+ - stale 'recording' WITHOUT chunks → expire + delete dir+ - stale 'finalizing' (has a recording) → re-enqueue stitch to unstick+ - fresh session → untouched++ job_queue.enqueue is patched so the async stitch worker never starts;+ we assert on the synchronous decisions cleanup makes.+ """upload_folder = _make_tmp_upload_folder()from src.api.recording_sessions import cleanup_expired_sessions+ from src.services.job_queue import job_queue+ old = datetime.utcnow() - timedelta(hours=48)++ enqueued = []++ def _fake_enqueue(**kw):+ enqueued.append(kw)+ return 999+with app.app_context():app.config["UPLOAD_FOLDER"] = upload_folderuser = _setup_user("sess_expire")- # Plant a stale session (last_seen_at well in the past)- stale = RecordingSession(- user_id=user.id,- mime_type="audio/webm",- status="recording",- chunk_count=1,- bytes_received=128,- )- db.session.add(stale)++ # stale recording WITH chunks → auto-finalize+ with_chunks = RecordingSession(user_id=user.id, mime_type="audio/webm",+ status="recording", chunk_count=3, bytes_received=512)+ db.session.add(with_chunks)db.session.flush()- stale.last_seen_at = datetime.utcnow() - timedelta(hours=48)- # Plant a fresh session- fresh = RecordingSession(- user_id=user.id,- mime_type="audio/webm",- status="recording",- chunk_count=1,- bytes_received=128,- )+ with_chunks.last_seen_at = old++ # stale recording WITHOUT chunks → expire+ empty = RecordingSession(user_id=user.id, mime_type="audio/webm",+ status="recording", chunk_count=0, bytes_received=0)+ db.session.add(empty)+ db.session.flush()+ empty.last_seen_at = old++ # stale finalizing (already has a placeholder recording) → re-enqueue+ stalled_rec = Recording(user_id=user.id, title="stalled", status="STITCHING",+ processing_source="recording_session", mime_type="audio/webm")+ db.session.add(stalled_rec)+ db.session.flush()+ stalled = RecordingSession(user_id=user.id, mime_type="audio/webm",+ status="finalizing", chunk_count=2, bytes_received=256,+ finalized_recording_id=stalled_rec.id)+ db.session.add(stalled)+ db.session.flush()+ stalled.last_seen_at = old++ # fresh recording → untouched+ fresh = RecordingSession(user_id=user.id, mime_type="audio/webm",+ status="recording", chunk_count=1, bytes_received=128)db.session.add(fresh)db.session.flush()- # Plant their dirs so cleanup can remove them- stale_dir = os.path.join(upload_folder, "_sessions", stale.id)- fresh_dir = os.path.join(upload_folder, "_sessions", fresh.id)- os.makedirs(stale_dir, exist_ok=True)- os.makedirs(fresh_dir, exist_ok=True)- db.session.commit()- reaped = cleanup_expired_sessions(app=app)- assert reaped == 1- assert db.session.get(RecordingSession, stale.id).status == "expired"+ for s in (with_chunks, empty, stalled, fresh):+ os.makedirs(os.path.join(upload_folder, "_sessions", s.id), exist_ok=True)+ db.session.commit()+ with_chunks_dir = os.path.join(upload_folder, "_sessions", with_chunks.id)+ empty_dir = os.path.join(upload_folder, "_sessions", empty.id)++ with patch.object(job_queue, "enqueue", _fake_enqueue):+ reaped = cleanup_expired_sessions(app=app)++ # cleanup committed on its own nested-app-context session; drop the+ # outer session's identity-map cache so our reads hit the DB.+ db.session.expire_all()++ assert reaped == 3 # auto-finalize + expire + re-enqueue (fresh untouched)++ # WITH chunks → finalizing, recording created, dir kept (stitch owns it)+ wc = db.session.get(RecordingSession, with_chunks.id)+ assert wc.status == "finalizing"+ assert wc.finalized_recording_id is not None+ assert os.path.isdir(with_chunks_dir)+ assert any(c.get("job_type") == "stitch" and c.get("recording_id") == wc.finalized_recording_id+ for c in enqueued)++ # EMPTY → expired, dir removed+ em = db.session.get(RecordingSession, empty.id)+ assert em.status == "expired"+ assert not os.path.isdir(empty_dir)++ # STALLED finalizing → stitch re-enqueued for its recording, last_seen bumped+ st = db.session.get(RecordingSession, stalled.id)+ assert st.status == "finalizing"+ assert st.last_seen_at > old+ assert any(c.get("job_type") == "stitch" and c.get("recording_id") == stalled_rec.id+ for c in enqueued)++ # FRESH → untouchedassert db.session.get(RecordingSession, fresh.id).status == "recording"- assert not os.path.isdir(stale_dir)- assert os.path.isdir(fresh_dir)- # Cleanup- db.session.delete(db.session.get(RecordingSession, stale.id))- db.session.delete(db.session.get(RecordingSession, fresh.id))+ # Cleanup (including the placeholder Recording auto-finalize created)+ for s in RecordingSession.query.filter_by(user_id=user.id).all():+ db.session.delete(s)+ for r in Recording.query.filter_by(user_id=user.id).all():+ db.session.delete(r)db.session.delete(user)db.session.commit()shutil.rmtree(upload_folder, ignore_errors=True)@@ -474,5 +530,5 @@ if __name__ == "__main__":test_finalize_rejects_when_no_chunks()test_abort_removes_session_dir()test_ownership_enforced_other_user_gets_404()- test_cleanup_reaps_expired_sessions()+ test_cleanup_auto_finalizes_with_chunks_expires_empty_and_rekicks_stalled()print("All recording-session tests passed.")diff --git a/tests/test_recording_stitch.py b/tests/test_recording_stitch.pyindex 036d979c..2521cd7d 100644--- a/tests/test_recording_stitch.py+++ b/tests/test_recording_stitch.py@@ -1,20 +1,26 @@"""Tests for the recording-stitch worker (#287 c/d).-Exercises the real ffmpeg concat-demux path (no mocking) on synthetic-audio. The container ships ffmpeg, so the end-to-end stitch is verified-by:--1. Generating two short sine-wave WAV chunks via ffmpeg.-2. Planting them as chunks in a real session dir.-3. Calling ``stitch_recording_session`` and checking the output file is- playable + roughly the expected duration.--We use WAV instead of webm so we can deterministically generate inputs-without depending on a browser to produce the matroska clusters that-real MediaRecorder chunks have. The ``concat`` demuxer logic is-container-agnostic.+Exercises the REAL assembly path (no mocking) on synthetic audio that+faithfully mirrors how a browser ``MediaRecorder`` emits data:++ - A continuous recording is one container whose FIRST timeslice chunk+ carries the init header and whose later chunks are headerless+ continuations. We simulate this by generating a real WebM/Opus file+ and byte-splitting it into fragments (only fragment 0 keeps the+ header) — exactly the shape real chunks have.+ - A recording that was resumed after a page reload is multiple complete+ containers (one per MediaRecorder), which we simulate with two whole+ WebM files planted as two chunks.++The earlier version of this test planted two *complete* WAV files as+chunks and fed them to ffmpeg's concat demuxer. That shape is unrealistic+(real timeslice chunks are NOT independently-valid files) and it masked a+bug where the demuxer decoded only the first headered chunk and silently+dropped the rest. These tests use realistic fixtures so that regression+cannot reappear unnoticed."""+import jsonimport osimport shutilimport subprocess@@ -22,6 +28,8 @@ import sysimport tempfileimport uuid+import pytest+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))from src.app import app, db@@ -31,32 +39,66 @@ from src.services.recording_stitch import (StitchError,_chunk_paths,_mime_to_extension,+ _chunk_starts_segment,+ _partition_into_segments,+ _WEBM_EBML_MAGIC,)app.config["WTF_CSRF_ENABLED"] = False-def _generate_wav(path, duration_seconds=1, freq_hz=440):- """Generate a short sine-wave WAV via ffmpeg. Used as chunk fodder.+def _have_webm_encoder():+ """True if this ffmpeg build can mux WebM/Opus (it can in CI + the app+ image; guard defensively so a minimal build skips rather than fails)."""+ try:+ r = subprocess.run(+ ['ffmpeg', '-hide_banner', '-loglevel', 'error', '-y',+ '-f', 'lavfi', '-i', 'sine=frequency=440:duration=1',+ '-ac', '1', '-ar', '48000', '-c:a', 'libopus', '-f', 'webm',+ os.path.join(tempfile.gettempdir(), f'_webmprobe_{uuid.uuid4().hex}.webm')],+ capture_output=True,+ )+ return r.returncode == 0+ except FileNotFoundError:+ return False+++_WEBM_OK = _have_webm_encoder()+_needs_webm = pytest.mark.skipif(not _WEBM_OK, reason="ffmpeg build lacks WebM/Opus encoder")+- We force the output format with -f wav because the chunk files use- a generic .bin extension (matching the streaming-client convention),- so ffmpeg would otherwise refuse to pick a muxer by guessing.- """+def _generate_webm(path, duration_seconds=3, freq_hz=440):+ """Write a real WebM/Opus file — a stand-in for one MediaRecorder run."""cmd = ['ffmpeg', '-hide_banner', '-loglevel', 'error', '-y',- '-f', 'lavfi',- '-i', f'sine=frequency={freq_hz}:duration={duration_seconds}',- '-ac', '1', '-ar', '16000',- '-f', 'wav',+ '-f', 'lavfi', '-i', f'sine=frequency={freq_hz}:duration={duration_seconds}',+ '-ac', '1', '-ar', '48000', '-c:a', 'libopus', '-f', 'webm',path,]subprocess.run(cmd, check=True)+def _split_into_chunks(src_path, sess_dir, n_parts, start_index=1):+ """Byte-split ``src_path`` into ``n_parts`` chunk-NNNNNN.bin fragments in+ ``sess_dir`` (continuing from ``start_index``). This reproduces+ MediaRecorder timeslice output: only the first fragment of the file holds+ the container header. Returns the next free chunk index."""+ with open(src_path, 'rb') as f:+ data = f.read()+ size = len(data)+ step = size // n_parts+ idx = start_index+ for i in range(n_parts):+ lo = i * step+ hi = size if i == n_parts - 1 else (i + 1) * step+ with open(os.path.join(sess_dir, f'chunk-{idx:06d}.bin'), 'wb') as out:+ out.write(data[lo:hi])+ idx += 1+ return idx++def _probe_duration(path):- """Return audio duration in seconds via ffprobe."""cmd = ['ffprobe', '-hide_banner', '-loglevel', 'error','-show_entries', 'format=duration',@@ -79,11 +121,41 @@ def _make_user():return user+def _plant_session(upload_folder, user, mime_type='audio/webm', chunk_count=1):+ """Create the placeholder Recording + RecordingSession the way+ finalize_session does, and return (recording, session, sess_dir)."""+ recording = Recording(+ user_id=user.id,+ title="Stitch test",+ status='STITCHING',+ mime_type=mime_type,+ processing_source='recording_session',+ )+ db.session.add(recording)+ db.session.flush()+ session = RecordingSession(+ user_id=user.id,+ mime_type=mime_type,+ status='finalizing',+ chunk_count=chunk_count,+ bytes_received=12345,+ finalized_recording_id=recording.id,+ )+ db.session.add(session)+ db.session.commit()+ sess_dir = os.path.join(upload_folder, "_sessions", session.id)+ os.makedirs(sess_dir, exist_ok=True)+ return recording, session, sess_dir+++# --------------------------------------------------------------------------+# Pure unit tests for segment detection (codec-free, always run)+# --------------------------------------------------------------------------+def test_mime_to_extension_maps_known_types():assert _mime_to_extension('audio/webm') == 'webm'assert _mime_to_extension('audio/mp4') == 'm4a'assert _mime_to_extension('audio/ogg') == 'ogg'- # Unknown → webm fallback (matches MediaRecorder default)assert _mime_to_extension('audio/whatever') == 'webm'assert _mime_to_extension('') == 'webm'@@ -91,16 +163,13 @@ def test_mime_to_extension_maps_known_types():def test_chunk_paths_returns_sorted_chunks():tmp = tempfile.mkdtemp(prefix="speakr-stitch-")try:- # Plant chunks out of name orderfor name in ('chunk-000003.bin', 'chunk-000001.bin', 'chunk-000002.bin'):with open(os.path.join(tmp, name), 'wb') as f:f.write(b'.')- # Plant some garbage that should NOT be picked upwith open(os.path.join(tmp, 'session.json'), 'wb') as f:f.write(b'{}')with open(os.path.join(tmp, 'chunk-bad.txt'), 'wb') as f:f.write(b'.')-paths = _chunk_paths(tmp)assert [os.path.basename(p) for p in paths] == ['chunk-000001.bin', 'chunk-000002.bin', 'chunk-000003.bin']finally:@@ -115,69 +184,125 @@ def test_chunk_paths_empty_dir_returns_empty_list():shutil.rmtree(tmp, ignore_errors=True)-def test_stitch_session_concatenates_two_wav_chunks_end_to_end():- """Plant two real WAV chunks; stitch produces a playable, ~2s WAV."""+def _write(tmp, name, data):+ p = os.path.join(tmp, name)+ with open(p, 'wb') as f:+ f.write(data)+ return p+++def test_chunk_starts_segment_detects_webm_and_mp4_headers():+ tmp = tempfile.mkdtemp(prefix="speakr-seg-")+ try:+ webm = _write(tmp, 'a.bin', _WEBM_EBML_MAGIC + b'\x00' * 32)+ mp4 = _write(tmp, 'b.bin', b'\x00\x00\x00\x20ftypiso5' + b'\x00' * 16)+ cont = _write(tmp, 'c.bin', b'\x6e\x79\x20\x01raw cluster continuation')+ assert _chunk_starts_segment(webm) is True+ assert _chunk_starts_segment(mp4) is True+ assert _chunk_starts_segment(cont) is False+ finally:+ shutil.rmtree(tmp, ignore_errors=True)+++def test_partition_single_segment_when_only_first_chunk_has_header():+ """The common case: one continuous recording. Only chunk 1 has a header,+ so everything collapses into a single segment (→ byte-join path)."""+ tmp = tempfile.mkdtemp(prefix="speakr-seg1-")+ try:+ c1 = _write(tmp, 'chunk-000001.bin', _WEBM_EBML_MAGIC + b'header+clusters')+ c2 = _write(tmp, 'chunk-000002.bin', b'\x99\xec\xb8\x72 continuation A')+ c3 = _write(tmp, 'chunk-000003.bin', b'\x4f\xb1\x7d\xb1 continuation B')+ segments = _partition_into_segments([c1, c2, c3])+ assert len(segments) == 1+ assert segments[0] == [c1, c2, c3]+ finally:+ shutil.rmtree(tmp, ignore_errors=True)+++def test_partition_starts_new_segment_on_each_header():+ """Resume case: a second header (a fresh MediaRecorder) opens a new+ segment, and its own continuations attach to it."""+ tmp = tempfile.mkdtemp(prefix="speakr-seg2-")+ try:+ c1 = _write(tmp, 'chunk-000001.bin', _WEBM_EBML_MAGIC + b'seg1 header')+ c2 = _write(tmp, 'chunk-000002.bin', b'\x99\xec\xb8\x72 seg1 cont')+ c3 = _write(tmp, 'chunk-000003.bin', _WEBM_EBML_MAGIC + b'seg2 header')+ c4 = _write(tmp, 'chunk-000004.bin', b'\x4f\xb1\x7d\xb1 seg2 cont')+ segments = _partition_into_segments([c1, c2, c3, c4])+ assert segments == [[c1, c2], [c3, c4]]+ finally:+ shutil.rmtree(tmp, ignore_errors=True)+++# --------------------------------------------------------------------------+# End-to-end stitch tests on realistic WebM fixtures (skip if no encoder)+# --------------------------------------------------------------------------++@_needs_webm+def test_stitch_single_segment_preserves_full_duration_end_to_end():+ """A 6s recording delivered as 4 byte-fragments (only the first carries+ the header) must stitch to ~6s. This is the regression guard: the old+ concat-demuxer produced ~1.5s here by dropping fragments 2-4."""upload_folder = tempfile.mkdtemp(prefix="speakr-stitch-uploads-")with app.app_context():app.config["UPLOAD_FOLDER"] = upload_folderuser = _make_user()+ recording, session, sess_dir = _plant_session(upload_folder, user, 'audio/webm', chunk_count=4)- # Pre-create the placeholder Recording row, the way finalize_session does.- recording = Recording(- user_id=user.id,- title="Stitch test",- status='STITCHING',- mime_type='audio/wav',- processing_source='recording_session',- )- db.session.add(recording)- db.session.flush()-- # Create the session row, pointing at the placeholder recording.- session = RecordingSession(- user_id=user.id,- mime_type='audio/wav',- status='finalizing',- chunk_count=2,- bytes_received=12345,- finalized_recording_id=recording.id,- )- db.session.add(session)- db.session.commit()-- sess_dir = os.path.join(upload_folder, "_sessions", session.id)- os.makedirs(sess_dir, exist_ok=True)- chunk_a = os.path.join(sess_dir, 'chunk-000001.bin')- chunk_b = os.path.join(sess_dir, 'chunk-000002.bin')- _generate_wav(chunk_a, duration_seconds=1, freq_hz=440)- _generate_wav(chunk_b, duration_seconds=1, freq_hz=660)+ src = os.path.join(upload_folder, 'src.webm')+ _generate_webm(src, duration_seconds=6, freq_hz=440)+ _split_into_chunks(src, sess_dir, n_parts=4)+ os.remove(src)recording_id, audio_path, metadata = stitch_recording_session(session.id)- # Output file exists and is playableassert os.path.exists(audio_path)duration = _probe_duration(audio_path)- # Two 1-second chunks → roughly 2s total (ffmpeg may round a hair).- assert 1.8 <= duration <= 2.2, f"unexpected duration {duration}"+ assert 5.5 <= duration <= 6.5, f"expected ~6s, got {duration} (chunks were dropped?)"- # Recording row was updated in placerec = db.session.get(Recording, recording_id)assert rec.status == 'PENDING'assert rec.audio_path == audio_pathassert rec.file_size and rec.file_size > 0assert rec.original_filename- # Session was marked finalized and its dir was removedsess = db.session.get(RecordingSession, session.id)assert sess.status == 'finalized'assert sess.finalized_at is not Noneassert not os.path.isdir(sess_dir)- # Cleanup- try:- os.remove(audio_path)- except OSError:- pass+ os.remove(audio_path)+ db.session.delete(sess)+ db.session.delete(rec)+ db.session.delete(user)+ db.session.commit()+ shutil.rmtree(upload_folder, ignore_errors=True)+++@_needs_webm+def test_stitch_multi_segment_resume_sums_durations_end_to_end():+ """A resumed recording is two complete containers (3s + 4s) planted as+ two chunks; assembly must concat across segments to ~7s."""+ upload_folder = tempfile.mkdtemp(prefix="speakr-stitch-resume-")+ with app.app_context():+ app.config["UPLOAD_FOLDER"] = upload_folder+ user = _make_user()+ recording, session, sess_dir = _plant_session(upload_folder, user, 'audio/webm', chunk_count=2)++ seg1 = os.path.join(sess_dir, 'chunk-000001.bin')+ seg2 = os.path.join(sess_dir, 'chunk-000002.bin')+ _generate_webm(seg1, duration_seconds=3, freq_hz=440)+ _generate_webm(seg2, duration_seconds=4, freq_hz=660)++ recording_id, audio_path, metadata = stitch_recording_session(session.id)++ assert os.path.exists(audio_path)+ duration = _probe_duration(audio_path)+ assert 6.3 <= duration <= 7.7, f"expected ~7s across two segments, got {duration}"++ os.remove(audio_path)+ rec = db.session.get(Recording, recording_id)+ sess = db.session.get(RecordingSession, session.id)db.session.delete(sess)db.session.delete(rec)db.session.delete(user)@@ -185,29 +310,70 @@ def test_stitch_session_concatenates_two_wav_chunks_end_to_end():shutil.rmtree(upload_folder, ignore_errors=True)+@_needs_webm+def test_stitch_with_no_user_title_sets_recognised_placeholder():+ """An in-app recording carries no user title, so the stitched recording+ must get a placeholder that is_placeholder_title recognises — otherwise+ generate_title_task would skip AI titling (the reported bug)."""+ from src.utils.titles import is_placeholder_title+ upload_folder = tempfile.mkdtemp(prefix="speakr-stitch-title-")+ with app.app_context():+ app.config["UPLOAD_FOLDER"] = upload_folder+ user = _make_user()+ recording, session, sess_dir = _plant_session(upload_folder, user, 'audio/webm', chunk_count=1)+ session.finalize_metadata = json.dumps({"notes": "n", "tags": []}) # no title+ db.session.commit()+ _generate_webm(os.path.join(sess_dir, 'chunk-000001.bin'), duration_seconds=2)++ recording_id, audio_path, metadata = stitch_recording_session(session.id)++ rec = db.session.get(Recording, recording_id)+ assert is_placeholder_title(rec.title, rec.original_filename) is True, \+ f"title {rec.title!r} would block AI titling"++ os.remove(audio_path)+ db.session.delete(db.session.get(RecordingSession, session.id))+ db.session.delete(rec)+ db.session.delete(user)+ db.session.commit()+ shutil.rmtree(upload_folder, ignore_errors=True)+++@_needs_webm+def test_stitch_preserves_a_real_user_title():+ """If the user did supply a title, the shared resolver keeps it (and AI+ titling leaves it alone)."""+ from src.utils.titles import is_placeholder_title+ upload_folder = tempfile.mkdtemp(prefix="speakr-stitch-utitle-")+ with app.app_context():+ app.config["UPLOAD_FOLDER"] = upload_folder+ user = _make_user()+ recording, session, sess_dir = _plant_session(upload_folder, user, 'audio/webm', chunk_count=1)+ session.finalize_metadata = json.dumps({"title": "Q3 Planning Sync"})+ db.session.commit()+ _generate_webm(os.path.join(sess_dir, 'chunk-000001.bin'), duration_seconds=2)++ recording_id, audio_path, metadata = stitch_recording_session(session.id)++ rec = db.session.get(Recording, recording_id)+ assert rec.title == "Q3 Planning Sync"+ assert is_placeholder_title(rec.title, rec.original_filename) is False++ os.remove(audio_path)+ db.session.delete(db.session.get(RecordingSession, session.id))+ db.session.delete(rec)+ db.session.delete(user)+ db.session.commit()+ shutil.rmtree(upload_folder, ignore_errors=True)++def test_stitch_raises_when_no_chunks_on_disk():upload_folder = tempfile.mkdtemp(prefix="speakr-stitch-nochunks-")with app.app_context():app.config["UPLOAD_FOLDER"] = upload_folderuser = _make_user()- recording = Recording(- user_id=user.id,- title="No chunks",- status='STITCHING',- mime_type='audio/webm',- processing_source='recording_session',- )- db.session.add(recording)- db.session.flush()- session = RecordingSession(- user_id=user.id,- mime_type='audio/webm',- status='finalizing',- chunk_count=0,- finalized_recording_id=recording.id,- )- db.session.add(session)- db.session.commit()+ recording, session, sess_dir = _plant_session(upload_folder, user, 'audio/webm', chunk_count=0)+ shutil.rmtree(sess_dir, ignore_errors=True) # no chunks on disktry:stitch_recording_session(session.id)@@ -235,7 +401,6 @@ _ORIGINAL_UPLOAD_FOLDER = app.config.get("UPLOAD_FOLDER")def setup_function(function): # noqa: D401 - pytest hook- """Restore UPLOAD_FOLDER before each test in case a prior one mutated it."""if _ORIGINAL_UPLOAD_FOLDER is not None:app.config["UPLOAD_FOLDER"] = _ORIGINAL_UPLOAD_FOLDER@@ -267,7 +432,14 @@ if __name__ == "__main__":test_mime_to_extension_maps_known_types()test_chunk_paths_returns_sorted_chunks()test_chunk_paths_empty_dir_returns_empty_list()- test_stitch_session_concatenates_two_wav_chunks_end_to_end()+ test_chunk_starts_segment_detects_webm_and_mp4_headers()+ test_partition_single_segment_when_only_first_chunk_has_header()+ test_partition_starts_new_segment_on_each_header()+ if _WEBM_OK:+ test_stitch_single_segment_preserves_full_duration_end_to_end()+ test_stitch_multi_segment_resume_sums_durations_end_to_end()+ else:+ print("(skipping WebM end-to-end tests: no encoder)")test_stitch_raises_when_no_chunks_on_disk()test_stitch_raises_when_session_missing()print("All stitch tests passed.")