TagQt provides a powerful template-based file renaming system that allows you to rename audio files based on their metadata tags.
Overview
The file renaming feature uses pattern templates with placeholders that are replaced with actual metadata values. This allows you to create consistent file naming schemes across your music library.
Available Template Patterns
The following template patterns are supported by the Renamer class:
| Pattern | Metadata Field | Default Value |
|---|
%artist% | Artist | Unknown Artist |
%title% | Title | Unknown Title |
%album% | Album | Unknown Album |
%year% | Year | (empty) |
%track% | Track Number | (empty) |
%genre% | Genre | (empty) |
%albumartist% | Album Artist | (empty) |
%bpm% | BPM | (empty) |
%key% | Initial Key | (empty) |
Common Patterns
Here are some commonly used naming patterns:
Pattern Examples
%artist% - %title%
→ Artist Name - Song Title.mp3
%track% %title%
→ 01 Song Title.mp3
%artist% - %album% - %track% - %title%
→ Artist Name - Album Name - 01 - Song Title.mp3
%albumartist%/%album%/%track% %title%
→ Album Artist/Album Name/01 Song Title.mp3
%year% - %album%/%track% - %artist% - %title%
→ 2024 - Album Name/01 - Artist Name - Song Title.mp3
Character Sanitization
The renamer automatically sanitizes filenames by replacing invalid characters with underscores:
Invalid characters: \ / * ? " < > |
# Example from rename.py
re.sub(r'[\\/*?:"<>|]', '_', filename)
Using the Renamer
- Navigate to Tools → File Actions → Rename Files
- Choose Selected or All Visible
- Enter your desired pattern in the dialog
- Preview the changes before applying
From the Command Palette
- Press
Ctrl+K to open the command palette
- Search for “Rename Files”
- Select the command
- Right-click on selected files
- Choose Rename Files (Selected)
Pattern Parsing
The renamer uses a sophisticated pattern parsing system:
# From rename.py:tag_to_filename
replacements = {
'%artist%': metadata.artist or 'Unknown Artist',
'%title%': metadata.title or 'Unknown Title',
# ... more patterns
}
result = pattern
for key, value in replacements.items():
result = result.replace(key, str(value))
Renamer class also supports extracting metadata from filenames using the same pattern syntax:
# Example: filename_to_tag method
pattern = "%artist% - %title%"
filename = "Artist Name - Song Title"
# Returns: {'artist': 'Artist Name', 'title': 'Song Title'}
Best Practices
Always preview your renaming operations before applying them to ensure the pattern produces the expected results.
File renaming operations cannot be undone. Make sure you have backups of your music library before performing bulk rename operations.
Recommendations
- Use track numbers with padding: Include
%track% for proper sorting
- Include artist and title: Essential for identification
- Consider folder structure: Use
/ separators for organizing into subdirectories
- Test on a small batch first: Preview and test your pattern on a few files before applying to your entire library
Technical Details
Source Code Reference
The file renaming functionality is implemented in:
- Source:
tagqt/core/rename.py (Renamer class)
- Methods:
tag_to_filename(pattern, metadata) - Generates filename from patternsanitize_filename(filename) - Removes invalid charactersfilename_to_tag(pattern, filename) - Extracts tags from filename
Implementation
The renaming operation is performed by the RenameWorker class, which:
- Validates the new filename
- Checks for conflicts
- Performs the rename operation
- Updates the file list in the UI
- Reports success or errors for each file
