A music, podcast, and sermon player you can use on your phone, in the browser, or desktop.
Built with arkio.
One server, three clients — a desktop program, a page in a browser, and a
phone — and one apply between them: every mutation is written once, in
Rust, and every peer replays the same log. Sign in once per device through
whatever OpenID Connect provider the server is pointed at; take any peer
offline, change things on both sides, come back, and watch the rebase.
One axum program: the sync socket at /sync, the sign-in routes under
/auth/, a health check at /healthz, and — when given one — the
browser client at /. One port for all of it, so a phone or another
laptop needs one address and no CORS.
nix run .#serve # a dev server on 127.0.0.1:8787, no provider
nix run .#serve 0.0.0.0:8787 # …reachable from a phone on the same network
nix build .#harken-server # the binary, at result/bin/harken-server
Point it at a directory and it fills the library from what is in it:
HARKEN_MEDIA=/srv/media nix run .#serve
/srv/media/
music/
Bach/air.flac → /media/music/Bach/air.flac
Music goes in music/. The root is kind-neutral because the file
column is: an episode or a sermon becomes a sibling directory rather
than a second setting and a second URL prefix to configure. Audio
outside music/ is not a track, however much it sounds like one.
It walks music/ at startup, watches the root after — a file copied in
appears without a rescan, and so does a music/ that did not exist
yet — and reads each track's tags rather than guessing them from the
folder names. Every track is added as an ordinary mutation, through the
same apply each peer runs, so the server is a peer here and not a
special case.
Rescanning is free. Adding a file the library already has is refused
inside apply, so restarting the service costs nothing however large
the directory, and two servers scanning the same share agree.
The bytes are served from /media/, with range requests, so seeking
works. What the log carries is each path relative to this directory —
the same string /media/ serves — so moving the directory moves the
media and nothing in the log has to change.
On NixOS that is {option}services.harken.mediaPath, which defaults to
/srv/media and is created, with its music/, on activation.
A dev server takes your word for who you are — nix run .#iced alice
is a login for a name — and says so every time it starts. It refuses to
run that way unless told to (HARKEN_DEV_AUTH=1), because on a machine
anyone else can reach it means anyone can write as anyone.
The flake exports a NixOS module. Point it at a provider and it signs people in for real: the server is the only OpenID Connect client, holds the secret, and hands each signed-in peer a session of its own, so the desktop, the browser and the phone need nothing but this address.
{
inputs.harken.url = "github:k2on/harken";
# in a NixOS configuration:
imports = [ inputs.harken.nixosModules.default ];
services.harken = {
enable = true;
publicUrl = "https://harken.example.com";
oidc = {
issuer = "https://auth.example.com/application/o/harken/";
clientId = "harken";
clientSecretFile = config.age.secrets.harken-oidc.path;
};
};
services.nginx.virtualHosts."harken.example.com" = {
enableACME = true;
forceSSL = true;
locations."/" = {
proxyPass = "http://127.0.0.1:8787";
proxyWebsockets = true;
};
};
}Register https://harken.example.com/auth/callback as the redirect URI
at the provider; the server derives it from publicUrl. The secret is a
file and never a store path: systemd hands it to the service as a
credential, and nothing else on the machine can read it.
services.harken also takes:
web— the browser client to serve at/. Defaults to this flake'sharken-web;nullserves the socket alone.redirects— extra places a login may send its code back to. Every server allows a loopback port (the desktop),harken://(the phone) and its ownpublicUrl(the browser client it serves).address,port,openFirewall— the default binds loopback, for the reverse proxy above to terminate TLS in front of.devAuth— the dev server's behaviour, for a machine nobody else can reach.
The log and the sessions live under /var/lib/harken.
The library in a window, on Linux and macOS. It keeps its own database and works offline; the server is where it syncs and where it signs in.
A sidebar down the left browses the library: the playlists, then the albums, then the artists. Moving onto one shows it — the cursor there is the selection, so nothing needs confirming. The tracks are a table of Name, Artist, Album and Time, and a now-playing bar sits along the bottom. Light or dark follows the system: every color comes from the theme, so there is none to get wrong, and every icon is drawn rather than typed, because the embedded font has no glyph for any of them.
It is driven from the keyboard, with vim's motions: j and k move,
h and l cross between the sidebar, the track list and the player,
5j and gg and 7G do what they do in vim, / searches the pane
you are in, <Enter> opens, <Space> plays or pauses and a says which
playlists a track is on — and makes one. Press ? for the rest.
The bar sounds nothing on the desktop — there is no audio device wired
up, and it says so rather than pretending — so playback is the
browser's today. See CLAUDE.md for what closing that would take.
nix run github:k2on/harken#harken-iced -- --server https://harken.example.com
nix profile install github:k2on/harken#harken-iced # …or keep it around
harken-iced --server https://harken.example.com
On NixOS, as a package:
environment.systemPackages = [
inputs.harken.packages.${pkgs.stdenv.hostPlatform.system}.harken-iced
];The first run opens a browser tab at the provider; the login is kept
under ~/.config/harken/ and the tab is not opened again. Against a dev
server (nix run .#serve) there is no tab: --user alice is honoured
as the name, which is what makes two peers on one laptop two commands.
nix run .#serve # terminal 1
nix run .#iced alice # terminal 2
nix run .#iced bob # terminal 3 — then take one offline and watch them sync
The client compiled to wasm with no server, no sign-in and a seeded
library, published to GitHub Pages on every push to main. It is the
real client — the same apply, the same maintained view, the same
rebase — with a feature that removes the parts needing somewhere to
connect to: there is no sign-in and no going offline, because there is
nothing to be offline from.
Its library is public-domain classical recordings streamed from Wikimedia Commons, so the bar plays. Pick a composer under Artists, or a work under Albums, and press a track.
nix build .#harken-demo # index.html and pkg/, ready to serve
A separate build from the real client rather than a runtime flag: a flag can be set by accident, a feature has to be asked for.
The same program compiled to wasm, in a page. It is served by the
server: services.harken.web on NixOS, or HARKEN_WEB pointed at a
built one, and the page signs in against the origin it came from.
nix build .#harken-web # index.html and pkg/, ready to serve
HARKEN_WEB=result nix run .#serve # …served by the server, at /
nix run .#web # on a laptop: rebuilt and served on :8080
nix run .#web serves the page from a port of its own, so it is told
where the server is: http://localhost:8080/?server=http://127.0.0.1:8787.
Served by the server there is nothing to tell.
What the sidebar picked is in the address bar — #album/Water%20Music — so
the back button goes back, the forward button goes forward, and a link to an
album is a link somebody can send.
An Expo app that calls into the same Rust, so it needs a development
build rather than Expo Go. It signs in through the server too: enter the
server's address, tap sign in, and the provider opens in a sheet that
closes itself when the login comes back on harken://. Once per server
per phone: after that it opens straight into the library, because both
answers that screen wants have already been given.
It plays, too. The library is the same one the desktop shows, browsed
by playlist, album or artist; tapping a row starts it and the list
becomes the queue, and every row opens a sheet of playlists to put it on
or make another. Playback is expo-audio — ExoPlayer on Android,
AVPlayer on iOS — with the transport on the lock screen, so it keeps
going when the screen does not.
nix build .#apk # the development APK, toolchain and all
nix build .#apk-release # the release build (debug-signed; see CLAUDE.md)
nix run .#expo-android # the edit loop, with Metro; needs `nix develop .#android`
Two apps can be installed side by side: dev.harken.koon.us from a
development build and harken.koon.us from a release one.
One description of what the program looks like, in branding/: the
palette, and the mark every icon is made from.
Black and white with gold — #000000 behind a dark theme, #FFFFFF
behind a light one, and one accent that means "this is playing", "this
is hearted", "press this". The two golds are not the same gold: a dark
sheet can take a bright leaf, a white one needs a darker, browner gold
or nothing is legible on it.
Neither client reads a color at run time — one is Rust, the other is
TypeScript — so both are generated from branding/nix/palette.nix:
iced/src/palette.rs the six colors iced generates a theme from
mobile/src/palette.ts the same, as the two tables `theme.ts` picks from
iced/web/favicon.svg the mark, carrying both themes in a media query
They are checked files like README.md: nix run .#write-files writes
them and nix flake check fails while a committed copy differs, which
is what stops the desktop and the phone drifting to two different golds.
The mark is a trumpet — Pictogrammers' Material Design Icons glyph,
vendored unmodified under Apache 2.0 with its licence in
branding/LICENSE.trumpet. Everything around it is here: the angle, the
optical centring on the pixels it inks rather than on its box, the
gradient ground, and the size each platform asks for.
nix build .#icons # every SVG and PNG, in the store
nix run .#icons # …and written into mobile/assets/images/
The rasters are written into the tree rather than consumed from the
store because Expo reads them off disk before nix is involved. They
cannot be checked files the way the palettes are: files compares
strings and a PNG is bytes.