Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
"""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.
The same session machinery also carries sliced uploads of files the user
already has on disk, so those can cross a reverse proxy with a body-size
limit below the file size. ``kind`` says which of the two a session is.
A sliced upload's chunks are fixed-size byte slices of one complete
container rather than MediaRecorder timeslices, so it finalizes through
the normal upload ingestion path (plain byte-join, no stitch, no remux)
and is never auto-finalized when abandoned: the user's original file
still exists, so there is nothing to recover.
"""
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 or ingestion hit a permanent error
)
RECORDING_SESSION_KINDS = (
'recorder', # in-app recorder streaming MediaRecorder timeslices
'sliced_upload', # byte slices of a file the user already has on disk
)
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')
kind = db.Column(db.String(20), nullable=False, default='recorder', index=True)
upload_filename = db.Column(db.String(255), nullable=True)
upload_total_bytes = db.Column(db.BigInteger, nullable=True)
# 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])
@property
def is_sliced_upload(self):
return self.kind == 'sliced_upload'
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,
'kind': self.kind,
'upload_filename': self.upload_filename,
'upload_total_bytes': self.upload_total_bytes,
'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,
}