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.
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]
[-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 Skip existing files
-y, --force-overwrite
Force overwrite of existing files without prompting
-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]
[--dont-sanitize] [--custom-sanitize CHARS]
[--dry-run] [--copy] [--skip-existing]
[--skip-no-metadata] [--logging {low,high}]
[--list-metadata FILE]
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
--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 default character replacements. Only use
custom --replace-char replacements.
--sanitize, --s Enable folder name sanitization using the allowed
character set (default behavior).
--dont-sanitize, --ds
Disable folder name sanitization using the allowed
character set. Only apply character replacements.
--custom-sanitize CHARS, --cs CHARS
Use custom character set for sanitization instead of
default. Provide all allowed characters as a string
(e.g., --cs 'abcABC123-_ ').
--dry-run Show what would be organized without actually moving
files
--copy Copy files instead of moving them (preserves original
library)
--skip-existing Skip organization if target file already exists
(default: True)
--skip-no-metadata Skip files that have no metadata for the specified
format fields
--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:
# Organize music library using default format: album/albumartist
python organize.py /path/to/music/library /path/to/organized/library
# Custom folder format with year and genre
python organize.py /music /organized --folder-format "{year}/{genre}/{albumartist}/{album}"
# Artist-based organization
python organize.py /music /organized --folder-format "{artist}/{album}"
# Detailed organization with track info
python organize.py /music /organized --folder-format "{albumartist}/{year} - {album}"
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: problematic chars become safe alternatives):
--replace-char "/" "-" # Replace forward slashes with dashes (default)
--rc ":" "-" # Replace colons with dashes (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 with conservative character set):
--sanitize # Explicitly enable character filtering (default behavior)
--s # Same as above using shortcut
--dont-sanitize # Disable character filtering, keep all characters
--ds # Same as above using shortcut
--ds --rc "/" "-" # No filtering, but still replace / with -
--dont-sanitize --dontreplace # No filtering or replacements at all
--s --rc "&" "and" # Explicit sanitize with custom replacements
--custom-sanitize "abcABC123-_ " # Use custom allowed character set
--cs "0123456789" # Only allow numbers using shortcut
Custom sanitization examples:
--cs "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_ " # Basic set
--cs "abcABC123[]()-_~@=+ " # Include brackets and symbols (may cause issues)
--custom-sanitize "αβγδεζηθικλμνξοπρστυφχψω" # Greek letters only
--cs "あいうえおかきくけこ" # Japanese characters
Folder format tips:
- Use forward slashes (/) to separate folder levels: "{artist}/{album}"
- 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
- Default character set excludes apostrophes and special chars for music player compatibility
For complete options, run: python /home/runner/work/Walrio/Walrio/modules/addons/file_relocater.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]
[--dont-sanitize] [--custom-sanitize CHARS] [--dry-run]
[--skip-existing] [--skip-no-metadata] [--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
-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, --s Enable filename sanitization using the allowed
character set (default behavior).
--dont-sanitize, --ds
Disable filename sanitization using the allowed
character set. Only apply character replacements.
--custom-sanitize CHARS, --cs CHARS
Use custom character set for sanitization instead of
default. Provide all allowed characters as a string
(e.g., --cs 'abcABC123-_ ').
--dry-run Show what would be renamed without actually renaming
files
--skip-existing Skip renaming if target filename already exists
(default: True)
--skip-no-metadata Skip files that have no metadata for the specified
format fields
--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}"
# Year and genre format
python rename.py /music --format "{year} - {genre} - {artist} - {title}"
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: / 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):
--sanitize # Explicitly enable character filtering (default behavior)
--s # Same as above using shortcut
--dont-sanitize # Disable character filtering, keep all characters
--ds # Same as above using shortcut
--ds --rc "/" "~" # No filtering, but still replace / with ~
--dont-sanitize --dontreplace # No filtering or replacements at all
--s --rc "&" "and" # Explicit sanitize with custom replacements
--custom-sanitize "abcABC123-_ " # Use custom allowed character set
--cs "0123456789" # Only allow numbers using shortcut
Custom sanitization examples:
--cs "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_ " # Basic set
--cs "abcABC123[]()-_~@=+ " # Include brackets and symbols
--custom-sanitize "αβγδεζηθικλμνξοπρστυφχψω" # Greek letters only
--cs "あいうえおかきくけこ" # 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 --custom-sanitize to define your own allowed character set
For complete options, run: python /home/runner/work/Walrio/Walrio/modules/addons/rename.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
Player
Location: /home/runner/work/Walrio/Walrio/modules/core/player.py
Audio Player using GStreamer with full playback control
Complete Help Output:
usage: player.py [-h] [--interactive] [--daemon]
[--command {play,pause,stop,resume,status}] [--volume VOLUME]
[--seek SEEK] [--loop LOOP]
[filepath]
Audio Player using GStreamer with full playback control
positional arguments:
filepath Path to the audio file to play
options:
-h, --help show this help message and exit
--interactive, -i Run in interactive mode with playback controls
--daemon, -d Run in daemon mode (for external control)
--command {play,pause,stop,resume,status}, -c {play,pause,stop,resume,status}
Send command to running player instance
--volume VOLUME, -v VOLUME
Set volume (0.0 to 1.0)
--seek SEEK, -s SEEK Seek to position in seconds
--loop LOOP, -l LOOP Set loop mode: 'none', number (e.g. '3'), or
'infinite'
Examples:
python player.py /path/to/song.mp3 # Simple playback
python player.py --interactive /path/to/song.mp3 # Interactive mode
python player.py --daemon /path/to/song.mp3 # Daemon mode (for Electron)
For complete options, run: python /home/runner/work/Walrio/Walrio/modules/core/player.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
Queue
Location: /home/runner/work/Walrio/Walrio/modules/core/queue.py
Audio Queue Manager - Play songs from your music library
Complete Help Output:
usage: queue.py [-h] [--db-path DB_PATH] [--shuffle] [--repeat]
[--artist ARTIST] [--album ALBUM] [--genre GENRE]
[--interactive] [--list] [--playlist PLAYLIST]
Audio Queue Manager - Play songs from your music library
options:
-h, --help show this help message and exit
--db-path DB_PATH Path to the SQLite database file (default:
walrio_library.db)
--shuffle Shuffle the queue
--repeat Repeat the queue when it ends
--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)
--interactive Start in interactive mode
--list List all songs in the library and exit
--playlist PLAYLIST Load songs from an M3U playlist file
Example: python queue.py --artist 'Pink Floyd' --shuffle OR python queue.py
--playlist myplaylist.m3u
For complete options, run: python /home/runner/work/Walrio/Walrio/modules/core/queue.py --help
Getting Help
Each tool provides comprehensive help with examples:
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/core/player.py --help
python /home/runner/work/Walrio/Walrio/modules/core/playlist.py --help
python /home/runner/work/Walrio/Walrio/modules/core/queue.py --help
python /home/runner/work/Walrio/Walrio/modules/addons/rename.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