Server-side recording sessions¶

Server-side recording sessions let the in-browser recorder stream audio chunks to Speakr as they are produced, rather than buffering the entire recording in browser RAM and uploading it at Stop. This unlocks longer recordings, makes crash recovery reliable, and removes the legacy client-side size cap.

Off by default; opt in with ENABLE_SERVER_RECORDING_CHUNKS=true. It is planned to become the default in an upcoming release once it has had wider testing.

What changes when it is on¶

Incognito recordings are the exception: they never open a server session, regardless of this flag. Audio from an incognito recording stays in the browser (RAM + IndexedDB) until the explicit process-without-saving upload, so the legacy 200 MB cap and its warning still apply to them. If a recording did stream to the server and the user switches it to incognito in the review pane afterwards, the server-side chunks are deleted before processing.

Sliced uploads of files on disk¶

The same session machinery also carries uploads of files the user already has on disk. A normal upload is one multipart POST /upload of the whole file, so a reverse proxy whose body limit is below the file size rejects it before Speakr sees it (Cloudflare's proxy caps request bodies at 100 MB on most plans). Any file larger than one slice is instead sent as fixed-size byte slices through POST /upload/session/{id}/chunks/{N} and finalized with POST /upload/session/{id}/finalize-upload, which byte-joins the slices and runs the result through the same ingestion pipeline as a single-shot upload.

This needs no configuration and is not covered by ENABLE_SERVER_RECORDING_CHUNKS, which governs the recorder only. The slice size is RECORDING_SESSION_MAX_CHUNK_BYTES (16 MB), advertised in the create response, and files at or below that size still go up in one request.

A few differences from a recorder session are worth knowing when reading logs:

• Its recording_session row has kind = 'sliced_upload', and each finalize route rejects the other kind with a 409.
• The slices are byte ranges of one complete container, not MediaRecorder timeslices, so finalize does a plain byte-join with no ffmpeg concat, no remux, and no container sniffing. What reaches ingestion is byte-identical to what the user picked, and from there it is treated exactly like a single-shot upload, conversion included.
• The client declares the file size when it opens the session, and finalize refuses to ingest slices that do not add up to it. A missing or short slice fails loudly rather than becoming a truncated recording.
• finalize-upload is synchronous: hashing, probing and any conversion happen in-request exactly as they do for POST /upload, so it holds the connection for as long as that takes and needs the same generous proxy read timeout. A retry after a lost response gets the first call's recording back rather than re-ingesting the file.
• An abandoned one is expired by the cleanup sweep rather than auto-finalized. The user still has the original file, and its slices are a truncated container rather than a playable partial recording.
• A failed finalize deletes the slices with it. They cannot be reused, since finalize only accepts a session that is still recording.

Resuming¶

An upload interrupted by the network is not restarted. The browser keeps the session id in localStorage under the file's identity (name, size, last-modified), so adding the same file again continues from the slice count the server reports rather than from zero, which is what makes the feature usable on a link bad enough to need it.

Only a rejection the server would repeat (an oversize slice, an exhausted quota, slices that do not add up) deletes the session, because retrying that costs the user another full transfer for the same answer. A dropped connection or a timeout leaves the session alone, including when it happens waiting for finalize-upload: the server may be ingesting at that moment, and the retry gets that recording back.

Operationally this means in-progress sliced uploads sit in UPLOAD_FOLDER/_sessions/ for up to RECORDING_SESSION_TTL_HOURS waiting for a resume that may never come, and count against RECORDING_SESSION_MAX_BYTES_PER_USER until the sweep expires them. The browser forgets a session after 24 hours regardless.

Configuration¶

Environment variables, all optional:

Reverse-proxy requirements¶

The chunk-streaming flow exchanges many small POST requests during the recording, plus one longer finalize call. Configure your reverse proxy so neither is killed in flight.

nginx / Nginx Proxy Manager¶

location /upload/session/ {
    # Chunk POSTs are capped at RECORDING_SESSION_MAX_CHUNK_BYTES (16 MB),
    # whether they carry a recorder timeslice or a file slice.
    proxy_pass http://speakr_upstream;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    client_max_body_size 32m;
    proxy_read_timeout 30s;
}

location ~* ^/upload/session/.+/finalize(-upload)?$ {
    # Finalize triggers ffmpeg concat which can take tens of seconds for
    # long recordings, and finalize-upload also hashes, probes and may
    # convert the file in-request. Give it room.
    proxy_pass http://speakr_upstream;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
}

If you do not split per-location, set a single proxy_read_timeout 600s on the parent block. The chunk POSTs are short and won't be affected by the larger timeout; finalize will get the headroom it needs.

Caddy¶

@finalize path_regexp ^/upload/session/[^/]+/finalize(-upload)?$
handle @finalize {
    reverse_proxy speakr:8899 {
        transport http {
            response_header_timeout 10m
        }
    }
}

Apache (mod_proxy)¶

ProxyTimeout 600
LimitRequestBody 33554432

How storage is laid out¶

UPLOAD_FOLDER/_sessions/
  <uuid-1>/
    session.json
    joined.bin              ← sliced uploads only, during finalize
    chunk-000001.bin
    chunk-000002.bin
    ...
  <uuid-2>/
    ...

• session.json is a JSON copy of the database row, written defensively for the case where the database is wiped but the disk survives.
• Chunks are stored under generic .bin extensions; format is determined by the database mime_type column and validated when stitching.
• Aborted sessions are torn down synchronously when the user clicks Discard. Sessions that go quiet for longer than RECORDING_SESSION_TTL_HOURS are reaped by the background cleanup thread, which also removes orphaned session directories that no longer have a database row (for example after a database reset).

Crash recovery¶

The recording client persists a small marker in localStorage (speakr.serverRecordingSession) on session creation. On page reload, Speakr checks the marker against the server: if the session is still in the recording state with at least one chunk on disk, the user is prompted to finalize the in-progress recording or abort it.

A full client-side resume of the open MediaRecorder is not possible because the underlying audio track does not survive a tab reload. The user-visible result is therefore: prompt → finalize the chunks already on the server, or discard them.

Operational health¶

• Disk usage: monitor UPLOAD_FOLDER/_sessions/ size. Long-running cleanup gaps or stuck recording rows can let it grow. The cleanup thread logs a summary line on every sweep that reaps at least one session.
• Peak disk during a sliced finalize: reassembly writes joined.bin alongside the slices it is built from, so a sliced upload briefly needs about twice the size of the file being uploaded. The slices are released once ingestion has taken the joined file. Size UPLOAD_FOLDER for twice your largest expected upload, per upload finalizing at once, and note that the usual reason a finalize fails is that the disk filled during this step. A failed reassembly marks the session failed and removes its slices rather than leaving the full file behind.
• ffmpeg availability: the stitch worker shells out to ffmpeg. If the binary is missing, finalize fails with a clear "ffmpeg binary not found on server PATH" error on the affected recording. Docker images ship ffmpeg by default; bare-metal installs need to ensure it is on PATH for the Speakr user.
• Per-user quota: when _user_bytes_in_progress >= the configured cap, the API returns 507 on POST /upload/session and on chunk uploads that would exceed the cap. Surfaced to the user as a quota banner.
• Deploys interrupt sliced uploads that are ingesting. A sliced upload ingests inside the finalize request, so recreating the container mid-ingest loses that work and leaves the session finalizing with nobody running it. The slices stay on disk, the stamping stops with the container, and about a minute and a half later the user's retry takes the session over and re-ingests from the slices already delivered. A retry inside that window is told the session is being finalized and waits. Slice POSTs and recorder sessions are unaffected: those requests are short, and their retries resume. Still worth timing a deploy for when nothing is uploading, since the interrupted ingest's work is thrown away either way.
• The upload staging directory has no sweeper. An ingest killed mid-flight leaves its staged copy of the file behind, and nothing removes it: the session sweep only owns _sessions/. This is not specific to sliced uploads, POST /upload behaves the same way, but it is worth a glance at UPLOAD_FOLDER/_staging after an incident.

API¶

All endpoints require an authenticated session. The CSRF token from the page meta tag is sent with every request.