# streamrip-go

A Go port of [streamrip](https://github.com/nathom/streamrip): a command-line
music downloader for Qobuz, Tidal, Deezer, SoundCloud, Yandex Music and
Beatport. Downloads tracks, albums, playlists, artist discographies and labels,
tags them, optionally embeds cover art and converts the result.

You need your own paid account for any source you use. This tool does not
provide or circumvent access to anything.

## Requirements

- Go 1.25 or newer (to build)
- `ffmpeg` and `ffprobe` — tagging and format conversion
- `yt-dlp` — required for SoundCloud only

```sh
# Arch
sudo pacman -S ffmpeg yt-dlp
# Debian/Ubuntu
sudo apt install ffmpeg && pipx install yt-dlp
# macOS
brew install ffmpeg yt-dlp
```

## Build

```sh
make build        # -> ./rip, with version info stamped in
make install      # into $(go env GOBIN)
./rip --version
```

Or without make: `go build ./cmd/rip`.

## Configuration

The first run writes a config file and tells you where. It lives at
`$XDG_CONFIG_HOME/streamrip/config.toml` (`~/Library/Application
Support/streamrip/config.toml` on macOS).

```sh
rip config path     # print the path
rip config open     # open in $EDITOR
rip config reset    # restore defaults
```

`config.toml.example` documents every key. The file holds credentials in
plaintext — provider passwords, the Deezer ARL cookie and OAuth tokens — so it
is created `0600`. Keep it that way.

Credentials you need to set, per source:

| Source     | Required config |
|------------|-----------------|
| Qobuz      | `email_or_userid` + `password_or_token` (md5 of your password), or `use_auth_token = true` with an auth token |
| Tidal      | `access_token` / `refresh_token` |
| Deezer     | `arl` (recommended), or `email` + `password` |
| Yandex     | `access_token` |
| Beatport   | `username` + `password` |
| SoundCloud | none; handled via `yt-dlp` |

Lyrics (plain and synced `.lrc`-style) are fetched for Qobuz, Tidal and Deezer.
Each costs one extra API request per track, so `metadata.exclude = ["lyrics"]`
turns them off for a faster rip.

Each provider section also has vendor `app_client_id`-style keys. Leave them
empty: they default to values built into the binary. They exist so that if a
provider rotates one, you can patch your install with a config edit instead of
waiting for a release.

## Usage

```sh
rip url https://play.qobuz.com/album/abc123
rip url https://www.beatport.com/release/example/123 --force

rip id qobuz album abc123
rip search qobuz album "kind of blue"
rip search tidal track "teardrop" --first
rip file urls.txt           # one URL per line, or a JSON list of IDs
rip lastfm --source qobuz <lastfm-playlist-url>

rip database downloads      # what has already been downloaded
rip database failed
```

Global options (these must come *before* the command):

```
-f, --folder <path>        Override downloads folder
-q, --quality <0-4>        Override provider quality
-c, --codec <codec>        Convert after download: ALAC, FLAC, OGG, MP3, AAC
-ndb, --no-db              Ignore the download database
    --no-progress          Disable progress bars
    --no-ssl-verify        Disable TLS verification
    --config-path <path>   Use a custom config file
-v, -vv                    Verbose logging (-vv also logs HTTP requests)
-V, --version              Show version
-h, --help                 Show help
```

Run `rip help <command>` for per-command help.

### Quality

`-q` is a 0–4 scale mapped onto each provider's own ladder. Qobuz and Beatport
have no tier 0, so `-q 0` is raised to 1 for those and reported on stderr.

| Source     | Range | 0 | Top tier |
|------------|-------|---|----------|
| Qobuz      | 1–4   | — | FLAC 24-bit up to 192 kHz |
| Tidal      | 0–4   | LOW (HE-AAC) | HI_RES_LOSSLESS |
| Deezer     | 0–4   | MP3 128 | FLAC (anything ≥ 2) |
| Yandex     | 0–4   | LOW | lossless |
| Beatport   | 1–4   | — | FLAC 16/44.1 |
| SoundCloud | 0–4   | ignored | provider-defined |

Each provider saturates at the top of its own ladder, so values above its
highest real tier are accepted and behave as that tier.

### Download database

Completed downloads are recorded in a SQLite database and skipped next time.
`--force` / `--ignore-db` overrides this for one run; `-ndb` disables it
entirely. Paths are configurable under `[database]`.

If you are upgrading from a build that predates source tracking, the database
is migrated on first open and a copy is kept alongside it as
`downloads.db.bak-<timestamp>`.

## Development

```sh
make check     # gofmt + vet + tests, what CI runs
make test
make race
make cover
make lint      # needs golangci-lint
```

The test suite runs in about a second and makes no network requests; provider
tests drive `httptest` servers.

Layout:

```
cmd/rip                 CLI entry point, one file per command group
internal/app            orchestration: queue, resolve, rip
internal/provider/*     one client per source, behind provider.Client
internal/download       HTTP downloads, progress bars, Deezer/Yandex decryption
internal/audio/{tag,convert}   ffmpeg tagging and conversion
internal/{naming,artwork,store,config,netutil,ratelimit,jsonutil,verbose}
```

### Known rough edges

Two deliberate pieces of technical debt, both documented rather than hidden:

- **No shared HTTP layer.** The request/decode/retry sequence is reimplemented
  in each provider client, and retry on 429/5xx exists in only two of six. A
  `provider/transport` package would remove roughly 700 lines.
- **Metadata is `map[string]any`.** `provider.Client` returns untyped maps, so
  each client hand-builds an undeclared "Qobuz-shaped" schema that
  `cmd/rip/search.go` then unpicks in a long switch. A typed media model is the
  natural next step; `internal/provider/qobuz/model.go` is a started-and-parked
  attempt at it.

## License

No license file is present, so this is "all rights reserved" by default. Add
one before distributing. Note that upstream streamrip is GPL-3.0.