86 lines
3.4 KiB
Markdown
86 lines
3.4 KiB
Markdown
# fsdy — the filesystem provider
|
|
|
|
Mounts a local directory at **`/fs`** in the crabidy library. The same
|
|
engine also powers the server-managed **`/crabidy`** mount (saved queues,
|
|
bookmarks, and captures), so everything below applies to its on-disk format
|
|
too.
|
|
|
|
No login: the provider only reads a directory you point it at.
|
|
|
|
## How it works
|
|
|
|
The provider walks one configured root directory. Every **directory**
|
|
becomes a queueable library node; every file ending in
|
|
**`.cbd-track.toml`** becomes a track; everything else (audio files,
|
|
covers, hidden entries) is invisible to the library. Listing order is
|
|
case-insensitive by file name — prefix files with numbers to fix an
|
|
order (the save writers use `0001`-style prefixes for exactly this
|
|
reason).
|
|
|
|
A track file carries the track's metadata plus a reference to the
|
|
playable thing:
|
|
|
|
```toml
|
|
title = "We Will Rock You" # required
|
|
artist = "Queen" # optional
|
|
duration = 122 # optional, seconds
|
|
|
|
[album] # optional
|
|
title = "News of the World"
|
|
release_date = "1977-10-28"
|
|
|
|
# Exactly ONE of the following four:
|
|
[playable]
|
|
file = "we-will-rock-you.flac" # local audio; absolute, or relative to
|
|
# this file's directory (relocatable)
|
|
# url = "https://example.org/radio.mp3" # http(s) stream
|
|
# link = "/tidal/artists/1/2/3" # another provider's track
|
|
# skipped = true # no audio: a capture recorded its
|
|
# source as uncapturable; shown red,
|
|
# skipped by playback
|
|
```
|
|
|
|
Malformed track files are skipped with a warning; they never break the
|
|
listing. `link` playables resolve exactly one hop (a link to a link
|
|
fails at play time), which keeps cycles impossible.
|
|
|
|
## Configuration — `~/.config/crabidy/fsdy.toml`
|
|
|
|
```toml
|
|
# Absolute path of the directory to expose under /fs.
|
|
# Default: the platform music directory (e.g. ~/Music). When neither is
|
|
# available the /fs mount is disabled — the rest of the server runs on.
|
|
# root = "/home/me/music"
|
|
```
|
|
|
|
## The server-managed `/crabidy` instance
|
|
|
|
`/crabidy` is a second instance of this same provider, over the server's
|
|
state directory `~/.local/state/crabidy/`, written by the server (queue
|
|
persistence, `w`, `W`) and readable with any file manager — it is just
|
|
folders of the track files described above.
|
|
|
|
- Each top-level folder is one save. It can be renamed (`e`) and deleted
|
|
(`d`) from a client.
|
|
- `current` is the continuously persisted play queue and is protected: you
|
|
cannot save over that name.
|
|
- A captured track's `[playable]` is a `store` entry naming a file in the
|
|
content store at `~/.local/share/crabidy/`, which is shared and
|
|
de-duplicated across every save.
|
|
- Deleting inside `/crabidy` removes only the metadata toml, **never** the
|
|
shared store audio — other saves may point at the same file. Audio that
|
|
ends up referenced by nothing shows up under `/orphans`, where you can
|
|
delete it for real.
|
|
|
|
The `scan` subcommand writes exactly these track files for a folder of audio,
|
|
so an existing music collection browses under `/fs` without any manual work:
|
|
|
|
```sh
|
|
crabidy-server scan ~/Music # index in place
|
|
crabidy-server scan ~/Downloads --capture # copy the audio into the store
|
|
```
|
|
|
|
Building the server without the `fs` cargo feature drops this provider, the
|
|
content store, `/crabidy`, `/orphans`, queue persistence, and `scan` — they
|
|
all share the same on-disk machinery.
|