chore: add README, Makefile, CI, lint config and --version

The repo had no README, Makefile, CI, linter config or version string. - README.md: requirements (ffmpeg/ffprobe, plus yt-dlp for SoundCloud), build, the per-source credentials table, usage, the quality scale and the download database's migration behaviour. Every claim was checked against the code rather than written from memory, which is how the quality-range bug below was found. It also records the two deferred refactors (no shared HTTP layer, and metadata as map[string]any) so they are documented rather than lore, and notes that there is no LICENSE file. - Makefile: build, install, test, race, cover, fmt, fmt-check, vet, lint, check, clean, help. `make build` stamps version/commit/date via -ldflags. - .github/workflows/ci.yml: gofmt, vet, build, test and test -race, plus a lint job. The linter is intentionally unpinned, with a comment: a golangci-lint built against an older Go cannot analyse a go1.25 module, which is the same reason a locally installed staticcheck built with go1.24 cannot run here. - .golangci.yml: standard set plus bodyclose, errorlint, nilerr and govet/copylocks. copylocks matters now that config.Config carries a mutex; bodyclose and errorlint target defects this codebase actually has. - `rip --version` / `-V`, documented in the help output, falling back to the VCS revision the toolchain embeds for `go install` builds. Fixes a bug introduced in the previous commit: Validate capped deezer quality at 2 and soundcloud at 1, but config.toml.example documents deezer as 2/3/4 and the global -q flag accepts 0-4, so a documented config would have failed to load. deezer's buildFormatPriority treats anything >= 2 as FLAC and soundcloud ignores the value entirely, so the real ceiling is 4 everywhere; only the Qobuz and Beatport floor of 1 is a genuine constraint. Pinned with a test that walks the whole documented range. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-10-16 13:57:25 +02:00 · 2026-10-03 17:14:59 +02:00
1 parent 384f32cd67
commit ff5fb1cdb5
@@ -0,0 +1,168 @@
+# 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` |
+
+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.