suno-archiver 1.0.0__tar.gz

suno_archiver-1.0.0/.env.example

@@ -0,0 +1,3 @@
+# Only needed if automatic browser-session detection doesn't work.
+# Your Suno __client cookie (from DevTools; see README "Auth").
+SUNO_COOKIE=your___client_cookie_here

suno_archiver-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+.env
+.env.*
+!.env.example
+.venv/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+suno_archive/
+suno_archive_*/
+.suno-archiver-state.json
+.DS_Store

suno_archiver-1.0.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-06-11
+
+Initial release.
+
+### Added
+- Archive your full Suno library: MP3 audio, cover art, and complete per-song metadata (prompt, tags, lyrics, duration, model, dates) as JSON, plus a master `library_index.json`
+- Optional lossless WAV download via `--wav` (requests Suno's conversion and polls)
+- Incremental sync with `--last-run`; date filtering with `--since`/`--until`
+- Automatic browser-session auth (Chrome/Brave/Firefox/Safari/Arc/...) with `SUNO_COOKIE` manual fallback
+- Concurrent downloads (4-worker pool); idempotent re-runs skip existing files
+- `doctor` command to diagnose auth and API health

suno_archiver-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hunter Shokrian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

suno_archiver-1.0.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: suno-archiver
+Version: 1.0.0
+Summary: Archive your Suno music library: audio, cover art, and complete metadata, with incremental sync
+Author-email: Hunter Shokrian <hnshokrian@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-music,archive,backup,cli,downloader,music-generation,suno
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: rookiepy>=0.5.0
+Description-Content-Type: text/markdown
+
+# suno-archiver
+
+Archive your entire Suno music library — MP3 audio, cover art, and full metadata — with one command.
+
+## Why
+
+Suno's web UI only lets you download tracks one at a time. If you've generated more than a handful, pulling them all by hand is tedious-to-impossible. This tool grabs your **entire** library in one command — audio, cover art, and full metadata as JSON — organized on your own disk.
+
+Useful if you:
+
+- have a large library (hundreds or thousands of generations) and want it all local — for a DAW, a dataset, offline access, or your own bookkeeping. A 1,600-track pull is one run, not 1,600 clicks.
+- want your data in a structured, scriptable form — every track's prompt, tags, model, and timestamps in JSON, plus a single `library_index.json` you can grep or query.
+- don't want to depend on the cloud staying put. Suno's Warner Music deal (early 2026) pulled free download access ahead of schedule; terms can change again. A local copy doesn't.
+
+Run it on a schedule with `--last-run` and the archive stays current automatically.
+
+> **Tested at scale.** A full **1,668-track library** spanning two years (2024–2026) archived in a single run — **5.7 GB**, 99.9% success rate, no rate-limiting or throttling. The handful of missing files were dead/transient links on Suno's CDN, not failures of the tool — and a re-run picks them up.
+
+## What it grabs
+
+| File | Details |
+|---|---|
+| `.mp3` | Audio (Suno's MP3 stream) |
+| `.jpg` | Cover art |
+| `.json` | Full metadata — prompt, tags, lyrics, duration, model version, created/updated dates |
+| `library_index.json` | All songs in one file, grep/jq-friendly |
+| `--wav` | Optional: triggers Suno's lossless conversion and downloads the WAV alongside the MP3 (slower — one conversion request per song) |
+
+## Important
+
+- **Personal backup of your own creations only.** Do not scrape other users' libraries.
+- **Audio downloads require a paid Suno plan** (Pro or Premier). Metadata-only runs work on free plans.
+- **Undocumented API** — Suno can change or break this at any time. Run `suno-archiver doctor` if something stops working, and check for updates with `pip install -U suno-archiver`.
+
+## Install
+
+```bash
+pipx install suno-archiver   # recommended: isolated environment
+# or
+pip install suno-archiver
+```
+
+Requires Python 3.9+.
+
+## Auth
+
+### Primary: just be logged in to suno.com in your browser
+
+That's it. `suno-archiver` uses [rookiepy](https://github.com/thewh1teagle/rookiepy) to read your existing browser session cookie automatically. Works with Chrome, Brave, Firefox, Safari, Arc, Edge, and more — no manual steps needed.
+
+```bash
+suno-archiver        # rookiepy finds your session automatically
+```
+
+### Fallback: set SUNO_COOKIE manually
+
+Use this if browser auto-detection fails (headless servers, CI, multiple profiles, or just for troubleshooting):
+
+1. Open [suno.com](https://suno.com) in Chrome and make sure you're logged in.
+2. Open DevTools → Network tab → reload the page.
+3. Click any request to `clerk.suno.com` (look for `client?__clerk_api_version=...`).
+4. Select the **Cookies** tab in the request detail panel.
+5. Find the `__client` cookie — it's a long three-segment JWT (looks like `eyJ...`).
+6. Copy its value.
+
+```bash
+# .env file or shell environment
+SUNO_COOKIE=eyJhbGci...   # paste the full __client value here
+```
+
+Then run `suno-archiver doctor` to confirm it's working.
+
+## Usage
+
+```bash
+suno-archiver                      # full archive: MP3s + covers + metadata
+suno-archiver --wav                # also WAVs (slower: conversion per song)
+suno-archiver --last-run           # only what's new since the last run
+suno-archiver --since "2 weeks ago"
+suno-archiver --dir ~/Music/suno_archive
+suno-archiver doctor               # diagnose auth/API issues
+```
+
+Re-runs are **idempotent** — existing files are skipped, so `--last-run` on a cron job keeps your archive current without re-downloading anything.
+
+## What lands on disk
+
+```
+suno_archive/
+├── 2026-06/
+│   ├── 2026-06-02_concrete-syncope_49291ca0.mp3
+│   ├── 2026-06-02_concrete-syncope_49291ca0.jpg     (cover art)
+│   └── 2026-06-02_concrete-syncope_49291ca0.json    (full metadata)
+├── library_index.json    (everything, searchable with jq/grep)
+└── .suno-archiver-state.json
+```
+
+Songs are organized into `YYYY-MM/` month folders. The state file records the last run timestamp for `--last-run` incremental syncs.
+
+## Resilient by design
+
+Archiving thousands of files over an undocumented API means things will occasionally go wrong mid-run. The tool is built so that they don't cost you:
+
+- **Per-file errors never abort the run.** A dead CDN link (403) or a transient hiccup (503) is counted and reported, then the run continues. You get a clear tally at the end: `3333 downloaded, 0 skipped, 3 errors`.
+- **Expired sessions self-heal.** Suno's auth tokens are short-lived; the tool transparently re-mints them, and retries once on a 401 before giving up.
+- **Interrupted runs are safe.** The `--last-run` watermark is only saved when a fetch completes cleanly — so a connection drop or a kill mid-run can never cause the *next* incremental sync to silently skip tracks. You just re-run.
+- **Re-runs are free.** Idempotent skipping means re-running after a partial failure costs nothing for already-downloaded files; only the gaps are retried.
+
+If the tool ever stops working entirely (Suno changed their API), `suno-archiver doctor` tells you *which* layer broke — your login, the auth exchange, or the library endpoint — so you know whether to re-log-in or wait for an update.
+
+## Related
+
+[replicate-predictions-downloader](https://github.com/closestfriend/replicate-predictions-downloader) — same idea for Replicate AI predictions: bulk-download all your generated outputs from Replicate's API.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

suno_archiver-1.0.0/README.md

@@ -0,0 +1,117 @@
+# suno-archiver
+
+Archive your entire Suno music library — MP3 audio, cover art, and full metadata — with one command.
+
+## Why
+
+Suno's web UI only lets you download tracks one at a time. If you've generated more than a handful, pulling them all by hand is tedious-to-impossible. This tool grabs your **entire** library in one command — audio, cover art, and full metadata as JSON — organized on your own disk.
+
+Useful if you:
+
+- have a large library (hundreds or thousands of generations) and want it all local — for a DAW, a dataset, offline access, or your own bookkeeping. A 1,600-track pull is one run, not 1,600 clicks.
+- want your data in a structured, scriptable form — every track's prompt, tags, model, and timestamps in JSON, plus a single `library_index.json` you can grep or query.
+- don't want to depend on the cloud staying put. Suno's Warner Music deal (early 2026) pulled free download access ahead of schedule; terms can change again. A local copy doesn't.
+
+Run it on a schedule with `--last-run` and the archive stays current automatically.
+
+> **Tested at scale.** A full **1,668-track library** spanning two years (2024–2026) archived in a single run — **5.7 GB**, 99.9% success rate, no rate-limiting or throttling. The handful of missing files were dead/transient links on Suno's CDN, not failures of the tool — and a re-run picks them up.
+
+## What it grabs
+
+| File | Details |
+|---|---|
+| `.mp3` | Audio (Suno's MP3 stream) |
+| `.jpg` | Cover art |
+| `.json` | Full metadata — prompt, tags, lyrics, duration, model version, created/updated dates |
+| `library_index.json` | All songs in one file, grep/jq-friendly |
+| `--wav` | Optional: triggers Suno's lossless conversion and downloads the WAV alongside the MP3 (slower — one conversion request per song) |
+
+## Important
+
+- **Personal backup of your own creations only.** Do not scrape other users' libraries.
+- **Audio downloads require a paid Suno plan** (Pro or Premier). Metadata-only runs work on free plans.
+- **Undocumented API** — Suno can change or break this at any time. Run `suno-archiver doctor` if something stops working, and check for updates with `pip install -U suno-archiver`.
+
+## Install
+
+```bash
+pipx install suno-archiver   # recommended: isolated environment
+# or
+pip install suno-archiver
+```
+
+Requires Python 3.9+.
+
+## Auth
+
+### Primary: just be logged in to suno.com in your browser
+
+That's it. `suno-archiver` uses [rookiepy](https://github.com/thewh1teagle/rookiepy) to read your existing browser session cookie automatically. Works with Chrome, Brave, Firefox, Safari, Arc, Edge, and more — no manual steps needed.
+
+```bash
+suno-archiver        # rookiepy finds your session automatically
+```
+
+### Fallback: set SUNO_COOKIE manually
+
+Use this if browser auto-detection fails (headless servers, CI, multiple profiles, or just for troubleshooting):
+
+1. Open [suno.com](https://suno.com) in Chrome and make sure you're logged in.
+2. Open DevTools → Network tab → reload the page.
+3. Click any request to `clerk.suno.com` (look for `client?__clerk_api_version=...`).
+4. Select the **Cookies** tab in the request detail panel.
+5. Find the `__client` cookie — it's a long three-segment JWT (looks like `eyJ...`).
+6. Copy its value.
+
+```bash
+# .env file or shell environment
+SUNO_COOKIE=eyJhbGci...   # paste the full __client value here
+```
+
+Then run `suno-archiver doctor` to confirm it's working.
+
+## Usage
+
+```bash
+suno-archiver                      # full archive: MP3s + covers + metadata
+suno-archiver --wav                # also WAVs (slower: conversion per song)
+suno-archiver --last-run           # only what's new since the last run
+suno-archiver --since "2 weeks ago"
+suno-archiver --dir ~/Music/suno_archive
+suno-archiver doctor               # diagnose auth/API issues
+```
+
+Re-runs are **idempotent** — existing files are skipped, so `--last-run` on a cron job keeps your archive current without re-downloading anything.
+
+## What lands on disk
+
+```
+suno_archive/
+├── 2026-06/
+│   ├── 2026-06-02_concrete-syncope_49291ca0.mp3
+│   ├── 2026-06-02_concrete-syncope_49291ca0.jpg     (cover art)
+│   └── 2026-06-02_concrete-syncope_49291ca0.json    (full metadata)
+├── library_index.json    (everything, searchable with jq/grep)
+└── .suno-archiver-state.json
+```
+
+Songs are organized into `YYYY-MM/` month folders. The state file records the last run timestamp for `--last-run` incremental syncs.
+
+## Resilient by design
+
+Archiving thousands of files over an undocumented API means things will occasionally go wrong mid-run. The tool is built so that they don't cost you:
+
+- **Per-file errors never abort the run.** A dead CDN link (403) or a transient hiccup (503) is counted and reported, then the run continues. You get a clear tally at the end: `3333 downloaded, 0 skipped, 3 errors`.
+- **Expired sessions self-heal.** Suno's auth tokens are short-lived; the tool transparently re-mints them, and retries once on a 401 before giving up.
+- **Interrupted runs are safe.** The `--last-run` watermark is only saved when a fetch completes cleanly — so a connection drop or a kill mid-run can never cause the *next* incremental sync to silently skip tracks. You just re-run.
+- **Re-runs are free.** Idempotent skipping means re-running after a partial failure costs nothing for already-downloaded files; only the gaps are retried.
+
+If the tool ever stops working entirely (Suno changed their API), `suno-archiver doctor` tells you *which* layer broke — your login, the auth exchange, or the library endpoint — so you know whether to re-log-in or wait for an update.
+
+## Related
+
+[replicate-predictions-downloader](https://github.com/closestfriend/replicate-predictions-downloader) — same idea for Replicate AI predictions: bulk-download all your generated outputs from Replicate's API.
+
+## License
+
+MIT — see [LICENSE](LICENSE).