feat(sources): local_folder source backend + import pipeline
First ingest path beyond manual upload (plan §1C). Source abstraction +
the first concrete backend, so a homelab can index an existing library.
- domain: SourceBackend/IndexableSource ports + SourceInfo/SourceFile shapes
- infrastructure/sources: LocalFolderSource (walks a mounted dir, idempotent
source_id = relative path) + registry built from settings
- application: LibraryImportService — batch sibling of UploadService; dedup on
(source, source_id), copy into storage, minimal track (metadata_status=pending,
enrichment fills the rest in 1D), per-file failures isolated
- workers: scan_local_folder arq task (registered) + enqueue helper (503 if
Redis down)
- api: GET /sources, POST /sources/{source}/scan (admin, enqueues), /health
- config: LOCAL_MEDIA_IMPORT_PATH; README + .env.example documented
- tests: scanner, registry, import service (fakes) + DB-gated sources API path
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -71,6 +71,26 @@ All settings come from environment variables (or `.env` in dev). See
|
||||
[`.env.example`](.env.example). External services (ML, AcoustID, MusicBrainz)
|
||||
are **optional** — the backend degrades gracefully when they are absent.
|
||||
|
||||
## Sources & importing music
|
||||
|
||||
Music enters the library through **source backends** (`app/infrastructure/sources`),
|
||||
selected via a registry. The first backend is **`local`** — it indexes a mounted
|
||||
folder, copying each audio file into managed storage and creating a track
|
||||
(`metadata_status=pending`; real metadata is filled later by enrichment).
|
||||
|
||||
```bash
|
||||
# point the instance at an existing library (mount read-only in compose)
|
||||
LOCAL_MEDIA_IMPORT_PATH=/import
|
||||
|
||||
GET /api/v1/sources # list configured sources + availability
|
||||
POST /api/v1/sources/local/scan # admin: enqueue an import (runs in the worker)
|
||||
GET /api/v1/sources/local/health # availability check
|
||||
```
|
||||
|
||||
Scanning is a background job (arq worker) — the endpoint only enqueues it; the
|
||||
walk + file copies never run in the request cycle. Re-scans are idempotent
|
||||
(dedup on `(source, source_id)`, where `source_id` is the path within the root).
|
||||
|
||||
## Subsonic API (`/rest`)
|
||||
|
||||
A Subsonic-compatible API is mounted at `/rest`, so standard clients (Symfonium,
|
||||
|
||||
Reference in New Issue
Block a user