Vocaluxe/VocaluxeWeb/README.md

Vocaluxe WebApp and webserver

Vocaluxe has a built-in webserver. Guests open the WebApp on their phones (scan the QR code shown under Options → Server), add songs to the queue, manage playlists and profiles and use the phone as a remote.

Folder	What it is
VocaluxeWeb	The webserver: ASP.NET Core 2.3 (Kestrel) on .NET Framework 4.8.1, REST API, live events
WebApp	The WebApp: Vue 3, TypeScript and Vite
Vocaluxe/Base/Web	The game side: starts the server (CWebServer) and implements IVocaluxeRemote (CVocaluxeRemote)

Architecture

• VocaluxeWeb does not reference the game. Everything it needs from Vocaluxe goes through the interface IVocaluxeRemote, which CVocaluxeRemote implements in the game.
• Requests run on Kestrel threads, but the game is not thread-safe. Calls into the game are queued with CMainThreadDispatcher and executed once per frame on the main thread (CWebHost.Tick, called from CWebServer.ProcessTasks). A call that is not executed within 5 seconds fails with 503.
• The queue is a normal playlist in the game (default name WebApp Queue). CQueueService keeps who requested a song and who sings it. Songs are inserted fairly: the n-th song of a person goes behind everybody's n-th song. The queue can also be opened and started in the game (song menu → options → playlist group → WebApp queue).
• Live updates (queue, game state, notifications) are sent with Server-Sent Events (GET /api/v1/events).
• Logins are kept in memory (HttpOnly cookie vlx_session, logged out after 12 hours without use). Profiles without PIN log in again automatically after a restart of Vocaluxe.

Roles and permissions

Every profile has a role: Guest, Player or Admin. Admins may do everything; what guests and players may do is set in the WebApp under More → Settings (stored in WebServer.json). Admins can also

• see and log out logged-in devices,
• deactivate and delete profiles,
• see the address, port and HTTPS state of the server (the port is set in config.xml under Server/ServerPort, default 3000; HTTPS is switched in the game under Options → Server).

Profile pictures

A profile picture is either an own photo (uploaded from the phone, saved as WebApp_*.jpg in the profile folder) or one of the avatars that come with Vocaluxe or were put into the profile folder (GET /api/v1/avatars). Uploaded photos of other people are not offered for selection.

Files

Stored in the Vocaluxe data folder:

File	Content
WebServer.json	WebApp settings: permissions, queue playlist name
WebServer.pfx	Self-signed certificate for HTTPS (created on first use)
WebCache	Resized covers and avatars

The built WebApp is copied to the Website folder next to Vocaluxe.exe.

Building

Node.js (LTS, 22.12 or newer) is required. Building the project VocaluxeWeb (or the whole solution) runs npm ci (only when package.json or package-lock.json changed) and npm run build in WebApp. If Node.js is missing, the build stops with a hint. Restart Visual Studio after installing Node.js.

Developing the WebApp

Start Vocaluxe with the webserver switched on, then:

cd WebApp
npm run dev

Vite serves the WebApp with hot reload and forwards /api and /swagger to Vocaluxe at http://localhost:3000. For another address use VOCALUXE_URL=http://192.168.0.10:3000 npm run dev.

REST API

• All endpoints are under /api/v1. Errors are returned as problem details ({ "title": "...", "status": 403 }).
• Swagger UI: http://<address>:3000/swagger, OpenAPI document: /swagger/v1/swagger.json.
• The TypeScript types of the WebApp (WebApp/src/api/schema.d.ts) are generated from the OpenAPI document. After changing the API, start Vocaluxe (or set VOCALUXE_URL) and run npm run api:generate in WebApp.

HTTPS

HTTP is the default. With Options → Server → Server encryption switched on, Vocaluxe uses HTTPS with a self-signed certificate for the computer's name and IP addresses. Browsers do not trust it and show a warning the first time ("Your connection is not private"); the connection is encrypted nevertheless. The WebApp explains this on its help page. Some browser features (camera, installing the WebApp on the home screen) only work over HTTPS. With the self-signed certificate they depend on the browser: some browsers allow them after accepting the warning, others don't.

Translations

The texts of the WebApp are in WebApp/src/locales/<language>.json (flat key/value JSON, en.json is the source). They are translated on Transifex like the game (see transifex.yaml, format KEYVALUEJSON). New languages are picked up automatically when a file is added. Placeholders like {name} must stay unchanged.

Tests

The NUnit tests in Tests/VocaluxeWeb cover PIN hashing, settings and permissions, the fair queue order and the device names shown to admins. They run with the other tests of the Tests project.