VTunedocs

Reference

VTune architecture#

VTune is one Node.js process backed by one SQLite database and one persistent data volume. The process owns five cooperating surfaces:

  1. Discord gateway and voice connections.
  2. Fastify API, Discord OAuth, sessions, and server-sent events.
  3. React dashboard assets served from the production container.
  4. FFmpeg/ffprobe upload conversion and playback pipelines.
  5. SQLite metadata, authorization, invitations, settings, and audit events.

Authorization#

A library track has exactly one owner and starts private. track_group_grants connects a track to zero or more groups. A user can access a track when they are the owner or have an active group_memberships row for at least one granted group. Instance administrators may inspect/delete content for moderation, but moderator visibility does not grant queue permission.

Queue authorization is checked when a library track is enqueued and again when playback starts. Membership, sharing, group, and suspension changes revalidate all active queues. The requester must also be present in the selected Discord voice channel.

Browser session bootstrap#

The dashboard begins with anonymous-safe GET /api/session. A missing, expired, or invalid session returns HTTP 200 with authenticated: false, null user and CSRF fields, and clears stale session cookies. A valid session returns the existing public user DTO and its CSRF token. The response is private and non-cacheable.

Authentication storage failures are not reclassified as anonymous sessions; they retain their server-error response so the branded retry state can surface an outage. Protected GET /api/me remains available for authenticated refresh flows and continues to return HTTP 401 without a valid session.

Storage#

Upload batches create owner-scoped upload_jobs rows before bytes are sent. Browsers stage at most two files concurrently in verified 4 MiB chunks, and SQLite commits the resumable offset only after each chunk checksum succeeds. Queued inputs are inspected with ffprobe and converted by exactly one single-threaded FFmpeg worker to 192 kbps Ogg Opus. FFmpeg progress is published at most twice per second through a payload-free uploads.changed SSE event.

Successful files move atomically to a generated /data/library/<discord-id>/<uuid>.ogg key and their staged input is removed. Failed and cancelled inputs remain retryable for 24 hours. Restart recovery reconciles staged bytes to the last committed offset, requeues interrupted probe/conversion work, and removes orphaned chunk/output files. Only generated keys become filesystem paths; user filenames never do. No HTTP route serves the media tree.

Playback sources#

Queue tracks use a discriminated TrackSource:

  • youtube: yt-dlp refreshes public metadata and streams into FFmpeg.
  • library: SQLite revalidates requester access and FFmpeg decodes the stored Opus file.

Both produce 48 kHz stereo PCM for the existing Discord voice player.

Persistence and migrations#

SQLite uses WAL and foreign keys. The v2 application migration and v3 durable upload migration each create a timestamped, version-preserving backup under /data/backups before changing the schema. Existing users, tracks, sharing, and guild settings are preserved. Upload jobs persist; voice sessions and playback queues intentionally remain in memory.