2 Command line and INI configuration
The package entry point accepts one or more music directories:
racket main.rkt MUSIC-DIRECTORY [...] |
racket main.rkt --config rkt-web-player.ini --no-browser |
The –config option reads defaults from an INI file. The file is normally named rkt-web-player.ini and is read from the current directory when the server is started with –config. Relative paths are interpreted in the process’s working directory.
Command-line values for –listen-ip, –port, –dlna-port, –playlist-keystore, –log-file and –no-browser override the corresponding defaults. Logging retention, log level, authentication and the playback-agent allowlist are configured in the INI file. Libraries configured under [libraries] use the INI key as their display name and the value as the root directory. The legacy [library] paths setting accepts a semicolon-separated list and is also supported. A complete example is:
[server] |
listen-ip=127.0.0.1 |
port=8080 |
|
[player] |
dlna-port=8734 |
local-output=true |
playlist-keystore=data/playlists.keystore |
|
[logging] |
log-file=data/rkt-web-player.log |
log-retention-days=7 |
log-level=debug |
|
[authentication] |
trusted-proxies=127.0.0.0/8;::1/128 |
session-seconds=604800 |
|
[playback-agents] |
; 64 hexadecimal characters, copied from an agent |
0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef=true |
|
[users] |
; Generate hashes with make-password-hash or set-user. |
hans=$argon2id$v=19$m=19456,t=2,p=1$... |
The [server] section controls the browser server. The default listen-ip is 127.0.0.1, so the interface is local-only by default; 0.0.0.0 or a LAN address makes it reachable from other machines. port defaults to 8080.
The [player] section controls playback. dlna-port defaults to 8734 and must be reachable by network renderers when they play files published by the server. local-output=true (the default) adds the server’s own audio device as an output. playlist-keystore selects the keystore for playlist tabs and language preferences; omission uses data/playlists.keystore below the installed collection. When embedding the player through run-web-player, passing #f disables persistence.
The [logging] section controls the rotating log file. The default file is data/rkt-web-player.log, retention defaults to seven days, and the default level is debug. The level is passed to simple-log; use a level supported by that package.
The [playback-agents] section is a default-deny allowlist. Each key must be the complete 64-character hexadecimal application ID of an agent and a value other than false permits registration. An empty section rejects all agents. This ID is a shared bearer credential, not a replacement for HTTPS.
The [authentication] section enables browser login when [users] has at least one entry. Each user value is an Argon2id hash, not a plaintext password. session-seconds defaults to seven days and is a sliding idle timeout. trusted-proxies is a semicolon-separated list of IP addresses or CIDR ranges whose forwarded client address may be trusted; keep it limited to the actual reverse proxy. The application does not terminate TLS, so use HTTPS at the reverse proxy before exposing an authenticated instance beyond a trusted LAN.
Create a password hash with make-password-hash, or run set-user in the directory containing the INI file. The set-user procedure updates rkt-web-player.ini interactively.
2.1 Playback-agent INI file
The GUI and CLI agents use a separate private INI file named rkt-web-player-agent.ini in the user’s Racket configuration directory. It contains the following values:
[server] |
url=http://127.0.0.1:8080 |
|
[agent] |
name=My playback |
app-id=64 hexadecimal characters |
The agent generates app-id once and reuses it so the server allowlist continues to work. The GUI writes the server URL and display name; the CLI can override them with –server and –name. Use –config with the CLI to select another agent INI file and therefore another identity. Agents make only outbound HTTP requests: they register and poll the server, download assigned tracks, and play them locally. They do not open an inbound port.
| (require rkt-web-player/users) | package: rkt-web-player |
Creates a salted Argon2id password hash suitable for a value in the INI [users] section. Passwords must contain at least twelve characters. }
Checks a password against an encoded Argon2id hash. }
| (require rkt-web-player/set-user) | package: rkt-web-player |
procedure
(set-user) → void?
Interactively reads a username and password and writes the corresponding Argon2id hash to the [users] section of "rkt-web-player.ini" in the current directory. The password must contain at least twelve characters. }
| (require rkt-web-player/player-agent) | |
| package: rkt-web-player | |
procedure
Starts the graphical polling playback agent. The agent keeps a generated 256-bit application identifier in a user-specific INI file, registers with the configured RKT Web Player server, downloads assigned tracks over HTTP, and plays them with racket-audio. Its configured display name is authoritative and is followed by the server. Importing the module does not start the GUI; the function must be called explicitly. During downloads, including prefetching the next track, the GUI shows the filename and received megabytes. When the server supplies the file size, it also shows the total size, percentage and a progress bar. The display updates every half second and disappears when the download finishes or fails. Interrupted downloads are retried twice, starting again from the beginning. After 60 seconds without incoming media data, the agent aborts the attempt instead of waiting indefinitely. If all three attempts fail, a failed play returns to the stopped state and the GUI displays the error, including byte counts for an incomplete file. Background prefetching and audio status updates preserve this message; a new playback command clears it. Polling continues, so subsequent commands can still be processed. The GUI and its racket-tray system tray support the same ten languages based on the operating-system language, with English as fallback. Closing or minimizing the window hides it in the tray. The tray menu restores the window or shuts down the agent; no SDL3 runtime is required. }
procedure
(run-player-agent-cli [ #:server-url server-url #:name name #:config-file config-file]) → void? server-url : (or/c string? #f) = #f name : (or/c string? #f) = #f config-file : (or/c path-string? #f) = #f
Starts a headless playback agent using the same audio and gapless-prefetch runtime as the GUI. Missing keyword values are read from the normal agent INI file. The procedure runs until interrupted. }