Add %tunique{} path template function for track disambiguation within albums - #6722
Open
arsaboo wants to merge 2 commits into
Open
Add %tunique{} path template function for track disambiguation within albums#6722arsaboo wants to merge 2 commits into
arsaboo wants to merge 2 commits into
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds a new %tunique{} path template and configuration to disambiguate tracks with identical titles within the same album.
Changes:
- Introduces
tmpl_tuniqueand aqueryoverride hook in_tmpl_uniqueto scope ambiguity checks to an album. - Adds defaults for
tuniqueinconfig_default.yamland documents the new template/config. - Adds a new test suite covering
%tunique{}behavior and edge cases.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| test/test_library.py | Adds %tunique{} test coverage for album-scoped track title collisions and formatting options. |
| docs/reference/pathformat.rst | Documents the new %tunique{} template and its default identifiers/disambiguators. |
| docs/reference/config.rst | Documents new tunique config keys and defaults. |
| docs/changelog.rst | Adds changelog entry announcing %tunique{}. |
| beets/library/models.py | Implements tmpl_tunique and extends _tmpl_unique with an optional pre-built query. |
| beets/config_default.yaml | Adds default configuration for tunique. |
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #6722 +/- ##
=======================================
Coverage 75.61% 75.62%
=======================================
Files 163 163
Lines 21323 21338 +15
Branches 3363 3367 +4
=======================================
+ Hits 16124 16137 +13
- Misses 4406 4407 +1
- Partials 793 794 +1
🚀 New features to boost your workflow:
|
arsaboo
force-pushed
the
tunique
branch
4 times, most recently
from
June 29, 2026 15:00
2c8f8b6 to
aa926d7
Compare
arsaboo
force-pushed
the
tunique
branch
4 times, most recently
from
July 15, 2026 14:33
2fedf30 to
81abe71
Compare
Member
|
I think it would be best to wait until #6825 is merged as I added types to these methods here. |
arsaboo
force-pushed
the
tunique
branch
2 times, most recently
from
July 16, 2026 12:45
25be7e8 to
fa12934
Compare
arsaboo
force-pushed
the
tunique
branch
2 times, most recently
from
July 28, 2026 23:26
6e541c3 to
2fc807b
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a new
%tunique{}path template function (analogous to%aunique{}for albums and%sunique{}for singletons) that disambiguates tracks within the same album that would otherwise produce identical filenames (e.g., two tracks with the same title on the same album or across different discs). This follows the structure and logic used inauniqueorsunique.Fixes #5950
Default configuration:
The function first finds all sibling items (same
album_id) with matching key values (default: sametitle). If duplicates exist, it iterates through the disambiguator fields looking for one that uniquely separates all duplicates. If no field suffices, the stable database ID is used as a fallback. For items without a duplicate, no suffix is added.This solves the problem where
beet movewould non-deterministically append .1/.2 suffixes viaunique_path()for duplicate-titled tracks, which would change every time the command was re-run.Example usage in path config:
For an album with two identically-titled tracks:
To Do
docs/to describe it.)docs/changelog.rstto the bottom of one of the lists near the top of the document.)