streamrip-go/README.md

streamrip-go

A Go port of 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

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

Build

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).

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

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

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

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.