document path templates

README.md

@@ -167,15 +167,16 @@ by the two interfaces is:
 
 - Filter your music by artist, genre, label, and "new"-ness
 - Create collages of releases and playlists of tracks
-- Group artist aliases together under a primary artist
-- Flag and unflag release "new"-ness
+- Configure directory and filename templates for releases and tracks
 - Edit release metadata as a text file
 - Run and store rules for (bulk) updating metadata
 - Import metadata and cover art from third-party sources
 - Extract embedded cover art to an external file
+- Flag and unflag release "new"-ness
+- Group artist aliases together under a primary artist
 - Create "phony" single releases from any individual track
-- Support for `.mp3`, `.m4a`, `.ogg` (vorbis), `.opus`, and `.flac` files
 - Support for multiple artist, label, and genre tags.
+- Support for `.mp3`, `.m4a`, `.ogg` (vorbis), `.opus`, and `.flac` files
 
 > [!NOTE]
 > Rosé modifies the managed audio files, even on first scan. If you do not want
@@ -382,6 +383,7 @@ For additional documentation, please refer to the following files:
 - [Managing Playlists & Collages](./docs/PLAYLISTS_COLLAGES.md)
 - [Improving Your Music Metadata](./docs/METADATA_TOOLS.md)
 - [Maintaining the Cache](./docs/CACHE_MAINTENANCE.md)
+- [Directory & Filename Templates](./docs/TEMPLATES.md)
 - [Shell Scripting](./docs/SHELL_SCRIPTING.md)
 - [Tagging Conventions](./docs/TAGGING_CONVENTIONS.md)
 - [Architecture](./docs/ARCHITECTURE.md)

docs/CONFIGURATION.md

@@ -33,6 +33,13 @@ fuse_mount_dir = "~/music"
 # === Optional values ===
 # =======================
 
+# If true, the directory and files in the source directory will be renamed
+# based on their tags. The rename will occur during Rosé's cache update
+# sequence. The source files will be renamed per the
+# `path_templates.source.release` and `path_templates.source.track`
+# configuration options. This is false by default.
+rename_source_files = false
+
 # Artist aliases: Grouping multiple names for the same artist together.
 #
 # Artists will sometimes release under multiple names. This is fine, but
@@ -108,8 +115,24 @@ cache_dir = "~/.cache/rose"
 # request.
 max_proc = 4
 
-# Stored metadata rules to be repeatedly ran in the future. See the Managing
-# Your Music Metadata document for more details.
+# The templates used to format the release directory names and track filenames
+# in the source directory and the virtual filesystem. See TEMPLATES.md for more
+# details.
+[path_templates]
+default.release = """
+{{ artists | artistsfmt }} -
+{% if year %}{{ year }}.{% endif %}
+{{ title }}
+{% if releasetype == "single" %}- {{ releasetype | releasetypefmt }}{% endif %}
+"""
+default.track = """
+{% if multidisc %}{{ discnumber.rjust(2, '0') }}-{% endif %}{{ tracknumber.rjust(2, '0') }}.
+{{ title }}
+{% if artists.guest %}(feat. {{ artists.guest | artistsarrayfmt }}){% endif %}
+"""
+
+# Stored metadata rules to be repeatedly ran in the future. See
+# METADATA_TOOLS.md for more details.
 [[stored_metadata_rules]]
 matcher = "genre:^Kpop$"
 actions = ["replace:K-Pop"]

docs/METADATA_TOOLS.md

@@ -421,6 +421,10 @@ The formal syntax is defined by the following grammar:
 <delete-action>  ::= 'delete'
 ```
 
+## Examples
+
+_TODO_
+
 ## Dry Runs
 
 You can preview a rule's changes with the `--dry-run` flag. For example:

docs/README.md

@@ -9,6 +9,7 @@ For more detailed documentation, please visit the following files:
 - [Managing Releases](./RELEASES.md)
 - [Improving Your Music Metadata](./METADATA_TOOLS.md)
 - [Maintaining the Cache](./CACHE_MAINTENANCE.md)
+- [Directory & Filename Templates](./TEMPLATES.md)
 - [Shell Scripting](./SHELL_SCRIPTING.md)
 - [Tagging Conventions](./docs/TAGGING_CONVENTIONS.md)
 - [Architecture](./ARCHITECTURE.md)

docs/RELEASES.md

@@ -27,6 +27,10 @@ new = false
 added_at = 2018-10-01 00:00:00-04:00
 ```
 
+The release directories and track files in `$music_source_dir` can be renamed
+with the `rename_source_files` configuration variable. See
+[Configuration](./CONFIGURATION.md) for more details.
+
 # "New" Releases
 
 Rosé supports flagging releases as "new." "New"-ness has no effects besides

docs/TEMPLATES.md

@@ -0,0 +1,130 @@
+# Directory and Filename Templates
+
+Rosé supports user-defined templates for configuring the directory and file
+names for each view of the virtual filesystem and for the source directory.
+
+> [!NOTE]
+> The source directory templates are only applied to the source directory if
+> the `rename_source_files` configuration option is true. See
+> [Configuration](./CONFIGURATION.md) for more details.
+
+To customize the templates, define them in your configuration file. The
+configuration keys for templates are:
+
+```toml
+[path_templates]
+default.release = "..."
+default.track = "..."
+source.release = "..."
+source.track = "..."
+all_releases.release = "..."
+all_releases.track = "..."
+new_releases.release = "..."
+new_releases.track = "..."
+recently_added_releases.release = "..."
+recently_added_releases.track = "..."
+artists.release = "..."
+artists.track = "..."
+genres.release = "..."
+genres.track = "..."
+labels.release = "..."
+labels.track = "..."
+collages.release = "..."
+collages.track = "..."
+playlists = "..."
+```
+
+# Template Language
+
+Rosé uses the Jinja templating language. See [Jinja's Template Designer
+Documentation](https://jinja.palletsprojects.com/en/3.1.x/templates/).
+
+After evaluating the template, Rosé replaces all adjacent whitespace characters
+(e.g. space, tab, newline, return, etc.) with a single space. This allows you
+to freely use multiple lines and comments when defining your templates, like
+so:
+
+```jinja
+{{ artists | artistsfmt }} -
+{% if year %}{{ year }}.{% endif %}         {# Hi! #}
+{{ title }}
+{% if releasetype == "single" %}- {{ releasetype | releasetypefmt }}{% endif %}
+```
+
+Rosé provides the following template variables for releases:
+
+```python
+added_at: str                   # ISO8601 timestamp of when the release was added to the library.
+title: str                  
+releasetype: str                # Type of the release (e.g. single, ep, etc). One of the enums as defined in TAGGING_CONVENTIONS.md.
+year: int | None             
+new: bool                       # The "new"-ness of the release. See RELEASES.md for documentation on this feature.
+genres: list[str]            
+labels: list[str]           
+artists: ArtistMapping          # All release artists: an object with 6 properties, each corresponding to one role.
+artists.main: list[Artist]      # The Artist object has a `name` property with the artist name.
+artists.guest: list[Artist]
+artists.remixer: list[Artist]
+artists.producer: list[Artist]
+artists.composer: list[Artist]
+artists.dj: list[Artist]
+position: str                   # If in a collage context, the zero-padded position of the release in the collage.
+```
+
+And provides the template variables for tracks:
+
+```python
+title: str 
+tracknumber: str  
+discnumber: str
+duration_seconds: int
+multidisc: bool                 # Whether the parent release has multiple discs.
+artists: ArtistMapping          # All track artists: an object with 6 properties, each corresponding to one role.
+artists.main: list[Artist]      # The Artist object has a `name` property with the artist name.
+artists.guest: list[Artist]
+artists.remixer: list[Artist]
+artists.producer: list[Artist]
+artists.composer: list[Artist]
+artists.dj: list[Artist]
+position: str                   # If in a playlist context, the zero-padded position of the track in the playlist.
+```
+
+Rosé also provides the following custom filters:
+
+```python
+arrayfmt: (list[str]) -> str               # Formats an array of strings as x, y & z.
+artistsarrayfmt: (list[Artist]) -> str     # Formats an array of Artist objects as x, y & z.
+artistsfmt: ArtistMapping -> str           # Formats an ArtistMapping; puts guests in (feat. x) and producers in (prod. x).
+releasetypefmt: str -> str                 # Correctly capitalizes the all-lowercase release type enum value.
+```
+
+# Examples
+
+_TODO_
+
+# Previewing Templates
+
+You can preview your templates with the following command. It will evaluate all
+your templates with sample data.
+
+```bash
+$ rose config preview-templates
+Preview for template Source Directory - Release:
+  Sample 1: Kim Lip - 2017. Kim Lip
+  Sample 2: BTS - 2016. Young Forever (花樣年華)
+Preview for template Source Directory - Track:
+  Sample 1: 01. Eclipse.opus
+  Sample 2: 02-05. House of Cards.opus
+
+Preview for template 1. All Releases - Release:
+  Sample 1: Kim Lip - 2017. Kim Lip - Single [K-Pop, Dance-Pop & Contemporary R&B]
+  Sample 2: BTS - 2016. Young Forever (花樣年華) [K-Pop]
+Preview for template 1. All Releases - Track:
+  Sample 1: 01. Eclipse.opus
+  Sample 2: 02-05. House of Cards.opus
+
+Preview for template 2. New Releases - Release:
+  Sample 1: Kim Lip - 2017. Kim Lip - Single [K-Pop, Dance-Pop & Contemporary R&B]
+  Sample 2: BTS - 2016. Young Forever (花樣年華) [K-Pop]
+...
+```

docs/VIRTUAL_FILESYSTEM.md

@@ -37,41 +37,17 @@ to create an intentional ordering.
 # Directory and File Names
 
 Rosé constructs a "virtual" directory name for each release and "virtual" file
-name for each track. Rosé uses the source directory's metadata tags to do so.
-When the source directory changes, the virtual names auto-update in response.
+name for each track. These filenames are different from the release's filenames
+in the source directory. Rosé uses the source directory's metadata tags to
+generate the virtual names. Therefore, when the music tags change, the virtual
+names auto-update in response.
 
-The release directory name template is:
-
-```
-%NEWNESS% %ALBUM_ARTISTS% - %YEAR%. %ALBUM_TITLE% - %RELEASE_TYPE% [%GENRE%]
-```
-
-> [!NOTE]
-> The `- %RELEASE_TYPE%` field is omitted when the release is of type `album`,
-> `other`, or `unknown`.
-
-The track file name template is:
-
-```
-%TRACK_ARTISTS% - %TRACK_TITLE%.%EXTENSION%
-```
-
-Depending on the view, the virtual names may have a _prefix_. The prefix is of
-the format `%PREFIX%. `. For example, tracks in a release have a position
-prefix of `%DISC_NUMBER%-%TRACK_NUMBER%. `. Collages and playlists apply a
-position prefix to each release/track in them. The Recently Added Releases view
-adds a date prefix to each release.
-
-"New" releases are prefixed with `{NEW}` in the virtual filesystem and appear
-in the `2. Releases - New` top-level directory.
-
-> [!NOTE]
-> The command line commands accept a release's virtual directory name as a
-> valid method of identifying a release. The virtual directory name passed to
-> those commands should not contain any date or position prefixes.
+The directory and file names are configurable. See [Directory & Filename
+Templates](./TEMPLATES.md) for details.
 
 Rosé also exposes all cover art under the filename `cover.{ext}`, regardless of
-the filename in the source directory.
+the filename in the source directory. Rosé also exposes the `.rose.{uuid}.toml`
+datafile in the virtual filesystem.
 
 # Hiding Artists, Genres, and Labels