#lang scribble/manual

@(require (for-label racket/base
                     racket/contract
                     rkt-web-player
                     rkt-web-player/player-agent
                     rkt-web-player/users))

@title{RKT Web Player}
@author{Hans van Dijkema}

@defmodule[rkt-web-player]

RKT Web Player combines local playback through @tt{racket-audio}
with UPnP and Sonos discovery and playback through
@tt{racket-audio-dlna}. The user interface is served to a web
browser by Racket's web server.

@defproc[(run-web-player
          [music-paths (listof (or/c path-string?
                                     (list/c string? path-string?)))]
          [#:allowed-agent-ids allowed-agent-ids (listof string?) null]
          [#:users users (listof (cons/c string? string?)) null]
          [#:local-networks local-networks (listof string?)]
          [#:trusted-proxies trusted-proxies (listof string?)]
          [#:session-seconds session-seconds exact-positive-integer? 43200]
          [#:listen-ip listen-ip string? "127.0.0.1"]
          [#:port port exact-positive-integer? 8080]
          [#:dlna-port dlna-port exact-positive-integer? 8734]
          [#:launch-browser? launch-browser? boolean? #t]) any/c] {

Treats every entry in @racket[music-paths] as a separate music library. A
two-element list supplies an explicit display name and path. The
@racket[allowed-agent-ids] list contains the 64-character application IDs that
may register as polling playback agents. All agents are denied when it is empty.
The function
starts the web interface on @racket[listen-ip] and @racket[port]. Directory
contents are browsed one level at a time. Metadata and recursive contents are
only read when the user adds or plays a selected item.

The @racket[dlna-port] is used to publish local audio files to a selected
network renderer. Player resources are closed when the web server exits.

The default listen address only exposes the interface to the local computer.
Use a LAN address deliberately if other devices should control the player.
}

@defmodule[rkt-web-player/users]

@defproc[(make-password-hash [password string?]) string?] {

Creates a salted Argon2id password hash suitable for a value in the INI
@tt{[users]} section. Passwords must contain at least twelve characters.
}

@defproc[(password-hash-valid? [password string?]
                               [encoded string?]) boolean?] {

Checks a password against an encoded Argon2id hash.
}

@defmodule[rkt-web-player/player-agent]

@defproc[(run-player-agent) any/c] {

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 @tt{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.
}