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**: .. code-block:: text 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**: .. code-block:: text 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**: .. code-block:: text 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**: .. code-block:: text 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**: .. code-block:: text 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**: .. code-block:: text 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**: .. code-block:: text 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 :doc:`api/index`. 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: .. code-block:: bash # Ubuntu/Debian sudo apt install ffmpeg # macOS (with Homebrew) brew install ffmpeg # Windows (with Chocolatey) choco install ffmpeg