SyncFM

SyncFM is a powerful Python tool for synchronizing your Last.fm scrobble history with custom GNU.fm instances like LoneStar. Whether you want to migrate your listening history, keep multiple music platforms in sync, or maintain a backup of your scrobbles, SyncFM makes the process simple and efficient.

Features

🔄 Scrobble Synchronization

• Seamlessly transfer your Last.fm listening history to GNU.fm instances
• Smart duplicate detection to avoid syncing the same tracks multiple times
• Support for custom date ranges and quick sync options

📊 Track Comparison

• Compare your Last.fm and GNU.fm libraries to identify missing tracks
• Visualize differences between platforms
• Selective synchronization of only missing tracks

🎵 Metadata Enrichment

• Automatically fetch track metadata including:
  • MusicBrainz IDs
  • Track durations
  • Album information
• Enhanced scrobbling with complete track information

🖥️ Multiple Interfaces

• Command-Line Interface: Full-featured terminal experience with rich progress tracking
• Graphical User Interface: Modern desktop application with intuitive controls
• Real-time Logging: Detailed operation logs in both interfaces

Installation

Prerequisites

• Python 3.10 or higher
• Last.fm API key and secret (get them from Last.fm API)
• Accounts on both Last.fm and your target GNU.fm instance

Using pip (Recommended)

pip install syncfm

From Source

git clone https://git.hirad.it/Hirad/SyncFM.git
cd SyncFM
pip install -e .

Configuration

Create a config.yaml file in your user data directory:

Linux/macOS

mkdir -p ~/.config/syncfm/
nano ~/.config/syncfm/config.yaml

Windows

mkdir %APPDATA%\syncfm
notepad %APPDATA%\syncfm\config.yaml

Configuration File Format

accounts:
  lastfm:
    username: "your_lastfm_username"
    password: "your_lastfm_password"
  lonestar:
    username: "your_lonestar_username"
    password: "your_lonestar_password"

api:
  key: "your_lastfm_api_key"
  secret: "your_lastfm_api_secret"

networks:
  source: "lastfm"
  target: "lonestar"

Usage

Command Line Interface

Basic Sync

# Sync all tracks from Last.fm to LoneStar
syncfm sync

# Quick sync (resume from last synced track)
syncfm sync --quick

# Dry run to preview what would be synced
syncfm sync --dry-run

Date Range Sync

# Sync tracks from a specific date range
syncfm sync --from 1609459200 --to 1640995200

# Sync from a specific date to now
syncfm sync --from 1609459200

Track Comparison

# Compare last 100 tracks between platforms
syncfm compare --number 100

# Compare and sync differences
syncfm compare --number 100

Graphical Interface

# Launch the graphical user interface
syncfm --gui

Graphical User Interface

The GUI provides an intuitive way to manage your sync operations:

1. Date Selection: Choose custom date ranges with a calendar widget
2. Progress Tracking: Visual progress bars and status updates
3. Real-time Logs: Live operation logging
4. One-click Operations: Simple buttons for common sync tasks

Advanced Features

Logging

SyncFM maintains detailed logs in your user data directory:

• Linux: ~/.local/share/syncfm/logs/syncfm.log
• macOS: ~/Library/Application Support/syncfm/logs/syncfm.log
• Windows: %APPDATA%\syncfm\logs\syncfm.log

Database

Track information is stored locally in an SQLite database:

• Linux: ~/.local/share/syncfm/syncfm.db
• macOS: ~/Library/Application Support/syncfm/syncfm.db
• Windows: %APPDATA%\syncfm\syncfm.db

Requirements

Python Dependencies

• click >= 8.2.1
• colorlog >= 6.9.0
• platformdirs >= 4.3.8
• pylast (custom GNU.fm fork)
• PyYAML >= 6.0.2
• rich >= 14.1.0
• PySide6 (for GUI)
• setuptools >= 80.9.0
• wheel >= 0.45.1

System Requirements

• Operating System: Linux, macOS, or Windows
• Python: 3.10 or higher
• Internet Connection: Required for API access
• Disk Space: Minimal (database grows with sync history)

Development

Setting Up Development Environment

git clone https://git.hirad.it/Hirad/SyncFM.git
cd SyncFM
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Running Tests

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

# Run tests (when available)
pytest

Code Structure

src/syncfm/
├── cli/          # Command-line interface components
├── config/       # Configuration management
├── database/     # SQLite database handling
├── gui/          # Graphical user interface (PySide6)
├── logs/         # Logging configuration
├── models/       # Data models and structures
├── networking/   # Network operations and API clients
└── utils/        # Utility functions

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Support

For issues, feature requests, or questions:

1. Check the Issues page
2. Submit a new issue if your problem isn't already reported
3. Contact the maintainer at hirad@hirad.it

Acknowledgments

• pylast - Python interface to Last.fm and other MusicBrainz-compatible webservices
• Rich - Rich text and beautiful formatting in the terminal
• PySide6 - Python bindings for the Qt cross-platform application toolkit