Local Music Library Sync

A local web application for building and maintaining a downloaded music library from Spotify and YouTube. Download and update collections (playlists/albums), generate .m3u8 playlists, edit ID3/metadata tags, and optionally sync metadata from Spotify.

📖 For detailed documentation, see the GitHub Wiki.

Features

• Staging + Sync Workflow: Paste Spotify playlist/album links or YouTube playlist links, review them in the staging area, then sync to download/update tracks
• Folder-Based Sync: Tracked collections store a .sync file in the collection folder, enabling automatic refresh on future sync runs
• Library Browser: Browse folders and audio files with an interactive tree view
• Metadata Editor: Edit ID3 tags (title, artist, album, year, genre) on individual audio files
• Batch Spotify Metadata Sync: Select multiple files and automatically match them on Spotify to update tags
• Playlist Generation: Automatically creates .m3u8 playlist files for each synced collection
• Parallel Downloads: Configurable parallel download jobs for faster syncing
• Flexible File Organization: Customizable filename and directory templates for organizing your library
• Multiple Audio Formats: Supports MP3, FLAC, OGG, M4A with configurable quality settings

Requirements

• Python: 3.10+ (recommended: 3.11+)
• FFmpeg: Required for audio conversion and extraction (used by yt-dlp)
• Spotify API Credentials (optional, but required for Spotify metadata sync):
  • SPOTIPY_CLIENT_ID
  • SPOTIPY_CLIENT_SECRET
  • Get credentials from Spotify Developer Dashboard

Installation

1. Clone the repository:

git clone https://github.com/zeti1223/Local-Music-Library-Sync.git
cd Local-Music-Library-Sync

2. Create a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Install FFmpeg (if not already installed):
   • Linux: sudo apt install ffmpeg (Debian/Ubuntu) or sudo pacman -S ffmpeg (Arch)
   • macOS: brew install ffmpeg
   • Windows: Download from ffmpeg.org

Configuration

The app reads configuration from environment variables and a local .env file (if present). You can also update settings through the web UI's Settings tab.

For detailed configuration options, environment variables, and template variables, see the Configuration Guide in the wiki.

Running the Application

Start the server:

python app.py

By default, the server binds to 0.0.0.0 (all interfaces) on port 8080. Access the web UI at:

• http://localhost:8080 (local)
• http://<your-ip>:8080 (network access)

To change the port, set the PORT environment variable or update it in Settings.

Usage

For detailed usage instructions, see the Usage Guide in the wiki, including:

• Adding collections to staging
• Syncing collections
• Editing metadata
• Batch metadata sync from Spotify
• Library organization

How Syncing Works

For detailed information about the sync process, staging workflow, and .sync file format, see the Sync Process wiki page.

API Documentation

The application provides a REST API used by the web UI. For complete API endpoint documentation, see the API Reference in the wiki.

Troubleshooting

For troubleshooting common issues, see the Troubleshooting Guide in the wiki.

Project Structure

For information about the project structure and supported audio formats, see the Project Structure wiki page.

License

See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.