Metadata-Version: 2.3
Name: spotifysaver
Version: 0.2.2
Summary: Download Spotify tracks/albums with metadata via YouTube Music (Perfect for Jellyfin libraries!)
License: MIT
Keywords: spotify,youtube-music,music-downloader,jellyfin,metadata,cli-tool
Author: Gabriel Baute
Author-email: gabrielbaute@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Utilities
Requires-Dist: click (>=8.1.3,<9.0.0)
Requires-Dist: pydantic (>=2.0,<3.0)
Requires-Dist: requests (>=2.31.0,<3.0.0)
Requires-Dist: spotipy (>=2.22.0,<3.0.0)
Requires-Dist: yt-dlp (>=2025.5.22,<2026.0.0)
Requires-Dist: ytmusicapi (>=1.0.0,<2.0.0)
Project-URL: Documentation, https://github.com/gabrielbaute/spotify-saver#readme
Project-URL: Homepage, https://github.com/gabrielbaute/spotify-saver
Project-URL: Repository, https://github.com/gabrielbaute/spotify-saver
Description-Content-Type: text/markdown

# SpotifySaver 🎵✨

[![Python](https://img.shields.io/badge/Python-3.8%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
[![PyPI Version](https://img.shields.io/pypi/v/spotifysaver?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/spotifysaver/)
[![FFmpeg](https://img.shields.io/badge/FFmpeg-Required-orange?logo=ffmpeg&logoColor=white)](https://ffmpeg.org/)
[![yt-dlp](https://img.shields.io/badge/yt--dlp-2023.7.6%2B-red)](https://github.com/yt-dlp/yt-dlp)
[![YouTube Music](https://img.shields.io/badge/YouTube_Music-API-yellow)](https://ytmusicapi.readthedocs.io/)
[![Spotify](https://img.shields.io/badge/Spotify-API-1ED760?logo=spotify)](https://developer.spotify.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

> All-in-one tool for downloading and organizing music with Spotify metadata for Jellyfin.

The app connects to the Spotify and YouTube Music APIs. The goal is to generate an .nfo XML file to complete the metadata required by Jellyfin when building music libraries.

Read this file in [Spanish](README_ES.md)

## 🌟 Features
- ✅ Download audio from YouTube Music with Spotify metadata
- ✅ Synchronized lyrics (.lrc) from LRC Lib
- ✅ Generation of Jellyfin-compatible `.info` files
- ✅ Automatic folder structure (Artist/Album)
- ✅ Command-line interface (CLI)

### Requirements
- Python 3.8+
- FFmpeg
- [Spotify Developer Account](https://developer.spotify.com/dashboard/)

```bash
# Installation with Poetry (recommended)
git clone https://github.com/gabrielbaute/spotify-saver.git
cd spotify-saver
poetry install

# Or with pip
pip install git+https://github.com/gabrielbaute/spotify-saver.git
```

⚠️ IMPORTANT: You must log in to your Spotify account as a developer, create an app, and obtain a "client id" and "client secret." You must place this information in an .env file in the project's root directory.

## ⚙️ Configuration

Create `.env` file:

```ini
SPOTIFY_CLIENT_ID=your_id
SPOTIFY_CLIENT_SECRET=your_secret
YTDLP_COOKIES_PATH="cookies.txt" # For age-restricted content
```

The `YTDLP_COOKIES_PATH` variable will indicate the location of the file with the YouTube Music cookies (important, don't use YouTube cookies, but YouTube Music), in case we have problems with restrictions on yt-dlp.

You can also check the .example.env file

## 💻 Using the CLI

### Available Commands

| Command | Description | Example |
|------------------------|--------------------------------------------------|----------------------------------------------|
| `download [URL]` | Download track/album from Spotify | `spotifysaver download "URL_SPOTIFY"` |
| `version` | Displays the installed version | `spotifysaver version` |

### Main Options

| Option | Description | Accepted Values ​​|
|---------------------|------------------------------------------|-------------------------|
| `--lyrics` | Download synchronized lyrics (.lrc) | Flag (no value) |
| `--output DIR` | Output directory | Valid path |
| `--format FORMAT` | Audio format | `m4a` (default), `mp3` |
| `--cover` | Saves the cover album in de directoy (.jpg) | Flag (no value) |
| `--nfo` | Generates a .nfo metadata file in the JellyFin format | Flag (no value) |

## 💡 Usage Examples
```bash
# Download album with synchronized lyrics
spotifysaver download "https://open.spotify.com/album/..." --lyrics

# Download album with album cover and metadata file
spotifysaver download "https://open.spotify.com/album/..." --nfo --cover

# Download song in MP3 format (still in development 🚧)
spotifysaver download "https://open.spotify.com/track/..." --format mp3
```

## 📂 Output Structure
```
Music/
├── Artist/
│ ├── Album (Year)/
│ │ ├── 01 - Song.m4a
│ │ ├── 01 - Song.lrc
│ │ ├── album.nfo
│ │ └── cover.jpg
│ └── artist_info.nfo
```

## 🤝 Contributions
1. Fork the project
2. Create your branch (`git checkout -b feature/new-feature`)
3. Commit your changes (`git commit -m 'Add awesome feature'`)
4. Push to the branch (`git push origin feature/new-feature`)
5. Open a Pull Request

## 📄 License

MIT © [TGabriel Baute](https://github.com/gabrielbaute)
