API Reference 

modules.core.database.load_playlist_to_database(playlist_path, conn)[source]

Load songs from M3U playlist and add to database.

Parameters:

playlist_path (str) – Path to the M3U playlist file.
conn (sqlite3.Connection) – Database connection object.

Returns:

True if playlist loaded successfully, False otherwise.

Return type:

modules.core.database.analyze_directory(directory_path, db_path)[source]

Analyze audio files in directory and store information in SQLite database.

Parameters:

directory_path (str) – Path to the directory to analyze.
db_path (str) – Path to the SQLite database file.

Returns:

True if analysis completed successfully, False otherwise.

Return type:

modules.core.database.main()[source]

Main function to handle command line arguments and analyze directory.

Parses command-line arguments and initiates database creation, directory scanning, or playlist loading operations.

Examples

Scan directory and create database:: python database.py /path/to/music
Scan directory with custom database path:: python database.py /path/to/music –db-path ~/music.db
Load playlist into database:: python database.py –playlist myplaylist.m3u –db-path ~/music.db
Scan with test directory:: python database.py ../../testing_files/

Metadata

Metadata Editor Tool

A tool to modify audio file metadata (tags, album art, etc.) using mutagen CLI tools. Supports all major audio formats including MP3, FLAC, OGG, MP4, OPUS, and more.

class modules.core.metadata.MetadataEditor[source]

Bases: object

A comprehensive metadata editor for audio files using mutagen CLI tools. Supports reading and writing metadata for all major audio formats.

Initialize MetadataEditor for working with audio file metadata.

__init__()[source]: Initialize MetadataEditor for working with audio file metadata.

is_supported_format(filepath: str) → bool[source]

Check if the file format is supported.

Parameters:: filepath (str) – Path to the audio file to check
Returns:: True if the file format is supported, False otherwise
Return type:: bool

get_metadata(filepath: str) → Dict[str, Any][source]

Get all metadata from an audio file using mutagen library directly.

Parameters:

filepath (str) – Path to the audio file to extract metadata from

Returns:

Dictionary with standardized tag names and metadata values,: or empty dict if extraction fails

Return type:

Dict[str, Any]

set_metadata(filepath: str, metadata: Dict[str, Any]) → bool[source]

Set metadata for an audio file using mutagen library directly.

Parameters:

filepath (str) – Path to the audio file to modify
metadata (Dict[str, Any]) – Dictionary containing metadata to set

Returns:

True if metadata was successfully set, False otherwise

Return type:

set_album_art(filepath: str, image_path: str) → bool[source]

Set album art for an audio file using mutagen library directly.

Parameters:

filepath (str) – Path to the audio file to modify
image_path (str) – Path to the image file to embed as album art

Returns:

True if album art was successfully set, False otherwise

Return type:

remove_album_art(filepath: str) → bool[source]

Remove album art from an audio file using mutagen library directly.

Parameters:: filepath (str) – Path to the audio file to modify
Returns:: True if album art was successfully removed, False otherwise
Return type:: bool

batch_edit_metadata(file_paths: List[str], metadata: Dict[str, Any]) → Dict[str, int][source]

Edit metadata for multiple files.

Parameters:

file_paths (List[str]) – List of file paths to modify
metadata (Dict[str, Any]) – Dictionary containing metadata to set

Returns:

Statistics about the operation with keys:

processed: Number of successfully processed files
errors: Number of files that failed processing

Return type:

Dict[str, int]

display_metadata(filepath: str)[source]

Display metadata for a file in a readable format.

Parameters:: filepath (str) – Path to the audio file to display metadata for

extract_metadata_for_database(filepath: str) → Dict[str, Any][source]

Extract metadata in the format expected by database.py.

Parameters:

filepath (str) – Path to the audio file to extract metadata from

Returns:

Dictionary with all metadata fields that database.py expects,: or None if metadata extraction fails

Return type:

Dict[str, Any]

extract_metadata_for_playlist(filepath: str) → Dict[str, Any][source]

Extract metadata in the format expected by playlist.py.

Parameters:

filepath (str) – Path to the audio file to extract metadata from

Returns:

Dictionary with metadata fields that playlist.py expects,: or None if metadata extraction fails

Return type:

Dict[str, Any]

embed_opus_album_art(opus_filepath: str, image_path: str) → bool[source]

Embed album art into OPUS files.

Parameters:

opus_filepath (str) – Path to the OPUS audio file to modify
image_path (str) – Path to the image file to embed as album art

Returns:

True if album art was successfully embedded, False otherwise

Return type:

modules.core.metadata.main()[source]

Main function for command-line usage.

Returns:: Exit code (0 for success, 1 for failure)
Return type:: int

modules.core.metadata.extract_metadata(filepath: str) → Dict[str, Any][source]

Convenience function for database.py compatibility. Extract metadata from an audio file in database format.

Parameters:

filepath (str) – Path to the audio file to extract metadata from

Returns:

Dictionary with metadata fields in database format,: or None if extraction fails

Return type:

Dict[str, Any]

modules.core.metadata.extract_metadata_for_playlist(filepath: str) → Dict[str, Any][source]

Convenience function for playlist.py compatibility. Extract metadata from an audio file in playlist format.

Parameters:

filepath (str) – Path to the audio file to extract metadata from

Returns:

Dictionary with metadata fields in playlist format,: or None if extraction fails

Return type:

Dict[str, Any]

modules.core.metadata.set_metadata(filepath: str, metadata: Dict[str, Any]) → bool[source]

Convenience function to set metadata for a file.

Parameters:

filepath (str) – Path to the audio file to modify
metadata (Dict[str, Any]) – Dictionary containing metadata to set

Returns:

True if metadata was successfully set, False otherwise

Return type:

modules.core.metadata.set_album_art(filepath: str, image_path: str) → bool[source]

Convenience function to set album art for a file.

Parameters:

filepath (str) – Path to the audio file to modify
image_path (str) – Path to the image file to embed as album art

Returns:

True if album art was successfully set, False otherwise

Return type:

modules.core.metadata.embed_opus_album_art(opus_filepath: str, image_path: str) → bool[source]

Convenience function to embed album art in OPUS files.

Parameters:

opus_filepath (str) – Path to the OPUS audio file to modify
image_path (str) – Path to the image file to embed as album art

Returns:

True if album art was successfully embedded, False otherwise

Return type:

modules.core.metadata.get_duration(filepath: str) → float[source]

Get the duration of an audio file in seconds.

Parameters:: filepath (str) – Path to the audio file
Returns:: Duration in seconds, or 0.0 if unable to determine
Return type:: float

modules.core.metadata.get_title(filepath: str) → str[source]

Get the title tag from an audio file.

Parameters:: filepath (str) – Path to the audio file.
Returns:: The title tag value or empty string if not found.
Return type:: str

modules.core.metadata.get_artist(filepath: str) → str[source]

Get the artist tag from an audio file.

Parameters:: filepath (str) – Path to the audio file.
Returns:: The artist tag value or empty string if not found.
Return type:: str

modules.core.metadata.get_album(filepath: str) → str[source]

Get the album tag from an audio file.

Parameters:: filepath (str) – Path to the audio file.
Returns:: The album tag value or empty string if not found.
Return type:: str

modules.core.metadata.get_albumartist(filepath: str) → str[source]

Get the albumartist tag from an audio file.

Parameters:: filepath (str) – Path to the audio file.
Returns:: The album artist tag value or empty string if not found.
Return type:: str

modules.core.metadata.get_year(filepath: str) → str[source]

Get the year/date tag from an audio file.

Parameters:: filepath (str) – Path to the audio file.
Returns:: The year value or empty string if not found.
Return type:: str

modules.core.metadata.get_genre(filepath: str) → str[source]

Get the genre tag from an audio file.

Parameters:: filepath (str) – Path to the audio file.
Returns:: The genre tag value or empty string if not found.
Return type:: str

modules.core.metadata.get_track(filepath: str) → str[source]

Get the track number from an audio file.

Parameters:: filepath (str) – Path to the audio file.
Returns:: The track number or empty string if not found.
Return type:: str

modules.core.metadata.get_disc(filepath: str) → str[source]

Get the disc number from an audio file.

Parameters:: filepath (str) – Path to the audio file.
Returns:: The disc number or empty string if not found.
Return type:: str

modules.core.metadata.get_comment(filepath: str) → str[source]

Get the comment from an audio file.

Parameters:: filepath (str) – Path to the audio file.
Returns:: The comment or empty string if not found.
Return type:: str

modules.core.metadata.get_composer(filepath: str) → str[source]

Get the composer from an audio file.

Parameters:: filepath (str) – Path to the audio file.
Returns:: The composer or empty string if not found.
Return type:: str

modules.core.metadata.get_performer(filepath: str) → str[source]

Get the performer from an audio file.

Parameters:: filepath (str) – Path to the audio file.
Returns:: The performer or empty string if not found.
Return type:: str

modules.core.metadata.get_grouping(filepath: str) → str[source]

Get the grouping from an audio file.

Parameters:: filepath (str) – Path to the audio file.
Returns:: The grouping or empty string if not found.
Return type:: str

Player

Audio Player using GStreamer Python Bindings

A simple audio player that uses GStreamer Python bindings for real-time control including volume, seeking, and playback management.

class modules.core.player.AudioPlayer[source]

Bases: object

GStreamer-based audio player with real-time control.

__init__()[source]

load_file(filepath)[source]: Load an audio file for playback.

play(seek_position=None)[source]: Start or resume playback.

pause()[source]: Pause playback.

resume()[source]: Resume paused playback.

stop()[source]: Stop playback.

set_volume(volume)[source]: Set playback volume in real-time.

get_volume()[source]

Get current volume level.

Returns:: Current volume between 0.0 and 1.0.
Return type:: float

seek(position_seconds)[source]: Seek to a specific position in the audio using VLC.

get_position()[source]: Get current playback position from VLC player.

get_duration()[source]: Get total duration of the current audio file.

set_loop_mode(mode)[source]

Set loop mode for playback.

Parameters:: mode (str) – Loop mode - ‘none’, number (e.g. ‘3’), or ‘infinite’.
Returns:: True if loop mode set successfully, False otherwise.
Return type:: bool

get_loop_mode()[source]

Get current loop mode.

Returns:: Current loop mode setting.
Return type:: str

get_repeat_count()[source]

Get number of times the current song has repeated.

Returns:: Number of repeats completed.
Return type:: int

get_state()[source]

Get current player state information.

Returns:

Dictionary containing player state including:

is_playing (bool): Whether audio is currently playing
is_paused (bool): Whether audio is paused
current_file (str): Path to current file
position (float): Current position in seconds
duration (float): Total duration in seconds
volume (float): Current volume level
loop_mode (str): Current loop mode
repeat_count (int): Number of repeats completed

Return type:

dict

run_interactive()[source]

Run the player in interactive mode with command input.

Starts a command-line interface allowing real-time control of playback through user commands.

handle_input()[source]

Handle user input in interactive mode.

Processes user commands while audio playback continues.

run_daemon()[source]

Run the player in daemon mode with socket-based command interface.

Creates a Unix socket server that listens for external commands.

modules.core.player.play_audio(filepath)[source]

Simple playback function for command-line compatibility.

Parameters:: filepath (str) – Path to the audio file to play.
Returns:: True if playback completed successfully, False otherwise.
Return type:: bool

modules.core.player.send_daemon_command(command)[source]

Send a command to a running daemon instance.

Parameters:: command (str) – Command to send to daemon
Returns:: True if command was sent successfully, False otherwise
Return type:: bool

modules.core.player.main()[source]

Main function to handle command line arguments and play audio.

Parses command-line arguments and initiates appropriate playback mode (simple, interactive, or daemon).

Examples

Simple playback:: python player.py /path/to/song.mp3
Interactive mode with controls:: python player.py –interactive /path/to/song.mp3
Daemon mode for external control:: python player.py –daemon /path/to/song.mp3
Using test file:: python player.py ../../testing_files/test.mp3

Playlist

Playlist Manager

A script that creates and manages M3U playlists from the audio library database.

modules.core.playlist.connect_to_database(db_path)[source]

Connect to the SQLite database and return connection.

Parameters:: db_path (str) – Path to the SQLite database file.
Returns:: Database connection object, or None if connection fails.
Return type:: sqlite3.Connection or None

modules.core.playlist.get_songs_from_database(conn, filters=None)[source]

Get songs from database based on filters.

Parameters:

conn (sqlite3.Connection) – Database connection object.
filters (dict, optional) – Dictionary with filter criteria. Supported keys: ‘artist’, ‘album’, ‘genre’ (all use partial matching).

Returns:

List of song records as sqlite3.Row objects.

Return type:

modules.core.playlist.format_song_info(song)[source]

Format song information for display.

Parameters:: song (dict or sqlite3.Row) – Song record with metadata.
Returns:: Formatted song information string with track number, artist, title, album, and duration.
Return type:: str

modules.core.playlist.get_relative_path(file_path, playlist_path)[source]

Convert file path to relative path from playlist location.

Parameters:

file_path (str) – Path to the audio file.
playlist_path (str) – Path to the playlist file.

Returns:

Relative path from playlist directory to audio file.

Return type:

str

modules.core.playlist.create_m3u_playlist(songs, playlist_path, use_absolute_paths=False, playlist_name='Playlist')[source]

Create M3U playlist file from a list of songs.

Parameters:

songs (list) – List of song dictionaries or database records.
playlist_path (str) – Path where the playlist file will be saved.
use_absolute_paths (bool, optional) – Use absolute paths instead of relative. Defaults to False.
playlist_name (str, optional) – Name of the playlist. Defaults to “Playlist”.

Returns:

True if playlist created successfully, False otherwise.

Return type:

modules.core.playlist.load_m3u_playlist(playlist_path)[source]

Load songs from M3U playlist file.

Parameters:: playlist_path (str) – Path to the M3U playlist file.
Returns:: List of song dictionaries parsed from the playlist.
Return type:: list

modules.core.playlist.extract_metadata(file_path)[source]

Extract metadata from audio file using the centralized metadata module.

Parameters:

file_path (str) – Path to the audio file.

Returns:

Dictionary containing extracted metadata, or None if extraction fails.: Keys include: url, title, artist, album, albumartist, length, track, disc, year, genre.

Return type:

dict or None

modules.core.playlist.scan_directory(directory_path)[source]

Scan directory recursively for audio files.

Parameters:: directory_path (str) – Path to the directory to scan.
Returns:: List of audio file paths found in the directory.
Return type:: list

modules.core.playlist.create_playlist_from_inputs(inputs, playlist_path, use_absolute_paths=False, playlist_name='Playlist')[source]

Create playlist from list of files and folders.

Parameters:

inputs (list) – List of file paths and/or directory paths.
playlist_path (str) – Path where the playlist file will be saved.
use_absolute_paths (bool, optional) – Use absolute paths instead of relative. Defaults to False.
playlist_name (str, optional) – Name of the playlist. Defaults to “Playlist”.

Returns:

True if playlist created successfully, False otherwise.

Return type:

modules.core.playlist.main()[source]

Main function for playlist management command-line interface.

Parses command-line arguments and performs playlist operations including creating playlists from database queries, files/directories, or loading existing playlists.

Examples

Create playlist from database with artist filter:: python playlist.py –name “My Playlist” –artist “Pink Floyd” –output playlists/
Create playlist from files and directories:: python playlist.py –name “Files” –inputs song1.mp3 song2.flac /path/to/music/
Create playlist from input file:: python playlist.py –name “From File” –input-file mylist.txt –output playlists/
Load and display existing playlist:: python playlist.py –load existing_playlist.m3u

Queue

Audio Queue Manager

A script that manages a queue of songs from the audio library and plays them using player.py and a db file (assumed to be generated by database.py).

class modules.core.queue.RepeatMode(value)[source]

Bases: Enum

Repeat modes for audio playback

OFF = 'off'

TRACK = 'track'

QUEUE = 'queue'

class modules.core.queue.QueueManager(songs=None)[source]

Bases: object

Queue manager that handles dynamic repeat modes for audio playback. Provides playlist-level loop control with dynamic mode switching.

Initialize the QueueManager.

Parameters:: songs (list, optional) – List of song dictionaries or database records. Defaults to None (empty list).

__init__(songs=None)[source]

Initialize the QueueManager.

Parameters:: songs (list, optional) – List of song dictionaries or database records. Defaults to None (empty list).

set_repeat_mode(mode)[source]

Set the repeat mode (can be changed dynamically). Mode changes preserve forward queue - only manual selections clear it.

Parameters:: mode (str or RepeatMode) – The repeat mode to set. Can be a string (“off”, “track”, “queue”) or RepeatMode enum value.

set_shuffle_mode(enabled)[source]

Set shuffle mode. Mode changes preserve forward queue - only manual selections clear it.

Parameters:: enabled (bool) – True to enable shuffle mode, False to disable it.

is_shuffle_effective()[source]

Check if shuffle mode is effectively active. Shuffle is only effective when repeat mode is OFF.

Returns:: True if shuffle is both enabled and effective, False otherwise.
Return type:: bool

current_song()[source]

Get the current song.

Returns:: The current song dictionary, or None if no song is available.
Return type:: dict or None

has_songs()[source]

Check if the queue has any songs.

Returns:: True if there are songs in the queue, False otherwise.
Return type:: bool

next_track()[source]

Move to next track based on repeat mode and shuffle mode. Prioritizes forward history (from previous button) over normal progression. Always adds current song to global history for universal previous functionality.

Returns:: True if there’s a next track, False if queue ended.
Return type:: bool

next_track_skip_missing()[source]

Move to next track like next_track() but automatically skips missing files. For auto-progression after song ends - prevents playing missing files.

Returns:: True if there’s a next available track, False if queue ended.
Return type:: bool

previous_track()[source]

Move to previous track using global playback history. Always goes to the previously played song regardless of mode. When going back, adds current song to forward history for next button.

Returns:: True if successfully moved to previous track, False otherwise.
Return type:: bool

set_current_index(index)[source]

Set the current track index. Manual song selection clears forward queue to resync predictions. History tracking ensures proper previous button functionality.

Parameters:: index (int) – The index to set as the current track.
Returns:: True if the index was valid and set successfully, False otherwise.
Return type:: bool

add_song(song)[source]

Add a song to the queue.

Parameters:: song (dict) – Song dictionary to add to the queue

add_songs(songs)[source]

Add multiple songs to the queue.

Parameters:: songs (list) – List of song dictionaries to add to the queue

remove_song(index)[source]

Remove a song from the queue by index.

Parameters:: index (int) – Index of song to remove
Returns:: True if song was removed, False if index was invalid
Return type:: bool

shuffle_queue()[source]

Shuffle the entire queue by randomly reordering all songs. This physically reorders the songs list and resets the current index.

Returns:: True if queue was shuffled, False if queue is empty
Return type:: bool

play_random_song()[source]

Jump to a completely random song in the queue. This doesn’t reorder the queue, just changes the current playing position.

Returns:: True if jumped to random song, False if queue is empty
Return type:: bool

clear_queue()[source]: Clear all songs from the queue.

handle_song_finished()[source]

Handle when current song finishes playing. Auto-skips missing files during progression.

Returns:

(should_continue: bool, next_song: dict or None): should_continue: True if playback should continue next_song: The next song to play, or None if should stop

Return type:

modules.core.queue.play_queue_with_manager(songs, repeat_mode='off', shuffle=False, start_index=0, conn=None)[source]

Play songs using QueueManager with dynamic repeat mode support. This approach handles looping at the queue level rather than player level.

Parameters:

songs (list) – List of song dictionaries or database records.
repeat_mode (str) – Repeat mode - “off”, “track”, or “queue”
shuffle (bool) – Enable shuffle mode
start_index (int) – Index to start playback from
conn (sqlite3.Connection) – Database connection for auto-adding missing songs

modules.core.queue.play_single_song_with_loop(song_path, repeat_mode='off')[source]

Play a single song with optional looping using the queue system. This function is designed for GUI integration.

Parameters:

song_path (str) – Path to the audio file
repeat_mode (str) – “off”, “track”, or “queue”

Returns:

The queue manager instance for external control

Return type:

QueueManager

modules.core.queue.connect_to_database(db_path)[source]

Connect to the SQLite database and return connection.

Parameters:: db_path (str) – Path to the SQLite database file.
Returns:: Database connection object, or None if connection fails.
Return type:: sqlite3.Connection or None

modules.core.queue.get_songs_from_database(conn, filters=None)[source]

Get songs from database based on filters.

Parameters:

conn (sqlite3.Connection) – Database connection object.
filters (dict, optional) – Dictionary with filter criteria. Supported keys: ‘artist’, ‘album’, ‘genre’ (all use partial matching).

Returns:

List of song records as sqlite3.Row objects, ordered by artist, album, disc, track.

Return type:

modules.core.queue.format_song_info(song)[source]

Format song information for display with comprehensive metadata.

Parameters:: song (dict or sqlite3.Row) – Song record with metadata.
Returns:: Formatted song information string with track, artist, title, albumartist, album, year, and duration.
Return type:: str

modules.core.queue.display_queue(queue, current_index=0)[source]

Display the current queue with highlighting for current song.

Parameters:

queue (list) – List of song dictionaries or database records.
current_index (int, optional) – Index of currently playing song. Defaults to 0.

modules.core.queue.play_queue(queue, shuffle=False, repeat=False, repeat_track=False, start_index=0, conn=None)[source]

Play songs in the queue with various playback options.

Parameters:

queue (list) – List of song dictionaries or database records.
shuffle (bool, optional) – Enable shuffle mode. Defaults to False.
repeat (bool, optional) – Enable repeat mode (queue repeat). Defaults to False.
repeat_track (bool, optional) – Enable track repeat mode. Defaults to False.
start_index (int, optional) – Index to start playback from. Defaults to 0.
conn (sqlite3.Connection, optional) – Database connection for auto-adding missing songs.

modules.core.queue.add_missing_song_to_database(file_path, conn)[source]

Add missing song to database automatically during playback.

Parameters:

file_path (str) – Path to the audio file to add.
conn (sqlite3.Connection) – Database connection object.

Returns:

True if song was added successfully, False otherwise.

Return type:

modules.core.queue.interactive_mode(conn)[source]

Interactive mode for queue management.

Provides a command-line interface for managing audio queues with commands for filtering, loading, and playing songs.

Parameters:: conn (sqlite3.Connection) – Database connection object.

modules.core.queue.main()[source]

Main function for audio queue management command-line interface.

Parses command-line arguments and performs queue operations including database filtering, playlist loading, and various playback modes.

Examples

Play all songs by an artist with shuffle:: python queue.py –artist “Pink Floyd” –shuffle
Play specific album on repeat:: python queue.py –album “Dark Side of the Moon” –repeat
Play from external playlist:: python queue.py –playlist myplaylist.m3u
Interactive mode with genre filter:: python queue.py –genre “Rock” –interactive
Custom database path:: python queue.py –db-path ~/music.db –shuffle

Addons Modules

Convert

Audio File Converter using FFmpeg

A flexible audio conversion tool that supports multiple input formats and provides various conversion options including output format selection, metadata preservation, bitrate adjustment, and bit depth selection.

class modules.addons.convert.AudioConverter(options: Dict[str, Any])[source]

Bases: object

Audio file converter using FFmpeg to convert between various audio formats with options for metadata preservation, bitrate, bit depth, and other settings.

Initialize the AudioConverter with the specified options.

Parameters:: options (dict) – Dictionary of conversion options

__init__(options: Dict[str, Any])[source]

Initialize the AudioConverter with the specified options.

Parameters:: options (dict) – Dictionary of conversion options

get_file_info(filepath: str) → Dict[str, Any][source]

Get detailed information about an audio file using FFprobe.

Parameters:: filepath (str) – Path to the audio file
Returns:: Dictionary containing file information
Return type:: dict

is_already_in_target_format(filepath: str) → bool[source]

Check if file is already in the target format with matching specs.

Parameters:: filepath (str) – Path to the audio file
Returns:: True if file is already in target format with matching specs
Return type:: bool

prompt_overwrite(filepath: str) → bool[source]

Prompt user for overwrite decision with options for all files.

Parameters:: filepath (str) – Path to the file that would be overwritten
Returns:: True if should overwrite, False if should skip
Return type:: bool

display_file_info(filepath: str)[source]

Display detailed information about an audio file.

Parameters:: filepath (str) – Path to the audio file

build_ffmpeg_command(input_file: str, output_file: str) → List[str][source]

Build the FFmpeg command for audio conversion based on the options.

Parameters:

input_file (str) – Path to the input file
output_file (str) – Path to the output file

Returns:

FFmpeg command as a list of arguments

Return type:

convert_file(input_file: str, output_dir: str | None = None) → Tuple[bool, str][source]

Convert a single audio file to the specified format.

Parameters:

input_file (str) – Path to the input file
output_dir (str, optional) – Output directory. If None, use the input directory.

Returns:

(success: bool, reason: str) where reason is one of:: ’converted’, ‘already_target_format’, ‘skipped_existing’, ‘skipped_user’, ‘error’

Return type:

convert_directory(input_dir: str, output_dir: str | None = None) → Tuple[int, int][source]

Convert all audio files in a directory to the specified format.

Parameters:

input_dir (str) – Input directory containing audio files
output_dir (str, optional) – Output directory. If None, use the input directory.

Returns:

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

Return type:

modules.addons.convert.parse_arguments()[source]

Parse command line arguments.

Returns:: Parsed arguments
Return type:: argparse.Namespace

modules.addons.convert.main()[source]: Main function for the audio converter.

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)_(albumartist)_(year) with sanitized folder names but can be changed by user.

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

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])[source]

Initialize the FileRelocater with the specified options.

Parameters:: options (dict) – Dictionary of organization options

sanitize_folder_name(text: str) → str[source]

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][source]

Extract metadata from an audio file using the metadata module’s specific functions.

Parameters:: filepath (str) – Path to the audio file
Returns:: Dictionary containing all available metadata with “Unknown” for missing values
Return type:: dict

generate_folder_path(filepath: str) → str | None[source]

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[source]

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:

organize_directory(source_dir: str, destination_root: str) → tuple[int, int][source]

Organize all audio files in a directory.

Parameters:

source_dir (str) – Source directory containing audio files
destination_root (str) – Root directory for organized files

Returns:

(number of files moved, total files processed)

Return type:

tuple[int, int]

update_playlists() → int[source]

Update all loaded playlists with new file paths using the PlaylistUpdater.

Returns:: Number of playlists successfully updated
Return type:: int

modules.addons.file_relocater.parse_arguments()[source]

Parse command line arguments.

Returns:: Parsed arguments
Return type:: argparse.Namespace

modules.addons.file_relocater.parse_character_replacements(replace_char_list, no_defaults=False)[source]

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 any default replacements

Returns:

Dictionary mapping old characters to new characters

Return type:

dict

modules.addons.file_relocater.validate_path_format(path_arg, arg_name)[source]

Validate that a path argument doesn’t contain invalid formatting like quoted strings.

Parameters:

path_arg (str) – The path argument to validate
arg_name (str) – The name of the argument (for error messages)

Returns:

True if valid, False if invalid

Return type:

modules.addons.file_relocater.main()[source]: Main function for the audio organizer.

Image Converter

Image Converter

A utility for converting images between different formats and resizing them using ImageMagick. Supports common image formats like JPEG, PNG, WebP, BMP, TIFF, and GIF. Provides options for quality control, size adjustment, and batch processing.

modules.addons.imageconverter.setup_logging(level: str = 'INFO') → Logger[source]

Set up logging configuration.

Parameters:: level (str) – Logging level (‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’)
Returns:: Configured logger instance
Return type:: logging.Logger

modules.addons.imageconverter.check_imagemagick() → bool[source]

Check if ImageMagick is available on the system.

Returns:: True if ImageMagick is available, False otherwise
Return type:: bool

modules.addons.imageconverter.get_supported_formats() → Dict[str, str][source]

Get supported image formats with descriptions.

Returns:: Dictionary of format extensions and their descriptions
Return type:: dict

modules.addons.imageconverter.validate_format(format_name: str) → str[source]

Validate and normalize image format.

Parameters:: format_name (str) – Image format name
Returns:: Normalized format name
Return type:: str
Raises:: ValueError – If format is not supported

modules.addons.imageconverter.parse_size(size_str: str, force_stretch: bool = False) → Tuple[str | None, bool][source]

Parse size string into ImageMagick geometry format.

Parameters:

size_str (str) – Size string in format ‘WIDTHxHEIGHT’, ‘WIDTH’, or ‘xHEIGHT’
force_stretch (bool) – Force exact dimensions, ignoring aspect ratio

Returns:

(geometry_string, maintain_aspect_ratio)

Return type:

Raises:

ValueError – If size string is invalid

modules.addons.imageconverter.get_image_info(image_path: str) → Dict[str, Any] | None[source]

Get information about an image using ImageMagick identify command.

Parameters:: image_path (str) – Path to the image file
Returns:: Image information or None if error
Return type:: dict or None

modules.addons.imageconverter.convert_image(input_path: str, output_path: str = None, output_format: str = None, geometry: str = None, quality: int = 100, auto_orient: bool = True, strip_metadata: bool = False, background_color: str = 'white') → bool[source]

Convert a single image file using ImageMagick.

Parameters:

input_path (str) – Path to input image file
output_path (str, optional) – Path for output file (auto-generated if None)
output_format (str, optional) – Output format (detected from extension if None)
geometry (str, optional) – ImageMagick geometry string for resizing
quality (int) – JPEG/WebP quality (1-100, only for lossy formats)
auto_orient (bool) – Auto-rotate based on EXIF orientation
strip_metadata (bool) – Remove EXIF metadata
background_color (str) – Background color for transparency removal

Returns:

True if conversion successful, False otherwise

Return type:

modules.addons.imageconverter.convert_batch(input_paths: List[str], output_dir: str = None, output_format: str = 'jpeg', geometry: str = None, quality: int = 100, auto_orient: bool = True, strip_metadata: bool = False, background_color: str = 'white', overwrite: bool = False) → Tuple[int, int][source]

Convert multiple images in batch using ImageMagick.

Parameters:

input_paths (list) – List of input image file paths
output_dir (str, optional) – Output directory (same as input if None)
output_format (str) – Output format for all images
geometry (str, optional) – ImageMagick geometry string for resizing
quality (int) – JPEG/WebP quality (1-100, only for lossy formats)
auto_orient (bool) – Auto-rotate based on EXIF orientation
strip_metadata (bool) – Remove EXIF metadata
background_color (str) – Background color for transparency removal
overwrite (bool) – Overwrite existing output files

Returns:

(successful_count, total_count)

Return type:

modules.addons.imageconverter.scan_directory(directory: str, recursive: bool = False) → List[str][source]

Scan directory for image files.

Parameters:

directory (str) – Directory path to scan
recursive (bool) – Scan subdirectories recursively

Returns:

List of image file paths

Return type:

modules.addons.imageconverter.parse_arguments()[source]

Parse command line arguments.

Returns:: Parsed arguments
Return type:: argparse.Namespace

modules.addons.imageconverter.main()[source]: Main function for the image converter.

Playlist Cloner

Playlist Cloner

Clones all audio files from a playlist to a new directory with optional format conversion. Useful for creating portable collections or converting playlists for specific devices.

class modules.addons.playlist_cloner.PlaylistCloner(playlist_path: str, output_dir: str, output_format: str = 'opus', bitrate: str = '192k', preserve_structure: bool = False, skip_existing: bool = True, dry_run: bool = False)[source]

Bases: object

Clones audio files from a playlist to a destination directory with optional format conversion.

Initialize the PlaylistCloner.

Parameters:

playlist_path (str) – Path to the M3U playlist file
output_dir (str) – Destination directory for cloned files
output_format (str) – Output audio format (default: opus)
bitrate (str) – Bitrate for lossy formats (default: 192k)
preserve_structure (bool) – If True, preserve folder structure; if False, flatten
skip_existing (bool) – Skip files that already exist in destination
dry_run (bool) – If True, show what would be done without actually doing it

__init__(playlist_path: str, output_dir: str, output_format: str = 'opus', bitrate: str = '192k', preserve_structure: bool = False, skip_existing: bool = True, dry_run: bool = False)[source]

Initialize the PlaylistCloner.

Parameters:

playlist_path (str) – Path to the M3U playlist file
output_dir (str) – Destination directory for cloned files
output_format (str) – Output audio format (default: opus)
bitrate (str) – Bitrate for lossy formats (default: 192k)
preserve_structure (bool) – If True, preserve folder structure; if False, flatten
skip_existing (bool) – Skip files that already exist in destination
dry_run (bool) – If True, show what would be done without actually doing it

clone_playlist() → Tuple[int, int, int, int][source]

Clone all files from the playlist to the output directory.

Returns:: (total, converted, copied, skipped, errors)
Return type:: Tuple[int, int, int, int]

modules.addons.playlist_cloner.parse_arguments()[source]

Parse command line arguments.

Returns:: Parsed arguments
Return type:: argparse.Namespace

modules.addons.playlist_cloner.main()[source]: Main entry point for the playlist cloner.

Playlist Deleter

Playlist Deleter

Deletes all audio files referenced in a playlist. WARNING: This is a destructive operation! Use with caution.

class modules.addons.playlist_deleter.PlaylistDeleter(playlist_path: str, delete_empty_dirs: bool = False, dry_run: bool = False, force: bool = False)[source]

Bases: object

Deletes all audio files referenced in a playlist.

Initialize the PlaylistDeleter.

Parameters:

playlist_path (str) – Path to the M3U playlist file
delete_empty_dirs (bool) – If True, delete empty directories after deleting files
dry_run (bool) – If True, show what would be deleted without actually deleting
force (bool) – If True, skip confirmation prompt

__init__(playlist_path: str, delete_empty_dirs: bool = False, dry_run: bool = False, force: bool = False)[source]

Initialize the PlaylistDeleter.

Parameters:

playlist_path (str) – Path to the M3U playlist file
delete_empty_dirs (bool) – If True, delete empty directories after deleting files
dry_run (bool) – If True, show what would be deleted without actually deleting
force (bool) – If True, skip confirmation prompt

delete_playlist_files() → Tuple[int, int, int, int][source]

Delete all files from the playlist.

Returns:: (total, deleted, missing, errors)
Return type:: Tuple[int, int, int, int]

modules.addons.playlist_deleter.parse_arguments()[source]

Parse command line arguments.

Returns:: Parsed arguments
Return type:: argparse.Namespace

modules.addons.playlist_deleter.main()[source]: Main entry point for the playlist deleter.

Playlist Fixer

Playlist Fixer

A tool to scan playlists for missing songs and attempt to resolve them by searching for matching files or prompting the user for replacements.

class modules.addons.playlist_fixer.PlaylistFixer(playlist_path: str, search_dirs: List[str] = None)[source]

Bases: object

Tool to fix missing songs in playlists by searching for replacements or prompting users.

Initialize the PlaylistFixer.

Parameters:

playlist_path (str) – Path to the playlist file to fix
search_dirs (List[str]) – Optional list of directories to search for missing files

__init__(playlist_path: str, search_dirs: List[str] = None)[source]

Initialize the PlaylistFixer.

Parameters:

playlist_path (str) – Path to the playlist file to fix
search_dirs (List[str]) – Optional list of directories to search for missing files

load_playlist() → List[Dict] | None[source]

Load the playlist using the playlist module.

Returns:: List of track dictionaries or None if failed
Return type:: Optional[List[Dict]]

find_missing_songs() → List[Tuple[int, Dict]][source]

Identify all missing songs in the playlist.

Returns:: List of (index, track_data) tuples for missing songs
Return type:: List[Tuple[int, Dict]]

build_file_cache()[source]: Build a cache of audio files in the search directories. Maps filename -> list of full paths for quick lookup.

find_replacement_candidates(missing_path: str) → List[str][source]

Find potential replacement files based on filename matching.

Parameters:: missing_path (str) – Path to the missing file
Returns:: List of candidate replacement paths
Return type:: List[str]

prompt_user_for_replacement(missing_track: Dict, candidates: List[str]) → str | None[source]

Prompt the user to select a replacement or take another action.

Parameters:

missing_track (Dict) – Track data for the missing song
candidates (List[str]) – List of candidate replacement paths

Returns:

Replacement path, ‘REMOVE’ to remove, ‘SKIP’ to skip, or None

Return type:

Optional[str]

fix_playlist(dry_run: bool = False) → bool[source]

Fix missing songs in the playlist.

Parameters:: dry_run (bool) – If True, show what would be fixed without saving
Returns:: True if playlist was modified (or would be in dry run), False otherwise
Return type:: bool

modules.addons.playlist_fixer.main()[source]: Main entry point for the playlist fixer tool.

Playlist Overlap

Playlist Overlap Finder

This script finds songs that appear in multiple playlists (overlap) and creates a new playlist containing only those overlapping songs.

class modules.addons.playlist_overlap.PlaylistOverlapFinder[source]

Bases: object

Find overlapping songs between playlists and create a new playlist with the results.

Initialize the PlaylistOverlapFinder.

__init__()[source]: Initialize the PlaylistOverlapFinder.

find_overlap(playlist_paths: List[str]) → Set[str][source]

Find songs that appear in all provided playlists.

Parameters:: playlist_paths (list) – List of playlist file paths
Returns:: Set of file paths that appear in all playlists
Return type:: set

find_unique_to_first(playlist_paths: List[str]) → Set[str][source]

Find songs that appear only in the first playlist but not in any others.

Parameters:: playlist_paths (list) – List of playlist file paths
Returns:: Set of file paths that appear only in the first playlist
Return type:: set

find_non_overlapping(playlist_paths: List[str]) → Set[str][source]

Find songs that don’t overlap (appear in only one playlist, not in all).

Parameters:: playlist_paths (list) – List of playlist file paths
Returns:: Set of file paths that appear in at least one playlist but not all
Return type:: set

create_overlap_playlist(playlist_paths: List[str], output_path: str, use_relative_paths: bool = True, mode: str = 'overlap') → bool[source]

Create a new playlist containing overlapping or non-overlapping songs.

Parameters:

playlist_paths (list) – List of playlist file paths to compare
output_path (str) – Path for the output playlist file
use_relative_paths (bool) – Whether to use relative paths in output
mode (str) – ‘overlap’, ‘unique-first’, or ‘non-overlapping’

Returns:

True if successful, False otherwise

Return type:

display_overlap_info(playlist_paths: List[str], mode: str = 'overlap') → None[source]

Display information about songs without creating a playlist.

Parameters:

playlist_paths (list) – List of playlist file paths to compare
mode (str) – ‘overlap’, ‘unique-first’, or ‘non-overlapping’

modules.addons.playlist_overlap.parse_arguments()[source]

Parse command line arguments.

Returns:: Parsed arguments
Return type:: argparse.Namespace

modules.addons.playlist_overlap.main()[source]: Main entry point for the playlist overlap finder.

Playlist Updater

Playlist Updater

A centralized utility for updating M3U playlist files when audio file paths change. Provides detailed logging and can be used by any module that modifies file paths.

class modules.addons.playlist_updater.PlaylistUpdater(playlist_paths: List[str], dry_run: bool = False)[source]

Bases: object

Centralized utility for updating playlists when file paths change. Provides detailed logging of all changes made to playlists.

Initialize the PlaylistUpdater.

Parameters:

playlist_paths (List[str]) – List of playlist file/directory paths to update
dry_run (bool) – If True, show what would be updated without saving

__init__(playlist_paths: List[str], dry_run: bool = False)[source]

Initialize the PlaylistUpdater.

Parameters:

playlist_paths (List[str]) – List of playlist file/directory paths to update
dry_run (bool) – If True, show what would be updated without saving

update_playlists(path_mapping: Dict[str, str]) → int[source]

Update all loaded playlists with new file paths. Provides detailed logging for each change made.

Parameters:: path_mapping (Dict[str, str]) – Dictionary mapping old paths to new paths
Returns:: Number of playlists successfully updated
Return type:: int

modules.addons.playlist_updater.load_playlists_from_paths(playlist_paths: List[str]) → List[str][source]

Helper function to load playlist file paths from a list of file/directory paths.

Parameters:: playlist_paths (List[str]) – List of paths (files or directories)
Returns:: List of playlist file paths
Return type:: List[str]

Rename

Audio File Renamer

A tool to rename audio files to a standardized format: “(track name) - (album)” while removing special characters that can cause issues with music players.

For file names, includes: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ[]()-_~@=+

class modules.addons.rename.AudioRenamer(options: Dict[str, Any])[source]

Bases: object

Audio file renamer that standardizes filenames based on metadata

Initialize the AudioRenamer with the specified options.

Parameters:: options (dict) – Dictionary of renaming options

__init__(options: Dict[str, Any])[source]

Initialize the AudioRenamer with the specified options.

Parameters:: options (dict) – Dictionary of renaming options

prompt_allow_special_chars(original_name: str, sanitized_name: str) → bool[source]

Prompt user whether to allow special characters when sanitization removes them.

Parameters:

original_name (str) – Original filename before sanitization
sanitized_name (str) – Filename after sanitization

Returns:

True if should allow special chars, False if should use sanitized version

Return type:

sanitize_filename(text: str) → str[source]

Clean a string to be safe for use as a filename.

Parameters:: text (str) – Text to sanitize
Returns:: Sanitized text
Return type:: str

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

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_new_filename(filepath: str) → str | None[source]

Generate a new filename based on metadata using the specified format.

Parameters:: filepath (str) – Path to the audio file
Returns:: New filename, or None if format cannot be resolved
Return type:: str or None

resolve_filename_conflict(filepath: str, new_filename: str, directory: str) → str[source]

Resolve filename conflicts by adding a counter to the title portion of the filename.

Parameters:

filepath (str) – Original file path
new_filename (str) – Proposed new filename
directory (str) – Target directory

Returns:

Resolved filename with counter added to title if needed

Return type:

str

rename_file(filepath: str) → bool[source]

Rename a single audio file based on its metadata.

Parameters:: filepath (str) – Path to the audio file
Returns:: True if rename was successful, False otherwise
Return type:: bool

rename_directory(directory: str) → tuple[int, int][source]

Rename all audio files in a directory.

Parameters:: directory (str) – Directory containing audio files
Returns:: (number of successful renames, total number of files processed)
Return type:: tuple

update_playlists() → int[source]

Update all loaded playlists with new file paths using the PlaylistUpdater.

Returns:: Number of playlists successfully updated
Return type:: int

modules.addons.rename.parse_arguments()[source]

Parse command line arguments.

Returns:: Parsed arguments
Return type:: argparse.Namespace

modules.addons.rename.parse_character_replacements(replace_char_list, no_defaults=False)[source]

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 any default replacements (deprecated parameter)

Returns:

Dictionary mapping old characters to new characters

Return type:

dict

modules.addons.rename.main()[source]: Main function for the audio renamer.

ReplayGain

ReplayGain LUFS Analyzer

A tool to analyze audio files for ReplayGain values using LUFS (Loudness Units relative to Full Scale). Uses rsgain tool for analysis and can optionally apply ReplayGain tags to files.

This implementation is inspired by the MuseAmp project by tapscodes.

class modules.addons.replaygain.ReplayGainAnalyzer(target_lufs: int = -18)[source]

Bases: object

Audio ReplayGain analyzer using rsgain for LUFS analysis

Initialize the ReplayGain analyzer.

Parameters:: target_lufs (int) – Target LUFS value for analysis (default: -18)

__init__(target_lufs: int = -18)[source]

Initialize the ReplayGain analyzer.

Parameters:: target_lufs (int) – Target LUFS value for analysis (default: -18)

is_supported_file(filepath: str) → bool[source]

Check if a file is a supported audio file.

Parameters:: filepath (str) – Path to the file
Returns:: True if the file is supported, False otherwise
Return type:: bool

analyze_file(filepath: str) → Dict[str, Any] | None[source]

Analyze a single audio file for ReplayGain values using rsgain.

Parameters:: filepath (str) – Path to the audio file
Returns:: Analysis results containing loudness, gain, and clipping info, or None if analysis failed
Return type:: dict or None

analyze_and_tag_file(filepath: str, skip_tagged: bool = True) → Dict[str, Any] | None[source]

Analyze a file and optionally apply ReplayGain tags.

Parameters:

filepath (str) – Path to the audio file
skip_tagged (bool) – If True, skip files that already have ReplayGain tags

Returns:

Analysis results, or None if analysis failed

Return type:

dict or None

analyze_directory(directory: str, recursive: bool = True, analyze_only: bool = True) → List[Dict[str, Any]][source]

Analyze all supported audio files in a directory.

Parameters:

directory (str) – Directory to analyze
recursive (bool) – If True, process subdirectories recursively
analyze_only (bool) – If True, only analyze without tagging

Returns:

List of analysis results for all processed files

Return type:

print_analysis_summary(results: List[Dict[str, Any]], detailed: bool = False)[source]

Print a summary of analysis results.

Parameters:

results (list) – List of analysis results
detailed (bool) – If True, print detailed per-file results

modules.addons.replaygain.parse_arguments()[source]

Parse command line arguments.

Returns:: Parsed arguments
Return type:: argparse.Namespace

modules.addons.replaygain.main()[source]: Main function for the ReplayGain analyzer.

Niche Modules

Apply Loudness

Apply Loudness Tool

A tool to apply gain adjustments directly to audio files using FFmpeg while preserving metadata and album art. Can apply gain based on ReplayGain values or direct dB adjustments.

class modules.niche.applyloudness.LoudnessApplicator(create_backup: bool = True)[source]

Bases: object

Audio loudness applicator using FFmpeg for gain adjustment

Initialize the loudness applicator.

Parameters:: create_backup (bool) – Whether to create backup files before modification

__init__(create_backup: bool = True)[source]

Initialize the loudness applicator.

Parameters:: create_backup (bool) – Whether to create backup files before modification

is_supported_file(filepath: str) → bool[source]

Check if a file is a supported audio file.

Parameters:: filepath (str) – Path to the file
Returns:: True if the file is supported, False otherwise
Return type:: bool

get_replaygain_value(filepath: str, target_lufs: int = -18) → float | None[source]

Get ReplayGain value for a file using the ReplayGain analyzer.

Parameters:

filepath (str) – Path to the audio file
target_lufs (int) – Target LUFS value for ReplayGain calculation

Returns:

ReplayGain value in dB, or None if analysis failed

Return type:

float or None

get_audio_properties(filepath: str) → Dict[str, Any][source]

Get audio properties from a file using FFprobe.

Parameters:: filepath (str) – Path to the audio file
Returns:: Audio properties including bit depth, sample rate, etc.
Return type:: dict

apply_gain_to_file(filepath: str, gain_db: float, output_dir: str | None = None) → bool[source]

Apply gain to a single audio file using FFmpeg while preserving metadata and album art.

Parameters:

filepath (str) – Path to the audio file
gain_db (float) – Gain to apply in dB
output_dir (str, optional) – Output directory for modified files (None for in-place)

Returns:

True if successful, False otherwise

Return type:

process_files(file_paths: List[str], gain_db: float | None = None, use_replaygain: bool = False, target_lufs: int = -18, output_dir: str | None = None) → Tuple[int, int][source]

Process multiple audio files to apply gain.

Parameters:

file_paths (list) – List of file paths to process
gain_db (float, optional) – Fixed gain to apply in dB
use_replaygain (bool) – Whether to use ReplayGain values instead of fixed gain
target_lufs (int) – Target LUFS for ReplayGain calculation
output_dir (str, optional) – Output directory for modified files

Returns:

(successful_count, total_count)

Return type:

process_directory(directory: str, recursive: bool = True, gain_db: float | None = None, use_replaygain: bool = False, target_lufs: int = -18, output_dir: str | None = None) → Tuple[int, int][source]

Process all supported audio files in a directory.

Parameters:

directory (str) – Directory to process
recursive (bool) – Whether to process subdirectories recursively
gain_db (float, optional) – Fixed gain to apply in dB
use_replaygain (bool) – Whether to use ReplayGain values instead of fixed gain
target_lufs (int) – Target LUFS for ReplayGain calculation
output_dir (str, optional) – Output directory for modified files

Returns:

(successful_count, total_count)

Return type:

modules.niche.applyloudness.parse_arguments()[source]

Parse command line arguments.

Returns:: Parsed arguments
Return type:: argparse.Namespace

modules.niche.applyloudness.main()[source]: Main function for the apply loudness tool.

Resize Album Art

Resize Album Art Tool

A utility to extract album art from audio files, resize it using imageconverter, and embed it back into the original audio file. Useful for standardizing album art sizes across a music collection.

modules.niche.resizealbumart.setup_logging(level: str = 'INFO') → Logger[source]

Set up logging configuration.

Parameters:: level (str) – Logging level (‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’)
Returns:: Configured logger instance
Return type:: logging.Logger

modules.niche.resizealbumart.extract_album_art(audio_file: str, output_image: str) → bool[source]

Extract album art from an audio file using FFmpeg.

Parameters:

audio_file (str) – Path to the audio file
output_image (str) – Path where to save the extracted album art

Returns:

True if extraction successful, False otherwise

Return type:

modules.niche.resizealbumart.get_supported_audio_formats() → List[str][source]

Get list of supported audio file extensions.

Returns:: List of supported audio file extensions
Return type:: list

modules.niche.resizealbumart.is_audio_file(filepath: str) → bool[source]

Check if a file is a supported audio file.

Parameters:: filepath (str) – Path to the file to check
Returns:: True if file is a supported audio format
Return type:: bool

modules.niche.resizealbumart.resize_album_art(audio_file: str, size: str = '1000x1000', quality: int = 95, format: str = 'jpeg', maintain_aspect: bool = False, backup: bool | str = False) → bool[source]

Resize album art in an audio file.

Parameters:

audio_file (str) – Path to the audio file
size (str) – Target size (e.g., “1000x1000”)
quality (int) – JPEG quality (1-100)
format (str) – Output format for the resized image
maintain_aspect (bool) – Whether to maintain aspect ratio
backup (bool) – Whether to create a backup of the original file
backup_dir (str) – Directory to store backup files (default: same as original)

Returns:

True if resize operation successful, False otherwise

Return type:

modules.niche.resizealbumart.process_directory(directory: str, size: str = '1000x1000', quality: int = 95, format: str = 'jpeg', maintain_aspect: bool = False, backup: bool | str = False, recursive: bool = False) → tuple[int, int][source]

Process all audio files in a directory.

Parameters:

directory (str) – Directory path to process
size (str) – Target size for album art
quality (int) – JPEG quality
format (str) – Output format for resized images
maintain_aspect (bool) – Whether to maintain aspect ratio
backup (bool | str) – Whether to create backups, or directory path for backups
recursive (bool) – Whether to process subdirectories

Returns:

(successful_count, total_count)

Return type:

modules.niche.resizealbumart.parse_arguments()[source]

Parse command line arguments.

Returns:: Parsed arguments
Return type:: argparse.Namespace

modules.niche.resizealbumart.main()[source]: Main function for the resize album art tool.

Walrio Import

Walrio Import Pipeline - Complete audio library import processing

This script orchestrates a complete import pipeline for audio files through the Walrio system. It processes input directories through the following stages in order: 1. Convert to FLAC format with 48kHz/16-bit specifications 2. Rename files with standardized character filtering 3. Apply ReplayGain analysis with -16 LUFS target 4. Apply loudness normalization using ReplayGain tags 5. Resize album artwork to 1000x1000 JPEG format

modules.niche.walrio_import.get_walrio_path()[source]

Get the path to the walrio.py unified interface.

Returns:: Absolute path to walrio.py
Return type:: str

modules.niche.walrio_import.run_walrio_command(module_name, input_path, extra_args=None, recursive=False)[source]

Run a walrio module command with the given arguments.

Parameters:

module_name (str) – Name of the module to run
input_path (str) – Input file or directory path
extra_args (list) – Additional arguments for the module
recursive (bool) – Whether to add recursive flag

Returns:

True if command succeeded, False otherwise

Return type:

modules.niche.walrio_import.process_import_pipeline(input_path, recursive=False, dry_run=False, playlist_dir=None, delete_originals=False)[source]

Run the complete import pipeline on the input path.

Parameters:

input_path (str) – Path to input file or directory
recursive (bool) – Whether to process recursively
dry_run (bool) – Whether to show commands without executing
playlist_dir (str) – Directory containing playlists to update after rename
delete_originals (bool) – Delete original files after conversion

Returns:

True if all steps succeeded, False otherwise

Return type: