Skip to content

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.py
new file mode 100644
index 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.py
index 7ff0df65..6915e258 100644
--- a/src/app.py
+++ b/src/app.py
@@ -624,6 +624,7 @@ from src.api.events import events_bp, init_events_helpers
from src.api.system import system_bp, init_system_helpers
from src.api.push_notifications import push_bp
from 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_required
diff --git a/src/config/startup.py b/src/config/startup.py
index 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 scheduler
initialize_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__.py
index 2a82004f..8d23e6c0 100644
--- a/src/models/__init__.py
+++ b/src/models/__init__.py
@@ -29,6 +29,7 @@ from .system import SystemSetting
from .audit import ShareAuditLog
from .push_subscription import PushSubscription
from .processing_job import ProcessingJob
+from .recording_session import RecordingSession, RECORDING_SESSION_STATUSES
from .token_usage import TokenUsage
from .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.py
new file mode 100644
index 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.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.")