API Reference
This section contains the complete API reference for Walrio modules, automatically generated from the source code docstrings.
Core Modules
Database
Audio Library Analyzer
A script that analyzes audio files in a directory and stores metadata in SQLite database.
- modules.core.database.create_database(db_path)[source]
Create a new SQLite database with tables for music library.
Creates a comprehensive database schema based on Strawberry Music Player for storing music metadata, file information, and library structure.
- modules.core.database.get_file_hash(filepath)[source]
Generate a simple hash for the file based on path and size.
- modules.core.database.extract_metadata(filepath)[source]
Extract metadata from audio file using the centralized metadata module.
- Parameters:
filepath (str) – Path to the audio file.
- Returns:
- Dictionary containing extracted metadata, or None if extraction fails.
Keys include: title, artist, album, albumartist, track, disc, year, originalyear, genre, composer, performer, grouping, comment, lyrics, length, bitrate, samplerate, bitdepth, compilation, art_embedded.
- Return type:
dict or None
- modules.core.database.scan_directory(directory_path, conn)[source]
Scan directory for audio files and add to database.
Recursively scans the specified directory for audio files, extracts metadata, and adds them to the database.
- Parameters:
directory_path (str) – Path to the directory to scan.
conn (sqlite3.Connection) – Database connection object.
- Returns:
(files_added, files_updated, errors) - counts of operation results.
- Return type:
- 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.
- 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:
objectA 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.
- get_metadata(filepath: str) Dict[str, Any][source]
Get all metadata from an audio file using mutagen library directly.
- set_metadata(filepath: str, metadata: Dict[str, Any]) bool[source]
Set metadata for an audio file using mutagen library directly.
- set_album_art(filepath: str, image_path: str) bool[source]
Set album art for an audio file using mutagen library directly.
- remove_album_art(filepath: str) bool[source]
Remove album art from an audio file using mutagen library directly.
- batch_edit_metadata(file_paths: List[str], metadata: Dict[str, Any]) Dict[str, int][source]
Edit metadata for multiple files.
- Parameters:
- Returns:
- Statistics about the operation with keys:
processed: Number of successfully processed files
errors: Number of files that failed processing
- Return type:
- 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.
- extract_metadata_for_playlist(filepath: str) Dict[str, Any][source]
Extract metadata in the format expected by playlist.py.
- modules.core.metadata.main()[source]
Main function for command-line usage.
- Returns:
Exit code (0 for success, 1 for failure)
- Return type:
- 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.
- 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.
- modules.core.metadata.set_metadata(filepath: str, metadata: Dict[str, Any]) bool[source]
Convenience function to set metadata for a file.
- modules.core.metadata.set_album_art(filepath: str, image_path: str) bool[source]
Convenience function to set album art for a file.
- modules.core.metadata.embed_opus_album_art(opus_filepath: str, image_path: str) bool[source]
Convenience function to embed album art in OPUS files.
- modules.core.metadata.get_duration(filepath: str) float[source]
Get the duration of an audio file in seconds.
- modules.core.metadata.get_albumartist(filepath: str) str[source]
Get the albumartist tag from an audio file.
- modules.core.metadata.get_year(filepath: str) str[source]
Get the year/date tag from an audio file.
- modules.core.metadata.get_track(filepath: str) str[source]
Get the track number from an audio file.
Player
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:
- modules.core.playlist.get_relative_path(file_path, playlist_path)[source]
Convert file path to relative path from playlist location.
- 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.extract_metadata(file_path)[source]
Extract metadata from audio file using the centralized metadata module.
- modules.core.playlist.scan_directory(directory_path)[source]
Scan directory recursively for audio files.
- 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:
- 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
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:
objectAudio 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.
- is_already_in_target_format(filepath: str) bool[source]
Check if file is already in the target format with matching specs.
- prompt_overwrite(filepath: str) bool[source]
Prompt user for overwrite decision with options for all files.
- 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.
- convert_file(input_file: str, output_dir: str | None = None) Tuple[bool, str][source]
Convert a single audio file to the specified format.
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.
- class modules.addons.file_relocater.FileRelocater(options: Dict[str, Any])[source]
Bases:
objectAudio 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
- get_file_metadata(filepath: str) Dict[str, str][source]
Extract metadata from an audio file using the metadata module’s specific functions.
- generate_folder_path(filepath: str) str | None[source]
Generate a folder path based on metadata using the specified format.
- move_file(source_filepath: str, destination_root: str) bool[source]
Move a single audio file to the organized folder structure.
- modules.addons.file_relocater.parse_arguments()[source]
Parse command line arguments.
- Returns:
Parsed arguments
- Return type:
- modules.addons.file_relocater.parse_character_replacements(replace_char_list, no_defaults=False)[source]
Parse character replacement arguments from command line.
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:
- 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:
- 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:
- 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:
- 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:
- 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.
- 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.
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:
objectAudio 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.
- get_file_metadata(filepath: str) Dict[str, str][source]
Extract metadata from an audio file using FFprobe.
- generate_new_filename(filepath: str) str | None[source]
Generate a new filename based on metadata using the specified format.
- 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.
- modules.addons.rename.parse_arguments()[source]
Parse command line arguments.
- Returns:
Parsed arguments
- Return type:
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:
objectAudio 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)
- analyze_file(filepath: str) Dict[str, Any] | None[source]
Analyze a single audio file for ReplayGain values using rsgain.
- analyze_and_tag_file(filepath: str, skip_tagged: bool = True) Dict[str, Any] | None[source]
Analyze a file and optionally apply ReplayGain tags.
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:
objectAudio 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
- get_replaygain_value(filepath: str, target_lufs: int = -18) float | None[source]
Get ReplayGain value for a file using the ReplayGain analyzer.
- get_audio_properties(filepath: str) Dict[str, Any][source]
Get audio properties from a file using FFprobe.
- 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.
- 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:
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:
- modules.niche.resizealbumart.extract_album_art(audio_file: str, output_image: str) bool[source]
Extract album art from an audio file using FFmpeg.
- 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:
- modules.niche.resizealbumart.is_audio_file(filepath: str) bool[source]
Check if a file is a supported audio file.
- 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:
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:
- 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.