Skip to main content

​
Overview

The Renamer class provides static methods for converting between audio file metadata and filenames using customizable patterns. It supports bidirectional conversion: generating filenames from tags and extracting tags from filenames.

​
Import

from tagqt.core.rename import Renamer

​
Methods

​
sanitize_filename

Removes invalid characters from filenames to ensure cross-platform compatibility. 
@staticmethod
def sanitize_filename(filename: str) -> str
​
filename
str
required
The filename string to sanitize
Returns: Sanitized filename with invalid characters (/ \ : * ? " < > |) replaced by underscores Example: 
clean = Renamer.sanitize_filename("Artist/Album: Title?")
print(clean)  # "Artist_Album_ Title_"

​
tag_to_filename

Generates a filename based on a pattern template and metadata object. 
@staticmethod
def tag_to_filename(pattern: str, metadata) -> str | None
​
pattern
str
required
Template pattern with placeholders for metadata fields
​
metadata
MetadataHandler
required
Metadata object containing tag information
Returns: Generated filename string, or None if metadata is invalid

​
Supported Pattern Placeholders

PlaceholderMetadata FieldFallback
%artist%artist”Unknown Artist”
%title%title”Unknown Title”
%album%album”Unknown Album”
%year%year""
%track%track_number""
%genre%genre""
%albumartist%album_artist""
%bpm%bpm""
%key%initial_key""
Example: 
from tagqt.core.tags import MetadataHandler

metadata = MetadataHandler("song.flac")
filename = Renamer.tag_to_filename("%track% - %artist% - %title%", metadata)
print(filename)  # "01 - Artist Name - Song Title"

​
filename_to_tag

Parses a filename using a pattern template to extract tag values. 
@staticmethod
def filename_to_tag(pattern: str, filename: str) -> dict | None
​
pattern
str
required
Template pattern matching the filename structure
​
filename
str
required
The filename to parse (without extension)
Returns: Dictionary with extracted tag names as keys and values as strings, or None if parsing fails Example: 
pattern = "%artist% - %title%"
filename = "The Beatles - Yesterday"

tags = Renamer.filename_to_tag(pattern, filename)
print(tags)
# {'artist': 'The Beatles', 'title': 'Yesterday'}
Complex Pattern Example: 
pattern = "%track% %artist% - %title% [%year%]"
filename = "01 Led Zeppelin - Stairway to Heaven [1971]"

tags = Renamer.filename_to_tag(pattern, filename)
print(tags)
# {
#   'track': '01',
#   'artist': 'Led Zeppelin',
#   'title': 'Stairway to Heaven',
#   'year': '1971'
# }

​
Notes

  • All methods are static and do not require instantiation
  • Pattern matching uses non-greedy regex to handle multiple consecutive placeholders
  • Invalid characters are automatically sanitized in generated filenames
  • Missing metadata fields use fallback values (empty string or “Unknown”)

Build docs developers (and LLMs) love

Get started for freeTalk to us