Command Line Usage
Walrio provides several command-line tools for audio file management and processing. These tools are located throughout the modules/ directory and can be run directly as Python scripts, or accessed through the unified walrio.py interface.
Unified Interface (Recommended)
Use the unified interface for easier access to all modules:
# General syntax
python modules/walrio.py <module> [module_args...]
# Get help and list modules
python modules/walrio.py --help
python modules/walrio.py list
# Get help for a specific module
python modules/walrio.py convert --help
Available Module Categories:
ADDONS: convert, rename, replaygain, imageconverter, file_relocater
NICHE: applyloudness, resizealbumart
CORE: database, metadata, player, playlist, queue
Direct Module Access
You can also run modules directly:
Available Tools
Addons Tools
Convert
Location: /home/runner/work/Walrio/Walrio/modules/addons/convert.py
Audio File Converter using FFmpeg
Complete Help Output:
usage: convert.py [-h] [--type {file,directory,auto}] [-o OUTPUT] [-r]
[--skip-existing {y,n}] [--force-overwrite {y,n}]
[-f {mp3,aac,opus,ogg,flac,alac,wav,wv}] [--metadata {y,n}]
[-b BITRATE] [-d {16,24,32}]
[--sample-rate {44100,48000,96000,192000,320000}]
[--channels {1,2}] [-q {low,standard,high,maximum}] [-i]
[--logging {low,high}] [--list-formats]
input [input ...]
Audio File Converter using FFmpeg
positional arguments:
input Input file(s) or directory to convert
options:
-h, --help show this help message and exit
--type {file,directory,auto}
Explicitly specify if inputs are files or a directory
(default: auto-detect)
-o OUTPUT, --output OUTPUT
Output directory (default: same as input)
-r, --recursive Recursively process directories
--skip-existing {y,n}, --se {y,n}
Skip existing files: y=yes, n=no (prompt)
--force-overwrite {y,n}, --fo {y,n}
Force overwrite of existing files: y=yes (force), n=no
(prompt)
-f {mp3,aac,opus,ogg,flac,alac,wav,wv}, --format {mp3,aac,opus,ogg,flac,alac,wav,wv}
Output format (default: flac)
--metadata {y,n} Preserve metadata: y=yes (default), n=no
-b BITRATE, --bitrate BITRATE
Audio bitrate for lossy formats (e.g., 128k, 256k,
320k)
-d {16,24,32}, --bit-depth {16,24,32}
Bit depth for lossless formats
--sample-rate {44100,48000,96000,192000,320000}
Sample rate in Hz
--channels {1,2} Number of audio channels (1=mono, 2=stereo)
-q {low,standard,high,maximum}, --quality {low,standard,high,maximum}
Encoding quality preset
-i, --info Display information about the input file and exit
--logging {low,high} Logging level: low (default) or high (verbose)
--list-formats List supported output formats and exit
Examples:
# Convert a single file to MP3
python convert.py input.wav --format mp3
# Convert multiple files at once
python convert.py file1.wav file2.mp3 file3.flac --format ogg
# Convert a directory of files to FLAC (default format)
python convert.py /music/input
# Convert files from multiple directories
python convert.py /music/input1 /music/input2 -o /music/output
# Explicitly specify that inputs are files
python convert.py file1 file2 --type file
# Convert files recursively without metadata, high logging level
python convert.py /music/input -o /music/output -r --metadata n --logging high
# Force overwrite existing files without prompting
python convert.py input.flac -f opus -y
For complete options, run: python /home/runner/work/Walrio/Walrio/modules/addons/convert.py --help
File Relocater
Location: /home/runner/work/Walrio/Walrio/modules/addons/file_relocater.py
Audio Library Organizer - Organize files into folder structures using metadata
Complete Help Output:
usage: file_relocater.py [-h] [-r] [--folder-format FOLDER_FORMAT]
[--replace-char OLD NEW] [--dontreplace]
[--sanitize CHARS] [--dont-sanitize] [--dry-run]
[--copy {y,n}] [--skip-existing]
[--process-no-metadata {y,n}] [--full-date]
[--logging {low,high}] [--list-metadata FILE]
[--check-dir]
source destination
Audio Library Organizer - Organize files into folder structures using metadata
positional arguments:
source Source directory containing audio files to organize
destination Destination root directory for organized library
options:
-h, --help show this help message and exit
-r, --recursive Recursively process subdirectories in source (default:
False)
--folder-format FOLDER_FORMAT
Folder structure format using metadata fields in
{field} syntax (default:
'{album}/{year}/{albumartist}')
--replace-char OLD NEW, --rc OLD NEW
Replace a specific character in folder names. Takes
two arguments: old character and new character (e.g.,
--replace-char '/' '-'). Use multiple times for
multiple replacements.
--dontreplace, --dr Disable standard character replacements. Only use
custom --replace-char replacements.
--sanitize CHARS, -s CHARS
Enable folder name sanitization with custom character
set. Provide all allowed characters as a string (e.g.,
--sanitize 'abcABC123-_ '). If no characters provided,
uses default set.
--dont-sanitize, --ds
Disable folder name sanitization (default: disabled).
Use this to explicitly override --sanitize in longer
commands where you might have accidentally included
it.
--dry-run Show what would be organized without actually moving
files
--copy {y,n} Copy files instead of moving them: y=yes (copy,
default), n=no (move files)
--skip-existing Skip organization if target file already exists
(default: True)
--process-no-metadata {y,n}, --pnm {y,n}
Process files with no metadata: y=yes (use filename as
folder), n=no (skip files, default)
--full-date Use full date from metadata instead of just the year
for {year} field
--logging {low,high} Logging level: low (default) or high (verbose)
--list-metadata FILE Show all available metadata fields for a specific file
and exit
--check-dir Check for common path formatting errors (like quoted
paths) and prompt user for confirmation
Examples:
# Organize music library using default format (copies files, skips files with no metadata): album/albumartist
python organize.py /path/to/music/library /path/to/organized/library
# Move files instead of copying them
python organize.py /music /organized --copy n
# Process files with no metadata using filename as folder name
python organize.py /music /organized --process-no-metadata y
python organize.py /music /organized --pnm y
# For music player compatibility (in the english language), use conservative character replacements and sanitization
python organize.py /music /organized --replace-char "/" "-" --replace-char "\\" "-" --replace-char ":" "-" --replace-char "|" "-" --sanitize "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_ "
# Custom folder format with year and genre (copying files, skipping files with no metadata)
python organize.py /music /organized --folder-format "{year}/{genre}/{albumartist}/{album}"
# Artist-based organization with conservative sanitization, process files with no metadata, move files
python organize.py /music /organized --folder-format "{artist}/{album}" --sanitize --pnm y --copy n
# Detailed organization with track info and custom character replacement
python organize.py /music /organized --folder-format "{albumartist}/{year} - {album}" --replace-char ":" "-"
Available pre-defined metadata fields:
{title} - Song title (searches: title, Title, TITLE, TIT2, etc.)
{album} - Album name (searches: album, Album, ALBUM, TALB, etc.)
{artist} - Track artist (searches: artist, Artist, TPE1, etc.)
{albumartist} - Album artist (searches: albumartist, AlbumArtist, TPE2, etc.)
{track} - Track number (searches: track, Track, tracknumber, etc.)
{year} - Release year (searches: year, Year, date, Date, etc.)
{genre} - Music genre (searches: genre, Genre, GENRE, etc.)
{disc} - Disc number (searches: disc, Disc, discnumber, etc.)
{composer} - Composer (searches: composer, Composer, TCOM, etc.)
{comment} - Comment field (searches: comment, Comment, COMM, etc.)
You can also use any raw metadata tag name (case-sensitive):
{ARTIST} - Use exact tag name from file
{TPE1} - Use ID3v2 tag directly
{Custom_Tag} - Use any custom tag present in the file
Character replacement examples (default: no replacements, files kept as-is):
--replace-char "/" "-" # Replace forward slashes with dashes only
--rc ":" "-" # Replace colons with dashes only (using shortcut)
--replace-char "&" "and" # Replace ampersands with 'and'
--rc "/" "-" --rc "&" "and" # Multiple replacements using shortcuts
--replace-char "?" "" # Remove question marks (replace with nothing)
--rc "/" "-" --rc "\" "-" --rc ":" "-" --rc "|" "-" # Conservative set for music players
Sanitization examples (default: no sanitization, keep all characters):
--sanitize # Enable character filtering using conservative character set
-s # Same as above using shortcut
--dont-sanitize # Explicitly disable character filtering (default behavior)
--ds # Same as above using shortcut
--sanitize "abcABC123-_ " # Enable filtering with custom allowed character set
--s "0123456789" # Only allow numbers using shortcut
--sanitize "" # Enable filtering with default character set
Custom sanitization examples:
--sanitize "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_ " # Basic set
--sanitize "abcABC123[]()-_~@=+ " # Include brackets and symbols (may cause issues)
--sanitize "αβγδεζηθικλμνξοπρστυφχψω" # Greek letters only
--s "あいうえおかきくけこ" # Japanese characters
Folder format tips:
- Use forward slashes (/) to separate folder levels: "{artist}/{album}"
- Missing fields will be empty (logged as warnings)
- Files with no metadata are skipped by default (use --process-no-metadata y to include them)
- When --process-no-metadata y is used, files with no metadata use filename as folder name
- Character replacements are applied before sanitization
- When sanitization is enabled, problematic characters are removed/replaced
- For music player compatibility (with the english language), consider using: --sanitize "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_ " --rc "/" "-" --rc ":" "-" --rc "\\" "-" --rc "|" "-"
- Default character set excludes apostrophes and special chars for maximum compatibility
For complete options, run: python /home/runner/work/Walrio/Walrio/modules/addons/file_relocater.py --help
Imageconverter
Location: /home/runner/work/Walrio/Walrio/modules/addons/imageconverter.py
Image Converter - Convert images between different formats and sizes using ImageMagick
Complete Help Output:
usage: imageconverter.py [-h] [-f FORMAT] [-o OUTPUT] [-s SIZE]
[--stretch {true,false}] [-q QUALITY]
[--no-auto-orient]
[--strip-exif-metadata {true,false}]
[--background BACKGROUND] [--overwrite] [-r] [--info]
[--list-formats]
[--logging {DEBUG,INFO,WARNING,ERROR}]
[input ...]
Image Converter - Convert images between different formats and sizes using ImageMagick
positional arguments:
input Input image file(s) or directory
options:
-h, --help show this help message and exit
-f FORMAT, --format FORMAT
Output format (default: jpeg)
-o OUTPUT, --output OUTPUT
Output file or directory (auto-generated if not
specified)
-s SIZE, --size SIZE Target size using ImageMagick geometry (default:
1000x1000)
--stretch {true,false}, --st {true,false}
Stretch images to exact dimensions instead of
maintaining aspect ratio (default: false)
-q QUALITY, --quality QUALITY
Quality for lossy formats (1-100, default: 100)
--no-auto-orient Disable auto-orientation based on EXIF
--strip-exif-metadata {true,false}, --sem {true,false}
Remove EXIF metadata from images (default: false)
--background BACKGROUND
Background color for transparency removal (default:
white)
--overwrite Overwrite existing output files (default: False)
-r, --recursive Process directories recursively (default: False)
--info Show image information and exit
--list-formats List supported formats and exit
--logging {DEBUG,INFO,WARNING,ERROR}
Logging level (default: INFO)
Examples:
# Convert single image to 1000x1000 JPEG (default behavior)
python imageconverter.py image.png
# Convert to different format, keeping default 1000x1000 size
python imageconverter.py image.png --format webp
# Convert with custom dimensions (maintains aspect ratio by default)
python imageconverter.py image.png --size 800x600
# Convert with forced stretching to exact dimensions
python imageconverter.py image.png --size 800x600 --stretch true
# Convert and resize by percentage
python imageconverter.py image.png --size 50%
# Batch convert all images in directory to default 1000x1000 JPEG
python imageconverter.py /path/to/images --recursive
# Convert with custom quality and strip metadata
python imageconverter.py image.jpg --quality 80 --strip-exif-metadata true
# Get image information
python imageconverter.py image.jpg --info
Supported formats: jpeg, jpg, png, webp, bmp, tiff, tif, gif, ico, svg, pdf, eps, psd
Note: By default, images maintain their aspect ratio when resized (e.g., 800x600 fits within those dimensions).
Use --stretch true to force exact dimensions and stretch the image instead.
ImageMagick geometry examples:
800x600 - Fit within 800x600 maintaining aspect ratio (default behavior)
800x600 - With --stretch true: resize to exactly 800x600 (stretches image)
800x600! - Force exact size (stretches - same as --stretch true)
800x600> - Only shrink if larger than 800x600
800x600< - Only enlarge if smaller than 800x600
50% - Resize to 50% of original size
For complete options, run: python /home/runner/work/Walrio/Walrio/modules/addons/imageconverter.py --help
Rename
Location: /home/runner/work/Walrio/Walrio/modules/addons/rename.py
Audio File Renamer - Rename files using custom metadata formats
Complete Help Output:
usage: rename.py [-h] [--type {file,directory,auto}] [-r] [-f FORMAT]
[--replace-char OLD NEW] [--dontreplace] [--sanitize CHARS]
[--dont-sanitize] [--auto-sanitize] [--force-allow-special]
[--dry-run] [--skip-existing]
[--resolve-conflicts {true,false}] [--skip-no-metadata]
[--full-date] [--logging {low,high}] [--list-metadata FILE]
input [input ...]
Audio File Renamer - Rename files using custom metadata formats
positional arguments:
input Input file(s) or directory to process
options:
-h, --help show this help message and exit
--type {file,directory,auto}
Explicitly specify if inputs are files or a directory
(default: auto-detect)
-r, --recursive Recursively process subdirectories (default: False)
-f FORMAT, --format FORMAT
Naming format using metadata fields in {field} syntax
(default: '{title} - {album} - {albumartist} -
{year}')
--replace-char OLD NEW, --rc OLD NEW
Replace a specific character in filenames. Takes two
arguments: old character and new character (e.g.,
--replace-char '/' '~'). Use multiple times for
multiple replacements.
--dontreplace, --dr Disable default character replacements (/ and \ to ~).
Only use custom --replace-char replacements.
--sanitize CHARS, --s CHARS
Enable filename sanitization with custom character
set. Provide all allowed characters as a string (e.g.,
--sanitize 'abcABC123-_ '). If no characters provided,
uses default set.
--dont-sanitize, --ds
Disable filename sanitization (default: disabled). Use
this to explicitly override --sanitize in longer
commands where you might have accidentally included
it.
--auto-sanitize Automatically sanitize filenames without prompting
when special characters are detected (disabled by
default)
--force-allow-special
Always allow special characters without prompting
(disabled by default, equivalent to --dont-sanitize
but still applies replacements)
--dry-run Show what would be renamed without actually renaming
files
--skip-existing Skip renaming if target filename already exists
(default: True, but overridden by conflict resolution)
--resolve-conflicts {true,false}
Resolve filename conflicts by adding counter to title
(default: true)
--skip-no-metadata Skip files that have no metadata for the specified
format fields
--full-date Use full date from metadata instead of just the year
for {year} field
--logging {low,high} Logging level: low (default) or high (verbose)
--list-metadata FILE Show all available metadata fields for a specific file
and exit
Examples:
# Rename using default format: title - album
python rename.py song.mp3
# Custom format with artist and year
python rename.py /music --format "{artist} - {title} ({year})"
# Track number prefix format
python rename.py /music --format "{track:02d} - {title}"
# Album folder organization format
python rename.py /music --format "{albumartist} - {album} - {title}"
# Resolve conflicts by adding counter to title (default behavior)
python rename.py /music
# Disable conflict resolution, skip conflicting files instead
python rename.py /music --resolve-conflicts false
# Custom format with conflict resolution
python rename.py /music --format "{artist} - {title}" --resolve-conflicts
Available pre-defined metadata fields:
{title} - Song title (searches: title, Title, TITLE, TIT2, etc.)
{album} - Album name (searches: album, Album, ALBUM, TALB, etc.)
{artist} - Track artist (searches: artist, Artist, TPE1, etc.)
{albumartist} - Album artist (searches: albumartist, AlbumArtist, TPE2, etc.)
{track} - Track number (searches: track, Track, tracknumber, etc.)
{year} - Release year (extracts year from date fields, use --full-date for complete date)
{genre} - Music genre (searches: genre, Genre, GENRE, etc.)
{disc} - Disc number (searches: disc, Disc, discnumber, etc.)
{composer} - Composer (searches: composer, Composer, TCOM, etc.)
{comment} - Comment field (searches: comment, Comment, COMM, etc.)
You can also use any raw metadata tag name (case-sensitive):
{ARTIST} - Use exact tag name from file
{TPE1} - Use ID3v2 tag directly
{Custom_Tag} - Use any custom tag present in the file
Character replacement examples (default: / and \ become ~):
--replace-char "/" "~" # Replace forward slashes with tildes (default)
--rc "\" "~" # Replace backslashes with tildes (default, using shortcut)
--replace-char "&" "and" # Replace ampersands with 'and'
--rc "/" "~" --rc "&" "and" # Multiple replacements using shortcuts
--replace-char "?" "" # Remove question marks (replace with nothing)
--dontreplace --rc "/" "-" # Disable defaults, only replace / with -
--dr --rc "=" "_" # Disable defaults using shortcut, replace = with _
Sanitization examples (default: sanitize enabled, prompt for special chars):
--sanitize # Explicitly enable character filtering (default behavior)
--s # Same as above using shortcut
--dont-sanitize # Disable character filtering, keep all characters (default)
--ds # Same as above using shortcut
--ds --rc "/" "~" # No filtering, but still replace / with ~
--dont-sanitize --dontreplace # No filtering or replacements at all
--sanitize "abcABC123-_ " # Enable filtering with custom allowed character set
--s "0123456789" # Only allow numbers using shortcut
--sanitize "" # Enable filtering with default character set
--auto-sanitize # Automatically remove special chars without prompting
--force-allow-special # Always keep special chars without prompting
Conflict resolution examples (default: resolve conflicts enabled):
python rename.py /music # Resolve conflicts by adding (2), (3) to title (default)
python rename.py /music --resolve-conflicts false # Skip files with conflicting names instead
python rename.py /music --resolve-conflicts true # Explicitly enable conflict resolution
python rename.py /music --skip-existing # Also skip existing files (when combined with --resolve-conflicts false)
Custom sanitization examples:
--sanitize "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_ " # Basic english set
--sanitize "abcABC123[]()-_~@=+ " # Include brackets and symbols
--sanitize "αβγδεζηθικλμνξοπρστυφχψω" # Greek letters only
--s "あいうえおかきくけこ" # Japanese characters
Format string tips:
- Use Python string formatting: {track:02d} for zero-padded numbers
- Missing fields will be empty (logged as warnings)
- Use --skip-no-metadata to skip files missing critical metadata
- Character replacements are applied before sanitization
- When sanitization is enabled, problematic characters are removed/replaced
- Use --sanitize "your_chars" to define your own allowed character set
For complete options, run: python /home/runner/work/Walrio/Walrio/modules/addons/rename.py --help
Replaygain
Location: /home/runner/work/Walrio/Walrio/modules/addons/replaygain.py
ReplayGain LUFS Analyzer - Analyze and tag audio files with ReplayGain values
Complete Help Output:
usage: replaygain.py [-h] (--analyze-only | --tag) [--target-lufs TARGET_LUFS]
[--skip-tagged] [--recursive] [--detailed] [--quiet]
[--json FILE] [--check-rsgain]
input [input ...]
ReplayGain LUFS Analyzer - Analyze and tag audio files with ReplayGain values
positional arguments:
input Audio files or directories to analyze
options:
-h, --help show this help message and exit
--analyze-only, --analyze
Only analyze files without applying ReplayGain tags
--tag Analyze files and apply ReplayGain tags
--target-lufs TARGET_LUFS, --lufs TARGET_LUFS
Target LUFS value for ReplayGain calculation (default:
-18)
--skip-tagged Skip files that already have ReplayGain tags (default:
False - process all files)
--recursive, -r Process directories recursively (default: False)
--detailed, --verbose
Show detailed per-file analysis results
--quiet, -q Suppress progress messages, only show summary
--json FILE Save analysis results to JSON file
--check-rsgain Check if rsgain is available and exit
Examples:
# Analyze files without tagging (dry run)
python replaygain.py /path/to/music --analyze-only
# Analyze and tag files with default -18 LUFS target
python replaygain.py /path/to/music --tag
# Use custom LUFS target
python replaygain.py /path/to/music --tag --target-lufs -16
# Analyze specific files
python replaygain.py song1.flac song2.mp3 --analyze-only
# Show detailed per-file results
python replaygain.py /path/to/music --analyze-only --detailed
# Tag files but skip those already tagged
python replaygain.py /path/to/music --tag --skip-tagged
# Force retag all files (default behavior - don't use --skip-tagged)
python replaygain.py /path/to/music --tag
Supported file formats:
- FLAC (.flac)
- MP3 (.mp3)
- M4A (.m4a)
LUFS Target Values:
-18 LUFS: ReplayGain 2.0 standard (default)
-16 LUFS: Apple Music standard
-14 LUFS: Spotify, Amazon Music, YouTube standard
-20 LUFS: TV broadcast standard
Requirements:
- rsgain tool (https://github.com/complexlogic/rsgain)
For complete options, run: python /home/runner/work/Walrio/Walrio/modules/addons/replaygain.py --help
Core Tools
Database
Location: /home/runner/work/Walrio/Walrio/modules/core/database.py
Audio Library Analyzer - Scans directory for audio files and stores metadata in SQLite database
Complete Help Output:
usage: database.py [-h] [--db-path DB_PATH] [--playlist PLAYLIST] [directory]
Audio Library Analyzer - Scans directory for audio files and stores metadata in SQLite database
positional arguments:
directory Path to the directory containing audio files
options:
-h, --help show this help message and exit
--db-path DB_PATH Path to SQLite database file (default:
walrio_library.db)
--playlist PLAYLIST Load songs from an M3U playlist file into the database
Examples:
python database.py /path/to/music --db-path ~/music.db
python database.py --playlist myplaylist.m3u --db-path ~/music.db
For complete options, run: python /home/runner/work/Walrio/Walrio/modules/core/database.py --help
Metadata
Location: /home/runner/work/Walrio/Walrio/modules/core/metadata.py
Modify audio file metadata using mutagen
Complete Help Output:
usage: metadata.py [-h] [--show] [--duration] [--set-title SET_TITLE]
[--set-artist SET_ARTIST] [--set-album SET_ALBUM]
[--set-albumartist SET_ALBUMARTIST] [--set-date SET_DATE]
[--set-year SET_YEAR] [--set-genre SET_GENRE]
[--set-track SET_TRACK] [--set-disc SET_DISC]
[--set-comment SET_COMMENT] [--set-album-art SET_ALBUM_ART]
[--remove-album-art] [--verbose]
[files ...]
Modify audio file metadata using mutagen
positional arguments:
files Audio files to process
options:
-h, --help show this help message and exit
--show Display current metadata
--duration Show only duration in seconds
--set-title SET_TITLE
Set title tag
--set-artist SET_ARTIST
Set artist tag
--set-album SET_ALBUM
Set album tag
--set-albumartist SET_ALBUMARTIST
Set album artist tag
--set-date SET_DATE Set date tag
--set-year SET_YEAR Set year tag
--set-genre SET_GENRE
Set genre tag
--set-track SET_TRACK
Set track number
--set-disc SET_DISC Set disc number
--set-comment SET_COMMENT
Set comment tag
--set-album-art SET_ALBUM_ART
Set album art from image file
--remove-album-art Remove album art
--verbose, -v Enable verbose logging
Examples:
# Display metadata
python metadata.py --show song.mp3
# Set title and artist
python metadata.py --set-title "New Title" --set-artist "New Artist" song.mp3
# Set album art
python metadata.py --set-album-art cover.jpg song.mp3
# Remove album art
python metadata.py --remove-album-art song.mp3
# Batch edit multiple files
python metadata.py --set-album "Album Name" *.mp3
For complete options, run: python /home/runner/work/Walrio/Walrio/modules/core/metadata.py --help
Playlist
Location: /home/runner/work/Walrio/Walrio/modules/core/playlist.py
Playlist Manager - Create and manage M3U playlists
Complete Help Output:
usage: playlist.py [-h] [--db-path DB_PATH] [--name NAME] [--output OUTPUT]
[--absolute] [--artist ARTIST] [--album ALBUM]
[--genre GENRE] [--load LOAD]
[--inputs INPUTS [INPUTS ...]] [--input-file INPUT_FILE]
Playlist Manager - Create and manage M3U playlists
options:
-h, --help show this help message and exit
--db-path DB_PATH Path to the SQLite database file (default:
walrio_library.db)
--name NAME Name of the playlist (required for database mode)
--output OUTPUT Directory to save the playlist file (default: current
directory)
--absolute Use absolute paths instead of relative paths
--artist ARTIST Filter songs by artist name (partial match)
--album ALBUM Filter songs by album name (partial match)
--genre GENRE Filter songs by genre (partial match)
--load LOAD Load and display contents of an existing M3U playlist
--inputs INPUTS [INPUTS ...]
List of audio files and/or directories to include in
the playlist
--input-file INPUT_FILE
Text file containing list of audio files/directories
(one per line)
Examples:
python playlist.py --name "My Playlist" --artist "Pink Floyd" --output playlists/
python playlist.py --name "Files" --inputs song1.mp3 song2.flac /path/to/music/
python playlist.py --name "From File" --input-file mylist.txt --output playlists/
For complete options, run: python /home/runner/work/Walrio/Walrio/modules/core/playlist.py --help
Modules Tools
Walrio
Location: /home/runner/work/Walrio/Walrio/modules/walrio.py
For module-specific help:
Complete Help Output:
Walrio - Unified Music Library Management System
==================================================
QUICK START - Common Commands:
python walrio.py convert /path/to/music --format flac
python walrio.py rename /path/to/music
python walrio.py replaygain /path/to/music
USAGE:
python walrio.py <module_name> [arguments...]
For module-specific help:
python walrio.py <module_name> --help
For a list of all modules and descriptions:
python walrio.py --help-more
For detailed documentation:
https://tapsoss.github.io/Walrio/
For complete options, run: python /home/runner/work/Walrio/Walrio/modules/walrio.py --help
Niche Tools
Applyloudness
Location: /home/runner/work/Walrio/Walrio/modules/niche/applyloudness.py
Apply Loudness Tool - Apply gain adjustments to audio files using FFmpeg
Complete Help Output:
usage: applyloudness.py [-h] (--gain GAIN | --replaygain)
[--target-lufs TARGET_LUFS] [--output DIR]
[--recursive] [--backup {true,false}] [--dry-run]
[--quiet] [--verbose] [--check-deps]
input [input ...]
Apply Loudness Tool - Apply gain adjustments to audio files using FFmpeg
positional arguments:
input Audio files or directories to process
options:
-h, --help show this help message and exit
--gain GAIN Fixed gain to apply in dB (e.g., +3, -2.5)
--replaygain Use ReplayGain values calculated from file analysis
--target-lufs TARGET_LUFS, --lufs TARGET_LUFS
Target LUFS value for ReplayGain calculation (default:
-18)
--output DIR, -o DIR Output directory for processed files (default: modify
files in-place)
--recursive, -r Process directories recursively (default: False)
--backup {true,false}
Create backup files when modifying in-place (default:
true)
--dry-run Show what would be processed without actually
modifying files
--quiet, -q Suppress progress messages, only show summary
--verbose, -v Show detailed processing information
--check-deps Check if required dependencies are available and exit
Examples:
# Apply fixed +3 dB gain to all files in a directory
python applyloudness.py /path/to/music --gain +3
# Apply -2 dB gain to specific files
python applyloudness.py song1.mp3 song2.flac --gain -2
# Use ReplayGain values with default -18 LUFS target
python applyloudness.py /path/to/music --replaygain
# Use ReplayGain with custom LUFS target (Apple Music standard)
python applyloudness.py /path/to/music --replaygain --target-lufs -16
# Process files and save to output directory (preserve originals)
python applyloudness.py /path/to/music --gain +1.5 --output /path/to/output
# Apply gain without creating backup files
python applyloudness.py /path/to/music --gain -1 --backup false
# Dry run to see what would be processed
python applyloudness.py /path/to/music --gain +2 --dry-run
Supported file formats:
- FLAC (.flac)
- MP3 (.mp3)
- M4A (.m4a)
- WAV (.wav)
- OGG (.ogg)
- Opus (.opus)
LUFS Target Values (for --replaygain mode):
-18 LUFS: ReplayGain 2.0 standard (default)
-16 LUFS: Apple Music standard
-14 LUFS: Spotify, Amazon Music, YouTube standard
-20 LUFS: TV broadcast standard
Requirements:
- FFmpeg (for audio processing)
- rsgain (for ReplayGain mode)
For complete options, run: python /home/runner/work/Walrio/Walrio/modules/niche/applyloudness.py --help
Resizealbumart
Location: /home/runner/work/Walrio/Walrio/modules/niche/resizealbumart.py
Resize Album Art - Extract, resize, and re-embed album art in audio files
Complete Help Output:
usage: resizealbumart.py [-h] [-s SIZE] [-q QUALITY] [-f {jpeg,jpg,png,webp}]
[--maintain-aspect] [--backup [BACKUP]] [-r]
[--logging {DEBUG,INFO,WARNING,ERROR}]
input [input ...]
Resize Album Art - Extract, resize, and re-embed album art in audio files
positional arguments:
input Input audio file(s) or directory
options:
-h, --help show this help message and exit
-s SIZE, --size SIZE Target size for album art (default: 1000x1000)
-q QUALITY, --quality QUALITY
JPEG quality for resized images (1-100, default: 95)
-f {jpeg,jpg,png,webp}, --format {jpeg,jpg,png,webp}
Output format for resized album art (default: jpeg)
--maintain-aspect Maintain aspect ratio instead of stretching to exact
dimensions
--backup [BACKUP] Create backup files before processing. Optionally
specify a directory path to store backups (default:
same location as original files)
-r, --recursive Process directories recursively
--logging {DEBUG,INFO,WARNING,ERROR}
Logging level (default: INFO)
Examples:
# Resize album art to default 1000x1000 JPEG in a single file
python resizealbumart.py song.mp3
# Resize to custom dimensions with quality setting
python resizealbumart.py song.mp3 --size 800x800 --quality 90
# Maintain aspect ratio instead of stretching
python resizealbumart.py song.mp3 --maintain-aspect
# Process an entire directory recursively
python resizealbumart.py /path/to/music/directory --recursive
# Process with creating backups
python resizealbumart.py song.mp3 --backup
# Store backups in a specific directory
python resizealbumart.py song.mp3 --backup /path/to/backups
# Use PNG format instead of JPEG
python resizealbumart.py song.mp3 --format png
Supported audio formats: .mp3, .flac, .ogg, .oga, .opus, .m4a, .mp4, .aac, .wav
For complete options, run: python /home/runner/work/Walrio/Walrio/modules/niche/resizealbumart.py --help
Walrio Import
Location: /home/runner/work/Walrio/Walrio/modules/niche/walrio_import.py
Walrio Import Pipeline - Complete audio library import processing
Complete Help Output:
usage: walrio_import.py [-h] [--recursive] [--dry-run] input
Walrio Import Pipeline - Complete audio library import processing
positional arguments:
input Input directory or file to process through the import
pipeline
options:
-h, --help show this help message and exit
--recursive, -r Process directories recursively (passed to all applicable
modules)
--dry-run Show commands that would be executed without actually
running them
Pipeline Stages (executed in order):
1. Convert to FLAC format (48kHz, 16-bit)
2. Rename files with character filtering
3. Apply ReplayGain analysis (-16 LUFS target)
4. Apply loudness normalization using ReplayGain tags
5. Resize album artwork to 1000x1000 JPEG
Examples:
# Process a single directory
python walrio_import.py /path/to/music
# Process recursively through subdirectories
python walrio_import.py /path/to/music --recursive
# Show what would be executed without running
python walrio_import.py /path/to/music --dry-run
For complete options, run: python /home/runner/work/Walrio/Walrio/modules/niche/walrio_import.py --help
Getting Help
Each tool provides comprehensive help with examples:
python /home/runner/work/Walrio/Walrio/modules/niche/applyloudness.py --help
python /home/runner/work/Walrio/Walrio/modules/addons/convert.py --help
python /home/runner/work/Walrio/Walrio/modules/core/database.py --help
python /home/runner/work/Walrio/Walrio/modules/addons/file_relocater.py --help
python /home/runner/work/Walrio/Walrio/modules/addons/imageconverter.py --help
python /home/runner/work/Walrio/Walrio/modules/core/metadata.py --help
python /home/runner/work/Walrio/Walrio/modules/core/playlist.py --help
python /home/runner/work/Walrio/Walrio/modules/addons/rename.py --help
python /home/runner/work/Walrio/Walrio/modules/addons/replaygain.py --help
python /home/runner/work/Walrio/Walrio/modules/niche/resizealbumart.py --help
python /home/runner/work/Walrio/Walrio/modules/walrio.py --help
python /home/runner/work/Walrio/Walrio/modules/niche/walrio_import.py --help
For detailed API documentation of these tools, see API Reference.
Dependencies
These command-line tools may require:
FFmpeg/FFprobe - For audio conversion and metadata extraction
Python 3.8+ - Required Python version
Additional libraries - See requirements.txt for specific tools
Installation of FFmpeg:
# Ubuntu/Debian
sudo apt install ffmpeg
# macOS (with Homebrew)
brew install ffmpeg
# Windows (with Chocolatey)
choco install ffmpeg