Musicman - Music Transcoding and Management Tool

A comprehensive command-line tool for managing and transcoding music libraries. Converts lossless audio (FLAC, WAV, etc.) to lossy formats (Opus, M4A, OGG, MP3) with full metadata preservation.

Features

• Convert: Transcode lossless audio files to compressed lossy formats

  • Multi-threaded conversion for speed
  • Full metadata preservation including MusicBrainz tags
  • Album art copying
  • Support for Opus, M4A/AAC, OGG Vorbis, and MP3 formats

• Scan: Analyze audio libraries for incomplete metadata

  • Check for missing required tags (title, artist, album, etc.)
  • Verify MusicBrainz ID presence
  • Detailed reporting

• Rename: Standardize filenames based on embedded metadata

  • Format: disc-track-title.ext (e.g., 1-05-Song Title.flac)
  • Dry-run mode to preview changes
  • Safety features for input directory protection

• Stats: Calculate library statistics

  • Track totals by artist and album
  • Duration calculations
  • Complete library analysis

• Additional Features:

  • Shell Completion: Generate completion scripts for Bash, Zsh, and Fish
  • Include/exclude path filtering
  • Profile-based configuration
  • Progress bars with spinner animations
  • Natural sort ordering
  • Dry-run mode for all operations

Prerequisites

Required

1. Rust 1.70 or later

   # Check your Rust version
   rustc --version
   

2. FFmpeg with codec support

   # On EndeavourOS/Arch Linux
   sudo pacman -S ffmpeg
   
   # Verify installation
   ffmpeg -version
   

Optional

For best quality M4A/AAC encoding:

# Install FFmpeg with libfdk-aac support
# On Arch Linux, this may require compiling from source or using AUR
yay -S ffmpeg-full  # or similar package with fdk-aac

Installation

Build from Source

# Clone or extract the project
cd musicman-rs

# Build the binary
cargo build --release

# Optional: Install to system
sudo cp target/release/musicman /usr/local/bin/

Configuration

Generate Default Config

musicman generate-config > ~/.config/musicman/musicman.ini

Configuration File Format

The config file is in INI format and supports multiple profiles:

[default]
input = /home/user/Music-Lossless
output = /home/user/Music
work_dir = /home/user/Music-Work
threads = 8
format = opus
quality = 192k

[mobile]
output = /home/user/Music-Mobile
format = m4a
quality = 4

Configuration Location

• Linux: ~/.config/musicman/musicman.ini
• macOS: ~/Library/Application Support/musicman/musicman.ini
• Windows: %APPDATA%\musicman\musicman.ini

Usage

Convert Command

Transcode lossless audio to lossy formats:

# Basic conversion (uses config file)
musicman convert

# Override config with command-line arguments
musicman convert -i ~/Music-Lossless -o ~/Music -f opus --quality 192k

# Use a specific profile
musicman convert -p mobile

# Dry run to preview operations
musicman convert --dry-run

# Force overwrite existing files
musicman convert --force

# Use specific number of threads
musicman convert -t 16

# Include/exclude specific paths
musicman convert --include "Artist1" --include "Artist2" --exclude "Compilations"

# Verbose output
musicman convert -v

# Quiet mode (no progress output)
musicman convert -q

Format Options

• opus (Recommended)

  • Quality: Bitrate (e.g., "128k", "192k", "256k")
  • 192k is transparent for most listeners

• m4a (AAC - Best for Apple devices)

  • Quality: VBR scale 1-5 (5 is highest) with fdk_aac
  • Use "5" for ~256kbps

• mp3 (Maximum compatibility)

  • Quality: LAME VBR scale 0-9 (0 is best)
  • Use "2" for ~190kbps, "0" for ~245kbps

• ogg (Vorbis)

  • Quality: scale 1-10 (10 is best)
  • Use "6" for ~192kbps

Scan Command

Check audio files for missing metadata:

# Scan input directory (default)
musicman scan

# Scan specific directories
musicman scan --input --output --workdir

# Use specific profile
musicman scan -p default

# Verbose output (shows all files, not just incomplete ones)
musicman scan -v

# With filtering
musicman scan --include "Artist Name" --exclude "Various Artists"

Rename Command

Rename files to standardized format based on metadata:

# Rename files in input directory (dry-run by default for safety)
musicman rename

# Rename files in output directory
musicman rename --output

# Rename in work directory
musicman rename --workdir

# Actually perform renames (not dry-run)
musicman rename --output  # Safe: output directory

# DANGER: Rename input directory (requires explicit flag)
musicman rename --input --rename-input

# Force overwrite if destination exists
musicman rename --force

# With filtering
musicman rename --output --include "Artist" --exclude "Compilations"

# Quiet mode
musicman rename -q

Safety Note: The rename command runs in dry-run mode by default for the input directory. Use --rename-input flag to actually modify the input directory.

Stats Command

Calculate library statistics:

# Stats for input directory
musicman stats --input

# Stats for all directories
musicman stats --input --output --workdir

# With filtering
musicman stats --input --include "Jazz" --exclude "Christmas"

Completion Command

Generate shell completion scripts:

# Bash
source <(musicman completion bash)

# Zsh
source <(musicman completion zsh)

# Fish
musicman completion fish | source

Examples

Complete Workflow

1. Generate configuration:

   mkdir -p ~/.config/musicman
   musicman generate-config > ~/.config/musicman/musicman.ini
   # Edit the config file to set your directories
   

2. Scan source library:

   musicman scan -v
   

3. Preview conversion:

   musicman convert --dry-run
   

4. Perform conversion:

   musicman convert
   

5. Rename output files:

   musicman rename --output
   

6. Check statistics:

   musicman stats --output
   

Selective Processing

Process only specific artists:

musicman convert --include "Miles Davis" --include "John Coltrane"

Exclude specific directories:

musicman convert --exclude "Compilations" --exclude "Soundtracks"

Multiple Profiles

Create profiles for different targets:

[default]
input = ~/Music-Lossless
output = ~/Music
format = opus
quality = 192k

[mobile]
output = ~/Music-Mobile
format = m4a
quality = 3

[archival]
output = ~/Music-Archive
format = mp3
quality = 0

Then use them:

musicman convert -p mobile
musicman convert -p archival

File Naming Convention

The tool standardizes filenames to: disc-track-title.ext

Examples:

• 1-01-Introduction.flac
• 1-05-Song Title.opus
• 2-03-Bonus Track.m4a

Special characters are handled:

• : → -
• : → -
• \, / → +
• * → -
• <, >, |, ", ? → removed

Supported Audio Formats

Lossless (Input)

• FLAC (.flac)
• WAV (.wav)
• AIFF (.aiff, .aif)
• APE (.ape)
• WavPack (.wv)

Lossy (Input/Output)

• MP3 (.mp3)
• M4A/AAC (.m4a)
• OGG Vorbis (.ogg)
• Opus (.opus)
• AAC (.aac)

Metadata Handling

The tool preserves comprehensive metadata:

• Core tags: Title, Artist, Album, Genre, Year
• Track info: Track number, Disc number
• Extended tags: Album Artist, Sort Orders, Label, ISRC
• MusicBrainz IDs: Track, Album, Artist, Release Group
• Album art: Cover images are preserved

Performance

• Multi-threaded: Uses all available CPU cores by default
• Progress tracking: Real-time progress bars with braille spinner
• Efficient: Skips already converted files automatically
• Concurrent: Multiple files converted simultaneously

Troubleshooting

FFmpeg not found

which ffmpeg
# If not found, install it:
sudo pacman -S ffmpeg

libfdk_aac warnings

If you see warnings about libfdk_aac, you can either:

1. Ignore them (built-in AAC encoder still works)
2. Install ffmpeg with fdk-aac support
3. Use a different format (opus, mp3, ogg)

Permission errors

Make sure you have:

• Read access to input directory
• Write access to output and work directories

Missing metadata warnings

Use the scan command to identify files with incomplete metadata:

musicman scan -v

Then tag your files using a tool like:

• MusicBrainz Picard
• beets
• EasyTAG

License

Consult your original project for licensing terms.

Version

Current version: 1.1.0