Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 27 additions & 19 deletions CONTRIBUTING.md

Large diffs are not rendered by default.

25 changes: 16 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,31 +12,36 @@ Libras is a browser-based minimalistic music player that connects to your own mu

## Features

- Browse artists, albums, and tracks.
- Browse and search artists, albums, and tracks together in Library, with shareable multi-select type filters. Older Search links keep their criteria.
- Stream music from your own server.
- Download music for offline playback and manage it in Settings → Downloads.
- Restore your playback queue and position between sessions.
- Restore this device’s playback queue and position between sessions, without autoplay.
- Explicitly Load server queue or Save queue to server from Queue in navigation. Startup, reconnect, library refresh and playback never exchange server queues. Loading confirms replacement and stops playback only after a valid result arrives; failed/stale loads leave local state intact. Saving an empty queue confirms clearing the server queue. Duplicate and unavailable IDs are retained; Subsonic selection uses a track ID, so duplicate occurrences are ambiguous (the local occurrence is retained when membership matches, otherwise the first match is selected). The demo has no server queue exchange.
- Install as a standalone web app.

## Get started

1. Open [Libras](https://libras-music.app/webapp/).
2. Connect to your music server with your server address, username, and password.
3. Browse your library and start listening.
3. Browse or search Library and start listening. Settings links back to the focused connection screen for sign-in.

**Play now** replaces the queue with that track only, or the chosen collection in its current scope. **Play next** inserts after the selected occurrence; **Add to queue** appends. Neither starts an inactive queue. Queue removal preserves other occurrences (including duplicates and unavailable tracks); removing the selected occurrence stops playback without choosing a replacement.

Just trying it out? Connect to the [Navidrome demo server](https://demo.navidrome.org/) using `https://demo.navidrome.org` as the server address and `demo` as both the username and password.

You'll need a reachable **HTTPS server with a Subsonic-compatible API**, such as [Navidrome](https://www.navidrome.org/), supporting OpenSubsonic's empty-query `search3` for library synchronization and configured to allow browser requests from `https://libras-music.app` (CORS). Libras is a player, not a music hosting service; bring your own server and library.

### Browser support

Safari 26.0 or newer is required; older Safari versions are not supported. The app uses native URLPattern and OPFS writable files. Safari 26.0–26.1 load Navigation API and invoker commands polyfills on demand; Safari 26.2+ use the native APIs. The dialog `closedby` polyfill and relative `rgb()` colors remain necessary for Safari 26. The standalone styleguide uses native browser features without polyfills.
Safari 26.0 or newer is required; older Safari versions are not supported. The app uses native URLPattern, OPFS writable files, and Web Locks. Without Web Locks, account activation is blocked rather than risking conflicting writes. Safari 26.0–26.1 load Navigation API and invoker commands polyfills on demand; Safari 26.2+ use the native APIs. The dialog `closedby` polyfill and relative `rgb()` colors remain necessary for Safari 26. The standalone styleguide uses native browser features without polyfills.

### Authentication and device storage

Libras tries salted token authentication first; your password stays in the browser for that attempt. Only a structured server rejection of token authentication (Subsonic code 41 or 42) automatically retries the same username and password over HTTPS, including on localhost. Invalid credentials, connection failures, and other errors never trigger a password retry.

Credentials persist in **localStorage** until you disconnect. Token login saves the username, token, and salt, not your password. Successfully verified direct-password login saves the actual password and sends it with subsequent requests, including artwork and streaming URLs. HTTPS encrypts transport, not localStorage; scripts running on the app's origin and anyone with access to your browser profile can read saved credentials. Use a trusted device and server, and disconnect on shared devices. Disconnect removes credentials but retains your offline account, music, and queue.
New connections keep credentials **in memory only** by default. Reloading retains your credential-free offline identity, music, and queue, but requires signing in again for server access. Select **Remember this device** only on a trusted device to save verified credentials in localStorage after the account workspace is accepted. Existing remembered credentials remain recognized until you disconnect or explicitly opt out; they are not silently deleted on startup. This choice controls Libras storage, not your browser’s password manager.

Remembered token login saves username/token/salt, not your password. Verified direct-password fallback saves the actual password and sends it with subsequent requests, including artwork and streaming URLs. HTTPS encrypts transport, not localStorage; same-origin scripts and anyone with access to your browser profile can read saved credentials. Disconnect removes credentials but retains offline identity/data unless you also choose local deletion.

## Install

Expand All @@ -46,15 +51,17 @@ You can use Libras in your browser or install it as a standalone web app:
- **Android:** Choose **Install app / Add to home screen** from the browser menu.
- **Desktop:** Use the browser's install option, where available.

Installation options vary by browser and device. Offline storage and background playback have not yet been verified on iOS.
Installation options vary by browser and device. Offline storage and background playback have not yet been verified on iOS. Physical iPhone validation is **NOT PERFORMED / PENDING DEVICE ACCESS**; see the [Safari and installed-mode validation protocol](docs/iphone-validation.md).

## Listen offline

Download music while online, then switch to **Offline Library** to listen without a connection.
Download music while connected, then choose **Work offline** in navigation or Settings. This turns off all server access, stops remote playback and pauses requested downloads while retaining their queued intent. Cached playback can continue. Choose **Connect** to resume queued downloads; failed jobs require Retry. Reconnecting never loads or saves the server queue.

**Library scope → All music / Downloaded** is independent of the connection. Downloaded filters browsing and search without disconnecting or changing your queue, position or active audio. All music can browse saved metadata offline; uncached tracks remain visible as unavailable.

- **Manage downloads:** Settings → Downloads.
- **Manage downloads:** Downloads in navigation (also linked from Settings). Totals count registered completed audio bytes, not total browser storage. Remove individual formats, or confirm **Remove all downloaded music** for this account. Queue membership and server files stay unchanged; pending jobs use the separate Cancel downloads action. Removing an active cached source stops/unloads it. Catalog deletion must succeed before bytes are reclaimed; failures remain visible for retry.
- **Refresh library:** Automatic when opening online, or via Settings → Refresh library.
- **Disconnect:** Clears credentials and optionally deletes this account’s local cache and downloads. Remembered identity, preferences, other accounts and server data are unchanged. Close other Libras tabs before deleting local data.
- **Disconnect:** Clears credentials and optionally deletes this account’s local cache and downloads. Remembered identity, preferences, other accounts and server data are unchanged. Only one tab can open an account’s local data at a time, including while deleting it. A second tab is blocked: close the owning tab, then select **Retry**. There is no automatic takeover or live cross-tab queue replication.
- **Storage:** Each server/account has its own offline library, saved only in this browser on this device. **Clearing site data deletes it.**

## App updates
Expand Down
28 changes: 28 additions & 0 deletions docs/iphone-validation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Physical iPhone playback and recovery validation

**Result: NOT PERFORMED / PENDING DEVICE ACCESS.** No physical iPhone is available in the automated environment. Desktop Chromium or automated WebKit results do not establish iPhone background playback, lock-screen integration, or installed-mode behavior.

Run this protocol separately in Safari and Add to Home Screen installed mode, on the same tested HTTPS origin. Use a disposable account and retain sanitized observations; never include credentials or credential-bearing media URLs.

## Record

- Date/tester, device model, iOS build, Safari version, browser or installed mode.
- App commit/build, origin/base path, server/version and CORS setup.
- Raw audio codec/container and duration; transcoded format and server settings.
- For each step: PASS / FAIL / NOT RUN, actual behavior, timestamps, sanitized logs, and reproduction steps. Do not replace this pending result without device evidence.

## Protocol (both modes)

1. Connect to a reachable HTTPS/CORS-enabled server. Play supported raw audio, then a source requiring transcoding fallback. Verify pause, resume, seek forward/backward and track changes. Record any activation-required error and explicit Play retry.
2. Check Media Session title/artwork, lock-screen play/pause/next/previous, screen lock and background playback. Navigate within the app and return from another app; confirm queue/position and that audio is not duplicated.
3. Interrupt with a call/alarm/another audio app. Switch speaker/headphones/Bluetooth output, disconnect the output, then return to the foreground and retry explicitly if required. Record OS-specific pause/resume behavior rather than assuming automatic recovery.
4. Download music to completion. Choose Work offline and airplane mode. Play and seek cached audio, including after pausing/resuming. Confirm uncached queue entries remain visible/removable and unavailable, without silently rewriting the queue.
5. Pause at a known position, background/close and relaunch. Verify saved selection/position, **no autoplay**, then explicit Play offline. Repeat in installed mode. Distinguish normal relaunch from OS termination/eviction; storage and the last uncheckpointed edit are not guaranteed after eviction.
6. Interrupt an active queued download by Work offline, network loss, and app termination (separate trials). Reconnect explicitly. Queued jobs restart from scratch; failed jobs require Retry. Verify playable completed files, correct byte totals, and no phantom completed records or corrupt audio.
7. Lose the network during remote playback/load/seek. Verify honest failure/interruption and explicit recovery after reconnect. Confirm cached playback still works and reconnection never replaces the local queue. Test explicit Load/Save server queue separately; load must not autoplay.
8. With an update waiting, decline/dismiss first: no reload. Approve Update now: only this approving document reloads, route and durable local queue/position survive, playback does not autoplay. Repeat with an already-installed update while offline and a second unapproved tab.
9. Open the same account in another tab: activation is blocked. Close the owner, choose Retry, and verify local queue/resume. Disconnect without deletion: credentials disappear but offline music remains. Reconnect, cancel/Escape local removal, then confirm deletion: this account's bytes disappear and active cached audio unloads; other accounts/server data remain unchanged.

## Evidence and limitations

Attach one result table per mode and raw/transcoded source, with failures and unrun steps explicit. Include sanitized console/service-worker observations where available, output-device details, time spent backgrounded/locked, and any OS eviction or termination. A successful short run is not a guarantee of indefinite iOS background execution or durable storage retention.
46 changes: 27 additions & 19 deletions src/_album.svelte
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
<script lang="ts">
import Icon from "./icon.svelte";
import LibraryScope from "./ui/library-scope.svelte";
import type { Cache, Immutable } from "./cache.svelte";
import type { Covers } from "./covers.svelte";
import Artwork from "./ui/artwork.svelte";
Expand Down Expand Up @@ -35,32 +36,29 @@
appName = "Libras",
}: Props = $props();

const offlineMode = $derived(session.offlineMode);
const offlineMode = $derived(session.downloadedOnly);
const loading = $derived(!session.localReady);
const libraryAvailable = $derived(cache.savedAt !== undefined);
const currentTrack = $derived(cache.tracks.get(cache.queue.tracks[cache.queue.index]));
const album = $derived(params.albumId ? cache.albums.get(params.albumId) : undefined);
const albumPlaybackState = $derived(
album && currentTrack?.albumId === album.id ? playbackState : undefined,
);
const albumCanPause = $derived(
albumPlaybackState === "playing" || albumPlaybackState === "loading",
);
const artist = $derived(album ? cache.artists.get(album.artistIds[0]) : undefined);
const atmosphere = $derived(album?.artworkId ? covers.ensureCover(album.artworkId) : undefined);
const visibleTracks = $derived(
album
? offlineMode
? (cache.albumTracks.get(album.id) ?? []).filter(
(track) => trackEngine.getStatus(track.id) === "downloaded",
? (cache.albumTracks.get(album.id) ?? []).filter((track) =>
trackEngine.isDownloaded(track.id),
)
: (cache.albumTracks.get(album.id) ?? [])
: [],
);
const visibleTrackIds = $derived(visibleTracks.map((track) => track.id));

function playTrack(track: Immutable<Track>) {
void playback.replaceQueueAndPlay(visibleTrackIds, visibleTrackIds.indexOf(track.id));
void playback.replaceQueueAndPlay([track.id]);
}

let menuTrackId = $state<string>();
Expand All @@ -86,6 +84,8 @@
<svelte:head><title>{album?.title ?? "Album"} | {appName}</title></svelte:head>

<Atmosphere src={libraryAvailable && artist && album ? atmosphere?.source : undefined} />
<LibraryScope {session} />
{#if playback.queueMessage}<p class="caption" role="status">{playback.queueMessage}</p>{/if}
<section class="split-layout" aria-label="Album details">
{#if libraryAvailable && artist && album}
<div class="detail-panel view-slide-up">
Expand All @@ -102,18 +102,16 @@
<button
class="button"
data-variant="primary"
aria-label={`${albumCanPause ? "Pause" : "Play"} ${album.title}`}
aria-label={`Play now ${album.title}`}
aria-busy={albumPlaybackState === "loading"}
disabled={!albumPlaybackState && !visibleTrackIds.length}
onclick={() => {
if (albumPlaybackState) void playback.toggle();
else void playback.replaceQueueAndPlay(visibleTrackIds);
}}
disabled={!visibleTrackIds.length ||
(session.offlineMode && !trackEngine.isDownloaded(visibleTrackIds[0]))}
onclick={() => void playback.replaceQueueAndPlay(visibleTrackIds)}
>
{#if albumPlaybackState === "loading"}
<Loader />
{:else}
<Icon name={albumCanPause ? "pause" : "play"} />
<Icon name="play" />
{/if}
</button>
<button
Expand Down Expand Up @@ -188,14 +186,23 @@
</span>
<div>
<p class="label">{track.title}</p>
{#if session.offlineMode && !trackEngine.isDownloaded(track.id)}
<p class="caption text-secondary" id={`unavailable-${index}`}>
Unavailable offline
</p>
{/if}
{#if credit && credit !== (album.displayArtist ?? artist.name).trim()}
<p class="caption text-secondary">{credit}</p>
{/if}
</div>
<button
class="button-quiet link-target"
aria-label={`${currentTrack?.id === track.id && playbackState !== "paused" ? "Pause" : "Play"} ${track.title}`}
onclick={() => playback.toggleTrack(track.id, visibleTrackIds)}
aria-label={`Play now ${track.title}`}
disabled={session.offlineMode && !trackEngine.isDownloaded(track.id)}
aria-describedby={session.offlineMode && !trackEngine.isDownloaded(track.id)
? `unavailable-${index}`
: undefined}
onclick={() => playTrack(track)}
data-longpressfor="album-detail-menu"
data-longpress="show-modal"
onfocus={() => (menuTrackId = track.id)}
Expand Down Expand Up @@ -291,15 +298,16 @@
<div class="stack-sm">
<button
class="menu-item"
disabled={!menuTrackIds.length}
disabled={!menuTrackIds.length ||
(session.offlineMode && !trackEngine.isDownloaded(menuTrackIds[0]))}
onclick={() => {
if (menuTrack) playTrack(menuTrack);
else void playback.replaceQueueAndPlay(menuTrackIds);
dismissActions();
}}
>
<Icon name="play" />
<span>Play</span>
<span>Play now</span>
</button>
<button
class="menu-item"
Expand All @@ -321,7 +329,7 @@
}}
>
<Icon name="plus" />
<span>Play last</span>
<span>Add to queue</span>
</button>
<button
class="menu-item"
Expand Down
Loading
Loading