fix tidal playlist metadata and retries

cmd/rip/args.go

@@ -24,7 +24,7 @@ type globalOptions struct {
 	codec       string
 	noProgress  bool
 	noSSLVerify bool
-	verbose     bool
+	verbose     int
 	command     string
 	commandArgs []string
 }
@@ -52,7 +52,13 @@ func parseGlobalArgs(args []string) (globalOptions, error) {
 		case arg == "--no-ssl-verify":
 			opts.noSSLVerify = true
 		case arg == "-v" || arg == "--verbose":
-			opts.verbose = true
+			if opts.verbose < 2 {
+				opts.verbose++
+			}
+		case arg == "-vv":
+			if opts.verbose < 2 {
+				opts.verbose = 2
+			}
 		case arg == "-f" || arg == "--folder":
 			if i+1 >= len(args) {
 				return globalOptions{}, fmt.Errorf("%s requires a value", arg)

cmd/rip/lastfm.go

@@ -86,7 +86,7 @@ func fetchLastFMPlaylist(ctx context.Context, verifySSL bool, playlistURL string
 	if !isValidLastFMPlaylistURL(playlistURL) {
 		return "", nil, fmt.Errorf("invalid playlist url")
 	}
-	client := netutil.NewHTTPClient(30*time.Second, verifySSL)
+	client := netutil.NewHTTPClient(30*time.Second, verifySSL, 0)
 
 	page1, err := fetchLastFMPlaylistPage(ctx, client, parsed, 1)
 	if err != nil {
@@ -123,7 +123,7 @@ func fetchLastFMPlaylist(ctx context.Context, verifySSL bool, playlistURL string
 }
 
 func fetchLastFMPlaylistViaMirror(ctx context.Context, verifySSL bool, playlistURL string) (string, []lastFMTrack, error) {
-	client := netutil.NewHTTPClient(30*time.Second, verifySSL)
+	client := netutil.NewHTTPClient(30*time.Second, verifySSL, 0)
 	all := make([]lastFMTrack, 0, 200)
 	title := ""
 
@@ -376,7 +376,7 @@ func fetchSoundcloudOEmbed(ctx context.Context, verifySSL bool, trackURL string)
 	q.Set("url", trackURL)
 	endpoint := "https://soundcloud.com/oembed?" + q.Encode()
 
-	client := netutil.NewHTTPClient(20*time.Second, verifySSL)
+	client := netutil.NewHTTPClient(20*time.Second, verifySSL, 0)
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
 	if err != nil {
 		return nil, err

cmd/rip/main.go

@@ -14,6 +14,7 @@ import (
 	"streamrip-go/internal/app"
 	"streamrip-go/internal/config"
 	"streamrip-go/internal/provider"
+	"streamrip-go/internal/verbose"
 
 	_ "modernc.org/sqlite"
 )
@@ -49,8 +50,11 @@ func main() {
 		os.Exit(1)
 	}
 	applyGlobalConfigOverrides(cfg, gopts)
-	if gopts.verbose {
+	verbose.SetLevel(gopts.verbose)
-		fmt.Fprintln(os.Stderr, "verbose mode enabled")
+	if gopts.verbose >= 2 {
+		fmt.Fprintln(os.Stderr, "verbose mode enabled (level 2: downloads + http)")
+	} else if gopts.verbose >= 1 {
+		fmt.Fprintln(os.Stderr, "verbose mode enabled (level 1: downloads)")
 	}
 
 	os.Args = append([]string{os.Args[0], gopts.command}, gopts.commandArgs...)

cmd/rip/main_test.go

@@ -227,7 +227,7 @@ func TestParseGlobalArgsAllOfficialFlags(t *testing.T) {
 	if !opts.noDB || !opts.qualitySet || opts.quality != 3 || !opts.codecSet || opts.codec != "VORBIS" {
 		t.Fatalf("unexpected quality/codec/db opts: %+v", opts)
 	}
-	if !opts.noProgress || !opts.noSSLVerify || !opts.verbose {
+	if !opts.noProgress || !opts.noSSLVerify || opts.verbose != 1 {
 		t.Fatalf("unexpected boolean opts: %+v", opts)
 	}
 	if opts.command != "search" {

internal/app/app.go

@@ -26,6 +26,7 @@ import (
 	soundcloudprovider "streamrip-go/internal/provider/soundcloud"
 	tidalprovider "streamrip-go/internal/provider/tidal"
 	"streamrip-go/internal/store"
+	"streamrip-go/internal/verbose"
 )
 
 type Main struct {
@@ -91,6 +92,10 @@ type videoDownloadableProvider interface {
 	GetVideoDownloadable(ctx context.Context, videoID string) (*provider.Downloadable, error)
 }
 
+type trackFallbackDownloader interface {
+	DownloadTrackFallback(ctx context.Context, trackID string, quality int, outputPath string) error
+}
+
 func New(cfg *config.Config) (*Main, error) {
 	var db store.Database
 	if cfg.Session.Database.DownloadsEnabled || cfg.Session.Database.FailedDownloadsEnabled {
@@ -110,18 +115,32 @@ func New(cfg *config.Config) (*Main, error) {
 		"soundcloud": soundcloudprovider.New(cfg),
 	}
 
-	return &Main{
+	m := &Main{
 		Config:    cfg,
 		Providers: providers,
 		Store:     db,
-		DL:        download.NewWithOptions(cfg.Session.Downloads.VerifySSL, cfg.Session.CLI.ProgressBars),
+		DL:        download.NewWithOptions(cfg.Session.Downloads.VerifySSL, cfg.Session.CLI.ProgressBars, downloaderMaxConnsPerHost(cfg.Session.Downloads.MaxConnections)),
 		Tagger:    tag.New(),
 		Pending:   []media.Pending{},
 		Media:     []media.Media{},
-	}, nil
+	}
+	verbose.SetSink(func(msg string) { m.DL.Logf("%s", msg) })
+	return m, nil
+}
+
+// downloaderMaxConnsPerHost picks the per-host idle connection cap for the
+// shared download client. We floor at 16 so artwork/manifest fetches and
+// concurrent track downloads to the same CDN host can reuse keep-alive
+// sockets even when the user configured a tiny max_connections.
+func downloaderMaxConnsPerHost(maxConnections int) int {
+	if maxConnections > 16 {
+		return maxConnections
+	}
+	return 16
 }
 
 func (m *Main) Close() error {
+	verbose.SetSink(nil)
 	m.DL.Close()
 	artwork.CleanupTempDirs()
 	for _, p := range m.Providers {
@@ -874,11 +893,21 @@ func (m *Main) ripTrack(ctx context.Context, p provider.Client, source, id, fall
 	if err = downloadOnce(); err != nil {
 		m.logf("retry: %s (%v)\n", filepath.Base(outPath), err)
 		if err = downloadOnce(); err != nil {
+			if fallbackProvider, ok := p.(trackFallbackDownloader); ok {
+				m.logf("fallback: %s via provider backup flow\n", filepath.Base(outPath))
+				if fbErr := fallbackProvider.DownloadTrackFallback(ctx, id, m.qualityForSource(source), outPath); fbErr == nil {
+					goto downloaded
+				} else {
+					m.logf("fallback failed: %s (%v)\n", filepath.Base(outPath), fbErr)
+				}
+			}
 			_ = m.Store.MarkFailed(ctx, source, "track", id)
 			return fmt.Errorf("id=%s title=%q download: %w", id, title, err)
 		}
 	}
 
+downloaded:
+
 	embedCoverPath := opts.albumEmbedCover
 	if opts.forPlaylist {
 		parent := opts.albumFolder
@@ -1260,11 +1289,12 @@ func buildTagMetadata(trackMeta map[string]any, title, source, trackID string, o
 	if discTotal == 0 {
 		discTotal = jsonutil.IntFromAny(trackMeta["numberOfVolumes"])
 	}
-	if discTotal == 0 && opts.albumDiscTotal > 0 {
+	if !opts.forPlaylist && discTotal == 0 && opts.albumDiscTotal > 0 {
 		discTotal = opts.albumDiscTotal
 	}
 	if opts.forPlaylist {
-		discTotal = 1
+		discNumber = 0
+		discTotal = 0
 	}
 	if !opts.forPlaylist && discNumber == 0 {
 		discNumber = 1

internal/app/app_test.go

@@ -309,7 +309,7 @@ func TestTrackRipFailsWhenTaggerReportsMissingFFmpeg(t *testing.T) {
 			"qobuz": &fakeProvider{url: ts.URL},
 		},
 		Store:  sqlite,
-		DL:     download.NewWithOptions(true, false),
+		DL:     download.NewWithOptions(true, false, 0),
 		Tagger: failingTagger{err: fmt.Errorf("ffmpeg not found: %w", exec.ErrNotFound)},
 	}
 
@@ -490,6 +490,43 @@ func TestBuildTagMetadataUsesAlbumArtistOverride(t *testing.T) {
 	}
 }
 
+func TestBuildTagMetadataPlaylistOmitsDiscTags(t *testing.T) {
+	meta := map[string]any{
+		"title":                 "One Step Too Far",
+		"track_number":          float64(15),
+		"media_number":          float64(2),
+		"numberOfVolumes":       float64(2),
+		"numberOfTracks":        float64(18),
+		"performer":             map[string]any{"name": "Faithless"},
+		"artist":                map[string]any{"name": "Faithless"},
+		"release_date":          "2005-01-01",
+		"release_date_original": "2005-01-01",
+		"album": map[string]any{
+			"id":     "23324600",
+			"title":  "Greatest Hits (Deluxe)",
+			"artist": map[string]any{"name": "Faithless"},
+		},
+	}
+	playlistCfg := config.DefaultConfigData().Metadata
+	applyPlaylistMetadataOverrides(meta, playlistCfg, "Road Trip", 3)
+	tags := buildTagMetadata(meta, "One Step Too Far", "tidal", "23324615", ripTrackOptions{forPlaylist: true, playlistName: "Road Trip", playlistPos: 3, total: 20})
+	if tags.Album != "Road Trip" {
+		t.Fatalf("album = %q, want Road Trip", tags.Album)
+	}
+	if tags.TrackNumber != 3 {
+		t.Fatalf("track number = %d, want 3", tags.TrackNumber)
+	}
+	if tags.TrackTotal != 20 {
+		t.Fatalf("track total = %d, want 20", tags.TrackTotal)
+	}
+	if tags.DiscNumber != 0 {
+		t.Fatalf("disc number = %d, want 0", tags.DiscNumber)
+	}
+	if tags.DiscTotal != 0 {
+		t.Fatalf("disc total = %d, want 0", tags.DiscTotal)
+	}
+}
+
 func TestTrackOutputPathFallsBackToDisc1(t *testing.T) {
 	tmp := t.TempDir()
 	d := config.DefaultConfigData()
@@ -537,7 +574,7 @@ func TestPlaylistRipPipeline(t *testing.T) {
 			"qobuz": &fakePlaylistProvider{url: ts.URL},
 		},
 		Store:  sqlite,
-		DL:     download.NewWithOptions(true, false),
+		DL:     download.NewWithOptions(true, false, 0),
 		Tagger: noopTagger{},
 	}
 
@@ -588,7 +625,7 @@ func TestPlaylistRipUsesSourceSubdirectory(t *testing.T) {
 			"qobuz": &fakePlaylistProvider{url: ts.URL},
 		},
 		Store:  sqlite,
-		DL:     download.NewWithOptions(true, false),
+		DL:     download.NewWithOptions(true, false, 0),
 		Tagger: noopTagger{},
 	}
 
@@ -773,7 +810,7 @@ func TestRipAlbumUsesResolvedAudioProfileForFolderName(t *testing.T) {
 			"qobuz": fake,
 		},
 		Store:  sqlite,
-		DL:     download.NewWithOptions(true, false),
+		DL:     download.NewWithOptions(true, false, 0),
 		Tagger: noopTagger{},
 	}
 

internal/download/downloader.go

@@ -20,6 +20,7 @@ import (
 	"golang.org/x/term"
 
 	"streamrip-go/internal/netutil"
+	"streamrip-go/internal/verbose"
 
 	"golang.org/x/crypto/blowfish"
 )
@@ -31,18 +32,23 @@ type Downloader struct {
 	barStarted   atomic.Int32
 }
 
+// downloadBufferSize sizes HTTP-to-disk copies. 1 MiB cuts read/write syscalls
+// ~32x vs Go's default 32 KiB io.Copy buffer, which matters for multi-MB FLAC
+// streams off CDNs that can sustain high per-connection throughput.
+const downloadBufferSize = 1 << 20
+
 func New() *Downloader {
-	return NewWithOptions(true, true)
+	return NewWithOptions(true, true, 0)
 }
 
 func NewWithVerifySSL(verifySSL bool) *Downloader {
-	return NewWithOptions(verifySSL, true)
+	return NewWithOptions(verifySSL, true, 0)
 }
 
-func NewWithOptions(verifySSL bool, showProgress bool) *Downloader {
+func NewWithOptions(verifySSL bool, showProgress bool, maxConnsPerHost int) *Downloader {
 	forceProgress := strings.EqualFold(os.Getenv("STREAMRIP_GO_FORCE_PROGRESS"), "1") || strings.EqualFold(os.Getenv("STREAMRIP_GO_FORCE_PROGRESS"), "true")
 	interactive := showProgress && (forceProgress || (term.IsTerminal(int(os.Stderr.Fd())) && strings.ToLower(os.Getenv("TERM")) != "dumb"))
-	d := &Downloader{http: netutil.NewHTTPClient(0, verifySSL), showProgress: interactive}
+	d := &Downloader{http: netutil.NewHTTPClient(0, verifySSL, maxConnsPerHost), showProgress: interactive}
 	if interactive {
 		d.progress = mpb.New(mpb.WithWidth(40), mpb.WithOutput(os.Stderr))
 	}
@@ -62,6 +68,7 @@ func (d *Downloader) FileVideo(ctx context.Context, sourceURL, outputPath string
 }
 
 func (d *Downloader) FileDeezerEncrypted(ctx context.Context, sourceURL, outputPath, trackID string) error {
+	logDownloadStart(sourceURL, outputPath)
 	if err := os.MkdirAll(filepath.Dir(outputPath), 0o755); err != nil {
 		return err
 	}
@@ -124,6 +131,11 @@ func (d *Downloader) FileDeezerEncrypted(ctx context.Context, sourceURL, outputP
 			)
 			defer bar.SetTotal(-1, true)
 		}
+		defer func() {
+			if !success && bar != nil {
+				bar.Abort(true)
+			}
+		}()
 	}
 
 	block, err := blowfish.NewCipher(deriveDeezerBlowfishKey(trackID))
@@ -171,6 +183,7 @@ func (d *Downloader) FileDeezerEncrypted(ctx context.Context, sourceURL, outputP
 }
 
 func (d *Downloader) file(ctx context.Context, sourceURL, outputPath string, allowProgress bool, includeVideo bool) error {
+	logDownloadStart(sourceURL, outputPath)
 	if err := os.MkdirAll(filepath.Dir(outputPath), 0o755); err != nil {
 		return err
 	}
@@ -244,7 +257,12 @@ func (d *Downloader) file(ctx context.Context, sourceURL, outputPath string, all
 			)
 			defer bar.SetTotal(-1, true)
 		}
-		buf := make([]byte, 256*1024)
+		defer func() {
+			if !success && bar != nil {
+				bar.Abort(true)
+			}
+		}()
+		buf := make([]byte, downloadBufferSize)
 		totalWritten := int64(0)
 		for {
 			n, readErr := reader.Read(buf)
@@ -269,7 +287,7 @@ func (d *Downloader) file(ctx context.Context, sourceURL, outputPath string, all
 			return err
 		}
 	} else {
-		written, copyErr := io.Copy(out, reader)
+		written, copyErr := io.CopyBuffer(out, reader, make([]byte, downloadBufferSize))
 		if copyErr != nil {
 			return copyErr
 		}
@@ -304,6 +322,16 @@ func (d *Downloader) Logf(format string, args ...any) {
 	fmt.Print(msg)
 }
 
+// logDownloadStart emits the source URL and destination filename when the
+// user passed -v or higher. The transport-level logger covers the same
+// requests at -vv, but this line gives a friendlier per-track summary.
+func logDownloadStart(sourceURL, outputPath string) {
+	if !verbose.Enabled(verbose.V) {
+		return
+	}
+	verbose.Printf(verbose.V, "download %s -> %s\n", sourceURL, filepath.Base(outputPath))
+}
+
 func shortenName(name string, max int) string {
 	if max <= 0 {
 		return name

internal/download/downloader_test.go

@@ -18,7 +18,7 @@ import (
 )
 
 func TestDownloaderHasNoClientTimeout(t *testing.T) {
-	d := NewWithOptions(true, false)
+	d := NewWithOptions(true, false, 0)
 	if d.http.Timeout != 0 {
 		t.Fatalf("http timeout = %v, want 0 (no global timeout)", d.http.Timeout)
 	}
@@ -95,7 +95,7 @@ func TestFileDeezerEncrypted(t *testing.T) {
 	}))
 	defer ts.Close()
 
-	d := NewWithOptions(true, false)
+	d := NewWithOptions(true, false, 0)
 	out := filepath.Join(t.TempDir(), "x", "a.flac")
 	if err = d.FileDeezerEncrypted(context.Background(), ts.URL, out, trackID); err != nil {
 		t.Fatalf("FileDeezerEncrypted() error = %v", err)
@@ -117,7 +117,7 @@ func TestDownloaderFileTruncatedResponseRemovesPartialFile(t *testing.T) {
 	}))
 	defer ts.Close()
 
-	d := NewWithOptions(true, false)
+	d := NewWithOptions(true, false, 0)
 	out := filepath.Join(t.TempDir(), "x", "a.bin")
 	err := d.File(context.Background(), ts.URL, out)
 	if err == nil || !errors.Is(err, io.ErrUnexpectedEOF) {
@@ -135,7 +135,7 @@ func TestFileDeezerEncryptedTruncatedResponseRemovesPartialFile(t *testing.T) {
 	}))
 	defer ts.Close()
 
-	d := NewWithOptions(true, false)
+	d := NewWithOptions(true, false, 0)
 	out := filepath.Join(t.TempDir(), "x", "a.flac")
 	err := d.FileDeezerEncrypted(context.Background(), ts.URL, out, "3135556")
 	if err == nil || !errors.Is(err, io.ErrUnexpectedEOF) {
@@ -152,7 +152,7 @@ func TestFileDeezerEncryptedBadStatus(t *testing.T) {
 	}))
 	defer ts.Close()
 
-	d := NewWithOptions(true, false)
+	d := NewWithOptions(true, false, 0)
 	out := filepath.Join(t.TempDir(), "x", "a.flac")
 	err := d.FileDeezerEncrypted(context.Background(), ts.URL, out, "3135556")
 	if err == nil || !strings.Contains(err.Error(), "status=403") {
@@ -171,7 +171,7 @@ func TestDownloaderFileContextCancellationRemovesPartialFile(t *testing.T) {
 	}))
 	defer ts.Close()
 
-	d := NewWithOptions(true, false)
+	d := NewWithOptions(true, false, 0)
 	out := filepath.Join(t.TempDir(), "x", "cancel.bin")
 	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Millisecond)
 	defer cancel()
@@ -185,7 +185,7 @@ func TestDownloaderFileContextCancellationRemovesPartialFile(t *testing.T) {
 }
 
 func TestStreamManifestWithFFmpegMissing(t *testing.T) {
-	d := NewWithOptions(true, false)
+	d := NewWithOptions(true, false, 0)
 	t.Setenv("PATH", "")
 	err := d.streamManifestWithFFmpeg(context.Background(), "https://example.com/live.m3u8", filepath.Join(t.TempDir(), "out.m4a"), false)
 	if err == nil || !strings.Contains(strings.ToLower(err.Error()), "ffmpeg not found") {
@@ -197,7 +197,7 @@ func TestStreamManifestWithFFmpegFailureRemovesPartialFile(t *testing.T) {
 	if _, err := exec.LookPath("ffmpeg"); err != nil {
 		t.Skip("ffmpeg not installed")
 	}
-	d := NewWithOptions(true, false)
+	d := NewWithOptions(true, false, 0)
 	out := filepath.Join(t.TempDir(), "out.m4a")
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()

internal/netutil/http.go

@@ -3,18 +3,103 @@ package netutil
 import (
 	"crypto/tls"
 	"net/http"
+	"net/url"
 	"time"
+
+	"streamrip-go/internal/verbose"
 )
 
-func NewHTTPClient(timeout time.Duration, verifySSL bool) *http.Client {
+const defaultMaxConnsPerHost = 16
+
+// NewHTTPClient builds an *http.Client whose transport is tuned for the
+// concurrent download workloads this app issues against single CDN hosts.
+//
+// maxConnsPerHost caps idle keep-alive sockets per host; pass <= 0 to use a
+// sensible default. The downloader and provider clients should pass the
+// configured concurrency so keep-alive sockets aren't evicted between workers.
+func NewHTTPClient(timeout time.Duration, verifySSL bool, maxConnsPerHost int) *http.Client {
+	if maxConnsPerHost <= 0 {
+		maxConnsPerHost = defaultMaxConnsPerHost
+	}
+
 	transport := http.DefaultTransport.(*http.Transport).Clone()
 	if transport.TLSClientConfig == nil {
 		transport.TLSClientConfig = &tls.Config{}
 	}
 	transport.TLSClientConfig.InsecureSkipVerify = !verifySSL
 
+	transport.MaxIdleConnsPerHost = maxConnsPerHost
+	if maxIdle := maxConnsPerHost * 4; maxIdle > transport.MaxIdleConns {
+		transport.MaxIdleConns = maxIdle
+	}
+	if transport.MaxIdleConns < 100 {
+		transport.MaxIdleConns = 100
+	}
+	transport.MaxConnsPerHost = 0
+	transport.IdleConnTimeout = 90 * time.Second
+	transport.WriteBufferSize = 64 * 1024
+	transport.ReadBufferSize = 64 * 1024
+	transport.ForceAttemptHTTP2 = true
+
 	return &http.Client{
 		Timeout:   timeout,
-		Transport: transport,
+		Transport: &loggingTransport{base: transport},
 	}
 }
+
+// loggingTransport emits one verbose line per HTTP request when verbose
+// level >= VV. The check is per-call so toggling the level at runtime
+// affects subsequent requests without rebuilding clients.
+type loggingTransport struct {
+	base http.RoundTripper
+}
+
+func (t *loggingTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	if !verbose.Enabled(verbose.VV) {
+		return t.base.RoundTrip(req)
+	}
+	start := time.Now()
+	resp, err := t.base.RoundTrip(req)
+	elapsed := time.Since(start).Round(time.Millisecond)
+	target := redactURL(req.URL)
+	if err != nil {
+		verbose.Printf(verbose.VV, "http %s %s -> error %v (%s)\n", req.Method, target, err, elapsed)
+		return resp, err
+	}
+	verbose.Printf(verbose.VV, "http %s %s -> %d (%s)\n", req.Method, target, resp.StatusCode, elapsed)
+	return resp, err
+}
+
+// redactURL hides values for query parameters that commonly carry
+// credentials so -vv output is safe to paste in an issue.
+func redactURL(u *url.URL) string {
+	if u == nil {
+		return ""
+	}
+	if u.RawQuery == "" {
+		return u.String()
+	}
+	q := u.Query()
+	redacted := false
+	for k := range q {
+		if isSensitiveParam(k) {
+			q.Set(k, "REDACTED")
+			redacted = true
+		}
+	}
+	if !redacted {
+		return u.String()
+	}
+	cp := *u
+	cp.RawQuery = q.Encode()
+	return cp.String()
+}
+
+func isSensitiveParam(name string) bool {
+	switch name {
+	case "user_auth_token", "api_token", "access_token", "refresh_token",
+		"request_sig", "signature", "password", "secret", "token", "code", "auth", "key":
+		return true
+	}
+	return false
+}

internal/provider/deezer/client.go

@@ -62,7 +62,7 @@ type Client struct {
 }
 
 func New(cfg *config.Config) *Client {
-	httpClient := netutil.NewHTTPClient(30*time.Second, cfg.Session.Downloads.VerifySSL)
+	httpClient := netutil.NewHTTPClient(30*time.Second, cfg.Session.Downloads.VerifySSL, cfg.Session.Downloads.MaxConnections)
 	if jar, err := cookiejar.New(nil); err == nil {
 		httpClient.Jar = jar
 	}
@@ -176,6 +176,9 @@ func (c *Client) GetMetadata(ctx context.Context, item, mediaType string) (map[s
 		if err != nil {
 			return nil, err
 		}
+		if tracks, pageErr := c.getCollectionPageItems(ctx, "/album/"+strings.TrimSpace(item)+"/tracks"); pageErr == nil {
+			resp["tracks"] = map[string]any{"data": tracks}
+		}
 		items := make([]any, 0)
 		if tracks, ok := resp["tracks"].(map[string]any); ok {
 			if data, ok := tracks["data"].([]any); ok {
@@ -197,6 +200,9 @@ func (c *Client) GetMetadata(ctx context.Context, item, mediaType string) (map[s
 		if err != nil {
 			return nil, err
 		}
+		if tracks, pageErr := c.getCollectionPageItems(ctx, "/playlist/"+strings.TrimSpace(item)+"/tracks"); pageErr == nil {
+			resp["tracks"] = map[string]any{"data": tracks}
+		}
 		items := make([]any, 0)
 		if tracks, ok := resp["tracks"].(map[string]any); ok {
 			if data, ok := tracks["data"].([]any); ok {
@@ -269,6 +275,35 @@ func (c *Client) getArtistAlbums(ctx context.Context, artistID string) (map[stri
 	return map[string]any{"data": all, "total": total}, nil
 }
 
+func (c *Client) getCollectionPageItems(ctx context.Context, path string) ([]any, error) {
+	const pageSize = 100
+	index := 0
+	total := -1
+	all := make([]any, 0)
+	for {
+		params := url.Values{}
+		params.Set("limit", strconv.Itoa(pageSize))
+		params.Set("index", strconv.Itoa(index))
+		resp, err := c.apiGet(ctx, path, params)
+		if err != nil {
+			return nil, err
+		}
+		data, _ := resp["data"].([]any)
+		all = append(all, data...)
+		if total < 0 {
+			total = jsonutil.IntFromAny(resp["total"])
+		}
+		if len(data) < pageSize {
+			break
+		}
+		index += len(data)
+		if total > 0 && index >= total {
+			break
+		}
+	}
+	return all, nil
+}
+
 func (c *Client) GetDownloadable(ctx context.Context, item string, _ int) (*provider.Downloadable, error) {
 	if strings.TrimSpace(c.license) == "" {
 		if err := c.ensureLaunchSession(ctx); err != nil {
@@ -282,7 +317,7 @@ func (c *Client) GetDownloadable(ctx context.Context, item string, _ int) (*prov
 	if err != nil {
 		return nil, err
 	}
-	trackToken, err := c.getTrackToken(ctx, item)
+	trackToken, mediaTrackID, err := c.getTrackToken(ctx, item)
 	if err != nil {
 		return nil, err
 	}
@@ -294,7 +329,13 @@ func (c *Client) GetDownloadable(ctx context.Context, item string, _ int) (*prov
 	if ext == "" {
 		ext = "mp3"
 	}
-	trackID := strings.TrimSpace(jsonutil.StringFromAny(meta["id"]))
+	trackID := strings.TrimSpace(media.TrackID)
+	if trackID == "" {
+		trackID = strings.TrimSpace(mediaTrackID)
+	}
+	if trackID == "" {
+		trackID = strings.TrimSpace(jsonutil.StringFromAny(meta["id"]))
+	}
 	if trackID == "" {
 		trackID = strings.TrimSpace(item)
 	}
@@ -549,32 +590,33 @@ func (c *Client) loginWithCredentials(ctx context.Context, email, password strin
 	return nil
 }
 
-func (c *Client) getTrackToken(ctx context.Context, trackID string) (string, error) {
+func (c *Client) getTrackToken(ctx context.Context, trackID string) (string, string, error) {
-	if token, err := c.getTrackTokenFromPipe(ctx, trackID); err == nil && strings.TrimSpace(token) != "" {
+	if token, mediaID, err := c.getTrackTokenFromPipe(ctx, trackID); err == nil && strings.TrimSpace(token) != "" {
-		return token, nil
+		return token, mediaID, nil
 	} else if errors.Is(err, errDeezerJWTExpired) {
 		c.refreshJWTFromAvailableState(ctx)
-		if token, retryErr := c.getTrackTokenFromPipe(ctx, trackID); retryErr == nil && strings.TrimSpace(token) != "" {
+		if token, mediaID, retryErr := c.getTrackTokenFromPipe(ctx, trackID); retryErr == nil && strings.TrimSpace(token) != "" {
-			return token, nil
+			return token, mediaID, nil
 		}
 	}
 	if err := c.ensureJWT(ctx, "deezer jwt unavailable for track media token"); err == nil {
-		if token, retryErr := c.getTrackTokenFromPipe(ctx, trackID); retryErr == nil && strings.TrimSpace(token) != "" {
+		if token, mediaID, retryErr := c.getTrackTokenFromPipe(ctx, trackID); retryErr == nil && strings.TrimSpace(token) != "" {
-			return token, nil
+			return token, mediaID, nil
 		}
 	}
 	resp, err := c.apiGet(ctx, "/track/"+url.PathEscape(strings.TrimSpace(trackID)), nil)
 	if err != nil {
-		return "", err
+		return "", "", err
 	}
 	token := strings.TrimSpace(jsonutil.StringFromAny(resp["track_token"]))
 	if token == "" {
-		return "", errors.New("deezer track metadata missing track_token")
+		return "", "", errors.New("deezer track metadata missing track_token")
 	}
-	return token, nil
+	mediaID := strings.TrimSpace(jsonutil.StringFromAny(resp["id"]))
+	return token, mediaID, nil
 }
 
-func (c *Client) getTrackTokenFromPipe(ctx context.Context, trackID string) (string, error) {
+func (c *Client) getTrackTokenFromPipe(ctx context.Context, trackID string) (string, string, error) {
 	query := `query KmpMpTrackMedia($trackId: String!) { track(trackId: $trackId) { media { __typename ...TrackMediaFields } } }  fragment TrackMediaFields on TrackMedia { id version token { payload expiresAt version } estimatedSizes { flac: FLAC mp3_320: MP3_320 mp3_128: MP3_128 mp3_misc: MP3_MISC opus_std: OPUS_STD opus_high: OPUS_HIGH sbc_256: SBC_256 aac_96: AAC_96 aac_64: AAC_64 ac4_ims: AC4_IMS dd_joc: DD_JOC mp4_ra1: MP4_RA1 mp4_ra2: MP4_RA2 mp4_ra3: MP4_RA3 } gain rights { sub { available } ads { available } } }`
 	body := map[string]any{
 		"operationName": "KmpMpTrackMedia",
@@ -589,13 +631,15 @@ func (c *Client) getTrackTokenFromPipe(ctx context.Context, trackID string) (str
 	}
 	out, err := c.pipeGraphQL(ctx, body, "deezer track media query")
 	if err != nil {
-		return "", err
+		return "", "", err
 	}
-	payload := strings.TrimSpace(jsonutil.StringFromAny(jsonutil.NestedMap(jsonutil.NestedMap(jsonutil.NestedMap(jsonutil.NestedMap(out, "data"), "track"), "media"), "token")["payload"]))
+	media := jsonutil.NestedMap(jsonutil.NestedMap(jsonutil.NestedMap(out, "data"), "track"), "media")
+	payload := strings.TrimSpace(jsonutil.StringFromAny(jsonutil.NestedMap(media, "token")["payload"]))
 	if payload == "" {
-		return "", errors.New("deezer track media response missing token payload")
+		return "", "", errors.New("deezer track media response missing token payload")
 	}
-	return payload, nil
+	mediaID := strings.TrimSpace(jsonutil.StringFromAny(media["id"]))
+	return payload, mediaID, nil
 }
 
 type lyricsResult struct {
@@ -1145,9 +1189,10 @@ func randomDeezerUA() string {
 }
 
 type mediaResult struct {
-	URL    string
+	URL     string
-	Format string
+	Format  string
-	Cipher string
+	Cipher  string
+	TrackID string
 }
 
 type deezerMediaError struct {
@@ -1270,19 +1315,50 @@ func (c *Client) getMediaURLWithRequest(ctx context.Context, trackToken string,
 		return nil, &deezerMediaError{Code: e.Code, Message: e.Message}
 	}
 	for _, want := range requestedFormats {
-		for _, m := range parsed.Data[0].Media {
+		for _, preferredCipher := range []string{"NONE", "BF_CBC_STRIPE"} {
-			if !strings.EqualFold(strings.TrimSpace(m.Format), want) {
+			for _, m := range parsed.Data[0].Media {
-				continue
+				if !strings.EqualFold(strings.TrimSpace(m.Format), want) {
+					continue
+				}
+				if !strings.EqualFold(strings.TrimSpace(m.Cipher.Type), preferredCipher) {
+					continue
+				}
+				if len(m.Sources) == 0 || strings.TrimSpace(m.Sources[0].URL) == "" {
+					continue
+				}
+				sourceURL := strings.TrimSpace(m.Sources[0].URL)
+				return &mediaResult{URL: sourceURL, Format: m.Format, Cipher: m.Cipher.Type, TrackID: extractTrackIDFromMediaURL(sourceURL)}, nil
 			}
-			if len(m.Sources) == 0 || strings.TrimSpace(m.Sources[0].URL) == "" {
-				continue
-			}
-			return &mediaResult{URL: m.Sources[0].URL, Format: m.Format, Cipher: m.Cipher.Type}, nil
 		}
 	}
 	return nil, errors.New("deezer media response contains no sources")
 }
 
+func extractTrackIDFromMediaURL(rawURL string) string {
+	u, err := url.Parse(strings.TrimSpace(rawURL))
+	if err != nil {
+		return ""
+	}
+	parts := strings.Split(strings.TrimSpace(strings.Trim(u.Path, "/")), "/")
+	for i := len(parts) - 1; i >= 0; i-- {
+		p := strings.TrimSpace(parts[i])
+		if p == "" {
+			continue
+		}
+		digitsOnly := true
+		for _, r := range p {
+			if r < '0' || r > '9' {
+				digitsOnly = false
+				break
+			}
+		}
+		if digitsOnly {
+			return p
+		}
+	}
+	return ""
+}
+
 func buildFormatPriority(quality int, allowFallback bool) []string {
 	want := "FLAC"
 	if quality <= 0 {

internal/provider/deezer/client_test.go

@@ -99,6 +99,118 @@ func TestGetMetadataArtistPaginatesAlbums(t *testing.T) {
 	}
 }
 
+func TestGetMetadataAlbumPaginatesTracks(t *testing.T) {
+	callCount := 0
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/album/46514392":
+			_ = json.NewEncoder(w).Encode(map[string]any{"id": 46514392, "title": "Clouseau30", "tracks": map[string]any{"data": []any{}}})
+		case "/album/46514392/tracks":
+			callCount++
+			index := r.URL.Query().Get("index")
+			limit := r.URL.Query().Get("limit")
+			if limit != "100" {
+				w.WriteHeader(http.StatusBadRequest)
+				return
+			}
+			switch index {
+			case "0":
+				items := make([]any, 0, 100)
+				for i := 0; i < 100; i++ {
+					items = append(items, map[string]any{"id": i + 1, "title": "T"})
+				}
+				_ = json.NewEncoder(w).Encode(map[string]any{"data": items, "total": 105})
+			case "100":
+				items := make([]any, 0, 5)
+				for i := 0; i < 5; i++ {
+					items = append(items, map[string]any{"id": 101 + i, "title": "T"})
+				}
+				_ = json.NewEncoder(w).Encode(map[string]any{"data": items, "total": 105})
+			default:
+				w.WriteHeader(http.StatusBadRequest)
+			}
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer ts.Close()
+
+	cfgData := config.DefaultConfigData()
+	c := New(&config.Config{File: cfgData, Session: cfgData})
+	c.loggedIn = true
+
+	origBase := baseURL
+	baseURL = ts.URL
+	defer func() { baseURL = origBase }()
+
+	meta, err := c.GetMetadata(context.Background(), "46514392", "album")
+	if err != nil {
+		t.Fatalf("GetMetadata() error = %v", err)
+	}
+	tracksObj, _ := meta["tracks"].(map[string]any)
+	items, _ := tracksObj["items"].([]any)
+	if len(items) != 105 {
+		t.Fatalf("tracks len = %d, want 105", len(items))
+	}
+	if callCount != 2 {
+		t.Fatalf("track page call count = %d, want 2", callCount)
+	}
+}
+
+func TestGetMetadataPlaylistPaginatesTracks(t *testing.T) {
+	callCount := 0
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/playlist/123":
+			_ = json.NewEncoder(w).Encode(map[string]any{"id": 123, "title": "Mix", "tracks": map[string]any{"data": []any{}}})
+		case "/playlist/123/tracks":
+			callCount++
+			index := r.URL.Query().Get("index")
+			limit := r.URL.Query().Get("limit")
+			if limit != "100" {
+				w.WriteHeader(http.StatusBadRequest)
+				return
+			}
+			switch index {
+			case "0":
+				items := make([]any, 0, 100)
+				for i := 0; i < 100; i++ {
+					items = append(items, map[string]any{"id": i + 1, "title": "T"})
+				}
+				_ = json.NewEncoder(w).Encode(map[string]any{"data": items, "total": 101})
+			case "100":
+				_ = json.NewEncoder(w).Encode(map[string]any{"data": []any{map[string]any{"id": 101, "title": "T"}}, "total": 101})
+			default:
+				w.WriteHeader(http.StatusBadRequest)
+			}
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer ts.Close()
+
+	cfgData := config.DefaultConfigData()
+	c := New(&config.Config{File: cfgData, Session: cfgData})
+	c.loggedIn = true
+
+	origBase := baseURL
+	baseURL = ts.URL
+	defer func() { baseURL = origBase }()
+
+	meta, err := c.GetMetadata(context.Background(), "123", "playlist")
+	if err != nil {
+		t.Fatalf("GetMetadata() error = %v", err)
+	}
+	tracksObj, _ := meta["tracks"].(map[string]any)
+	items, _ := tracksObj["items"].([]any)
+	if len(items) != 101 {
+		t.Fatalf("tracks len = %d, want 101", len(items))
+	}
+	if callCount != 2 {
+		t.Fatalf("track page call count = %d, want 2", callCount)
+	}
+}
+
 func TestGetDownloadableNativeCipher(t *testing.T) {
 	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		switch r.URL.Path {
@@ -161,6 +273,58 @@ func TestGetDownloadableNativeCipher(t *testing.T) {
 	}
 }
 
+func TestGetDownloadablePrefersNoneCipherWhenAvailable(t *testing.T) {
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/track/42":
+			_ = json.NewEncoder(w).Encode(map[string]any{"id": 42, "title": "X", "track_token": "tt"})
+		case "/media":
+			_ = json.NewEncoder(w).Encode(map[string]any{"data": []any{map[string]any{"errors": []any{}, "media": []any{
+				map[string]any{"cipher": map[string]any{"type": "BF_CBC_STRIPE"}, "format": "FLAC", "sources": []any{map[string]any{"url": "https://cdn.example/bf"}}},
+				map[string]any{"cipher": map[string]any{"type": "NONE"}, "format": "FLAC", "sources": []any{map[string]any{"url": "https://cdn.example/plain"}}},
+			}}}})
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer ts.Close()
+
+	cfgData := config.DefaultConfigData()
+	cfgData.Deezer.ARL = "arl"
+	c := New(&config.Config{File: cfgData, Session: cfgData})
+	c.loggedIn = true
+	c.arl = "arl"
+	c.license = "license"
+	c.jwt = "jwt"
+
+	origBase := baseURL
+	origMedia := mediaURL
+	origPipe := pipeURL
+	baseURL = ts.URL
+	mediaURL = ts.URL + "/media"
+	pipeURL = ts.URL + "/pipe"
+	defer func() {
+		baseURL = origBase
+		mediaURL = origMedia
+		pipeURL = origPipe
+	}()
+
+	d, err := c.GetDownloadable(context.Background(), "42", 2)
+	if err != nil {
+		t.Fatalf("GetDownloadable() error = %v", err)
+	}
+	if d.Cipher != "NONE" || d.URL != "https://cdn.example/plain" {
+		t.Fatalf("expected NONE cipher source, got %+v", d)
+	}
+}
+
+func TestExtractTrackIDFromMediaURL(t *testing.T) {
+	url := "https://f-cdnt-stream.dzcdn.net/media/1/9/6/4/8/2552667002/64821d6a2007e90768fa0300b508fcf4.flac?hdnea=x"
+	if got := extractTrackIDFromMediaURL(url); got != "2552667002" {
+		t.Fatalf("extractTrackIDFromMediaURL() = %q, want 2552667002", got)
+	}
+}
+
 func TestLoginPrefersARLFlowOverRefreshShortcut(t *testing.T) {
 	mobileToken := testMobileToken(t)
 	refreshCalled := false
@@ -298,13 +462,16 @@ func TestGetTrackTokenPrefersPipeToken(t *testing.T) {
 		pipeURL = origPipe
 	}()
 
-	token, err := c.getTrackToken(context.Background(), "42")
+	token, mediaID, err := c.getTrackToken(context.Background(), "42")
 	if err != nil {
 		t.Fatalf("getTrackToken() error = %v", err)
 	}
 	if token != "pipe-track-token" {
 		t.Fatalf("token = %q, want pipe-track-token", token)
 	}
+	if mediaID != "" {
+		t.Fatalf("mediaID = %q, want empty when pipe media id missing", mediaID)
+	}
 }
 
 func TestGetDownloadableUsesPipeTrackToken(t *testing.T) {

internal/provider/qobuz/client.go

@@ -1,20 +1,28 @@
 package qobuz
 
 import (
+	"bytes"
 	"context"
+	"crypto/aes"
+	"crypto/cipher"
 	"crypto/md5"
+	"crypto/sha256"
 	"encoding/base64"
 	"encoding/hex"
 	"encoding/json"
 	"errors"
 	"fmt"
+	"hash"
 	"io"
 	"net/http"
 	"net/url"
+	"os"
+	"path/filepath"
 	"regexp"
 	"sort"
 	"strconv"
 	"strings"
+	"sync"
 	"time"
 
 	"streamrip-go/internal/config"
@@ -22,10 +30,28 @@ import (
 	"streamrip-go/internal/netutil"
 	"streamrip-go/internal/provider"
 	"streamrip-go/internal/ratelimit"
+
+	"github.com/vbauerster/mpb/v8"
+	"github.com/vbauerster/mpb/v8/decor"
+	"golang.org/x/crypto/hkdf"
 )
 
 const baseURL = "https://www.qobuz.com/api.json/0.2"
 
+const (
+	mobileAppID        = "312369995"
+	mobileAppSecret    = "e79f8b9be485692b0e5f9dd895826368"
+	mobileUserAgent    = "Dalvik/2.1.0 (Linux; U; Android 9; Nexus 6P Build/PQ3A.190801.002) QobuzMobileAndroid/9.7.0.3-b26022717"
+	mobileAppVersion   = "9.7.0.3"
+	mobileSessionProf  = "qbz-1"
+	mobileSegmentTries = 3
+)
+
+var qobuzUUIDBytes = []byte{
+	0x3b, 0x42, 0x12, 0x92, 0x56, 0xf3, 0x5f, 0x75,
+	0x92, 0x36, 0x63, 0xb6, 0x9a, 0x1f, 0x52, 0xb2,
+}
+
 var (
 	errMissingCredentials = errors.New("missing qobuz credentials")
 	errNotLoggedIn        = errors.New("qobuz client not logged in")
@@ -40,12 +66,29 @@ type Client struct {
 	loggedIn bool
 	secret   string
 	uat      string
+
+	mobileMu          sync.Mutex
+	mobileAccessToken string
+	mobileSessionID   string
+	mobileSessionInfo string
+	mobileKEK         []byte
+}
+
+type mobileFileURL struct {
+	URL         string  `json:"url"`
+	URLTemplate string  `json:"url_template"`
+	NSegments   int     `json:"n_segments"`
+	FormatID    int     `json:"format_id"`
+	MimeType    string  `json:"mime_type"`
+	Sampling    float64 `json:"sampling_rate"`
+	BitDepth    int     `json:"bits_depth"`
+	Key         string  `json:"key"`
 }
 
 func New(cfg *config.Config) *Client {
 	return &Client{
 		cfg:      cfg,
-		http:     netutil.NewHTTPClient(30*time.Second, cfg.Session.Downloads.VerifySSL),
+		http:     netutil.NewHTTPClient(30*time.Second, cfg.Session.Downloads.VerifySSL, cfg.Session.Downloads.MaxConnections),
 		limiter:  ratelimit.New(cfg.Session.Downloads.RequestsPerMinute),
 		baseURL:  baseURL,
 		fetchCfg: nil,
@@ -399,6 +442,122 @@ func (c *Client) Close() error {
 	return nil
 }
 
+func (c *Client) DownloadTrackFallback(ctx context.Context, trackID string, quality int, outputPath string) error {
+	q := &c.cfg.Session.Qobuz
+	if strings.TrimSpace(q.EmailOrUserID) == "" || strings.TrimSpace(q.PasswordOrToken) == "" || q.UseAuthToken {
+		return errors.New("qobuz mobile fallback requires email/password credentials")
+	}
+	if quality < 1 || quality > 4 {
+		quality = q.Quality
+	}
+	formatID := qualityMap(quality)
+
+	if err := c.ensureMobileSession(ctx); err != nil {
+		return err
+	}
+	fileURL, err := c.mobileGetFileURL(ctx, trackID, formatID)
+	if err != nil {
+		return err
+	}
+
+	if err = os.MkdirAll(filepath.Dir(outputPath), 0o755); err != nil {
+		return err
+	}
+	out, err := os.Create(outputPath)
+	if err != nil {
+		return err
+	}
+	success := false
+	defer func() {
+		_ = out.Close()
+		if !success {
+			_ = os.Remove(outputPath)
+		}
+	}()
+
+	progress := mpb.New(mpb.WithWidth(40), mpb.WithOutput(os.Stderr))
+	defer progress.Wait()
+	desc := shortenName(filepath.Base(outputPath), 54)
+	bar := progress.AddSpinner(
+		0,
+		mpb.PrependDecorators(
+			decor.Name(desc+" ", decor.WC{W: 56, C: decor.DSyncWidth | decor.DindentRight}),
+		),
+		mpb.AppendDecorators(
+			decor.CurrentKibiByte("% .1f", decor.WCSyncWidthR),
+			decor.Name(" | ", decor.WCSyncWidth),
+			decor.Elapsed(decor.ET_STYLE_GO, decor.WCSyncWidthR),
+		),
+		mpb.BarRemoveOnComplete(),
+	)
+	defer func() {
+		if !success {
+			bar.Abort(true)
+		}
+		bar.SetTotal(-1, true)
+	}()
+
+	if strings.TrimSpace(fileURL.URL) != "" && fileURL.NSegments == 0 {
+		err = c.mobileCopyURLToWriter(ctx, strings.TrimSpace(fileURL.URL), out, bar)
+		if err != nil {
+			return err
+		}
+		success = true
+		return nil
+	}
+	if strings.TrimSpace(fileURL.URLTemplate) == "" {
+		return errors.New("qobuz mobile fallback: no download URL available")
+	}
+
+	var trackKey []byte
+	if strings.TrimSpace(fileURL.Key) != "" {
+		trackKey, err = c.mobileDeriveTrackKey(fileURL.Key)
+		if err != nil {
+			return fmt.Errorf("derive mobile track key: %w", err)
+		}
+	}
+
+	nSegs := fileURL.NSegments
+	if nSegs == 0 {
+		nSegs = 1
+	}
+	initURL := strings.Replace(fileURL.URLTemplate, "$SEGMENT$", "0", 1)
+	initData, err := c.mobileDownloadSegment(ctx, initURL)
+	if err != nil {
+		return fmt.Errorf("download init segment: %w", err)
+	}
+
+	if hdr := extractFLACHeader(initData); hdr != nil {
+		if _, err = out.Write(hdr); err != nil {
+			return err
+		}
+		bar.IncrBy(len(hdr))
+	} else {
+		if _, err = out.Write(initData); err != nil {
+			return err
+		}
+		bar.IncrBy(len(initData))
+	}
+
+	for seg := 1; seg <= nSegs; seg++ {
+		segURL := strings.Replace(fileURL.URLTemplate, "$SEGMENT$", strconv.Itoa(seg), 1)
+		data, dlErr := c.mobileDownloadSegment(ctx, segURL)
+		if dlErr != nil {
+			return fmt.Errorf("download segment %d: %w", seg, dlErr)
+		}
+		frames := extractFrames(data, trackKey)
+		if _, err = out.Write(frames); err != nil {
+			return err
+		}
+		bar.IncrBy(len(frames))
+	}
+	if err = out.Sync(); err != nil {
+		return err
+	}
+	success = true
+	return nil
+}
+
 func (c *Client) getPlaylist(ctx context.Context, playlistID string) (map[string]any, error) {
 	pageLimit := 500
 	params := url.Values{}
@@ -820,3 +979,460 @@ func sortedKeys(m map[string][]string) []string {
 	sort.Strings(keys)
 	return keys
 }
+
+func (c *Client) ensureMobileSession(ctx context.Context) error {
+	c.mobileMu.Lock()
+	defer c.mobileMu.Unlock()
+	if c.mobileAccessToken != "" && c.mobileSessionID != "" && c.mobileSessionInfo != "" {
+		return nil
+	}
+	q := &c.cfg.Session.Qobuz
+	if err := c.mobileLogin(ctx, q.EmailOrUserID, q.PasswordOrToken); err != nil {
+		return err
+	}
+	if err := c.mobileStartSession(ctx); err != nil {
+		c.mobileAccessToken = ""
+		return err
+	}
+	return nil
+}
+
+func (c *Client) mobileLogin(ctx context.Context, username, password string) error {
+	ts := time.Now().Unix()
+	params := url.Values{}
+	params.Set("app_id", mobileAppID)
+	params.Set("username", username)
+	params.Set("password", password)
+	params.Set("request_ts", strconv.FormatInt(ts, 10))
+	params.Set("request_sig", mobileSignRequest("oauth2/login", []kv{{"password", password}, {"username", username}}, ts))
+
+	reqURL := baseURL + "/oauth2/login?" + params.Encode()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, reqURL, nil)
+	if err != nil {
+		return err
+	}
+	c.setMobileHeaders(req)
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return fmt.Errorf("mobile login request failed: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return err
+	}
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("mobile login failed: status=%d body=%s", resp.StatusCode, string(body))
+	}
+	var parsed struct {
+		OAuth2 struct {
+			AccessToken string `json:"access_token"`
+		} `json:"oauth2"`
+	}
+	if err = json.Unmarshal(body, &parsed); err != nil {
+		return fmt.Errorf("mobile login parse failed: %w", err)
+	}
+	if strings.TrimSpace(parsed.OAuth2.AccessToken) == "" {
+		return errors.New("mobile login returned empty token")
+	}
+	c.mobileAccessToken = strings.TrimSpace(parsed.OAuth2.AccessToken)
+	return nil
+}
+
+func (c *Client) mobileStartSession(ctx context.Context) error {
+	ts := time.Now().Unix()
+	params := url.Values{}
+	params.Set("app_id", mobileAppID)
+	params.Set("request_ts", strconv.FormatInt(ts, 10))
+	params.Set("request_sig", mobileSignRequest("session/start", []kv{{"profile", mobileSessionProf}}, ts))
+
+	reqURL := baseURL + "/session/start?" + params.Encode()
+	form := url.Values{}
+	form.Set("profile", mobileSessionProf)
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, reqURL, strings.NewReader(form.Encode()))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	c.setMobileHeaders(req)
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return fmt.Errorf("mobile session request failed: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return err
+	}
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("mobile session start failed: status=%d body=%s", resp.StatusCode, string(body))
+	}
+	var parsed struct {
+		SessionID string `json:"session_id"`
+		Infos     string `json:"infos"`
+	}
+	if err = json.Unmarshal(body, &parsed); err != nil {
+		return fmt.Errorf("mobile session parse failed: %w", err)
+	}
+	if strings.TrimSpace(parsed.SessionID) == "" || strings.TrimSpace(parsed.Infos) == "" {
+		return errors.New("mobile session start returned incomplete session data")
+	}
+	c.mobileSessionID = strings.TrimSpace(parsed.SessionID)
+	c.mobileSessionInfo = strings.TrimSpace(parsed.Infos)
+	c.mobileKEK = nil
+	return nil
+}
+
+func (c *Client) mobileGetFileURL(ctx context.Context, trackID string, formatID int) (*mobileFileURL, error) {
+	ts := time.Now().Unix()
+	params := url.Values{}
+	params.Set("app_id", mobileAppID)
+	params.Set("track_id", trackID)
+	params.Set("format_id", strconv.Itoa(formatID))
+	params.Set("intent", "stream")
+	params.Set("request_ts", strconv.FormatInt(ts, 10))
+	params.Set("request_sig", mobileSignRequest("file/url", []kv{{"format_id", strconv.Itoa(formatID)}, {"intent", "stream"}, {"track_id", trackID}}, ts))
+	reqURL := baseURL + "/file/url?" + params.Encode()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, reqURL, nil)
+	if err != nil {
+		return nil, err
+	}
+	c.setMobileHeaders(req)
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("mobile file url failed: status=%d body=%s", resp.StatusCode, string(body))
+	}
+	var parsed mobileFileURL
+	if err = json.Unmarshal(body, &parsed); err != nil {
+		return nil, fmt.Errorf("mobile file url parse failed: %w", err)
+	}
+	return &parsed, nil
+}
+
+func (c *Client) mobileCopyURLToWriter(ctx context.Context, sourceURL string, out io.Writer, bar *mpb.Bar) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, sourceURL, nil)
+	if err != nil {
+		return err
+	}
+	c.setMobileHeaders(req)
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("mobile fallback download failed: status=%d", resp.StatusCode)
+	}
+	written, err := io.Copy(out, &countingReader{r: resp.Body, onRead: func(n int) {
+		if bar != nil && n > 0 {
+			bar.IncrBy(n)
+		}
+	}})
+	if err != nil {
+		return err
+	}
+	if resp.ContentLength > 0 && written != resp.ContentLength {
+		return io.ErrUnexpectedEOF
+	}
+	return nil
+}
+
+type countingReader struct {
+	r      io.Reader
+	onRead func(int)
+}
+
+func (c *countingReader) Read(p []byte) (int, error) {
+	n, err := c.r.Read(p)
+	if n > 0 && c.onRead != nil {
+		c.onRead(n)
+	}
+	return n, err
+}
+
+func shortenName(name string, max int) string {
+	if max <= 0 {
+		return name
+	}
+	r := []rune(name)
+	if len(r) <= max {
+		return name
+	}
+	if max <= 3 {
+		return string(r[:max])
+	}
+	return string(r[:max-3]) + "..."
+}
+
+func (c *Client) mobileDownloadSegment(ctx context.Context, sourceURL string) ([]byte, error) {
+	var lastErr error
+	for attempt := 0; attempt < mobileSegmentTries; attempt++ {
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, sourceURL, nil)
+		if err != nil {
+			return nil, err
+		}
+		c.setMobileHeaders(req)
+		resp, err := c.http.Do(req)
+		if err != nil {
+			lastErr = err
+			time.Sleep(time.Duration(500*(attempt+1)) * time.Millisecond)
+			continue
+		}
+		if resp.StatusCode != http.StatusOK {
+			lastErr = fmt.Errorf("status=%d", resp.StatusCode)
+			_ = resp.Body.Close()
+			time.Sleep(time.Duration(500*(attempt+1)) * time.Millisecond)
+			continue
+		}
+		data, readErr := io.ReadAll(resp.Body)
+		_ = resp.Body.Close()
+		if readErr != nil {
+			lastErr = readErr
+			time.Sleep(time.Duration(500*(attempt+1)) * time.Millisecond)
+			continue
+		}
+		return data, nil
+	}
+	if lastErr == nil {
+		lastErr = errors.New("unknown segment error")
+	}
+	return nil, fmt.Errorf("mobile segment download failed after retries: %w", lastErr)
+}
+
+func (c *Client) setMobileHeaders(req *http.Request) {
+	req.Header.Set("User-Agent", mobileUserAgent)
+	req.Header.Set("X-App-Id", mobileAppID)
+	req.Header.Set("X-App-Version", mobileAppVersion)
+	req.Header.Set("X-Device-Platform", "android")
+	req.Header.Set("X-Device-Model", "Nexus 6P")
+	req.Header.Set("X-Device-Os-Version", "9")
+	if c.mobileAccessToken != "" {
+		req.Header.Set("Authorization", "Bearer "+c.mobileAccessToken)
+	}
+	if c.mobileSessionID != "" {
+		req.Header.Set("X-Session-Id", c.mobileSessionID)
+	}
+}
+
+func mobileSignRequest(endpoint string, params []kv, ts int64) string {
+	method := strings.ReplaceAll(endpoint, "/", "")
+	sortKVs(params)
+	var sb strings.Builder
+	sb.WriteString(method)
+	for _, p := range params {
+		sb.WriteString(p.Key)
+		sb.WriteString(p.Value)
+	}
+	sb.WriteString(strconv.FormatInt(ts, 10))
+	sb.WriteString(mobileAppSecret)
+	h := md5.Sum([]byte(sb.String()))
+	return hex.EncodeToString(h[:])
+}
+
+type kv struct {
+	Key   string
+	Value string
+}
+
+func sortKVs(s []kv) {
+	for i := 0; i < len(s); i++ {
+		for j := i + 1; j < len(s); j++ {
+			if s[j].Key < s[i].Key {
+				s[i], s[j] = s[j], s[i]
+			}
+		}
+	}
+}
+
+func (c *Client) mobileDeriveTrackKey(encryptedKey string) ([]byte, error) {
+	if len(c.mobileKEK) == 16 {
+		return unwrapQobuzTrackKey(encryptedKey, c.mobileKEK)
+	}
+	parts := strings.SplitN(c.mobileSessionInfo, ".", 2)
+	if len(parts) != 2 {
+		return nil, errors.New("invalid mobile session infos format")
+	}
+	salt, err := base64.RawURLEncoding.DecodeString(parts[0])
+	if err != nil {
+		return nil, fmt.Errorf("decode mobile salt: %w", err)
+	}
+	info, err := base64.RawURLEncoding.DecodeString(parts[1])
+	if err != nil {
+		return nil, fmt.Errorf("decode mobile info: %w", err)
+	}
+	reader := hkdf.New(func() hash.Hash { return sha256.New() }, hexDecodeOrNil(mobileAppSecret), salt, info)
+	kek := make([]byte, 16)
+	if _, err = io.ReadFull(reader, kek); err != nil {
+		return nil, fmt.Errorf("mobile hkdf derive failed: %w", err)
+	}
+	c.mobileKEK = kek
+	return unwrapQobuzTrackKey(encryptedKey, kek)
+}
+
+func hexDecodeOrNil(s string) []byte {
+	b, _ := hex.DecodeString(s)
+	return b
+}
+
+func unwrapQobuzTrackKey(encryptedKey string, kek []byte) ([]byte, error) {
+	parts := strings.SplitN(encryptedKey, ".", 3)
+	if len(parts) != 3 || parts[0] != mobileSessionProf {
+		return nil, errors.New("invalid qobuz track key format")
+	}
+	encKey, err := base64.RawURLEncoding.DecodeString(parts[1])
+	if err != nil {
+		return nil, fmt.Errorf("decode encrypted key failed: %w", err)
+	}
+	iv, err := base64.RawURLEncoding.DecodeString(parts[2])
+	if err != nil {
+		return nil, fmt.Errorf("decode key iv failed: %w", err)
+	}
+	block, err := aes.NewCipher(kek)
+	if err != nil {
+		return nil, err
+	}
+	decrypted := make([]byte, len(encKey))
+	mode := cipher.NewCBCDecrypter(block, iv)
+	mode.CryptBlocks(decrypted, encKey)
+	if len(decrypted) < 16 {
+		return nil, errors.New("decrypted key too short")
+	}
+	return decrypted[:16], nil
+}
+
+func extractFLACHeader(data []byte) []byte {
+	blocks := findDFLABlocks(data)
+	if blocks == nil {
+		return nil
+	}
+	out := make([]byte, 4+len(blocks))
+	copy(out, "fLaC")
+	copy(out[4:], blocks)
+	return out
+}
+
+func findDFLABlocks(data []byte) []byte {
+	pos := 0
+	for pos+8 <= len(data) {
+		size := int(uint32(data[pos])<<24 | uint32(data[pos+1])<<16 | uint32(data[pos+2])<<8 | uint32(data[pos+3]))
+		if size < 8 || pos+size > len(data) {
+			break
+		}
+		t := data[pos+4 : pos+8]
+		if string(t) == "dfLa" {
+			body := data[pos+8 : pos+size]
+			if len(body) > 4 {
+				return body[4:]
+			}
+		}
+		var inner []byte
+		switch string(t) {
+		case "moov", "trak", "mdia", "minf", "stbl":
+			inner = data[pos+8 : pos+size]
+		case "stsd":
+			if pos+16 <= pos+size {
+				inner = data[pos+16 : pos+size]
+			}
+		case "fLaC":
+			if pos+36 <= pos+size {
+				inner = data[pos+36 : pos+size]
+			}
+		}
+		if inner != nil {
+			if result := findDFLABlocks(inner); result != nil {
+				return result
+			}
+		}
+		pos += size
+	}
+	return nil
+}
+
+func extractFrames(data []byte, key []byte) []byte {
+	var frames []byte
+	pos := 0
+	for pos+8 <= len(data) {
+		boxSize := int(uint32(data[pos])<<24 | uint32(data[pos+1])<<16 | uint32(data[pos+2])<<8 | uint32(data[pos+3]))
+		if boxSize < 8 || pos+boxSize > len(data) {
+			break
+		}
+		if string(data[pos+4:pos+8]) == "uuid" && boxSize >= 36 {
+			if pos+24 > len(data) {
+				pos += boxSize
+				continue
+			}
+			if bytes.Equal(data[pos+8:pos+24], qobuzUUIDBytes) {
+				f := parseUUIDBox(data, pos, boxSize, key)
+				frames = append(frames, f...)
+			}
+		}
+		pos += boxSize
+	}
+	return frames
+}
+
+func parseUUIDBox(data []byte, boxStart, boxSize int, key []byte) []byte {
+	bodyOff := boxStart + 24
+	if bodyOff+12 > len(data) {
+		return nil
+	}
+	rawOffset := readU32BE(data, bodyOff+4)
+	numSamples := int(readU24BE(data, bodyOff+9))
+	if numSamples == 0 || numSamples > 10000 {
+		return nil
+	}
+	tableOff := bodyOff + 12
+	sampleDataOff := boxStart + int(rawOffset)
+	var frames []byte
+	offset := sampleDataOff
+	for i := 0; i < numSamples; i++ {
+		et := tableOff + i*16
+		if et+16 > len(data) || offset >= len(data) {
+			break
+		}
+		size := readU32BE(data, et)
+		encFlag := data[et+6] != 0 || data[et+7] != 0
+		end := offset + int(size)
+		if end > len(data) {
+			break
+		}
+		if encFlag && len(key) == 16 {
+			iv := make([]byte, 16)
+			copy(iv[:8], data[et+8:et+16])
+			block, err := aes.NewCipher(key)
+			if err != nil {
+				return frames
+			}
+			stream := cipher.NewCTR(block, iv)
+			decrypted := make([]byte, end-offset)
+			stream.XORKeyStream(decrypted, data[offset:end])
+			frames = append(frames, decrypted...)
+		} else {
+			frames = append(frames, data[offset:end]...)
+		}
+		offset = end
+	}
+	return frames
+}
+
+func readU32BE(data []byte, off int) uint32 {
+	if off+4 > len(data) {
+		return 0
+	}
+	return uint32(data[off])<<24 | uint32(data[off+1])<<16 | uint32(data[off+2])<<8 | uint32(data[off+3])
+}
+
+func readU24BE(data []byte, off int) uint32 {
+	if off+3 > len(data) {
+		return 0
+	}
+	return uint32(data[off])<<16 | uint32(data[off+1])<<8 | uint32(data[off+2])
+}

internal/provider/tidal/client.go

@@ -22,11 +22,13 @@ import (
 )
 
 const (
-	baseURL   = "https://api.tidalhifi.com/v1"
+	baseURL              = "https://api.tidalhifi.com/v1"
-	openAPIV2 = "https://openapi.tidal.com/v2"
+	lyricsAPIv1          = "https://api.tidal.com/v1"
-	authURL   = "https://auth.tidal.com/v1/oauth2"
+	openAPIV2            = "https://openapi.tidal.com/v2"
-	clientID  = "fX2JxdmntZWK0ixT"
+	authURL              = "https://auth.tidal.com/v1/oauth2"
-	clientSec = "1Nm5AfDAjxrgJFJbKNWLeAyKGVGmINuXPPLHVXAvxAg="
+	clientID             = "fX2JxdmntZWK0ixT"
+	clientSec            = "1Nm5AfDAjxrgJFJbKNWLeAyKGVGmINuXPPLHVXAvxAg="
+	tidalRequestAttempts = 3
 )
 
 var qualityMap = map[int]string{
@@ -50,21 +52,23 @@ var atmosAudioQualities = []string{"HI_RES_LOSSLESS", "HI_RES", "LOSSLESS", "HIG
 var ErrMissingTidalToken = errors.New("missing tidal access_token")
 
 type Client struct {
-	cfg      *config.Config
+	cfg       *config.Config
-	http     *http.Client
+	http      *http.Client
-	limiter  *ratelimit.Limiter
+	limiter   *ratelimit.Limiter
-	baseURL  string
+	baseURL   string
-	openAPI  string
+	lyricsAPI string
-	loggedIn bool
+	openAPI   string
+	loggedIn  bool
 }
 
 func New(cfg *config.Config) *Client {
 	return &Client{
-		cfg:     cfg,
+		cfg:       cfg,
-		http:    netutil.NewHTTPClient(30*time.Second, cfg.Session.Downloads.VerifySSL),
+		http:      netutil.NewHTTPClient(30*time.Second, cfg.Session.Downloads.VerifySSL, cfg.Session.Downloads.MaxConnections),
-		limiter: ratelimit.New(cfg.Session.Downloads.RequestsPerMinute),
+		limiter:   ratelimit.New(cfg.Session.Downloads.RequestsPerMinute),
-		baseURL: baseURL,
+		baseURL:   baseURL,
-		openAPI: openAPIV2,
+		lyricsAPI: lyricsAPIv1,
+		openAPI:   openAPIV2,
 	}
 }
 
@@ -206,11 +210,52 @@ func (c *Client) GetMetadata(ctx context.Context, item, mediaType string) (map[s
 		if album, ok := resp["album"].(map[string]any); ok {
 			enrichTidalImage(album)
 		}
+		// Lyrics live on a separate endpoint, so fetching them costs an extra
+		// rate-limited roundtrip per track. Users who don't embed lyrics can
+		// opt out via metadata.exclude = ["lyrics"].
+		if !c.lyricsExcluded() {
+			if lyrics, lrc := c.fetchTrackLyrics(ctx, item); lyrics != "" || lrc != "" {
+				if lyrics != "" {
+					resp["lyrics"] = lyrics
+				}
+				if lrc != "" {
+					resp["lyrics_synced"] = lrc
+				}
+			}
+		}
 	}
 
 	return resp, nil
 }
 
+func (c *Client) lyricsExcluded() bool {
+	for _, k := range c.cfg.Session.Metadata.Exclude {
+		if strings.EqualFold(strings.TrimSpace(k), "lyrics") {
+			return true
+		}
+	}
+	return false
+}
+
+func (c *Client) fetchTrackLyrics(ctx context.Context, trackID string) (string, string) {
+	params := url.Values{}
+	params.Set("deviceType", "PHONE")
+	params.Set("locale", "en_US")
+	params.Set("platform", "ANDROID")
+
+	resp, status, err := c.apiRequest(ctx, "tracks/"+url.PathEscape(strings.TrimSpace(trackID))+"/lyrics", params, c.lyricsAPI)
+	if err != nil {
+		return "", ""
+	}
+	if status != http.StatusOK {
+		return "", ""
+	}
+
+	lyrics := strings.TrimSpace(stringify(resp["lyrics"]))
+	lrc := strings.TrimSpace(stringify(resp["subtitles"]))
+	return lyrics, lrc
+}
+
 func (c *Client) Search(ctx context.Context, mediaType, query string, limit int) ([]map[string]any, error) {
 	if !c.loggedIn {
 		return nil, errors.New("tidal client not logged in")
@@ -247,10 +292,11 @@ func (c *Client) GetDownloadable(ctx context.Context, trackID string, quality in
 	}
 
 	if c.cfg.Session.Tidal.PreferAtmos {
-		if c.trackSupportsAtmos(ctx, trackID) {
+		// No tracks/{id} pre-check: getAtmosDownloadable already validates
-			if d, _ := c.getAtmosDownloadable(ctx, trackID); d != nil {
+		// each candidate response via playbackLooksAtmos and falls back
-				return d, nil
+		// through the format-specific trackManifests paths.
-			}
+		if d, _ := c.getAtmosDownloadable(ctx, trackID); d != nil {
+			return d, nil
 		}
 	}
 
@@ -265,6 +311,10 @@ func (c *Client) GetDownloadable(ctx context.Context, trackID string, quality in
 	}
 	if status == http.StatusOK {
 		if d := downloadableFromPlaybackManifest(resp); d != nil {
+			// Tidal's playbackinfo sometimes returns an m4a (HIGH/AAC)
+			// stream even when LOSSLESS+ was requested. There is no
+			// lossless m4a tier, so retry via the openAPI v2 manifest
+			// before settling for the downgrade.
 			if quality >= 2 && d.Extension == "m4a" {
 				if strict, strictErr := c.getDownloadableFromTrackManifest(ctx, trackID, quality); strictErr == nil && strict != nil {
 					return strict, nil
@@ -794,11 +844,111 @@ func resolvePlaylistURL(baseRaw, refRaw string) string {
 	return baseURL.ResolveReference(refURL).String()
 }
 
-func (c *Client) apiRequest(ctx context.Context, path string, params url.Values, base string) (map[string]any, int, error) {
+func shouldRetryStatus(status int) bool {
-	if err := c.limiter.Wait(ctx); err != nil {
+	return status == http.StatusTooManyRequests || status >= http.StatusInternalServerError
-		return nil, 0, err
+}
-	}
 
+func retryDelay(retryAfter string, attempt int) time.Duration {
+	retryAfter = strings.TrimSpace(retryAfter)
+	if retryAfter != "" {
+		if seconds, err := strconv.Atoi(retryAfter); err == nil && seconds >= 0 {
+			return time.Duration(seconds) * time.Second
+		}
+		if when, err := http.ParseTime(retryAfter); err == nil {
+			if delay := time.Until(when); delay > 0 {
+				return delay
+			}
+			return 0
+		}
+	}
+	return time.Duration(attempt+1) * 500 * time.Millisecond
+}
+
+func waitRetry(ctx context.Context, delay time.Duration) error {
+	if delay <= 0 {
+		return nil
+	}
+	timer := time.NewTimer(delay)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}
+
+func parseAPIResponseBody(body []byte, status int) (map[string]any, error) {
+	out := map[string]any{}
+	if len(body) == 0 {
+		return out, nil
+	}
+	if err := json.Unmarshal(body, &out); err != nil {
+		if status < http.StatusOK || status >= http.StatusMultipleChoices {
+			if raw := strings.TrimSpace(string(body)); raw != "" {
+				out["raw"] = raw
+			}
+			return out, nil
+		}
+		return nil, err
+	}
+	return out, nil
+}
+
+func readAPIResponse(resp *http.Response) (map[string]any, int, string, error) {
+	defer func() { _ = resp.Body.Close() }()
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, resp.StatusCode, resp.Header.Get("Retry-After"), err
+	}
+	parsed, err := parseAPIResponseBody(body, resp.StatusCode)
+	return parsed, resp.StatusCode, resp.Header.Get("Retry-After"), err
+}
+
+func (c *Client) doJSONWithRetry(ctx context.Context, newRequest func() (*http.Request, error)) (map[string]any, int, error) {
+	var lastStatus int
+	for attempt := 0; attempt < tidalRequestAttempts; attempt++ {
+		if err := c.limiter.Wait(ctx); err != nil {
+			return nil, 0, err
+		}
+		req, err := newRequest()
+		if err != nil {
+			return nil, 0, err
+		}
+		resp, err := c.http.Do(req)
+		if err != nil {
+			if attempt+1 < tidalRequestAttempts {
+				if waitErr := waitRetry(ctx, retryDelay("", attempt)); waitErr != nil {
+					return nil, 0, waitErr
+				}
+				continue
+			}
+			return nil, 0, err
+		}
+
+		parsed, status, retryAfter, err := readAPIResponse(resp)
+		lastStatus = status
+		if err != nil {
+			if attempt+1 < tidalRequestAttempts {
+				if waitErr := waitRetry(ctx, retryDelay(retryAfter, attempt)); waitErr != nil {
+					return nil, 0, waitErr
+				}
+				continue
+			}
+			return nil, status, err
+		}
+		if shouldRetryStatus(status) && attempt+1 < tidalRequestAttempts {
+			if waitErr := waitRetry(ctx, retryDelay(retryAfter, attempt)); waitErr != nil {
+				return nil, 0, waitErr
+			}
+			continue
+		}
+		return parsed, status, nil
+	}
+	return map[string]any{}, lastStatus, nil
+}
+
+func (c *Client) apiRequest(ctx context.Context, path string, params url.Values, base string) (map[string]any, int, error) {
 	if params == nil {
 		params = url.Values{}
 	}
@@ -814,65 +964,31 @@ func (c *Client) apiRequest(ctx context.Context, path string, params url.Values,
 		reqURL += "?" + params.Encode()
 	}
 
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, reqURL, nil)
+	return c.doJSONWithRetry(ctx, func() (*http.Request, error) {
-	if err != nil {
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, reqURL, nil)
-		return nil, 0, err
+		if err != nil {
-	}
+			return nil, err
-	req.Header.Set("Authorization", "Bearer "+c.cfg.Session.Tidal.AccessToken)
-	req.Header.Set("User-Agent", "streamrip-go/0.1")
-
-	resp, err := c.http.Do(req)
-	if err != nil {
-		return nil, 0, err
-	}
-	defer func() { _ = resp.Body.Close() }()
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return nil, resp.StatusCode, err
-	}
-	parsed := map[string]any{}
-	if len(body) > 0 {
-		if err = json.Unmarshal(body, &parsed); err != nil {
-			return nil, resp.StatusCode, err
 		}
-	}
+		req.Header.Set("Authorization", "Bearer "+c.cfg.Session.Tidal.AccessToken)
-
+		req.Header.Set("User-Agent", "streamrip-go/0.1")
-	return parsed, resp.StatusCode, nil
+		return req, nil
+	})
 }
 
 func (c *Client) apiPost(ctx context.Context, endpoint string, form url.Values, basicAuth bool) (map[string]any, int, error) {
-	if err := c.limiter.Wait(ctx); err != nil {
+	return c.doJSONWithRetry(ctx, func() (*http.Request, error) {
-		return nil, 0, err
+		req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewBufferString(form.Encode()))
-	}
+		if err != nil {
-
+			return nil, err
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewBufferString(form.Encode()))
-	if err != nil {
-		return nil, 0, err
-	}
-	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
-	req.Header.Set("User-Agent", "streamrip-go/0.1")
-	if basicAuth {
-		auth := base64.StdEncoding.EncodeToString([]byte(clientID + ":" + clientSec))
-		req.Header.Set("Authorization", "Basic "+auth)
-	}
-
-	resp, err := c.http.Do(req)
-	if err != nil {
-		return nil, 0, err
-	}
-	defer func() { _ = resp.Body.Close() }()
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return nil, resp.StatusCode, err
-	}
-	out := map[string]any{}
-	if len(body) > 0 {
-		if err = json.Unmarshal(body, &out); err != nil {
-			return nil, resp.StatusCode, err
 		}
-	}
+		req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
-	return out, resp.StatusCode, nil
+		req.Header.Set("User-Agent", "streamrip-go/0.1")
+		if basicAuth {
+			auth := base64.StdEncoding.EncodeToString([]byte(clientID + ":" + clientSec))
+			req.Header.Set("Authorization", "Basic "+auth)
+		}
+		return req, nil
+	})
 }
 
 func stringify(v any) string {

internal/provider/tidal/client_test.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
+	"net/url"
 	"reflect"
 	"strconv"
 	"testing"
@@ -162,6 +163,159 @@ func TestGetMetadataArtistPaginatesAlbums(t *testing.T) {
 	}
 }
 
+func TestGetMetadataTrackAddsLyricsAndSyncedLyrics(t *testing.T) {
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/v1/tracks/42":
+			_ = json.NewEncoder(w).Encode(map[string]any{"id": 42, "title": "Song", "album": map[string]any{"id": 10, "title": "Album"}})
+		case "/v1/tracks/42/lyrics":
+			q := r.URL.Query()
+			if q.Get("deviceType") != "PHONE" || q.Get("locale") != "en_US" || q.Get("platform") != "ANDROID" || q.Get("countryCode") != "MY" {
+				w.WriteHeader(http.StatusBadRequest)
+				_ = json.NewEncoder(w).Encode(map[string]any{"error": "bad query"})
+				return
+			}
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"lyrics":    "plain lyrics line",
+				"subtitles": "[00:00.00]plain lyrics line",
+			})
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer ts.Close()
+
+	cfgData := config.DefaultConfigData()
+	cfgData.Tidal.AccessToken = "token"
+	cfgData.Tidal.CountryCode = "MY"
+	c := New(&config.Config{File: cfgData, Session: cfgData})
+	c.loggedIn = true
+	c.baseURL = ts.URL + "/v1"
+	c.lyricsAPI = ts.URL + "/v1"
+
+	meta, err := c.GetMetadata(context.Background(), "42", "track")
+	if err != nil {
+		t.Fatalf("GetMetadata() err = %v", err)
+	}
+	if got := stringify(meta["lyrics"]); got != "plain lyrics line" {
+		t.Fatalf("lyrics = %q, want plain lyrics line", got)
+	}
+	if got := stringify(meta["lyrics_synced"]); got != "[00:00.00]plain lyrics line" {
+		t.Fatalf("lyrics_synced = %q, want synced lrc", got)
+	}
+}
+
+func TestGetMetadataTrackIgnoresLyricsEndpointFailure(t *testing.T) {
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/v1/tracks/42":
+			_ = json.NewEncoder(w).Encode(map[string]any{"id": 42, "title": "Song"})
+		case "/v1/tracks/42/lyrics":
+			w.WriteHeader(http.StatusNotFound)
+			_ = json.NewEncoder(w).Encode(map[string]any{"error": "not found"})
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer ts.Close()
+
+	cfgData := config.DefaultConfigData()
+	cfgData.Tidal.AccessToken = "token"
+	cfgData.Tidal.CountryCode = "US"
+	c := New(&config.Config{File: cfgData, Session: cfgData})
+	c.loggedIn = true
+	c.baseURL = ts.URL + "/v1"
+	c.lyricsAPI = ts.URL + "/v1"
+
+	meta, err := c.GetMetadata(context.Background(), "42", "track")
+	if err != nil {
+		t.Fatalf("GetMetadata() err = %v", err)
+	}
+	if _, ok := meta["lyrics"]; ok {
+		t.Fatalf("did not expect lyrics when endpoint fails")
+	}
+	if _, ok := meta["lyrics_synced"]; ok {
+		t.Fatalf("did not expect lyrics_synced when endpoint fails")
+	}
+}
+
+func TestAPIRequestRetriesTooManyRequests(t *testing.T) {
+	calls := 0
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/tracks/42" {
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+		calls++
+		if calls == 1 {
+			w.Header().Set("Retry-After", "0")
+			w.WriteHeader(http.StatusTooManyRequests)
+			_, _ = w.Write([]byte("slow down"))
+			return
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"id": 42, "title": "Song"})
+	}))
+	defer ts.Close()
+
+	cfgData := config.DefaultConfigData()
+	cfgData.Downloads.RequestsPerMinute = 0
+	cfgData.Tidal.AccessToken = "token"
+	cfgData.Tidal.CountryCode = "US"
+	c := New(&config.Config{File: cfgData, Session: cfgData})
+	c.baseURL = ts.URL + "/v1"
+
+	resp, status, err := c.apiRequest(context.Background(), "tracks/42", nil, c.baseURL)
+	if err != nil {
+		t.Fatalf("apiRequest() err = %v", err)
+	}
+	if status != http.StatusOK {
+		t.Fatalf("status = %d, want %d", status, http.StatusOK)
+	}
+	if calls != 2 {
+		t.Fatalf("calls = %d, want 2", calls)
+	}
+	if stringify(resp["title"]) != "Song" {
+		t.Fatalf("title = %q, want Song", stringify(resp["title"]))
+	}
+}
+
+func TestAPIPostRetriesTooManyRequests(t *testing.T) {
+	calls := 0
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/token" {
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+		calls++
+		if calls == 1 {
+			w.Header().Set("Retry-After", "0")
+			w.WriteHeader(http.StatusTooManyRequests)
+			_, _ = w.Write([]byte("slow down"))
+			return
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"access_token": "fresh-token"})
+	}))
+	defer ts.Close()
+
+	cfgData := config.DefaultConfigData()
+	cfgData.Downloads.RequestsPerMinute = 0
+	c := New(&config.Config{File: cfgData, Session: cfgData})
+
+	resp, status, err := c.apiPost(context.Background(), ts.URL+"/token", url.Values{"grant_type": []string{"refresh_token"}}, false)
+	if err != nil {
+		t.Fatalf("apiPost() err = %v", err)
+	}
+	if status != http.StatusOK {
+		t.Fatalf("status = %d, want %d", status, http.StatusOK)
+	}
+	if calls != 2 {
+		t.Fatalf("calls = %d, want 2", calls)
+	}
+	if stringify(resp["access_token"]) != "fresh-token" {
+		t.Fatalf("access_token = %q, want fresh-token", stringify(resp["access_token"]))
+	}
+}
+
 func TestGetDownloadablePrefersAtmosWhenEnabled(t *testing.T) {
 	var calls []string
 	allImmersive := true

internal/verbose/verbose.go

@@ -0,0 +1,68 @@
+// Package verbose provides a process-wide verbosity level and a pluggable
+// log sink so verbose output integrates with the downloader's progress bars.
+//
+// Level meaning:
+//
+//	0 (Off) - no extra output
+//	1 (V)   - log per-track CDN URLs from the downloader
+//	2 (VV)  - additionally log every outbound HTTP request via the
+//	          netutil-wrapped transport (covers all provider API calls
+//	          and downloads)
+package verbose
+
+import (
+	"fmt"
+	"os"
+	"sync/atomic"
+)
+
+const (
+	Off byte = 0
+	V   byte = 1
+	VV  byte = 2
+)
+
+var (
+	level atomic.Uint32
+	sink  atomic.Pointer[func(string)]
+)
+
+// SetLevel clamps and stores the verbosity level. Pass 0 to disable.
+func SetLevel(l int) {
+	if l < 0 {
+		l = 0
+	}
+	if l > int(VV) {
+		l = int(VV)
+	}
+	level.Store(uint32(l))
+}
+
+func Level() byte { return byte(level.Load()) }
+
+func Enabled(l byte) bool { return Level() >= l }
+
+// SetSink installs a writer for verbose output. Use this to route logs
+// through the downloader so they don't tear progress bars. Pass nil to
+// fall back to stderr.
+func SetSink(fn func(string)) {
+	if fn == nil {
+		sink.Store(nil)
+		return
+	}
+	sink.Store(&fn)
+}
+
+// Printf emits a line at the given level if verbosity is enabled. The
+// caller is responsible for including a trailing newline.
+func Printf(l byte, format string, args ...any) {
+	if !Enabled(l) {
+		return
+	}
+	msg := fmt.Sprintf(format, args...)
+	if p := sink.Load(); p != nil {
+		(*p)(msg)
+		return
+	}
+	_, _ = fmt.Fprint(os.Stderr, msg)
+}