update the configuration doc

README.md

@@ -161,6 +161,20 @@ This section contains a concise list of Rosé's features.
 - Support for `.mp3`, `.m4a`, `.ogg` (vorbis), `.opus`, and `.flac` audio
   files.
 
+And the following are opinionated decisions that might make this tool
+unsuitable for you:
+
+- Rosé modifies files in the source directory, even as early as the first
+  library scan. All mutations in Rosé are persisted by writing to the source
+  directory; Rosé maintains no state of its own outside of the source
+  directory. This makes Rosé work very poorly with files being seeded as
+  torrents.
+- Rosé expects all releases to be immediate child directories of the
+  source directory. And Rosé expects that all tracks belong to a "release"
+  (meaning an album, single, EP, etc.). This means that loose audio files at
+  the top-level of the source directory will be ignored. This makes Rosé work
+  very poorly with libraries organized as collections of tracks.
+
 ## Installation
 
 Install Rosé with Nix Flakes. If you do not have Nix Flakes, you can install

docs/ARCHITECTURE.md

@@ -66,10 +66,10 @@ it's a hot path and quite expensive if implemented poorly.
 
 The read cache update first pulls all relevant cached data from SQLite. Stored
 on each track is the mtime during the previous cache update. The cache update
-uses `stat` to check whether the mtime has changed and only reads the file if
-the `mtime` has changed. Throughout the update, we take note of the changes to
-apply. At the end of the update, we make a few fat SQL queries to batch the
-writes.
+checks whether any files have changed via `readdir` and `stat` calls, and only
+reads the file if the `mtime` has changed. Throughout the update, we take note
+of the changes to apply. At the end of the update, we make a few fat SQL
+queries to batch the writes.
 
 The update process is also parallelizable, so we shard workloads across
 multiple processes.

docs/CONFIGURATION.md

@@ -1,69 +1,89 @@
 # Configuration
 
-Rosé must be configured prior to use. Rosé is configured via a TOML file
-located at `${XDG_CONFIG_HOME:-$HOME/.config}/rose/config.toml`.
+Rosé is configured by a TOML file.
+
+The configuration, by default, is located at `${XDG_CONFIG_HOME:-$HOME/.config}/rose/config.toml`.
+The `--config/-c` flag can be specified to load a configuration file from a
+different location.
 
 The configuration parameters, with examples, are:
 
 ```toml
+# =======================
 # === Required values ===
+# =======================
 
-# The directory containing the music to manage. This source directory WILL be
-# modified by Rosé; if you do not want the files in directory to be modified,
-# use another tool!
+# The directory containing the music to manage. Rosé has strong expectations
+# towards the organization of this directory.
+#
+# All releases are expected to be immediate child directories of the
+# music_source_dir. And Rosé expects that all tracks belong to a "release"
+# (meaning an album, single, EP, etc.). Therefore, loose audio files at the
+# top-level of the source directory will be ignored.
+#
+# Rosé also writes collages and playlists to this directory, as `!collages` and
+# `!playlists` subdirectories.
 music_source_dir = "~/.music-source"
-# The directory to mount the library's virtual filesystem on. This is the
-# primary "user interface" of Rosé, and the directory in which you will be able
-# to browse your music library.
+
+# The directory to mount the virtual filesystem on.
 fuse_mount_dir = "~/music"
 
+# =======================
 # === Optional values ===
+# =======================
 
-# The directory to write the cache to. Defaults to
-# `${XDG_CACHE_HOME:-$HOME/.cache}/rose`.
-cache_dir = "~/.cache/rose"
-# Maximum parallel processes that the cache updater can spawn. Defaults to
-# nproc/2. The higher this number is; the more performant the cache update will
-# be.
-max_proc = 4
-# Artist aliases: Releases belonging to an alias will also "belong" to the main
-# artist. This option improves the Artist browsing view by showing the aliased
-# releases in the main artist's releases list.
+# Artist aliases: Grouping multiple names for the same artist together.
+#
+# Artists will sometimes release under multiple names. This is fine, but
+# wouldn't it be nice if all releases by an artist, regardless of whichever
+# alias was used, appeared in a single spot?
+#
+# That's what this configuration option enables. This configuration option
+# makes the releases of "aliased" artists also appear under the main artist in
+# the Artists browsing view.
 artist_aliases = [
   { artist = "Abakus", aliases = ["Cinnamon Chasers"] },
   { artist = "tripleS", aliases = ["EVOLution", "LOVElution", "+(KR)ystal Eyes", "Acid Angel From Asia", "Acid Eyes"] },
 ]
-# Artists, genres, and labels to show in the virtual filesystem navigation. By
-# default, all artists, genres, and labels are shown. However, these values can
-# be used to filter the listed values to a specific few. This is useful e.g. if
-# you only care to browse your favorite genres and labels.
+
+# Artists, genres, and labels to show in their respective top-level virtual
+# filesystem directories. By # default, all artists, genres, and labels are
+# shown. However, if this configuration parameter is specified, the list can be
+# restricted to a specific few values. This is useful if you only care about a
+# few specific genres and labels.
 fuse_artists_whitelist = [ "xxx", "yyy" ]
 fuse_genres_whitelist = [ "xxx", "yyy" ]
 fuse_labels_whitelist = [ "xxx", "yyy" ]
 # Artists, genres, and labels to hide from the virtual filesystem navigation.
-# These options remove specific entities from the default policy of listing all
-# entities. These options are mutually exclusive with the fuse_*_whitelist
-# options; if both are specified for a given entity type, the configuration
-# will not validate.
+# These options remove specific entities from their respective top-level
+# virtual filesystem directories. This is useful if there are a few values you
+# don't find useful, e.g. a random featuring artist or one super niche genre.
+# 
+# These options are mutually exclusive with the fuse_*_whitelist options; if
+# both are specified for a given entity type, the configuration will not
+# validate.
 fuse_artists_blacklist = [ "xxx" ]
 fuse_genres_blacklist = [ "xxx" ]
 fuse_labels_blacklist = [ "xxx" ]
-```
 
-The `--config/-c` flag overrides the config location.
+# The directory to write the cache to. Defaults to
+# `${XDG_CACHE_HOME:-$HOME/.cache}/rose`.
+cache_dir = "~/.cache/rose"
 
-## Music Source Dir
+# Maximum parallel processes that the read cache updater can spawn. Defaults to
+# $(nproc)/2. The higher this number is; the more performant the cache update
+# will be.
+max_proc = 4
 
-The `music_source_dir` must be a flat directory of releases, meaning all releases
-must be top-level directories inside `music_source_dir`. Each release should also
-be a single directory in `music_source_dir`.
+```
 
-Every directory should follow the format: `$music_source_dir/$release_name/**/$track.mp3`.
-A release can have arbitrarily many nested subdirectories.
+## Systemd Unit Files
 
-So for example: `$music_source_dir/BLACKPINK - 2016. SQUARE ONE/*.mp3`.
+If you want Rosé to always be on, you can configure systemd to manage Rosé.
+Systemd can ensure that Rosé starts on boot and restarts on failure.
 
-Rosé writes playlist and collage files to the `$music_source_dir/.playlists`
-and `$music_source_dir/.collages` directories. Each file is a human-readable
-TOML file.
+Some systemd unit files are:
 
+```ini
+TODO
+```

rose/cache.py

@@ -219,7 +219,7 @@ class StoredDataFile:
 STORED_DATA_FILE_REGEX = re.compile(r"\.rose\.([^.]+)\.toml")
 
 # TODO: Push this into the configuration.
-ROSE_IGNORE_DIRS = [".stversions"]
+ROSE_IGNORE_DIRS = [".stversions", "!collages", "!playlists"]
 
 
 def update_cache(c: Config, force: bool = False) -> None: