Metadata-Version: 2.4
Name: spinback
Version: 0.3.0
Summary: Prepare tracks for DJing: download from YouTube, SoundCloud, Bandcamp or Mixcloud, import Spotify/Deezer playlists by OCR from screenshots or a screen recording of the scrolling playlist, then preview, cut and clean them
Keywords: dj,traktor,serato,yt-dlp,youtube,soundcloud,bandcamp,mixcloud,spotify,deezer,ocr,loudness,flac
Author: leogermond
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: click>=8.3.1
Requires-Dist: contractme>=2
Requires-Dist: epycs>=2
Requires-Dist: fastapi>=0.162.0
Requires-Dist: more-itertools>=10.8.0
Requires-Dist: mutagen>=1.48.1
Requires-Dist: pillow>=12
Requires-Dist: rapidocr-onnxruntime>=1.4.4
Requires-Dist: requests>=2.32.5
Requires-Dist: requests-cache>=1.3.1
Requires-Dist: selenium>=4.41.0
Requires-Dist: selenium-requests>=2.0.4
Requires-Dist: uvicorn>=0.54.0
Requires-Dist: yt-dlp>=2026.8.19
Requires-Python: >=3.14, <3.15
Project-URL: Homepage, https://gitlab.com/leogermond/spinback
Project-URL: Repository, https://gitlab.com/leogermond/spinback
Description-Content-Type: text/markdown

# spinback

spinback is a local web app to prepare tracks for mixing. It downloads from
YouTube, YouTube Music, SoundCloud, Bandcamp and Mixcloud in the best format
DJ software reads without re-encoding, with tags and cover art. It imports a
Spotify or Deezer playlist from a screen recording (read by OCR) and finds it
on YouTube. It previews, cuts and cleans a track (gain, loudness
normalisation, equaliser, limiter) and exports FLAC. It browses your music
folders: Traktor's when Traktor is installed, otherwise your Music folder.
Traktor is an optional integration.


[![pipeline status](https://gitlab.com/leogermond/spinback/badges/main/pipeline.svg)](https://gitlab.com/leogermond/spinback/-/commits/main)
![coverage](https://gitlab.com/leogermond/spinback/badges/main/coverage.svg?job=test)

[![Linter: ruff](https://img.shields.io/badge/Linter-Ruff-brightgreen?style=flat-square)](https://github.com/charliermarsh/ruff)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json)](https://github.com/copier-org/copier)

## Quick start

Windows: paste this line in PowerShell. It installs uv and ffmpeg if they are
missing, then starts spinback.

```powershell
irm https://gitlab.com/leogermond/spinback/-/raw/main/install.ps1 | iex
```

macOS and Linux:

```sh
curl -LsSf https://gitlab.com/leogermond/spinback/-/raw/main/install.sh | sh
```

On macOS and Linux, install ffmpeg yourself if the script reports it missing
(`brew install ffmpeg`, `sudo apt install ffmpeg`).

Already have uv and ffmpeg? Run:

```sh
uvx --python 3.14 spinback
```

To install the command permanently:

```sh
pipx install spinback
# or
uv tool install spinback
```

The distribution, the command and the Python package are all named `spinback`.

## Features

- Download from YouTube, YouTube Music, SoundCloud, Bandcamp and Mixcloud,
  untouched audio (no re-encoding) with tags and cover art.
- Import a Spotify or Deezer playlist by OCR and search each track on YouTube
  ([details](#importing-a-spotify-or-deezer-playlist-ocr)).
- Preview, cut and clean a track: gain, loudness normalisation, equaliser,
  limiter, FLAC export.
- Browse your music folders, from Traktor's collection when it is installed,
  else from the Music folder.

## Usage

`spinback` serves the web GUI on http://127.0.0.1:8765 (the port of the
config, `~/.config/spinback/config.toml`, else 8765) and opens it in the
browser, the Windows one under WSL. `spinback --no-browser` only serves it;
`spinback gui --port … --music-dir … --traktor-dir …` sets its options.
`spinback --help` lists the command-line steps (`video-songs`, `yt-resolve`,
`yt-playlist`, `yt-download`, `playlists`, `songs`).

## Importing a Spotify or Deezer playlist (OCR)

Spotify and Deezer protect their sites with DRM and offer spinback no API:
there is no account access and no playlist URL to give. spinback reads the
playlist from what is on screen instead.

**Record.** On your phone, use the native screen recording (iOS or Android),
open the playlist, then scroll slowly from the top to the bottom without
pausing or stopping the recording. Screenshots work too: take several that overlap a little, so every track
appears in at least one, and give them in scrolling order.

**Supported apps.** Spotify (dark theme) and Deezer (light theme), on iOS;
layouts are tuned for an iPhone in portrait. The app is detected from the
brightness of the screen, and `--app spotify` or `--app deezer` forces it.
Any resolution works, a copy recompressed by WhatsApp included.

**Import.** In the downloader, use the import button or drop the video or the
screenshots on it (several screenshots dropped together are sorted by file
name: rename them if that is not the scrolling order), or run
`spinback video-songs <video>` or `spinback video-songs <shot1> <shot2> …`
on the command line.

**Then.** spinback reads the tracks by OCR and searches each one on YouTube.
It shows a score and alternatives for every match; validate them before
downloading.

**Known limits.**

- Titles truncated by the app stay truncated.
- OCR sometimes misreads a letter.
- The first track can be cut off by the top of the screen.
- Accents and non-Latin characters are the least reliable.
