First commit. Again. Yo ho. Again
This commit is contained in:
119
README.md
Normal file
119
README.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# ☠ PLAYLIST PIRATE
|
||||
|
||||
**Break free from the stream. Pay the artist. Own your music.**
|
||||
|
||||
---
|
||||
|
||||
## What is this?
|
||||
|
||||
Playlist Pirate is a free, open-source tool that takes your Spotify playlist exports and turns them into something actually useful: static HTML pages with embedded YouTube players, and optionally — MP3s on your own machine.
|
||||
|
||||
No subscription. No algorithm. No ads. No data harvest. Just your music, on your terms.
|
||||
|
||||
---
|
||||
|
||||
## Why does this exist?
|
||||
|
||||
Because Spotify is a bad deal. For everyone. But mostly for artists.
|
||||
|
||||
Here's the math: an independent artist earns somewhere between **$0.003 and $0.005 per stream** on Spotify. That means roughly **250–500 streams to earn $1.00** — and if they're signed to a label, that label takes 80–85% of even that, pushing the number closer to **1,500–2,000 streams per dollar** that reaches the artist.
|
||||
|
||||
Put it this way: **you could hand an indie artist a dollar, download their album, listen to it 400 times, and still have treated them fairer than Spotify does.**
|
||||
|
||||
Meanwhile:
|
||||
- **Bandcamp** gives artists ~85% of every sale. A $1 purchase puts ~$0.85 directly in the artist's pocket.
|
||||
- **YouTube** pays less per view than Spotify does per stream (~$0.001–$0.002), but at least you can link people directly to the artist's channel, which builds their audience.
|
||||
- **Direct support** — buying from the artist's own site, Bandcamp, Patreon, a merch table — is the only model that actually works for working musicians.
|
||||
|
||||
Spotify's 2023 policy change made this worse: they raised the minimum stream threshold for royalty eligibility to **1,000 streams per year**, cutting the bottom tier of artists — the independent, the emerging, the weird and wonderful — out of any payment at all.
|
||||
|
||||
The streaming model concentrates money at the top. It always has. It's by design.
|
||||
|
||||
> **$1 direct to an artist = the same as ~250–500 streams on Spotify for an indie act, or 1,500–2,000+ streams if they're on a label deal.**
|
||||
> *[Sources: Trichordist Streaming Price Bible; UK DCMS Committee 2021; Spotify's own disclosed rate ranges; RIAA data. Rates vary and shift — always look at current figures.]*
|
||||
|
||||
Playlist Pirate exists to help you walk away from that model. Keep your playlists. Ditch the platform.
|
||||
|
||||
---
|
||||
|
||||
## How it works
|
||||
|
||||
Four discrete, opt-in steps. Nothing runs automatically.
|
||||
|
||||
### Pipeline (CLI)
|
||||
|
||||
```
|
||||
CSV → resolve → search → build → download
|
||||
```
|
||||
|
||||
| Step | Command | What it does |
|
||||
|------|---------|--------------|
|
||||
| **resolve** | `playlist.py resolve *.csv` | Parses your Spotify CSV exports into `*-playlist.md` tracking files. Captures track title, artists, ISRC, Spotify ID. |
|
||||
| **search** | `playlist.py search *-playlist.md` | Uses `yt-dlp` to find YouTube URLs for each track. No API key. Resumable — re-run it and it picks up where it left off. ~3–7 seconds per track. |
|
||||
| **build** | `playlist.py build *-playlist.md --out <dir>` | Hits MusicBrainz (no API key, polite 1 req/sec) to fetch recording data and artist URLs — homepage, Bandcamp, SoundCloud, Patreon, in that priority order. Generates static HTML pages with embedded YouTube players, fire-spectrum colors, and links out to the artist directly. |
|
||||
| **download** | `playlist.py download *-playlist.md --output <dir>` | Downloads MP3s via `yt-dlp` + `ffmpeg`. Embeds ID3 tags via `mutagen`. Marks tracks done in the `.md` file so you never double-download. |
|
||||
|
||||
### GUI
|
||||
|
||||
There's a browser-based GUI (`gui.py`) wrapping the same pipeline via Flask. It runs locally, opens in your browser, and gives you accordion-style controls for each step, a live log panel, and per-track download selection. There's also a PyInstaller-built single binary (`dist/playlist-gui`) for running without Python.
|
||||
|
||||
### Tracking file format
|
||||
|
||||
```
|
||||
# Playlist Name
|
||||
<!-- source: filename.csv | updated: 2026-... -->
|
||||
|
||||
- [ ] Track Title | Artist Name | ISRC:XXXXXX | SP:SpotifyID | https://youtu.be/XXXXX
|
||||
- [x] Downloaded Track | Artist | ISRC:... | SP:... | https://...
|
||||
- [-] Not Found | Artist | ISRC:- | SP:- | NOT_FOUND
|
||||
```
|
||||
|
||||
`[ ]` = pending · `[x]` = done · `[-]` = not found on YouTube
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
```
|
||||
pip install yt-dlp rich mutagen
|
||||
```
|
||||
|
||||
- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** — does the heavy lifting. YouTube search and download. No API key required.
|
||||
- **[rich](https://github.com/Textualize/rich)** — terminal output that doesn't look like 1993.
|
||||
- **[mutagen](https://github.com/quodlibet/mutagen)** — ID3 tag writing.
|
||||
- **[MusicBrainz](https://musicbrainz.org/)** — open music encyclopedia. ISRC lookup → artist URLs. Free, no key, rate-limited politely.
|
||||
- **ffmpeg** — for MP3 conversion (system install, not a Python package).
|
||||
|
||||
### The yt-dlp caveat
|
||||
|
||||
This tool depends on `yt-dlp`. If `yt-dlp` stops working — because YouTube changes its API, or because a court somewhere decides the sky is the ceiling — **this tool breaks in the download and search steps**. The build step (HTML generation) and resolve step (CSV parsing) are unaffected.
|
||||
|
||||
`yt-dlp` is a community-maintained FOSS project. Keep it updated. And if it ever goes away, something else will take its place. It always does.
|
||||
|
||||
---
|
||||
|
||||
## Ethos
|
||||
|
||||
Everything this tool does uses **publicly available tools and data, accessed respectfully**:
|
||||
|
||||
- YouTube search via `yt-dlp` with polite delays
|
||||
- MusicBrainz at 1 request per second (their documented rate limit)
|
||||
- No scraping. No API key abuse. No spoofing.
|
||||
- No data sent anywhere except to the services being queried
|
||||
- The generated HTML includes **links back to artists' own sites** — Bandcamp, SoundCloud, Patreon, their homepage. Backlinks improve search engine rankings. A link from a real page to an artist's real site is a small act of support that compounds over time.
|
||||
|
||||
This is not a tool for stealing from artists. It is a tool for **owning your own library** and **finding the artists you love** so you can support them directly.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
FOSS. Use it, fork it, improve it. If you make money off it, buy an artist's album.
|
||||
|
||||
---
|
||||
|
||||
## Find the artists. Pay the artists. Own your music.
|
||||
|
||||
> Bandcamp: [bandcamp.com](https://bandcamp.com)
|
||||
> MusicBrainz: [musicbrainz.org](https://musicbrainz.org)
|
||||
> yt-dlp: [github.com/yt-dlp/yt-dlp](https://github.com/yt-dlp/yt-dlp)
|
||||
Reference in New Issue
Block a user