MusicList for Soundiiz 🎵

Professional command-line tool for extracting music file metadata for Soundiiz import.

✨ Features

• 🎵 Multi-Format Support - AAC, AU, FLAC, MP3, OGG, M4A, WAV, WMA
• 📊 Multiple Export Formats - CSV (Soundiiz), JSON, M3U, TXT
• 🔍 Intelligent Metadata Extraction - Reads tags and parses filenames (format: "Artist - Title")
• 📁 Recursive Scanning - Automatically searches all subdirectories
• 🔄 Automatic File Splitting - Splits large playlists into multiple files (configurable)
• 🔎 Duplicate Detection - Automatically finds and removes duplicate songs
• 📦 Batch Processing - Process multiple directories simultaneously
• 🛡️ Robust Error Handling - Skips problematic files and continues processing
• ✅ Production-Ready - Fully tested with comprehensive test suite
• 🌐 Unicode Support - Correct handling of special characters
• 📝 Detailed Logging - Verbose mode for debugging

📋 Table of Contents

• Installation
• Quick Start
• Usage Examples
• Configuration
• Export Formats
• Soundiiz Import
• Development
• Testing
• Contributing
• License

🚀 Installation

Option 1: PyPI (Recommended - Easiest!)

# Install from PyPI
pip install musiclist-for-soundiiz

# That's it! Start using it:
musiclist-for-soundiiz -i ~/Music -o output.csv

# Or launch the GUI:
musiclist-for-soundiiz-gui

Prerequisites: Python 3.8 or higher

For GUI support on Linux:

sudo apt-get install python3-tk  # Ubuntu/Debian

Option 2: Docker (No Python Required!)

# Quick start with Docker
docker build -t musiclist-for-soundiiz .

docker run --rm \
  -v /path/to/music:/music:ro \
  -v $(pwd)/output:/output \
  musiclist-for-soundiiz \
  -i /music -o /output/playlist.csv

📖 See DOCKER.md for complete Docker guide

Option 3: From Source (Development)

Prerequisites

• Python 3.8 or higher
• Tkinter (for GUI, optional):
  • Ubuntu/Debian: sudo apt-get install python3-tk
  • macOS: Pre-installed with Python
  • Windows: Pre-installed with Python

Install

# Clone the repository
git clone https://github.com/lucmuss/musiclist-for-soundiiz.git
cd musiclist-for-soundiiz

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install package
pip install -e .

# Or with development dependencies
pip install -e ".[dev]"

⚡ Quick Start

GUI Version (Recommended for Beginners)

# Launch the graphical interface
musiclist-for-soundiiz-gui

Features:

• 🖱️ Easy drag-and-drop interface
• 📊 Real-time progress tracking
• 🎨 Visual duplicate detection
• ✅ No command line knowledge required

Command Line Version

# Scan music files and export as CSV
musiclist-for-soundiiz -i /path/to/music -o output.csv

# Result: output.csv (ready for Soundiiz import)

📚 Usage Examples

🖥️ GUI Application

The easiest way to use MusicList for Soundiiz:

# Start the GUI
musiclist-for-soundiiz-gui

GUI Features:

1. Add Directories: Click "Add Directory" to select music folders
2. Choose Output: Select file name and format (CSV, JSON, M3U, TXT)
3. Options: Enable duplicate detection, recursive scanning
4. Process: Click "Process Files" and watch the progress
5. Done: Get visual confirmation and find your exported file

Perfect for users who prefer a visual interface over command line!

🎯 Command Line - Basic Usage

# Scan directory and create CSV
musiclist-for-soundiiz -i /music/library -o soundiiz.csv

📝 Different Export Formats

# CSV export (default, for Soundiiz)
musiclist-for-soundiiz -i /music -o playlist.csv -f csv

# JSON export (with all metadata)
musiclist-for-soundiiz -i /music -o playlist.json -f json

# Create M3U playlist
musiclist-for-soundiiz -i /music -o playlist.m3u -f m3u

# Simple text list (Title - Artist)
musiclist-for-soundiiz -i /music -o playlist.txt -f txt

🎨 Filter by File Type

# Only MP3 and FLAC files
musiclist-for-soundiiz -i /music -e .mp3 .flac -o output.csv

# Only OGG files
musiclist-for-soundiiz -i /music -e .ogg -o ogg_files.csv

📁 Non-Recursive Scanning

# Only current directory (no subdirectories)
musiclist-for-soundiiz -i /music --no-recursive -o output.csv

🔧 Customize File Splitting

# Maximum songs per file
musiclist-for-soundiiz -i /music -o output.csv --max-songs-per-file 200

# For more than 200 songs, multiple files are created:
# output_1.csv, output_2.csv, output_3.csv, ...

🔍 Verbose Mode (Debugging)

# Detailed output for debugging
musiclist-for-soundiiz -i /music -o output.csv -v

# Or completely silent (errors only)
musiclist-for-soundiiz -i /music -o output.csv -q

📦 Batch Processing (Multiple Directories)

# Process multiple directories simultaneously
musiclist-for-soundiiz -i /music/rock /music/pop /music/jazz -o all_music.csv

# Combine music from different sources
musiclist-for-soundiiz -i /external_hdd/music /nas/music /downloads/music -o combined.csv

🔎 Duplicate Detection

# Detect duplicates and create report
musiclist-for-soundiiz -i /music --detect-duplicates -o output.csv

# Detect duplicates and save to file
musiclist-for-soundiiz -i /music --detect-duplicates --duplicate-report duplicates.txt -o output.csv

# Automatically remove duplicates (keep first copy)
musiclist-for-soundiiz -i /music --remove-duplicates -o output.csv

# Remove duplicates (keep last copy)
musiclist-for-soundiiz -i /music --remove-duplicates --duplicate-strategy keep_last -o output.csv

# Remove duplicates (keep shortest path)
musiclist-for-soundiiz -i /music --remove-duplicates --duplicate-strategy keep_shortest_path -o output.csv

⚙️ Configuration

Command-Line Options

Option	Description	Default
-i, --input	Path(s) to music director(y/ies)	Required
-o, --output	Output file path	output.csv
-f, --format	Export format (csv/json/m3u/txt)	csv
-e, --extensions	File extensions to filter	All supported
--no-recursive	Don't scan subdirectories	false
--max-songs-per-file	Max songs per file	200
--no-pretty-json	Compact JSON (no indentation)	false
--detect-duplicates	Detect and display duplicates	false
--remove-duplicates	Remove duplicates from export	false
--duplicate-strategy	Strategy (keep_first/keep_last/keep_shortest_path)	keep_first
--duplicate-report	Save duplicate report to file	-
-v, --verbose	Enable verbose logging	false
-q, --quiet	Only show errors	false
--version	Show version	-

📄 Export Formats

CSV (Soundiiz-compatible)

title,artist,album,isrc,
Song Title,Artist Name,Album Name,,
Another Song,"Artist, with comma",Album 2,,

Note: The trailing comma is part of the Soundiiz specification.

JSON

{
  "total_songs": 2,
  "songs": [
    {
      "title": "Song Title",
      "artist": "Artist Name",
      "album": "Album Name",
      "isrc": "",
      "genre": "Rock",
      "year": "2020",
      "duration": "180",
      "file_path": "/path/to/song.mp3",
      "filename": "song.mp3"
    }
  ]
}

M3U (Playlist)

#EXTM3U
#EXTINF:180,Artist Name - Song Title
/path/to/song.mp3

TXT (Simple List)

Song Title - Artist Name
Another Song - Another Artist

🎵 Soundiiz Import

Step-by-Step Guide

1. Create CSV file:

   musiclist-for-soundiiz -i /path/to/music -o my_music.csv
   

2. Go to Soundiiz:

   • Open soundiiz.com
   • Sign in

3. Start Import:

   • Click "Import"
   • Select "CSV File"
   • Upload your my_music.csv

4. Export to Streaming Service:

   • Select target platform (Spotify, Apple Music, etc.)
   • Confirm export

Supported Audio Formats

✅ AAC (.aac) - Advanced Audio Coding
✅ AU (.au) - AU Audio File
✅ FLAC (.flac) - Free Lossless Audio Codec
✅ MP3 (.mp3) - MPEG Audio Layer III
✅ OGG (.ogg) - OGG Vorbis
✅ M4A (.m4a) - MPEG-4 Audio
✅ WAV (.wav) - Waveform Audio File
✅ WMA (.wma) - Windows Media Audio

💻 Development

Setup Development Environment

# Clone repository
git clone https://github.com/lucmuss/musiclist-for-soundiiz.git
cd musiclist-for-soundiiz

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install development dependencies
pip install -e ".[dev]"

Code Quality

# Format code
black src tests

# Sort imports
isort src tests

# Linting
flake8 src tests --max-line-length=100

# Type checking
mypy src

🧪 Testing

Run Tests

# Run all tests
pytest

# With coverage report
pytest --cov=musiclist_for_soundiiz --cov-report=html

# Specific test file
pytest tests/test_extractor.py

# Verbose mode
pytest -v

Test Coverage

The project has a comprehensive test suite:

• ✅ Unit tests for all formats (AAC, AU, FLAC, MP3, OGG)
• ✅ Tests for all export formats (CSV, JSON, M3U, TXT)
• ✅ Tests for error handling
• ✅ Tests for edge cases (special characters, Unicode, etc.)
• ✅ Tests for recursive/non-recursive scanning
• ✅ Tests for duplicate detection
• ✅ Tests for batch processing

📊 Project Structure

musiclist-for-soundiiz/
├── src/
│   └── musiclist_for_soundiiz/
│       ├── __init__.py
│       ├── cli.py                 # Command-line interface
│       ├── extractor.py           # Metadata extraction
│       ├── exporter.py            # Export functionality
│       └── duplicate_detector.py  # Duplicate detection
├── tests/
│   ├── __init__.py
│   ├── test_extractor.py          # Extractor tests
│   ├── test_exporter.py           # Exporter tests
│   ├── test_duplicate_detector.py # Duplicate detection tests
│   ├── test_cli.py                # CLI tests
│   └── test_integration.py        # Integration tests
├── .github/
│   └── workflows/
│       └── ci.yml                 # GitHub Actions CI/CD
├── setup.py                       # Package configuration
├── requirements.txt               # Dependencies
├── requirements-dev.txt           # Dev dependencies
├── mypy.ini                       # MyPy configuration
├── .gitignore
├── LICENSE
├── CONTRIBUTING.md
└── README.md

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for details.

Quick Steps

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests
5. Run tests (pytest)
6. Commit (git commit -m 'feat: add amazing feature')
7. Push (git push origin feature/amazing-feature)
8. Create a Pull Request

📝 License

This project is licensed under the MIT License - see LICENSE for details.

🙏 Acknowledgments

Created with:

• Mutagen - Python Audio Metadata Library
• pytest - Testing Framework

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: README

🗺️ Roadmap

• GUI Interface (tkinter/PyQt)
• Direct Spotify/Apple Music integration
• Docker Container
• Web Interface
• Intelligent genre detection
• Playlist analysis and statistics

💡 Examples

Process Large Music Library

# Scan 10,000+ songs and split into multiple CSV files
musiclist-for-soundiiz -i /large/library -o playlist.csv --max-songs-per-file 500
# Creates: playlist_1.csv, playlist_2.csv, playlist_3.csv, ...

Lossless Formats Only

# Only FLAC and WAV
musiclist-for-soundiiz -i /music -e .flac .wav -o lossless.csv

Complete Export (All Formats)

# CSV for Soundiiz
musiclist-for-soundiiz -i /music -o soundiiz.csv -f csv

# JSON for backup/analysis
musiclist-for-soundiiz -i /music -o backup.json -f json

# M3U for media player
musiclist-for-soundiiz -i /music -o playlist.m3u -f m3u

Find Duplicates in Large Library

# Find duplicates and create detailed report
musiclist-for-soundiiz -i /large/library \
  --detect-duplicates \
  --duplicate-report dups.txt \
  -o clean.csv

# Automatically remove duplicates and export clean list
musiclist-for-soundiiz -i /large/library \
  --remove-duplicates \
  --duplicate-strategy keep_shortest_path \
  -o clean_playlist.csv

Combine Multiple Music Sources

# Combine music from multiple hard drives/folders
musiclist-for-soundiiz \
  -i /mnt/hdd1/music /mnt/hdd2/music /home/user/Downloads/music \
  --remove-duplicates \
  -o combined.csv

---

Developed with ❤️ for the music community