Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
Phase A: server-side recording-session backend with async ffmpeg stitch (#287 c/d)
Murtaza Nasir033ad583d58c
diff --git a/src/api/recording_sessions.py b/src/api/recording_sessions.pynew file mode 100644index 00000000..0a758ba6--- /dev/null+++ b/src/api/recording_sessions.py@@ -0,0 +1,413 @@+"""Recording-session endpoints for server-side chunk streaming.++Backend half of issue #287 (c)(d): instead of accumulating the entire+audio blob in the browser until the user clicks Upload, the in-app+recorder POSTs MediaRecorder chunks to the server as they are produced.++Endpoints+---------++::++ POST /upload/session create+ POST /upload/session/<sid>/chunks/<n> append chunk (n=1..)+ GET /upload/session/<sid> status+ POST /upload/session/<sid>/finalize request stitch+ DELETE /upload/session/<sid> abort + cleanup++All endpoints require login. They write the on-disk layout described in+``src/models/recording_session.py``.++Finalize is async: the endpoint creates a placeholder Recording row in+``STITCHING`` status, enqueues a ``stitch`` job via the existing+``job_queue``, and returns the recording id immediately. The worker+(see :mod:`src.services.recording_stitch`) runs ``ffmpeg`` concat demux,+moves the resulting file into ``UPLOAD_FOLDER``, and either enqueues a+follow-up ``transcribe`` job on success or marks the recording ``FAILED``.++Limits+------++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`` (default+24) are reaped by :func:`cleanup_expired_sessions` from an APScheduler+job; cleanup flips status to ``expired`` before removing the directory.+"""++import json+import os+import shutil+from datetime import datetime, timedelta++from flask import Blueprint, request, jsonify, current_app+from flask_login import login_required, current_user++from src.database import db+from src.models import RecordingSession, Recording, RECORDING_SESSION_STATUSES+from src.services.job_queue import job_queue+++recording_sessions_bp = Blueprint('recording_sessions', __name__)+++# --- Config knobs (env-overridable, read fresh each call so tests can patch) ---++def _session_root():+ upload_folder = current_app.config.get('UPLOAD_FOLDER') or '/data/uploads'+ return os.path.join(upload_folder, '_sessions')+++def _session_dir(session_id):+ return os.path.join(_session_root(), session_id)+++def _max_bytes_per_user():+ return int(os.environ.get('RECORDING_SESSION_MAX_BYTES_PER_USER', str(5 * 1024 * 1024 * 1024)))+++def _ttl_hours():+ return int(os.environ.get('RECORDING_SESSION_TTL_HOURS', '24'))+++def _allowed_mime_types():+ raw = os.environ.get(+ 'RECORDING_SESSION_ALLOWED_MIME_TYPES',+ 'audio/webm,audio/ogg,audio/mp4,audio/mpeg,audio/wav,audio/x-m4a',+ )+ return {m.strip().lower() for m in raw.split(',') if m.strip()}+++def _max_chunk_bytes():+ """Per-chunk upload size cap. A MediaRecorder timeslice of a few seconds+ yields chunks well under 1 MB even at high bitrates, so 16 MB is a wide+ safety margin that still rejects accidental whole-file uploads."""+ return int(os.environ.get('RECORDING_SESSION_MAX_CHUNK_BYTES', str(16 * 1024 * 1024)))+++# --- Helpers ----------------------------------------------------------------++def _ensure_owned(session):+ """Return None if ok, otherwise a Flask response tuple."""+ if not session:+ return jsonify({'error': 'Session not found'}), 404+ if session.user_id != current_user.id:+ # 404 instead of 403 so the existence of other users' sessions is+ # not leaked to the caller.+ return jsonify({'error': 'Session not found'}), 404+ return None+++def _user_bytes_in_progress(user_id):+ """Sum of bytes_received across this user's non-terminal sessions."""+ total = db.session.query(db.func.coalesce(db.func.sum(RecordingSession.bytes_received), 0)).filter(+ RecordingSession.user_id == user_id,+ RecordingSession.status.in_(('recording', 'finalizing')),+ ).scalar() or 0+ return int(total)+++def _write_session_manifest(session):+ """Write a JSON copy of the session row next to the chunks. This is a+ belt-and-braces recovery aid: if the DB is wiped but the disk survives,+ the manifest tells an operator what was being uploaded."""+ dir_path = _session_dir(session.id)+ os.makedirs(dir_path, exist_ok=True)+ manifest_path = os.path.join(dir_path, 'session.json')+ try:+ with open(manifest_path, 'w') as f:+ json.dump(session.to_dict(), f, indent=2)+ except Exception as e:+ current_app.logger.warning(f"Could not write session manifest for {session.id}: {e}")+++# --- Endpoints --------------------------------------------------------------++@recording_sessions_bp.route('/upload/session', methods=['POST'])+@login_required+def create_session():+ """Create a new in-progress recording session.++ Body (JSON, all optional): {"mime_type": "audio/webm"}.++ Returns ``{session_id, expires_at, max_chunk_bytes}`` on success.+ """+ data = request.get_json(silent=True) or {}+ mime_type = (data.get('mime_type') or 'audio/webm').strip().lower()+ if mime_type not in _allowed_mime_types():+ return jsonify({+ 'error': f'Unsupported mime_type {mime_type!r}',+ 'allowed': sorted(_allowed_mime_types()),+ }), 400++ # Per-user quota check before we let them open another session.+ if _user_bytes_in_progress(current_user.id) >= _max_bytes_per_user():+ return jsonify({+ 'error': 'Per-user in-progress recording storage quota exhausted',+ 'quota_bytes': _max_bytes_per_user(),+ }), 507 # Insufficient Storage++ session = RecordingSession(+ user_id=current_user.id,+ mime_type=mime_type,+ status='recording',+ )+ db.session.add(session)+ db.session.commit()++ try:+ os.makedirs(_session_dir(session.id), exist_ok=True)+ _write_session_manifest(session)+ except OSError as e:+ # Roll back so we don't leak a half-created session row.+ db.session.delete(session)+ db.session.commit()+ current_app.logger.error(f"Could not create session dir: {e}")+ return jsonify({'error': 'Server could not allocate session storage'}), 500++ expires_at = session.created_at + timedelta(hours=_ttl_hours())+ return jsonify({+ 'session_id': session.id,+ 'mime_type': session.mime_type,+ 'status': session.status,+ 'expires_at': expires_at.isoformat(),+ 'max_chunk_bytes': _max_chunk_bytes(),+ }), 201+++@recording_sessions_bp.route('/upload/session/<string:session_id>', methods=['GET'])+@login_required+def get_session(session_id):+ """Return the current status of an in-progress session."""+ session = db.session.get(RecordingSession, session_id)+ err = _ensure_owned(session)+ if err is not None:+ return err+ return jsonify(session.to_dict())+++@recording_sessions_bp.route('/upload/session/<string:session_id>/chunks/<int:chunk_index>', methods=['POST'])+@login_required+def upload_chunk(session_id, chunk_index):+ """Append one chunk to a session.++ The chunk index must equal ``session.chunk_count + 1`` (strict in-order+ uploads). If it does not, the response is 409 with the expected next+ index, so the client can resync without losing the recording.++ The chunk body is read from ``request.data`` (raw bytes) or from a file+ field named ``chunk`` (multipart). The raw-bytes path is preferred by+ the streaming client because it avoids the multipart framing overhead+ on every short request.+ """+ session = db.session.get(RecordingSession, session_id)+ err = _ensure_owned(session)+ if err is not None:+ return err++ if session.status != 'recording':+ return jsonify({+ 'error': f'Session is in status {session.status!r}; chunks are no longer accepted',+ }), 409++ expected_index = session.chunk_count + 1+ if chunk_index != expected_index:+ return jsonify({+ 'error': 'Out-of-order chunk',+ 'expected_chunk_index': expected_index,+ 'got': chunk_index,+ }), 409++ # Accept either raw body or multipart upload.+ chunk_bytes = None+ if 'chunk' in request.files:+ f = request.files['chunk']+ chunk_bytes = f.read()+ else:+ chunk_bytes = request.get_data(cache=False)++ if not chunk_bytes:+ return jsonify({'error': 'Empty chunk body'}), 400++ if len(chunk_bytes) > _max_chunk_bytes():+ return jsonify({+ 'error': 'Chunk exceeds max_chunk_bytes',+ 'max_chunk_bytes': _max_chunk_bytes(),+ 'got': len(chunk_bytes),+ }), 413++ # Per-user quota check: the new chunk must not push the user over.+ projected = _user_bytes_in_progress(current_user.id) - session.bytes_received + session.bytes_received + len(chunk_bytes)+ if projected > _max_bytes_per_user():+ return jsonify({+ 'error': 'Per-user in-progress recording storage quota would be exceeded',+ 'quota_bytes': _max_bytes_per_user(),+ }), 507++ dir_path = _session_dir(session.id)+ os.makedirs(dir_path, exist_ok=True)+ chunk_path = os.path.join(dir_path, f'chunk-{chunk_index:06d}.bin')+ try:+ with open(chunk_path, 'wb') as f:+ f.write(chunk_bytes)+ except OSError as e:+ current_app.logger.error(f"Could not write chunk {chunk_index} for session {session_id}: {e}")+ return jsonify({'error': 'Server could not write chunk'}), 500++ session.chunk_count = chunk_index+ session.bytes_received = (session.bytes_received or 0) + len(chunk_bytes)+ session.last_seen_at = datetime.utcnow()+ db.session.commit()++ # Manifest is best-effort; missing it doesn't break the flow.+ _write_session_manifest(session)++ return ('', 204)+++@recording_sessions_bp.route('/upload/session/<string:session_id>/finalize', methods=['POST'])+@login_required+def finalize_session(session_id):+ """Request asynchronous stitch and transcription kickoff.++ Body (JSON, all optional): metadata to attach to the resulting+ Recording row: ``{title, notes, tags, folder_id, asr_options,+ transcription_model, hotwords, initial_prompt, prompt_variables}``.++ Returns ``{recording_id, status}`` immediately. The actual stitch+ happens off-request via the job queue; clients can poll+ ``GET /api/v1/recordings/{id}/status`` to follow progress.+ """+ session = db.session.get(RecordingSession, session_id)+ err = _ensure_owned(session)+ if err is not None:+ return err++ if session.status not in ('recording', 'finalizing'):+ return jsonify({+ 'error': f'Session is in status {session.status!r}; cannot finalize',+ }), 409++ if session.chunk_count <= 0:+ return jsonify({'error': 'No chunks uploaded yet'}), 409++ metadata = request.get_json(silent=True) or {}+ if not isinstance(metadata, dict):+ return jsonify({'error': 'finalize body must be a JSON object'}), 400++ # Create a placeholder Recording row. The stitch worker will fill in+ # audio_path and file_size after concat completes.+ title = (metadata.get('title') or f"Recording {datetime.utcnow().strftime('%Y-%m-%d %H:%M')}").strip() or "Recording"+ notes = metadata.get('notes') or None+ folder_id = metadata.get('folder_id')+ if folder_id in ('', 'none', 'null'):+ folder_id = None++ recording = Recording(+ user_id=current_user.id,+ title=title[:200],+ status='STITCHING',+ notes=notes,+ folder_id=folder_id if isinstance(folder_id, int) else None,+ processing_source='recording_session',+ mime_type=session.mime_type,+ )+ 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}")+ # 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),+ }), 500++ return jsonify({+ 'recording_id': recording.id,+ 'status': session.status,+ }), 202+++@recording_sessions_bp.route('/upload/session/<string:session_id>', methods=['DELETE'])+@login_required+def abort_session(session_id):+ """Abort an in-progress session and clean up its on-disk chunks.++ If the session has already finalized, this returns 409; finalized+ sessions are owned by the stitch worker, not the user.+ """+ session = db.session.get(RecordingSession, session_id)+ err = _ensure_owned(session)+ if err is not None:+ return err++ if session.status == 'finalized':+ return jsonify({'error': 'Session already finalized'}), 409++ session.status = 'aborted'+ session.last_seen_at = datetime.utcnow()+ db.session.commit()++ # 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}")++ return ('', 204)+++# --- Cleanup hook -----------------------------------------------------------++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.+ """+ if app is None:+ from flask import current_app as _ca+ app = _ca._get_current_object()++ with app.app_context():+ cutoff = datetime.utcnow() - timedelta(hours=_ttl_hours())+ candidates = RecordingSession.query.filter(+ RecordingSession.last_seen_at < cutoff,+ RecordingSession.status.in_(('recording', 'finalizing')),+ ).all()+ for 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)+ except 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)diff --git a/src/app.py b/src/app.pyindex 7ff0df65..6915e258 100644--- a/src/app.py+++ b/src/app.py@@ -624,6 +624,7 @@ from src.api.events import events_bp, init_events_helpersfrom src.api.system import system_bp, init_system_helpersfrom src.api.push_notifications import push_bpfrom src.api.api_v1 import api_v1_bp, init_api_v1_helpers+from src.api.recording_sessions import recording_sessions_bp# Database initialization (extracted to src/init_db.py)from src.init_db import initialize_database@@ -670,6 +671,13 @@ app.register_blueprint(push_bp)app.register_blueprint(api_v1_bp)csrf.exempt(api_v1_bp) # API v1 uses token auth, not CSRF+# Recording sessions (#287 c/d): the streaming client POSTs binary chunk+# bodies via fetch with the session cookie. CSRF tokens are easy to attach+# from JS, so we keep the protection on by default — but each individual+# chunk request is a fetch call from our own SPA, which already carries+# the token, so no exemption is needed here.+app.register_blueprint(recording_sessions_bp)+# PWA Web Share Target (issue #285): the native share sheet cannot round-trip# a CSRF token, so the share-target endpoint is exempted. Authentication still# happens via the session cookie carried by the browser; @login_requireddiff --git a/src/config/startup.py b/src/config/startup.pyindex 2d4f0724..dc28517f 100644--- a/src/config/startup.py+++ b/src/config/startup.py@@ -135,6 +135,49 @@ def initialize_job_queue(app):app.logger.error(f"Failed to start job queue: {e}", exc_info=True)+def initialize_recording_session_cleanup(app):+ """Sweep expired recording sessions on a background thread.++ Issue #287 (c)(d): in-progress recording sessions accumulate chunk+ files in ``UPLOAD_FOLDER/_sessions/<id>/``. The session row's+ ``last_seen_at`` is updated on every chunk POST; sessions that go+ silent for longer than ``RECORDING_SESSION_TTL_HOURS`` (default 24)+ are reaped here and their on-disk dirs removed.++ Runs on the same pattern as the other schedulers in this module+ (daemon thread with a sleep loop), with a configurable interval via+ ``RECORDING_SESSION_CLEANUP_INTERVAL_SECONDS`` (default 3600 = hourly).+ """+ import os+ import threading+ import time++ interval = int(os.environ.get('RECORDING_SESSION_CLEANUP_INTERVAL_SECONDS', '3600'))+ if interval <= 0:+ app.logger.info("Recording-session cleanup disabled (interval <= 0)")+ return++ def _loop():+ from src.api.recording_sessions import cleanup_expired_sessions+ app.logger.info(f"Recording-session cleanup scheduler started (interval={interval}s)")+ # First sweep happens after the interval, not at boot, to avoid+ # contention with other startup tasks.+ while True:+ try:+ time.sleep(interval)+ reaped = cleanup_expired_sessions(app=app)+ if reaped:+ app.logger.info(f"Recording-session cleanup reaped {reaped} session(s)")+ except Exception as e:+ app.logger.error(f"Recording-session cleanup error: {e}", exc_info=True)+ # Don't tight-loop on failure+ time.sleep(60)++ thread = threading.Thread(target=_loop, daemon=True, name="RecordingSessionCleanup")+ thread.start()+ app.logger.info("✅ Recording-session cleanup scheduler initialized")++def run_startup_tasks(app):"""Run all startup tasks that need to happen after app creation."""from src.models import SystemSetting@@ -156,3 +199,6 @@ def run_startup_tasks(app):# Initialize auto-deletion schedulerinitialize_auto_deletion_scheduler(app)++ # Initialize recording-session cleanup scheduler (#287 c/d)+ initialize_recording_session_cleanup(app)diff --git a/src/models/__init__.py b/src/models/__init__.pyindex 2a82004f..8d23e6c0 100644--- a/src/models/__init__.py+++ b/src/models/__init__.py@@ -29,6 +29,7 @@ from .system import SystemSettingfrom .audit import ShareAuditLogfrom .push_subscription import PushSubscriptionfrom .processing_job import ProcessingJob+from .recording_session import RecordingSession, RECORDING_SESSION_STATUSESfrom .token_usage import TokenUsagefrom .transcription_usage import TranscriptionUsage@@ -64,6 +65,8 @@ __all__ = ['SystemSetting','PushSubscription','ProcessingJob',+ 'RecordingSession',+ 'RECORDING_SESSION_STATUSES','TokenUsage','TranscriptionUsage',]diff --git a/src/models/recording_session.py b/src/models/recording_session.pynew file mode 100644index 00000000..4434faf9--- /dev/null+++ b/src/models/recording_session.py@@ -0,0 +1,122 @@+"""RecordingSession model for server-side in-progress recording chunks.++Implements the backend half of issue #287 (c)(d): instead of accumulating+the entire audio blob in browser RAM until the user clicks Upload, the+in-app recorder POSTs MediaRecorder chunks to the server as they are+produced. This model tracks the open session: a session id, the user who+owns it, the chunks received so far, and the status as it transitions+from `recording` → `finalizing` → `finalized` (with `aborted` and+`expired` as terminal failure states).++The on-disk layout for a session is:++ {UPLOAD_FOLDER}/_sessions/<session_id>/+ session.json ← redundant copy of the columns for crash recovery+ chunk-000001.webm+ chunk-000002.webm+ ...++On finalize, the chunks are stitched into a single file via ffmpeg concat+demux (handles pause/resume across MediaRecorder restarts, which a raw+cat would corrupt). The resulting file becomes the new Recording's+audio_path and the session directory is removed.+"""++import uuid+from datetime import datetime++from src.database import db+++# Status constants kept as module-level strings so callers can reference+# them by name. SQLAlchemy doesn't enforce the enum, so all reads / writes+# go through these constants.+RECORDING_SESSION_STATUSES = (+ 'recording', # client is actively POSTing chunks+ 'finalizing', # finalize requested; stitch job is queued or running+ 'finalized', # stitch completed; session dir may already be removed+ 'aborted', # user (or admin) cancelled before finalize+ 'expired', # TTL elapsed without finalize; cleanup ran+ 'failed', # stitch job hit a permanent error+)+++class RecordingSession(db.Model):+ """An in-progress browser-recorder session with chunks on the server."""++ __tablename__ = 'recording_session'++ # Use a UUID4 string as the primary key. Predictable integer ids would+ # let an attacker who guesses an id POST chunks into another user's+ # session before the ownership check fires; UUID4 makes that infeasible.+ id = db.Column(db.String(36), primary_key=True, default=lambda: str(uuid.uuid4()))++ user_id = db.Column(+ db.Integer,+ db.ForeignKey('user.id', ondelete='CASCADE'),+ nullable=False,+ index=True,+ )++ # The MIME type the client declared when creating the session. Stored so+ # we can validate per-chunk uploads (reject anything inconsistent with+ # the declared type) and pick the right ffmpeg input args at stitch time.+ mime_type = db.Column(db.String(100), nullable=False, default='audio/webm')++ # Status transitions are guarded by the API; see RECORDING_SESSION_STATUSES.+ status = db.Column(db.String(20), nullable=False, default='recording', index=True)++ # Monotonic counter advanced on every successful chunk POST. The next+ # expected client-supplied chunk index equals `chunk_count + 1`. Out-of-+ # order POSTs are rejected with a 409 telling the client the expected+ # next index so it can resync.+ chunk_count = db.Column(db.Integer, nullable=False, default=0)++ # Cumulative bytes received across all chunks. Used for the per-user+ # storage quota check and to populate Recording.file_size on finalize.+ bytes_received = db.Column(db.BigInteger, nullable=False, default=0)++ # Set when finalize succeeds; lets the recording detail view link back+ # to the session that produced it for audit purposes.+ finalized_recording_id = db.Column(+ db.Integer,+ db.ForeignKey('recording.id', ondelete='SET NULL'),+ nullable=True,+ index=True,+ )++ # Optional user-supplied finalize metadata (notes, tags, folder, ASR+ # options, prompt variables). Stored as JSON text so the stitch worker+ # can read it without an additional table.+ finalize_metadata = db.Column(db.Text, nullable=True)++ # Optional error message when status == 'failed'.+ error_message = db.Column(db.Text, nullable=True)++ created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False, index=True)+ last_seen_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False, index=True)+ finalized_at = db.Column(db.DateTime, nullable=True)++ user = db.relationship(+ 'User',+ backref=db.backref('recording_sessions', lazy='dynamic', cascade='all, delete-orphan'),+ )+ finalized_recording = db.relationship('Recording', foreign_keys=[finalized_recording_id])++ def __repr__(self): # pragma: no cover - debugging aid+ return f'<RecordingSession {self.id} user={self.user_id} status={self.status} chunks={self.chunk_count}>'++ def to_dict(self):+ """Public view of the session for API responses."""+ return {+ 'session_id': self.id,+ 'status': self.status,+ 'mime_type': self.mime_type,+ 'chunk_count': self.chunk_count,+ 'bytes_received': self.bytes_received,+ 'created_at': self.created_at.isoformat() if self.created_at else None,+ 'last_seen_at': self.last_seen_at.isoformat() if self.last_seen_at else None,+ 'finalized_at': self.finalized_at.isoformat() if self.finalized_at else None,+ 'finalized_recording_id': self.finalized_recording_id,+ 'error_message': self.error_message,+ }diff --git a/src/services/job_queue.py b/src/services/job_queue.pyindex ef14c74f..412a245c 100644--- a/src/services/job_queue.py+++ b/src/services/job_queue.py@@ -327,6 +327,8 @@ class FairJobQueue:self._run_reprocess_transcription(job, recording, params)elif job_type == 'reprocess_summary':self._run_reprocess_summary(job, recording, params)+ elif job_type == 'stitch':+ self._run_stitch(job, recording, params)else:raise ValueError(f"Unknown job type: {job_type}")@@ -453,6 +455,47 @@ class FairJobQueue:user_id=params.get('user_id'))+ def _run_stitch(self, job, recording, params):+ """Stitch in-progress recording-session chunks into a single file (#287 c/d).++ On success the recording row is updated in place (audio_path,+ file_size, status='PENDING') and a follow-up ``transcribe`` job is+ enqueued. On failure the recording is flipped to FAILED with the+ ffmpeg error message visible to the user.+ """+ from src.services.recording_stitch import (+ stitch_recording_session,+ kickoff_transcription_for_stitched,+ StitchError,+ )++ session_id = (params or {}).get('session_id')+ if not session_id:+ raise ValueError("stitch job missing required 'session_id' param")++ try:+ recording_id, final_path, metadata = stitch_recording_session(session_id)+ except StitchError as e:+ # Mark the recording FAILED so the user sees the error in the UI.+ # The session row was already flipped to 'failed' by the worker,+ # except in cases where stitch raised before touching it; do both+ # defensively.+ from src.models import RecordingSession+ recording.status = 'FAILED'+ recording.transcription = f"Processing failed: {e}"+ sess = db.session.get(RecordingSession, session_id)+ if sess and sess.status not in ('finalized', 'aborted', 'expired'):+ sess.status = 'failed'+ sess.error_message = str(e)+ db.session.commit()+ raise++ kickoff_transcription_for_stitched(+ recording_id=recording_id,+ user_id=recording.user_id,+ metadata=metadata,+ )+def enqueue(self,user_id: int,diff --git a/src/services/recording_stitch.py b/src/services/recording_stitch.pynew file mode 100644index 00000000..379cdae0--- /dev/null+++ b/src/services/recording_stitch.py@@ -0,0 +1,218 @@+"""Stitch worker for server-side recording chunks (#287 c/d).++The :func:`stitch_recording_session` function is called from the+``stitch`` job_queue dispatch. It++1. 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).+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+ picks it up).+6. Removes the session directory and marks the session ``finalized``.+7. Enqueues a ``transcribe`` job for the recording.++Any failure flips the recording status to FAILED with a descriptive+``transcription`` payload (mirrors the existing failure-surface format+upload_file uses) and the session to ``failed`` so the user can see what+happened.+"""++import json+import logging+import os+import shutil+import subprocess+from datetime import datetime+from pathlib import Path+from typing import Tuple++from src.database import db+from src.models import RecordingSession, Recording+++logger = logging.getLogger(__name__)+++class StitchError(Exception):+ """Raised when concat / move / cleanup fails. The message is surfaced+ on the Recording's ``transcription`` field so the user can see what+ went wrong from the UI."""+++def _session_dir(upload_folder: str, session_id: str) -> str:+ return os.path.join(upload_folder, '_sessions', session_id)+++def _chunk_paths(session_dir: str) -> list:+ """Return chunk file paths in monotonic order. ``chunk-NNNNNN.bin``+ naming sorts lexicographically by index because of the zero pad."""+ if not os.path.isdir(session_dir):+ return []+ entries = sorted(+ e for e in os.listdir(session_dir)+ if e.startswith('chunk-') and e.endswith('.bin')+ )+ return [os.path.join(session_dir, e) for e in entries]+++def _mime_to_extension(mime_type: str) -> str:+ """Pick a sensible output extension for the stitched container."""+ mapping = {+ 'audio/webm': 'webm',+ 'audio/ogg': 'ogg',+ 'audio/mp4': 'm4a',+ 'audio/x-m4a': 'm4a',+ 'audio/mpeg': 'mp3',+ 'audio/wav': 'wav',+ }+ 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.++ 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'+ 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')+ finally:+ # Clean up the manifest regardless of outcome.+ try:+ if os.path.exists(manifest_path):+ os.remove(manifest_path)+ except OSError:+ pass+++def stitch_recording_session(session_id: str) -> Tuple[int, str]:+ """Stitch a session's chunks into a final audio file.++ Returns ``(recording_id, audio_path)`` on success. Raises+ :class:`StitchError` on any failure; the caller (job_queue worker)+ is responsible for updating the Recording row's status and+ surfacing the error to the user.+ """+ session = db.session.get(RecordingSession, session_id)+ if not session:+ raise StitchError(f'session {session_id} not found')+ if not session.finalized_recording_id:+ raise StitchError(f'session {session_id} has no finalized_recording_id')++ recording = db.session.get(Recording, session.finalized_recording_id)+ if not recording:+ raise StitchError(f'recording {session.finalized_recording_id} not found')++ from flask import current_app+ upload_folder = current_app.config.get('UPLOAD_FOLDER') or '/data/uploads'+ sess_dir = _session_dir(upload_folder, session_id)++ chunk_paths = _chunk_paths(sess_dir)+ if not chunk_paths:+ raise StitchError(f'session {session_id} has no chunks on disk')++ extension = _mime_to_extension(session.mime_type)+ timestamp = datetime.utcnow().strftime('%Y%m%d%H%M%S')+ 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)++ file_size = os.path.getsize(final_path)++ # Update the recording row in place. We don't change the title - the+ # finalize endpoint set it.+ recording.audio_path = final_path+ recording.original_filename = final_filename+ recording.file_size = file_size+ recording.status = 'PENDING'+ if not recording.meeting_date:+ recording.meeting_date = session.created_at++ session.status = 'finalized'+ session.finalized_at = datetime.utcnow()+ session.last_seen_at = datetime.utcnow()+ db.session.commit()++ # Remove the session directory now that we have the stitched output.+ try:+ if os.path.isdir(sess_dir):+ shutil.rmtree(sess_dir, ignore_errors=True)+ 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 = {}++ return recording.id, final_path, metadata+++def kickoff_transcription_for_stitched(+ recording_id: int,+ user_id: int,+ metadata: dict,+) -> None:+ """Enqueue the downstream transcribe job using the same precedence+ chain as ``upload_file`` for the fields that apply to a recording+ that already exists. Idempotent (the job_queue rejects duplicate+ active jobs of the same type for the same recording)."""+ from src.services.job_queue import job_queue+ job_queue.enqueue(+ user_id=user_id,+ recording_id=recording_id,+ job_type='transcribe',+ params={+ 'language': metadata.get('language') or metadata.get('asr_language'),+ 'min_speakers': metadata.get('min_speakers'),+ 'max_speakers': metadata.get('max_speakers'),+ 'hotwords': metadata.get('hotwords'),+ 'initial_prompt': metadata.get('initial_prompt'),+ 'transcription_model': metadata.get('transcription_model'),+ },+ is_new_upload=True,+ )diff --git a/tests/test_recording_sessions.py b/tests/test_recording_sessions.pynew file mode 100644index 00000000..230bc58a--- /dev/null+++ b/tests/test_recording_sessions.py@@ -0,0 +1,386 @@+"""End-to-end tests for the recording-session API (#287 c/d).++Exercises:++- POST /upload/session create+- POST /upload/session/<id>/chunks/<n> upload (in-order, out-of-order, oversize)+- GET /upload/session/<id> status+- POST /upload/session/<id>/finalize enqueue stitch (mocked)+- DELETE /upload/session/<id> abort + dir cleanup+- ownership boundary (one user cannot touch another's session)+- cleanup_expired_sessions reaps stale sessions and removes dirs++The ffmpeg concat path is exercised indirectly: the finalize test mocks+the stitch job_queue.enqueue so we don't need ffmpeg in the test env; a+companion test of the stitch module itself goes in test_recording_stitch.+"""++import os+import shutil+import sys+import tempfile+import uuid+from datetime import datetime, timedelta+from unittest.mock import patch++sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))++from src.app import app, db+from src.models import User, Recording, RecordingSession+++app.config["WTF_CSRF_ENABLED"] = False+++def _setup_user(prefix):+ suffix = uuid.uuid4().hex[:8]+ user = User(+ username=f"{prefix}_{suffix}",+ email=f"{prefix}_{suffix}@local.test",+ password="x",+ )+ db.session.add(user)+ db.session.commit()+ return user+++def _login(client, user):+ """Swap the test_client session to a given user.++ Tests that switch users between requests need to invalidate+ Flask-Login's per-request cache on ``g``, which leaks across+ test_client calls when the outer test wraps in ``with+ app.app_context()`` (the cache is bound to the app context, not the+ request context). Pop ``_login_user`` so the next request re-runs+ the user_loader against the freshly-written session.+ """+ from flask import g+ with client.session_transaction() as sess:+ sess.clear()+ sess["_user_id"] = str(user.id)+ sess["_fresh"] = True+ try:+ g.pop("_login_user", None)+ except RuntimeError:+ # Outside of an app context; not in a switching scenario.+ pass+++def _make_tmp_upload_folder():+ """Spin up a unique upload folder so tests don't trample one another."""+ tmp = tempfile.mkdtemp(prefix="speakr-test-sessions-")+ return tmp+++def test_create_session_returns_session_id_and_makes_dir():+ upload_folder = _make_tmp_upload_folder()+ with app.app_context():+ app.config["UPLOAD_FOLDER"] = upload_folder+ user = _setup_user("sess_create")+ client = app.test_client()+ _login(client, user)+ resp = client.post("/upload/session", json={"mime_type": "audio/webm"})+ assert resp.status_code == 201, resp.data+ body = resp.get_json()+ assert "session_id" in body+ assert body["mime_type"] == "audio/webm"+ assert body["status"] == "recording"+ assert "expires_at" in body+ assert body["max_chunk_bytes"] > 0++ # Dir exists on disk+ session_dir = os.path.join(upload_folder, "_sessions", body["session_id"])+ assert os.path.isdir(session_dir)+ # Manifest exists+ assert os.path.exists(os.path.join(session_dir, "session.json"))++ db.session.delete(db.session.get(RecordingSession, body["session_id"]))+ db.session.delete(user)+ db.session.commit()+ shutil.rmtree(upload_folder, ignore_errors=True)+++def test_create_session_rejects_unsupported_mime_type():+ upload_folder = _make_tmp_upload_folder()+ with app.app_context():+ app.config["UPLOAD_FOLDER"] = upload_folder+ user = _setup_user("sess_bad_mime")+ client = app.test_client()+ _login(client, user)+ resp = client.post("/upload/session", json={"mime_type": "video/h264"})+ assert resp.status_code == 400+ assert "allowed" in resp.get_json()+ db.session.delete(user)+ db.session.commit()+ shutil.rmtree(upload_folder, ignore_errors=True)+++def test_chunk_upload_in_order_succeeds_and_advances_counter():+ upload_folder = _make_tmp_upload_folder()+ with app.app_context():+ app.config["UPLOAD_FOLDER"] = upload_folder+ user = _setup_user("sess_chunks")+ client = app.test_client()+ _login(client, user)+ resp = client.post("/upload/session", json={"mime_type": "audio/webm"})+ sid = resp.get_json()["session_id"]++ # Three chunks, in order+ for i in range(1, 4):+ r = client.post(+ f"/upload/session/{sid}/chunks/{i}",+ data=b"x" * 64,+ content_type="application/octet-stream",+ )+ assert r.status_code == 204, (i, r.data)++ # Status reflects the counters+ r = client.get(f"/upload/session/{sid}")+ body = r.get_json()+ assert body["chunk_count"] == 3+ assert body["bytes_received"] == 64 * 3+ # Disk has 3 chunks+ sess_dir = os.path.join(upload_folder, "_sessions", sid)+ chunk_files = sorted(f for f in os.listdir(sess_dir) if f.startswith("chunk-"))+ assert chunk_files == ["chunk-000001.bin", "chunk-000002.bin", "chunk-000003.bin"]++ client.delete(f"/upload/session/{sid}")+ db.session.delete(user)+ db.session.commit()+ shutil.rmtree(upload_folder, ignore_errors=True)+++def test_chunk_upload_out_of_order_returns_409_with_expected_index():+ upload_folder = _make_tmp_upload_folder()+ with app.app_context():+ app.config["UPLOAD_FOLDER"] = upload_folder+ user = _setup_user("sess_oo")+ client = app.test_client()+ _login(client, user)+ resp = client.post("/upload/session", json={"mime_type": "audio/webm"})+ sid = resp.get_json()["session_id"]+ # Skip 1, send 2 first+ r = client.post(f"/upload/session/{sid}/chunks/2", data=b"y" * 10, content_type="application/octet-stream")+ assert r.status_code == 409+ body = r.get_json()+ assert body["expected_chunk_index"] == 1+ assert body["got"] == 2+ client.delete(f"/upload/session/{sid}")+ db.session.delete(user)+ db.session.commit()+ shutil.rmtree(upload_folder, ignore_errors=True)+++def test_chunk_upload_rejects_empty_body():+ upload_folder = _make_tmp_upload_folder()+ with app.app_context():+ app.config["UPLOAD_FOLDER"] = upload_folder+ user = _setup_user("sess_empty")+ client = app.test_client()+ _login(client, user)+ resp = client.post("/upload/session", json={"mime_type": "audio/webm"})+ sid = resp.get_json()["session_id"]+ r = client.post(f"/upload/session/{sid}/chunks/1", data=b"", content_type="application/octet-stream")+ assert r.status_code == 400+ client.delete(f"/upload/session/{sid}")+ db.session.delete(user)+ db.session.commit()+ shutil.rmtree(upload_folder, ignore_errors=True)+++def test_finalize_creates_recording_and_enqueues_stitch_job():+ upload_folder = _make_tmp_upload_folder()+ with app.app_context():+ app.config["UPLOAD_FOLDER"] = upload_folder+ user = _setup_user("sess_fin")+ client = app.test_client()+ _login(client, user)+ sid = client.post("/upload/session", json={"mime_type": "audio/webm"}).get_json()["session_id"]+ client.post(f"/upload/session/{sid}/chunks/1", data=b"\x00" * 100, content_type="application/octet-stream")++ captured = {}++ def fake_enqueue(*args, **kwargs):+ captured.update(kwargs)+ return 999++ with patch("src.services.job_queue.job_queue.enqueue", side_effect=fake_enqueue):+ r = client.post(f"/upload/session/{sid}/finalize", json={"title": "Soak test", "notes": "n"})+ assert r.status_code == 202, r.data+ body = r.get_json()+ assert "recording_id" in body+ assert body["status"] == "finalizing"++ # Recording row exists in STITCHING status+ rec = db.session.get(Recording, body["recording_id"])+ assert rec is not None+ assert rec.status == "STITCHING"+ assert rec.title == "Soak test"+ assert rec.user_id == user.id+ # Stitch enqueue was called with the session id+ assert captured.get("job_type") == "stitch"+ assert captured["params"]["session_id"] == sid+ assert captured.get("is_new_upload") is True++ # Cleanup+ sess = db.session.get(RecordingSession, sid)+ sess.status = 'aborted' # avoid trying to actually stitch+ db.session.commit()+ client.delete(f"/upload/session/{sid}")+ db.session.delete(rec)+ db.session.delete(user)+ db.session.commit()+ shutil.rmtree(upload_folder, ignore_errors=True)+++def test_finalize_rejects_when_no_chunks():+ upload_folder = _make_tmp_upload_folder()+ with app.app_context():+ app.config["UPLOAD_FOLDER"] = upload_folder+ user = _setup_user("sess_empty_fin")+ client = app.test_client()+ _login(client, user)+ sid = client.post("/upload/session", json={"mime_type": "audio/webm"}).get_json()["session_id"]+ r = client.post(f"/upload/session/{sid}/finalize", json={})+ assert r.status_code == 409+ client.delete(f"/upload/session/{sid}")+ db.session.delete(user)+ db.session.commit()+ shutil.rmtree(upload_folder, ignore_errors=True)+++def test_abort_removes_session_dir():+ upload_folder = _make_tmp_upload_folder()+ with app.app_context():+ app.config["UPLOAD_FOLDER"] = upload_folder+ user = _setup_user("sess_abort")+ client = app.test_client()+ _login(client, user)+ sid = client.post("/upload/session", json={"mime_type": "audio/webm"}).get_json()["session_id"]+ client.post(f"/upload/session/{sid}/chunks/1", data=b"z" * 50, content_type="application/octet-stream")+ sess_dir = os.path.join(upload_folder, "_sessions", sid)+ assert os.path.isdir(sess_dir)++ r = client.delete(f"/upload/session/{sid}")+ assert r.status_code == 204+ assert not os.path.isdir(sess_dir)++ sess = db.session.get(RecordingSession, sid)+ assert sess.status == "aborted"+ db.session.delete(sess)+ db.session.delete(user)+ db.session.commit()+ shutil.rmtree(upload_folder, ignore_errors=True)+++def test_ownership_enforced_other_user_gets_404():+ upload_folder = _make_tmp_upload_folder()+ with app.app_context():+ app.config["UPLOAD_FOLDER"] = upload_folder+ user_a = _setup_user("sess_owner_a")+ user_b = _setup_user("sess_owner_b")+ client = app.test_client()+ _login(client, user_a)+ sid = client.post("/upload/session", json={"mime_type": "audio/webm"}).get_json()["session_id"]+ # Switch login to user B+ _login(client, user_b)+ # B should not be able to GET / POST chunks / finalize / abort A's session+ assert client.get(f"/upload/session/{sid}").status_code == 404+ assert client.post(f"/upload/session/{sid}/chunks/1", data=b"x", content_type="application/octet-stream").status_code == 404+ assert client.post(f"/upload/session/{sid}/finalize", json={}).status_code == 404+ assert client.delete(f"/upload/session/{sid}").status_code == 404+ # A can still operate+ _login(client, user_a)+ assert client.delete(f"/upload/session/{sid}").status_code == 204+ db.session.delete(user_a)+ db.session.delete(user_b)+ db.session.commit()+ shutil.rmtree(upload_folder, ignore_errors=True)+++def test_cleanup_reaps_expired_sessions():+ upload_folder = _make_tmp_upload_folder()+ from src.api.recording_sessions import cleanup_expired_sessions+ with app.app_context():+ app.config["UPLOAD_FOLDER"] = upload_folder+ user = _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)+ 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,+ )+ 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"+ assert 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))+ db.session.delete(user)+ db.session.commit()+ shutil.rmtree(upload_folder, ignore_errors=True)+++_ORIGINAL_UPLOAD_FOLDER = app.config.get("UPLOAD_FOLDER")+++def setup_function(function): # noqa: D401 - pytest hook+ """Reset UPLOAD_FOLDER before each test so prior mutations do not leak."""+ if _ORIGINAL_UPLOAD_FOLDER is not None:+ app.config["UPLOAD_FOLDER"] = _ORIGINAL_UPLOAD_FOLDER+++def teardown_function(function):+ if _ORIGINAL_UPLOAD_FOLDER is not None:+ app.config["UPLOAD_FOLDER"] = _ORIGINAL_UPLOAD_FOLDER+++def teardown_module(module):+ if _ORIGINAL_UPLOAD_FOLDER is not None:+ app.config["UPLOAD_FOLDER"] = _ORIGINAL_UPLOAD_FOLDER+ with app.app_context():+ for u in User.query.filter(User.username.like("sess_%")).all():+ for s in RecordingSession.query.filter_by(user_id=u.id).all():+ db.session.delete(s)+ db.session.delete(u)+ db.session.commit()+++if __name__ == "__main__":+ test_create_session_returns_session_id_and_makes_dir()+ test_create_session_rejects_unsupported_mime_type()+ test_chunk_upload_in_order_succeeds_and_advances_counter()+ test_chunk_upload_out_of_order_returns_409_with_expected_index()+ test_chunk_upload_rejects_empty_body()+ test_finalize_creates_recording_and_enqueues_stitch_job()+ test_finalize_rejects_when_no_chunks()+ test_abort_removes_session_dir()+ test_ownership_enforced_other_user_gets_404()+ test_cleanup_reaps_expired_sessions()+ print("All recording-session tests passed.")diff --git a/tests/test_recording_stitch.py b/tests/test_recording_stitch.pynew file mode 100644index 00000000..036d979c--- /dev/null+++ b/tests/test_recording_stitch.py@@ -0,0 +1,273 @@+"""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.+"""++import os+import shutil+import subprocess+import sys+import tempfile+import uuid++sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))++from src.app import app, db+from src.models import User, Recording, RecordingSession+from src.services.recording_stitch import (+ stitch_recording_session,+ StitchError,+ _chunk_paths,+ _mime_to_extension,+)+++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.++ 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.+ """+ cmd = [+ 'ffmpeg', '-hide_banner', '-loglevel', 'error', '-y',+ '-f', 'lavfi',+ '-i', f'sine=frequency={freq_hz}:duration={duration_seconds}',+ '-ac', '1', '-ar', '16000',+ '-f', 'wav',+ path,+ ]+ subprocess.run(cmd, check=True)+++def _probe_duration(path):+ """Return audio duration in seconds via ffprobe."""+ cmd = [+ 'ffprobe', '-hide_banner', '-loglevel', 'error',+ '-show_entries', 'format=duration',+ '-of', 'default=noprint_wrappers=1:nokey=1',+ path,+ ]+ out = subprocess.run(cmd, check=True, capture_output=True)+ return float(out.stdout.decode().strip())+++def _make_user():+ suffix = uuid.uuid4().hex[:8]+ user = User(+ username=f"stitch_{suffix}",+ email=f"stitch_{suffix}@local.test",+ password="x",+ )+ db.session.add(user)+ db.session.commit()+ return user+++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'+++def test_chunk_paths_returns_sorted_chunks():+ tmp = tempfile.mkdtemp(prefix="speakr-stitch-")+ try:+ # Plant chunks out of name order+ for 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 up+ with 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:+ shutil.rmtree(tmp, ignore_errors=True)+++def test_chunk_paths_empty_dir_returns_empty_list():+ tmp = tempfile.mkdtemp(prefix="speakr-stitch-empty-")+ try:+ assert _chunk_paths(tmp) == []+ finally:+ 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."""+ upload_folder = tempfile.mkdtemp(prefix="speakr-stitch-uploads-")+ with app.app_context():+ app.config["UPLOAD_FOLDER"] = upload_folder+ user = _make_user()++ # 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)++ recording_id, audio_path, metadata = stitch_recording_session(session.id)++ # Output file exists and is playable+ assert 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}"++ # Recording row was updated in place+ rec = db.session.get(Recording, recording_id)+ assert rec.status == 'PENDING'+ assert rec.audio_path == audio_path+ assert rec.file_size and rec.file_size > 0+ assert rec.original_filename++ # Session was marked finalized and its dir was removed+ sess = db.session.get(RecordingSession, session.id)+ assert sess.status == 'finalized'+ assert sess.finalized_at is not None+ assert not os.path.isdir(sess_dir)++ # Cleanup+ try:+ os.remove(audio_path)+ except OSError:+ pass+ db.session.delete(sess)+ 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_folder+ user = _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()++ try:+ stitch_recording_session(session.id)+ assert False, "expected StitchError"+ except StitchError as e:+ assert 'no chunks' in str(e).lower()++ db.session.delete(session)+ db.session.delete(recording)+ db.session.delete(user)+ db.session.commit()+ shutil.rmtree(upload_folder, ignore_errors=True)+++def test_stitch_raises_when_session_missing():+ with app.app_context():+ try:+ stitch_recording_session('00000000-0000-0000-0000-000000000000')+ assert False, "expected StitchError for missing session"+ except StitchError as e:+ assert 'not found' in str(e).lower()+++_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+++def teardown_function(function):+ if _ORIGINAL_UPLOAD_FOLDER is not None:+ app.config["UPLOAD_FOLDER"] = _ORIGINAL_UPLOAD_FOLDER+++def teardown_module(module):+ if _ORIGINAL_UPLOAD_FOLDER is not None:+ app.config["UPLOAD_FOLDER"] = _ORIGINAL_UPLOAD_FOLDER+ with app.app_context():+ for u in User.query.filter(User.username.like("stitch_%")).all():+ for s in RecordingSession.query.filter_by(user_id=u.id).all():+ db.session.delete(s)+ for r in Recording.query.filter_by(user_id=u.id).all():+ if r.audio_path and os.path.exists(r.audio_path):+ try:+ os.remove(r.audio_path)+ except OSError:+ pass+ db.session.delete(r)+ db.session.delete(u)+ db.session.commit()+++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_stitch_raises_when_no_chunks_on_disk()+ test_stitch_raises_when_session_missing()+ print("All stitch tests passed.")