8000 GitHub - k2on/harken · GitHub
[go: up one dir, main page]

Skip to content
k2onPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Harken

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.

The server

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

The media ABEB directory

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.

On NixOS, with OpenID Connect

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's harken-web; null serves 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 own publicUrl (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 desktop client

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 demo

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 browser client

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.

The phone

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.

Branding

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.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0