Rules¶
tunedex fix cleans tags with bundled fixes and your own rules. Both change only tunedex's library. Audio files are never touched, and later scans and imports keep the fixed values. Every change in the plan says which fix or rule made it.
The same conditions also filter tunedex list --where.
Where the rules come from¶
- The file given with
--rules FILE. - Otherwise,
rules.yamlin the tunedex home, when it exists. - Otherwise, the bundled fixes with their defaults.
--only NAME limits a run to some fixes or rule ids. It is repeatable, or takes names separated by commas.
Fixes¶
Fixes run in this order, each one seeing the result of the previous ones:
| Fix | What it does | Default fields | On by default |
|---|---|---|---|
title_from_file_name |
Fills a missing title, and artist, from Artist - Title.mp3. Also restores a title cut at 30 characters (ID3v1) when the file name holds the whole of it. |
title, artist |
yes |
fix_encoding |
Repairs Café → Café and & → &. |
every text field | yes |
normalize_characters |
Full-width : → : outside CJK text; odd and repeated spaces. |
every text field | yes |
remove_urls |
Glue (freebeats.com) → Glue; also http…, www.… and a domain at the end (Glue my-free-mp3s.com). |
title, artist, album |
yes |
remove_video_ids |
Glue [dOFq-swCWro] → Glue. |
title |
yes |
underscores_to_spaces |
Sunrise_Overlook_320 → Sunrise Overlook 320. Underscores inside a URL or a domain are kept. |
title, album |
yes |
remove_leading_number |
03 - Glue → Glue; also a store id, 1156882 Glue → Glue. |
title |
yes |
split_artist_title |
With no artist, Sam Paganini - Galaxy → artist Sam Paganini, title Galaxy, when the file name starts with the same Sam Paganini -. |
artist, title |
yes |
extract_featured |
Storm (feat. Mira) or Storm feat Mira → title Storm, artist … feat. Mira. |
title, artist |
yes |
extract_remixer |
Fills the remixer from (Tom Ray Remix); the title is unchanged. |
remixer |
yes |
remove_itunes_data |
Clears a comment that only holds iTunes volume data (00000EC8 00000EC8 …). |
comment |
yes |
fix_case |
whisper of the trees → Whisper of the Trees. |
title, album |
no: one-case titles are often deliberate (HUMBLE., bad guy) |
The rules file¶
A rules file has three optional sections, fixes, rules and rename:
fixes:
extract_featured: false # turn a fix off
remove_urls:
fields: [title, comment] # change which fields it cleans
fix_case: # turn it on, with words to keep as written
keep: [DJ, MC, SBTRKT]
rules:
- id: no-year-in-title
when: {field: title, op: matches, value: ' \[\d{4}\]$'}
then: {replace: title, pattern: ' \[\d{4}\]$', with: ''}
- id: one-dnb-genre
match: any
when:
- {field: genre, op: equals, value: DnB}
- {field: genre, op: equals, value: Drum n Bass}
then: {set: genre, value: Drum And Bass}
rename:
pattern: '{artist} - {title}{ (remixer remix)}'
fixes¶
Each entry maps a fix's name to one of:
false, to turn the fix off;true, to turn it on with its defaults;- its options:
fields, a list of text fields, for the fixes that clean any field (fix_encoding,normalize_characters,remove_urls,remove_video_ids,underscores_to_spaces,fix_case);keep, forfix_case: words to keep exactly as written.
A fix the file does not name keeps its default.
rules¶
Rules run after the fixes, in file order. Each rule has:
| Key | Meaning |
|---|---|
id |
A name for the rule. It is shown in the plan and accepted by --only. |
when |
One condition or a list of them. |
match |
all (the default) or any: whether every condition or at least one must hold. |
then |
One action or a list of them. |
The actions are:
{replace: FIELD, pattern: REGEX, with: TEXT}replaces every match of the regular expression in a text field.withcan use the pattern's groups as\1.{set: FIELD, value: VALUE}sets a field. An empty value clears it.
If a value does not fit the field, such as text for bpm, that rule leaves the track unchanged and the plan shows a warning.
Running the same fixes and rules again on their result changes nothing.
rename¶
The file name pattern of tunedex rename, used when the command gets no --pattern:
rename:
pattern: '{artist} - {title} [{year}]'
pattern is the only key. A pattern with an unknown field, or with an optional part that does not hold exactly one field, is reported with the other errors of the file. The renaming guide describes patterns.
Conditions¶
A condition names a field, an op and, for most operators, a value (or values for in):
{field: bpm, op: gte, value: 170}
{field: genre, op: in, values: [Techno, House]}
{field: comment, op: empty}
field is any track field, such as title, bpm, key, date_added or tags.
| Field type | Operators |
|---|---|
| Text | equals, not_equals, contains, not_contains, starts_with, ends_with, in, matches |
| Numbers and dates | equals, not_equals, gt, gte, lt, lte, in |
| Any | empty, not_empty |
- Text comparisons ignore case, except
matches, which takes a regular expression. - A condition on an empty field is false for every operator except
empty,not_equalsandnot_contains.
An unknown fix, field, operator, option or action, or an invalid regular expression, is an invalid_rule error that names the rule. Nothing is planned.
--where¶
tunedex list --where takes conditions as short FIELD OP VALUE expressions:
| Operator | Means |
|---|---|
= |
equals |
!= |
not_equals |
~ |
contains |
!~ |
not_contains |
> >= < <= |
gt gte lt lte |
tunedex list --where "genre=Techno" --where "bpm>=130"
tunedex list --where "title~remix"
tunedex list --where "comment="
FIELD=with no value matches an empty field, andFIELD!=matches a field with a value.- On
tags,=and!=mean contains and does not contain. --whereis repeatable, and every condition must hold.