modules.addons.file_relocater

File Relocater

A tool to move audio files into folder structures based on metadata. Moves files from a source library into organized subfolders under a specified root directory.

Default folder structure: /(album)/(year)/(albumartist)/ with sanitized folder names but can be changed by user.

Functions

main()	Main function for the audio organizer.
parse_arguments()	Parse command line arguments.
parse_character_replacements(replace_char_list)	Parse character replacement arguments from command line.

Classes

FileRelocater(options)

Audio library organizer that moves files into folder structures based on metadata

class modules.addons.file_relocater.FileRelocater(options: Dict[str, Any])

Bases: object

Audio library organizer that moves files into folder structures based on metadata

Initialize the FileRelocater with the specified options.

Parameters:

options (dict) – Dictionary of organization options

__init__(options: Dict[str, Any])

Initialize the FileRelocater with the specified options.

Parameters:

options (dict) – Dictionary of organization options

sanitize_folder_name(text: str) → str

Clean a string to be safe for use as a folder name.

Parameters:

text (str) – Text to sanitize

Returns:

Sanitized text

Return type:

str

get_file_metadata(filepath: str) → Dict[str, str]

Extract metadata from an audio file using FFprobe.

Parameters:

filepath (str) – Path to the audio file

Returns:

Dictionary containing all available metadata

Return type:

dict

generate_folder_path(filepath: str) → str | None

Generate a folder path based on metadata using the specified format.

Parameters:

filepath (str) – Path to the audio file

Returns:

Relative folder path, or None if format cannot be resolved

Return type:

str or None

move_file(source_filepath: str, destination_root: str) → bool

Move a single audio file to the organized folder structure.

Parameters:

• source_filepath (str) – Path to the source audio file

• destination_root (str) – Root directory for organized files

Returns:

True if move was successful, False otherwise

Return type:

bool

organize_directory(source_directory: str, destination_root: str) → tuple[int, int]

Organize all audio files in a directory.

Parameters:

• source_directory (str) – Directory containing audio files to organize

• destination_root (str) – Root directory for organized files

Returns:

(number of successful moves, total number of files processed)

Return type:

tuple

modules.addons.file_relocater.parse_arguments()

Parse command line arguments.

Returns:

Parsed arguments

Return type:

argparse.Namespace

modules.addons.file_relocater.parse_character_replacements(replace_char_list, no_defaults=False)

Parse character replacement arguments from command line.

Parameters:

• replace_char_list (list) – List of [old_char, new_char] pairs

• no_defaults (bool) – If True, don’t include default replacements

Returns:

Dictionary mapping old characters to new characters

Return type:

dict

modules.addons.file_relocater.main()

Main function for the audio organizer.