Skip to content
Open
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
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ Routes use the bare query, for example `/webapp/?/library/artist/123#section`. E
### Persistence and account safety

- Read Cache collections directly; change them through explicit methods. Session owns account details; Cache accepts an opaque account key and hashes it for storage. An undefined key creates an empty, non-persisting fallback. A defined key does not mean hydration succeeded.
- Library, queue, playlist, and image memory updates checkpoint asynchronously. Downloads instead await explicit queued/failed/completed commits in one versioned store; failed jobs require explicit Retry or a bulk Download action. Interrupted queued jobs restart from scratch, never adopting unregistered bytes. Successful byte close wins cancellation while completed metadata commits; cancellation joins that work. Unknown queued/failed job fields, including old attempts, are ignored on load and omitted on subsequent writes; orphan-file reclamation after old attempts or abrupt termination is intentionally out of scope. Offline library limits browsing/listening, not requested downloads. Do not treat visible state as proof of persistence. Unreadable download documents are preserved, not reset; readable saved files remain usable.
- Library, queue, playlist, and image memory updates checkpoint asynchronously. Downloads instead await explicit queued/failed/completed commits in one versioned store; failed jobs require explicit Retry or a bulk Download action. Interrupted queued jobs restart from scratch, never adopting unregistered bytes. Successful byte close wins cancellation while completed metadata commits; cancellation joins that work. Unknown queued/failed job fields, including old attempts, are ignored on load and omitted on subsequent writes; orphan-file reclamation after old attempts or abrupt termination is intentionally out of scope. Work offline disables all server domains and pauses queued downloads, retaining durable intent. One Network-owned connection serves every domain; reconnect resumes queued, never failed jobs. All music/Downloaded is a separate browsing preference and never filters or rewrites the queue. Cached playback may continue offline; remote playback stops. Do not treat visible state as proof of persistence. Unreadable download documents are preserved, not reset; readable saved files remain usable.
- Credentials use localStorage only, until disconnect. Token login stores username/token/salt; verified direct-password fallback stores the actual password. localStorage is not encrypted and is readable by same-origin scripts. Never log credentials or credential-bearing URLs. Legacy token records migrate without changing account keys; migration writeback is best-effort.
- Disconnect retains local data for offline use. Same-account reconnects reuse the live cache to preserve edits. Account changes drain old writes and retire resources before committing the new workspace. Late results must not leak into a different account.
- Startup and manual refresh pull library/artwork/playlist state only. The device queue is authoritative: no automatic server queue reads or writes on startup, refresh, reconnect, progress, pause or visibility changes. Local resume checkpoints remain automatic. Queue in navigation opens Now Playing even when empty/stopped; only confirmed Load server queue and explicit Save queue to server exchange queues. Empty saves confirm clearing the server queue. One exchange runs at a time; local edits remain available. Loads discard stale account/connection/revision/playback results and never autoplay. Saves send a stable starting snapshot without changing local playback. Subsonic selects by track ID, not occurrence: retain a matching local occurrence when membership matches, otherwise select the first match. Preserve unknown IDs. Demo exchange controls are disabled.
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,9 @@ Installation options vary by browser and device. Offline storage and background

## 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.
- **Refresh library:** Automatic when opening online, or via Settings → Refresh library.
Expand Down
17 changes: 14 additions & 3 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,7 +36,7 @@
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]));
Expand All @@ -51,8 +52,8 @@
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) ?? [])
: [],
Expand Down Expand Up @@ -86,6 +87,7 @@
<svelte:head><title>{album?.title ?? "Album"} | {appName}</title></svelte:head>

<Atmosphere src={libraryAvailable && artist && album ? atmosphere?.source : undefined} />
<LibraryScope {session} />
<section class="split-layout" aria-label="Album details">
{#if libraryAvailable && artist && album}
<div class="detail-panel view-slide-up">
Expand Down Expand Up @@ -188,13 +190,22 @@
</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}`}
disabled={session.offlineMode && !trackEngine.isDownloaded(track.id)}
aria-describedby={session.offlineMode && !trackEngine.isDownloaded(track.id)
? `unavailable-${index}`
: undefined}
onclick={() => playback.toggleTrack(track.id, visibleTrackIds)}
data-longpressfor="album-detail-menu"
data-longpress="show-modal"
Expand Down
10 changes: 6 additions & 4 deletions src/_artist.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 @@ -34,7 +35,7 @@
}: Props = $props();

const loading = $derived(!session.localReady);
const offlineMode = $derived(session.offlineMode);
const offlineMode = $derived(session.downloadedOnly);
const libraryAvailable = $derived(cache.savedAt !== undefined);
const artist = $derived(params.artistId ? cache.artists.get(params.artistId) : undefined);
const atmosphere = $derived(artist?.artworkId ? covers.ensureCover(artist.artworkId) : undefined);
Expand All @@ -53,8 +54,8 @@
const visibleAlbums = $derived(
offlineMode
? albums.filter((album) =>
(cache.albumTracks.get(album.id) ?? []).some(
(track) => trackEngine.getStatus(track.id) === "downloaded",
(cache.albumTracks.get(album.id) ?? []).some((track) =>
trackEngine.isDownloaded(track.id),
),
)
: albums,
Expand All @@ -63,7 +64,7 @@

function availableTrackIds(items: readonly Immutable<Track>[]) {
return items
.filter((track) => !offlineMode || trackEngine.getStatus(track.id) === "downloaded")
.filter((track) => !offlineMode || trackEngine.isDownloaded(track.id))
.map((track) => track.id);
}

Expand All @@ -85,6 +86,7 @@
<svelte:head><title>{artist?.name ?? "Artist"} | {appName}</title></svelte:head>

<Atmosphere src={libraryAvailable && artist ? atmosphere?.source : undefined} />
<LibraryScope {session} />
<section class="split-layout" aria-label="Artist details">
{#if libraryAvailable && artist}
<div class="detail-panel view-slide-up">
Expand Down
3 changes: 3 additions & 0 deletions src/_downloads.svelte
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,9 @@
{counts.downloaded === 1 ? "track" : "tracks"} available for offline listening, {counts.pending}
pending
</p>
{#if trackEngine.waitingForConnection && trackEngine.downloadCount}
<p class="body">Paused while working offline</p>
{/if}
<div class="row-sm row-wrap">
<button
class="button"
Expand Down
12 changes: 7 additions & 5 deletions src/_library.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 @@ -34,12 +35,12 @@
const tracks = $derived(menuArtist ? artistTracks(menuArtist) : []);
const availableTrackIds = $derived(
tracks
.filter((track) => !offlineMode || trackEngine.getStatus(track.id) === "downloaded")
.filter((track) => !offlineMode || trackEngine.isDownloaded(track.id))
.map((track) => track.id),
);

const loading = $derived(!session.localReady);
const offlineMode = $derived(session.offlineMode);
const offlineMode = $derived(session.downloadedOnly);
const libraryAvailable = $derived(cache.savedAt !== undefined);
const libraryError = $derived(
session.refreshError ||
Expand All @@ -50,7 +51,7 @@
const visibleArtists = $derived(
offlineMode
? artists.filter((artist) =>
artistTracks(artist).some((track) => trackEngine.getStatus(track.id) === "downloaded"),
artistTracks(artist).some((track) => trackEngine.isDownloaded(track.id)),
)
: artists,
);
Expand All @@ -71,6 +72,7 @@

<section aria-labelledby="library-heading">
<h1 class="visually-hidden" id="library-heading">Your library</h1>
<LibraryScope {session} />
{#if session.loadingAfterConnect}
<div class="library-loading" role="status">
<Loader size="xl" />
Expand Down Expand Up @@ -161,7 +163,7 @@
{:else if !loading}
<div class="stack-md">
<h3 class="heading-sm">
{offlineMode ? "No downloaded artists." : "No artists found."}
{offlineMode ? "No downloaded music." : "No artists found."}
</h3>
<p class="body">
{offlineMode
Expand All @@ -180,7 +182,7 @@
{libraryError || "Add your music server to start listening."}
</p>
<div class="row-sm">
{#if libraryError && session.auth && !offlineMode}
{#if libraryError && session.auth && !session.offlineMode}
<button
class="button"
data-size="text"
Expand Down
25 changes: 18 additions & 7 deletions src/_search.svelte
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,7 @@

<script lang="ts">
import Icon from "./icon.svelte";
import LibraryScope from "./ui/library-scope.svelte";
import { getSearchParameters, navigate } from "./router.svelte";
import { onVisible } from "./viewport";
import type { Cache } from "./cache.svelte";
Expand Down Expand Up @@ -174,7 +175,7 @@
cache.artists,
cache.albums,
cache.tracks,
session.offlineMode ? isAvailable : undefined,
session.downloadedOnly ? isAvailable : undefined,
),
);

Expand Down Expand Up @@ -221,7 +222,7 @@
);

function isAvailable(id: string) {
return !session.offlineMode || trackEngine.getStatus(id) === "downloaded";
return !session.downloadedOnly || trackEngine.isDownloaded(id);
}

let menuSelection = $state.raw<{
Expand Down Expand Up @@ -277,7 +278,7 @@
if (group === "Artists") {
const albums = (cache.artistAlbums.get(record.id) ?? []).filter(
(album) =>
!session.offlineMode ||
!session.downloadedOnly ||
(cache.albumTracks.get(album.id) ?? []).some((track) => isAvailable(track.id)),
);
const count = albums.reduce(
Expand Down Expand Up @@ -318,6 +319,7 @@
<svelte:head><title>Search | {appName}</title></svelte:head>

<section class="stack-lg scroll-runway">
<LibraryScope {session} />
<h1 class="heading-lg uppercase">Search</h1>
<div class="card stack-md">
<search class="stack-xs">
Expand Down Expand Up @@ -379,15 +381,15 @@
<h2 class="heading-sm">
{cache.savedAt === undefined
? "Connect your library"
: session.offlineMode
? "No downloaded music to search."
: session.downloadedOnly
? "No downloaded music."
: "Your library is empty."}
</h2>
<p class="body">
{cache.savedAt === undefined
? "Add your music server to start searching."
: session.offlineMode
? "Download music from the library to search offline."
: session.downloadedOnly
? "Choose All music to browse all saved metadata."
: "Your music will appear here after synchronization."}
</p>
<div class="row-sm">
Expand Down Expand Up @@ -429,6 +431,11 @@
<Artwork {covers} id={record.artworkId} size="sm" />
<div>
<p class="label">{record.title}</p>
{#if track && session.offlineMode && !trackEngine.isDownloaded(track.id)}
<p class="caption text-secondary" id={`unavailable-${record.id}`}>
Unavailable offline
</p>
{/if}
<p class="caption text-secondary">{supportingText(group, record)}</p>
</div>
</div>
Expand All @@ -450,6 +457,10 @@
data-longpressfor="search-menu"
data-longpress="show-modal"
onfocus={() => selectMenu(group, record.id)}
disabled={session.offlineMode && !trackEngine.isDownloaded(record.id)}
aria-describedby={session.offlineMode && !trackEngine.isDownloaded(record.id)
? `unavailable-${record.id}`
: undefined}
onclick={() => playback.toggleTrack(record.id, trackContext(record.id))}
></button>
{/if}
Expand Down
39 changes: 17 additions & 22 deletions src/_settings.svelte
Original file line number Diff line number Diff line change
Expand Up @@ -360,37 +360,32 @@
id="settings-offline-card"
aria-labelledby="settings-offline-title"
>
<div class="row-md row-justify">
<h2 class="heading-md uppercase" id="settings-offline-title">
<label for="settings-offline">Offline library</label> is {session.offlineMode
? "on"
: "off"}
</h2>
<input
class="switch"
id="settings-offline"
type="checkbox"
role="switch"
<h2 class="heading-md uppercase" id="settings-offline-title">Connection</h2>
<p class="label">
{session.busy ? "Connecting…" : session.offlineMode ? "Working offline" : "Connected"}
</p>
{#if session.auth}
<button
class="button"
data-size="text"
data-variant="secondary"
disabled={session.busy}
aria-describedby="settings-offline-help"
checked={session.offlineMode}
disabled={!session.auth || session.busy}
onchange={(event) => void session.setOfflineMode(event.currentTarget.checked)}
/>
</div>
onclick={() => void session.setOfflineMode(!session.offlineMode)}
>{session.offlineMode ? "Connect" : "Work offline"}</button
>
{/if}
<p class="body" id="settings-offline-help">
{#if !session.auth}
{demo
? "Reload the demo to browse online. Any previews you kept remain available."
: "Connect to a server to browse online. Any music you kept remains available."}
{:else if session.offlineMode}
Showing downloaded music only. Turn this off to browse and stream {demo
? "demo previews"
: "from your server"}.
Server access is off. Requested downloads are paused.
{:else}
Browse your full library and stream {demo ? "demo previews" : "from your server"}. Turn
this on to show downloaded music only.
Server access is on. Choose Downloaded in Library scope to browse saved music without
disconnecting.
{/if}
Requested downloads continue when connected, including with Offline library on.
</p>
<div class="row-sm">
<a class="button" data-size="text" data-variant="secondary" href="?/downloads"
Expand Down
23 changes: 22 additions & 1 deletion src/app.svelte
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@
selection,
tracks: trackEngine,
covers,
isAvailable: (id) => !offlineMode || trackEngine.getStatus(id) === "downloaded",
isAvailable: (id) => !offlineMode || trackEngine.isDownloaded(id),
});
const player = new AudioTransport({
onposition: (position) => playback.setPosition(position),
Expand Down Expand Up @@ -249,6 +249,27 @@
Settings
</a>
</nav>
<section class="stack-sm" aria-label="Connection">
<p class="caption text-secondary">
{session.busy ? "Connecting…" : offlineMode ? "Working offline" : "Connected"}
</p>
{#if session.busy}
<button
class="menu-item"
onclick={() => (session.auth ? void session.setOfflineMode(true) : session.cancelConnect())}
>Cancel</button
>
{:else if session.auth}
<button class="menu-item" onclick={() => void session.setOfflineMode(!offlineMode)}
>{offlineMode ? "Connect" : "Work offline"}</button
>
{:else}
<a class="menu-item" href="?/settings" onclick={() => navigationDrawer?.close()}>Connect</a>
{/if}
{#if offlineMode}<p class="caption text-secondary">
Server access is off. Requested downloads are paused.
</p>{/if}
</section>
{#if appUpdate?.message}
<hr class="separator" />
<section class="stack-sm" aria-label="App update">
Expand Down
11 changes: 2 additions & 9 deletions src/network.svelte.ts
Original file line number Diff line number Diff line change
Expand Up @@ -647,15 +647,8 @@ export class Network {
return result;
}

/** Open authenticated access. A supplied signal owns an independent lifetime,
* including while browsing is offline; otherwise Network owns browsing access. */
open(auth: Auth, signal?: AbortSignal) {
if (signal) {
signal.throwIfAborted();
const connection = this.#createConnection(auth);
signal.addEventListener("abort", () => connection.client.abort(), { once: true });
return this.#access(connection);
}
/** Open authenticated access within the single Network-owned lifetime. */
open(auth: Auth) {
if (this.#mode === "offline") throw new Error("Network access is offline.");
const connection = this.prepare(auth);
return this.accept(connection);
Expand Down
Loading
Loading