Skip to content

Liquid Glass and Apple Music touches for the Spotify iOS app. A GPL-3.0 fork of spoti.pw 0.21.1.

C
35.1 KB
Raw Blame
// The chain: every source in the order the Lyrics page puts them in, asked one after another, the
// first with timed lyrics answering for the track.
//
// Stopping at the first answer is what makes the lyrics card under the player appear at all. For a
// track Spotify has no lyrics of its own for, the card is only offered when the answer to Spotify's
// lyrics request arrives within about a second of the player building its list of cards; a walk that
// went on through every source for word timing took three seconds and more, and the card never came.
// So the order is the priority, as it reads on the Lyrics page: a source further down is only asked
// when those above it had nothing timed, and then only for what they lacked.
#import "Core/SGCore.h"
#import "LyricsSources.h"
#import "Shared/Lyrics/Lyrics.h"
#import "Shared/LocalFiles/LocalFiles.h"
#import "Shared/LocalFiles/LocalLyrics.h"
#import "Settings/SGSourcesPage.h"
#import "Settings/SGPageStyle.h"
#import "Headers/SPTPlayer.h"
#import <stdatomic.h>

static const NSTimeInterval kTimeout = 6;
static const NSUInteger kKeptTracks = 40;

// What the switches were called while Musixmatch was the only source; read once, to carry an
// existing install's settings over to the order.
static NSString *const kLegacyMusixmatch = @"spotifyglass.musixmatchLyrics";
static NSString *const kLegacyAllTracks = @"spotifyglass.musixmatchAllTracks";
static NSString *const kLegacyNetEase = @"spotifyglass.neteaseWordTiming";

@implementation SGLyricsLink
@end

@implementation SGLyricsResult
@end

@implementation SGLyricsQuery
@end

@implementation SGLyricsProvider
@end

#pragma mark - the requests the sources share

// Every request any source has lost to the network or to a server too busy to answer, counted so a
// walk can tell "no source has lyrics" from "a source could not say". Only the first is kept.
static _Atomic NSUInteger sg_failures;

BOOL SGLyricsReplyFailed(NSURLResponse *response, NSError *error) {
    NSInteger status = [response isKindOfClass:NSHTTPURLResponse.class] ? ((NSHTTPURLResponse *)response).statusCode : 0;
    return error || status == 429 || status >= 500;
}

void SGLyricsNoteReply(NSURLResponse *response, NSError *error) {
    if (SGLyricsReplyFailed(response, error)) atomic_fetch_add(&sg_failures, 1);
}

NSURL *SGLyricsURL(NSString *base, NSDictionary<NSString *, NSString *> *query) {
    NSURLComponents *url = [NSURLComponents componentsWithString:base];
    NSMutableArray<NSURLQueryItem *> *items = [NSMutableArray array];
    [query enumerateKeysAndObjectsUsingBlock:^(NSString *name, NSString *value, BOOL *stop) {
        [items addObject:[NSURLQueryItem queryItemWithName:name value:value]];
    }];
    url.queryItems = items;
    return url.URL;
}

static NSMutableURLRequest *requestFor(NSURL *url, NSDictionary<NSString *, NSString *> *headers) {
    if (!url) return nil;
    NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url cachePolicy:NSURLRequestReloadIgnoringLocalCacheData timeoutInterval:kTimeout];
    [headers enumerateKeysAndObjectsUsingBlock:^(NSString *name, NSString *value, BOOL *stop) {
        [request setValue:value forHTTPHeaderField:name];
    }];
    return request;
}

// The body whatever the status, and the reply it came with, on the session's own queue so the callers
// below can read it there before they hand the result to the main queue; nil for both when there was none.
static void sendForReply(NSURLRequest *request, void (^done)(NSData *body, NSHTTPURLResponse *response)) {
    if (!request) {
        dispatch_async(dispatch_get_main_queue(), ^{ done(nil, nil); });
        return;
    }
    NSURL *url = request.URL;
    [[NSURLSession.sharedSession dataTaskWithRequest:request completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
        NSHTTPURLResponse *reply = [response isKindOfClass:NSHTTPURLResponse.class] ? (NSHTTPURLResponse *)response : nil;
        SGLyricsNoteReply(response, error);
        if (error || reply.statusCode >= 400) SGLog(@"lyrics: %@ answered %ld, error %@", url.host, (long)reply.statusCode, error);
        done(data, reply);
    }] resume];
}

static void send(NSURLRequest *request, void (^done)(NSData *body)) {
    sendForReply(request, ^(NSData *body, NSHTTPURLResponse *reply) {
        done(reply.statusCode >= 400 ? nil : body);
    });
}

static id jsonIn(NSData *body) {
    return body.length ? [NSJSONSerialization JSONObjectWithData:body options:0 error:nil] : nil;
}

static NSString *textIn(NSData *body) {
    return body.length ? [[NSString alloc] initWithData:body encoding:NSUTF8StringEncoding] : nil;
}

static void onMain(void (^done)(id), id parsed) {
    dispatch_async(dispatch_get_main_queue(), ^{ done(parsed); });
}

void SGLyricsGetJSONThen(NSURL *url, NSDictionary<NSString *, NSString *> *headers, id (^parse)(id root), void (^done)(id parsed)) {
    send(requestFor(url, headers), ^(NSData *body) {
        onMain(done, parse(jsonIn(body)));
    });
}

void SGLyricsGetJSON(NSURL *url, NSDictionary<NSString *, NSString *> *headers, void (^done)(id root)) {
    SGLyricsGetJSONThen(url, headers, ^id(id root) { return root; }, done);
}

void SGLyricsGetJSONReply(NSURL *url, NSDictionary<NSString *, NSString *> *headers, void (^done)(id root, NSHTTPURLResponse *response)) {
    sendForReply(requestFor(url, headers), ^(NSData *body, NSHTTPURLResponse *reply) {
        id root = jsonIn(body);
        dispatch_async(dispatch_get_main_queue(), ^{ done(root, reply); });
    });
}

void SGLyricsGetTextThen(NSURL *url, id (^parse)(NSString *text), void (^done)(id parsed)) {
    send(requestFor(url, nil), ^(NSData *body) {
        onMain(done, parse(textIn(body)));
    });
}

void SGLyricsGetText(NSURL *url, void (^done)(NSString *text)) {
    SGLyricsGetTextThen(url, ^id(NSString *text) { return text; }, done);
}

void SGLyricsPostJSON(NSURL *url, NSDictionary<NSString *, NSString *> *headers, id body, void (^done)(id root)) {
    NSData *written = [NSJSONSerialization isValidJSONObject:body]
        ? [NSJSONSerialization dataWithJSONObject:body options:0 error:nil] : nil;
    NSMutableURLRequest *request = written ? requestFor(url, headers) : nil;
    request.HTTPMethod = @"POST";
    request.HTTPBody = written;
    [request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
    send(request, ^(NSData *answer) {
        onMain(done, jsonIn(answer));
    });
}

// A pause this long between two lines gets a ♪, so Spotify's page does not hold the last one.
static const NSInteger kBreakMs = 3000;

void SGLyricsPageLines(NSArray<SGKaraokeLine *> *lines, NSArray<NSNumber *> **starts, NSArray<NSString *> **texts) {
    NSMutableArray<NSNumber *> *at = [NSMutableArray array];
    NSMutableArray<NSString *> *said = [NSMutableArray array];
    SGKaraokeLine *last = nil;
    for (SGKaraokeLine *line in lines) {
        if (last && line.start - last.end >= kBreakMs) {
            [at addObject:@(last.end)];
            [said addObject:@"♪"];
        }
        NSString *text = SGKaraokeLineText(line);
        // The backing vocals read on the same line on Spotify's own page, which has one row a line.
        if (line.backing) text = [text stringByAppendingFormat:@" %@", SGKaraokeLineText(line.backing)];
        [at addObject:@(line.start)];
        [said addObject:text];
        last = line;
    }
    if (last) {
        [at addObject:@(last.end)];
        [said addObject:@""];
    }
    *starts = at;
    *texts = said;
}

#pragma mark - which sources there are, and in what order

NSArray<SGLyricsProvider *> *SGLyricsAllProviders(void) {
    static NSArray<SGLyricsProvider *> *all;
    static dispatch_once_t once;
    dispatch_once(&once, ^{
        SGLyricsProvider *(^make)(NSString *, NSString *, NSString *, SGLyricsAsk) =
        ^(NSString *key, NSString *name, NSString *detail, SGLyricsAsk ask) {
            SGLyricsProvider *provider = [SGLyricsProvider new];
            provider.key = key;
            provider.name = name;
            provider.detail = detail;
            // A source that matches by Spotify's own track id has everything it needs from the
            // start; the rest wait for the player to name the track before they can search.
            provider.needsName = ![key isEqualToString:@"musixmatch"] && ![key isEqualToString:SGSpicyLyricsKey];
            provider.untimed = [key isEqualToString:@"genius"];
            provider.ask = ask;
            return provider;
        };
        all = @[
            make(@"binilyrics", @"BiniLyrics", @"Apple Music word timing", SGBiniLyricsAsk),
            make(@"musixmatch", @"Musixmatch", @"Spotify's licensed catalog", SGMusixmatchAsk),
            make(@"unison", @"Unison", @"Hand-timed, few tracks", SGUnisonAsk),
            make(@"netease", @"NetEase", @"Word timing, censored", SGNetEaseAsk),
            make(@"lrclib", @"LRCLIB", @"Line timing, open fallback", SGLrcLibAsk),
            make(SGSpicyLyricsKey, @"Spicy Lyrics", @"Community word syncs, your own key", SGSpicyLyricsAsk),
            make(@"qqmusic", @"QQ Music", @"Line timing, Chinese catalog", SGQQMusicAsk),
            make(@"kugou", @"KuGou", @"Word timing, Chinese catalog", SGKuGouAsk),
            make(SGImportedLRCKey, @"Imported LRC", @"Your own .lrc files", SGImportedLRCAsk),
            make(@"genius", @"Genius", @"Untimed, when no other has lyrics", SGGeniusAsk),
        ];
    });
    return all;
}

SGLyricsProvider *SGLyricsProviderFor(NSString *key) {
    for (SGLyricsProvider *provider in SGLyricsAllProviders()) {
        if ([provider.key isEqualToString:key]) return provider;
    }
    return nil;
}

// An install from before the order existed keeps what it had: the sources it was using, in the only
// order there was. Nothing is switched on for it that it had not already asked for.
static NSArray<NSString *> *fromLegacyKeys(void) {
    if (!SGFlag(kLegacyMusixmatch, NO)) return @[];
    NSMutableArray<NSString *> *order = [NSMutableArray arrayWithObject:@"musixmatch"];
    if (SGFlag(kLegacyNetEase, NO)) [order addObject:@"netease"];
    return order;
}

// With nothing stored and nothing to carry over, every source is on: the user's own files first, word
// timing ahead of line timing, the two Chinese catalogs once the rest have missed, and Genius's untimed
// words under everything.
// Spicy Lyrics passes straight on without its key.
static NSArray<NSString *> *defaultOrder(void) {
    return @[SGImportedLRCKey, SGSpicyLyricsKey, @"binilyrics", @"musixmatch", @"unison", @"netease", @"lrclib", @"qqmusic", @"kugou", @"genius"];
}

NSArray<NSString *> *SGLyricsOrder(void) {
    id stored = [NSUserDefaults.standardUserDefaults arrayForKey:SGKeyLyricsProviders];
    NSArray *legacy = fromLegacyKeys();
    NSArray *keys = [stored isKindOfClass:NSArray.class] ? stored : legacy.count ? legacy : defaultOrder();
    NSMutableArray<NSString *> *order = [NSMutableArray array];
    for (id key in keys) {
        if ([key isKindOfClass:NSString.class] && SGLyricsProviderFor(key) && ![order containsObject:key]) [order addObject:key];
    }
    return order;
}

void SGLyricsSetOrder(NSArray<NSString *> *keys) {
    [NSUserDefaults.standardUserDefaults setObject:keys ?: @[] forKey:SGKeyLyricsProviders];
}

// With EeveeSpotify injected, its own lyrics answer Spotify's requests and the mod's stand aside: two
// tweaks holding and answering the same request froze Spotify after launch.
BOOL SGLyricsEnabled(void) {
    return SGLyricsOrder().count > 0 && !SGLyricsStandAsideForEevee();
}

#pragma mark - what is known about the track

// The player knows every track it has played by name, which is what every source but Musixmatch
// searches by. The track is looked up by id rather than compared with the one playing now: a lyrics
// request often lands a beat before the player moves on to its track, and comparing then left the
// query nameless. A track the player has not reported starts with nothing, and the first source
// that matches by id fills the rest in.
SGLyricsQuery *SGLyricsQueryFor(NSString *trackID) {
    SGLyricsQuery *query = [SGLyricsQuery new];
    query.trackID = trackID;
    // A local file is named by its own key: its tags, and the names the user gave it over them.
    NSDictionary *local = SGLocalFileInfo(trackID);
    if (local) {
        query.title = local[@"title"];
        query.artist = local[@"artist"];
        query.album = local[@"album"];
        query.seconds = [local[@"seconds"] integerValue];
        return query;
    }
    SPTPlayerTrack *track = SGKaraokeTrackFor(trackID);
    if (!track) return query;
    query.title = track.trackTitle;
    query.artist = track.artistName;
    NSDictionary<NSString *, NSString *> *metadata = track.metadata;
    // With "every track" on, the metadata hook has just noted Spotify's own verdict and forced has_lyrics on;
    // off, nothing notes it and has_lyrics is Spotify's own.
    id has = metadata[@"has_lyrics"];
    if (has && SGLyricsSpotifyHas(trackID) < 0) SGLyricsNoteSpotifyHas(trackID, [@"true" isEqual:has]);
    id album = metadata[@"album_title"];
    id length = metadata[@"duration"];
    if ([album isKindOfClass:NSString.class]) query.album = album;
    if ([length respondsToSelector:@selector(integerValue)]) query.seconds = [length integerValue] / 1000;
    return query;
}

static void learnFrom(SGLyricsQuery *query, SGLyricsResult *result) {
    if (!query.title.length && result.title.length) query.title = result.title;
    if (!query.artist.length && result.artist.length) query.artist = result.artist;
    if (!query.album.length && result.album.length) query.album = result.album;
    if (query.seconds <= 0 && result.seconds > 0) query.seconds = result.seconds;
}

#pragma mark - the walk

// Main queue only, except sg_missing and sg_credits.
static NSMutableDictionary<NSString *, id> *sg_kept;
static NSMutableDictionary<NSString *, NSMutableArray *> *sg_waiting;
static NSMutableSet<NSString *> *sg_missing;
static NSMutableDictionary<NSString *, NSString *> *sg_credits;
// Spotify's own has_lyrics per track, as its metadata said. The player's metadata is read many
// times a second while a list scrolls, so a value already noted costs one lookup and no write.
static NSMutableDictionary<NSString *, NSNumber *> *sg_spotifyHas;
static const NSUInteger kNotedTracks = 200;

static void setUp(void) {
    static dispatch_once_t once;
    dispatch_once(&once, ^{
        sg_kept = [NSMutableDictionary dictionary];
        sg_waiting = [NSMutableDictionary dictionary];
        sg_missing = [NSMutableSet set];
        sg_credits = [NSMutableDictionary dictionary];
        sg_spotifyHas = [NSMutableDictionary dictionary];
    });
}

// Whether the source's lines are better than what the walk already has: any lines beat none, and
// finer timing beats coarser — words timed beat a line's start, which beats plain text. Read off the
// lines themselves, which say how they were really timed, rather than off what the source claimed.
static BOOL betterLines(SGLyricsResult *merged, SGLyricsResult *fresh) {
    if (!fresh.karaokeLines.count) return NO;
    return !merged.karaokeLines.count || SGKaraokeLinesTiming(fresh.karaokeLines) < SGKaraokeLinesTiming(merged.karaokeLines);
}

static NSString *timingName(NSArray<SGKaraokeLine *> *lines) {
    switch (SGKaraokeLinesTiming(lines)) {
        case SGKaraokeTimingWords: return @"word timed";
        case SGKaraokeTimingLine: return @"line timed";
        default: return @"untimed";
    }
}

// The same for the text Spotify's own page shows: any text beats none, timed beats untimed.
static BOOL betterTexts(SGLyricsResult *merged, SGLyricsResult *fresh) {
    if (!fresh.texts.count) return NO;
    return !merged.texts.count || (fresh.synced && !merged.synced);
}

// How long a lyrics request waits for the player to name its track before the walk starts without a
// name. The request routinely lands a few hundred milliseconds before the player reports the track
// it belongs to, and a walk started in that gap passes over every source that searches by name.
static const NSTimeInterval kNameWait = 1.5, kNamePoll = 0.1;

static BOOL named(SGLyricsQuery *query) {
    return query.title.length && query.artist.length;
}

// The credits that carry links or must show, by their text, as their sources answered. Main queue.
static NSMutableDictionary<NSString *, SGLyricsResult *> *sg_noted;
static const NSUInteger kNotedCredits = 100;

static void noteCredit(SGLyricsResult *result) {
    if (!result.provider.length || !(result.creditRequired || result.creditLinks.count)) return;
    if (!sg_noted) sg_noted = [NSMutableDictionary dictionary];
    if (sg_noted.count >= kNotedCredits) [sg_noted removeAllObjects];
    sg_noted[result.provider] = result;
}

BOOL SGLyricsCreditRequired(NSString *credit) {
    return credit && sg_noted[credit].creditRequired;
}

NSArray<SGLyricsLink *> *SGLyricsCreditLinks(NSString *text) {
    if (!text.length) return nil;
    SGLyricsResult *exact = sg_noted[text];
    if (exact) return exact.creditLinks;
    // The longest credit the text holds, so "Spicy Lyrics, synced by a" is not read as a shorter one.
    SGLyricsResult *found = nil;
    for (NSString *credit in sg_noted) {
        if ([text containsString:credit] && credit.length > found.provider.length) found = sg_noted[credit];
    }
    return found.creditLinks;
}

void SGLyricsOpenCreditLinks(NSArray<SGLyricsLink *> *links, UIView *from) {
    if (!links.count) return;
    if (links.count == 1) {
        [UIApplication.sharedApplication openURL:links.firstObject.url options:@{} completionHandler:nil];
        return;
    }
    UIAlertController *sheet = [UIAlertController alertControllerWithTitle:nil message:nil preferredStyle:UIAlertControllerStyleActionSheet];
    for (SGLyricsLink *link in links) {
        NSURL *url = link.url;
        [sheet addAction:[UIAlertAction actionWithTitle:link.title style:UIAlertActionStyleDefault handler:^(UIAlertAction *action) {
            [UIApplication.sharedApplication openURL:url options:@{} completionHandler:nil];
        }]];
    }
    [sheet addAction:[UIAlertAction actionWithTitle:@"Cancel" style:UIAlertActionStyleCancel handler:nil]];
    sheet.popoverPresentationController.sourceView = from;
    sheet.popoverPresentationController.sourceRect = from.bounds;
    [SGTopController() presentViewController:sheet animated:YES completion:nil];
}

// One walk down the order for one track.
@interface SGLyricsWalk : NSObject
@property (nonatomic, copy) NSArray<NSString *> *order;
@property (nonatomic) NSUInteger index;
@property (nonatomic, strong) SGLyricsQuery *query;
@property (nonatomic, strong) SGLyricsResult *merged;
// Sources that needed a name the query did not have when their turn came.
@property (nonatomic, strong) NSMutableArray<NSString *> *passedOver;
// sg_failures when the walk started. Another walk's failure counts too, which at worst asks again.
@property (nonatomic) NSUInteger failuresAtStart;
// The source picked for the track when the walk started, asked first.
@property (nonatomic, copy) NSString *picked;
// The picked source answered with lines, which are the walk's answer however they are timed.
@property (nonatomic) BOOL pickedAnswered;
@end

@implementation SGLyricsWalk
@end

// Musixmatch's community translations are not waited for here: the lines take them as they are kept
// for the lyrics view (Shared/Lyrics/KaraokeSource.x), whichever source won, Spotify included.
static void finish(SGLyricsWalk *walk) {
    SGLyricsQuery *query = walk.query;
    SGLyricsResult *merged = walk.merged;
    NSString *trackID = query.trackID;
    SGLyricsResult *lyrics = merged.karaokeLines.count || merged.texts.count ? merged : nil;
    // A walk that ends with nothing is only an answer when every source got to search. One that passed a
    // source over for want of a name asked it nothing, and keeping that as "no lyrics" would stick to the
    // track: every later request would get the kept nil, and the lyrics card would be taken off the track
    // for the rest of the session. The same goes for a walk during which a request failed: a busy
    // server's 503 read as "no lyrics" hid a track's lyrics until Spotify was restarted.
    BOOL everyoneAsked = !walk.passedOver.count;
    BOOL failed = atomic_load(&sg_failures) != walk.failuresAtStart;
    id picked = SGLyricsChosenSource(trackID) ? sg_kept[trackID] : nil;
    if (walk.pickedAnswered) {
        SGLyricsKeepChosen(trackID, lyrics);
    } else if ([picked isKindOfClass:SGLyricsResult.class]) {
        // A source was picked from the player's ⋯ while the walk ran: the pick stands, and the walk's answer
        // is what Automatic puts back. Not when the walk began with a pick of its own: that one was asked
        // first and may have answered, so the walk never learned what the order would choose.
        if (!walk.picked) SGLyricsNoteOrderChoice(trackID, lyrics);
        lyrics = picked;
    } else if (lyrics || (everyoneAsked && !failed) || merged.instrumental) {
        // With a pick whose request failed, the walk's answer is kept, but not as the pick's: it weighs
        // against Spotify's own lines as any walk's does, and the next walk asks the pick first again.
        if (sg_kept.count >= kKeptTracks) [sg_kept removeAllObjects];
        sg_kept[trackID] = lyrics ?: NSNull.null;
        if (!lyrics) {
            @synchronized (sg_missing) { [sg_missing addObject:trackID]; }
        }
    }
    SGLog(@"lyrics: %@ ends with %@", trackID, lyrics
          ? [NSString stringWithFormat:@"%lu %@ lines from %@, %lu page lines",
             (unsigned long)lyrics.karaokeLines.count, timingName(lyrics.karaokeLines),
             lyrics.provider, (unsigned long)lyrics.texts.count]
          : everyoneAsked && failed ? @"nothing, a request failed on the way; not kept, so the next request asks again"
          : everyoneAsked ? @"nothing"
          : [NSString stringWithFormat:@"nothing, %@ never knowing its name; not kept, so the next request asks again",
             [walk.passedOver componentsJoinedByString:@", "]]);
    NSArray *waiting = sg_waiting[trackID];
    [sg_waiting removeObjectForKey:trackID];
    for (void (^done)(SGLyricsResult *) in waiting) done(lyrics);
}

// Whether the walk has its answer. walk.merged is the best seen so far: betterLines keeps the finest timed
// lines, the first in the order among equals, so a walk run to the end takes words over a line's start over
// plain text. It stops at the first timed answer, or with Prefer word-by-word timing at the first with words
// timed. A source picked for the track is asked first, and its answer ends the walk in step, as a timed
// imported LRC does.
static BOOL settled(SGLyricsWalk *walk) {
    SGLyricsResult *merged = walk.merged;
    if (!(merged.synced && merged.texts.count && merged.karaokeLines.count)) return NO;
    if (!SGFlag(SGKeyLyricsPreferWordTiming, NO)) return YES;
    return SGKaraokeLinesTiming(merged.karaokeLines) == SGKaraokeTimingWords;
}

static void step(SGLyricsWalk *walk) {
    SGLyricsQuery *query = walk.query;
    SGLyricsResult *merged = walk.merged;
    if (settled(walk)) {
        finish(walk);
        return;
    }
    if (walk.index >= walk.order.count) {
        // A source that matches by id named the track partway down: the ones passed over ask now,
        // in the order they came in. Once, since they cannot be passed over again with a name.
        if (walk.passedOver.count && named(query)) {
            SGLog(@"lyrics: %@ named partway as \"%@\" by \"%@\", asking %@ after all", query.trackID,
                  query.title, query.artist, [walk.passedOver componentsJoinedByString:@", "]);
            walk.order = walk.passedOver;
            walk.index = 0;
            walk.passedOver = [NSMutableArray array];
            step(walk);
            return;
        }
        finish(walk);
        return;
    }
    SGLyricsProvider *provider = SGLyricsProviderFor(walk.order[walk.index++]);
    // Not yet known asks: wrongly passing Genius over would keep "no lyrics" for a track Spotify has none for.
    // The source picked for the track is asked whatever Spotify has: the pick stands timed or not.
    if (provider.untimed && ![provider.key isEqualToString:walk.picked]
        && (merged.karaokeLines.count || merged.texts.count || SGLyricsSpotifyHas(query.trackID) == 1)) {
        step(walk);
        return;
    }
    if (provider.needsName && !named(query)) {
        [walk.passedOver addObject:provider.key];
        step(walk);
        return;
    }
    NSUInteger failures = atomic_load(&sg_failures);
    provider.ask(query, ^(SGLyricsResult *fresh) {
        learnFrom(query, fresh);
        noteCredit(fresh);
        // Instrumental counts as no lines here; a failed request does not, as the server may only be busy.
        if ([provider.key isEqualToString:walk.picked] && !fresh.karaokeLines.count && atomic_load(&sg_failures) == failures) {
            SGLyricsDropChoice(query.trackID, walk.picked);
        }
        if (fresh.instrumental) {
            SGLog(@"lyrics: %@ is instrumental, by %@", query.trackID, provider.key);
            merged.instrumental = YES;
            finish(walk);
            return;
        }
        // The pick stands timed or not, so a timed source lower in the order cannot replace it. A pick made while
        // the walk runs is left to finish, which keeps the order's answer for Automatic.
        BOOL pick = [provider.key isEqualToString:walk.picked] && [walk.picked isEqualToString:SGLyricsChosenSource(query.trackID)];
        // The user's own timed file is the answer too: Prefer word-by-word timing looks past the sources' line timing,
        // not past lyrics the user imported for the song (#111). Below a source as finely timed, the order still wins.
        BOOL imported = fresh.synced && [provider.key isEqualToString:SGImportedLRCKey] && betterLines(merged, fresh);
        if (fresh.karaokeLines.count && (pick || imported)) {
            if (!fresh.provider) fresh.provider = provider.name;
            walk.merged = fresh;
            walk.pickedAnswered = pick;
            finish(walk);
            return;
        }
        if (betterLines(merged, fresh)) {
            merged.karaokeLines = fresh.karaokeLines;
            merged.wordTimed = fresh.wordTimed;
            merged.provider = fresh.provider ?: provider.name;
            if (SGFlag(SGKeyLyricsPreferWordTiming, NO) && SGKaraokeLinesTiming(fresh.karaokeLines) == SGKaraokeTimingLine && walk.index < walk.order.count) {
                SGLog(@"lyrics: %@ line timed by %@, asking on for words timed", query.trackID, merged.provider);
            }
        }
        if (betterTexts(merged, fresh)) {
            merged.starts = fresh.starts;
            merged.texts = fresh.texts;
            merged.synced = fresh.synced;
            if (!merged.provider) merged.provider = fresh.provider ?: provider.name;
            // Spotify's page names the source of its own text, which can be another than the lines'.
            merged.pageProvider = fresh.provider ?: provider.name;
        }
        step(walk);
    });
}

static void startWalk(NSString *trackID, SGLyricsQuery *query) {
    NSMutableArray<NSString *> *order = [SGLyricsOrder() mutableCopy];
    NSString *chosen = SGLyricsChosenSource(trackID);
    if (chosen && [order containsObject:chosen]) {
        [order removeObject:chosen];
        [order insertObject:chosen atIndex:0];
    } else if (chosen) {
        SGLyricsDropChoice(trackID, chosen);
        chosen = nil;
    }
    SGLog(@"lyrics: asking %@ for %@ as \"%@\" by \"%@\", album \"%@\", %lds",
          [order componentsJoinedByString:@", "], trackID, query.title, query.artist, query.album, (long)query.seconds);
    SGLyricsWalk *walk = [SGLyricsWalk new];
    walk.order = order;
    walk.picked = chosen;
    walk.query = query;
    walk.merged = [SGLyricsResult new];
    walk.passedOver = [NSMutableArray array];
    walk.failuresAtStart = atomic_load(&sg_failures);
    step(walk);
}

// Starts the walk as soon as the player has named the track, or once it has waited long enough
// that it is not going to: a track opened for something other than what is playing is never named.
static void whenNamed(NSString *trackID, NSTimeInterval waited) {
    SGLyricsQuery *query = SGLyricsQueryFor(trackID);
    if (named(query) || waited >= kNameWait) {
        if (!named(query)) SGLog(@"lyrics: the player never named %@ in %.1fs", trackID, waited);
        startWalk(trackID, query);
        return;
    }
    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(kNamePoll * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
        whenNamed(trackID, waited + kNamePoll);
    });
}

void SGLyricsFetch(NSString *trackID, void (^done)(SGLyricsResult *result)) {
    setUp();
    dispatch_async(dispatch_get_main_queue(), ^{
        if (!trackID.length) {
            done(nil);
            return;
        }
        id kept = sg_kept[trackID];
        if (kept) {
            done(kept == NSNull.null ? nil : kept);
            return;
        }
        NSMutableArray *waiting = sg_waiting[trackID];
        if (waiting) {
            [waiting addObject:[done copy]];
            return;
        }
        sg_waiting[trackID] = [NSMutableArray arrayWithObject:[done copy]];
        whenNamed(trackID, 0);
    });
}

BOOL SGLyricsMayHave(NSString *trackID) {
    setUp();
    @synchronized (sg_missing) { return ![sg_missing containsObject:trackID]; }
}

void SGLyricsPrefetch(NSString *trackID) {
    if (!trackID.length) return;
    SGLyricsFetch(trackID, ^(SGLyricsResult *result) {});
}

NSInteger SGLyricsSpotifyHas(NSString *trackID) {
    setUp();
    if (!trackID) return -1;
    @synchronized (sg_spotifyHas) {
        NSNumber *has = sg_spotifyHas[trackID];
        return has ? has.integerValue : -1;
    }
}

void SGLyricsNoteSpotifyHas(NSString *trackID, BOOL has) {
    setUp();
    if (!trackID.length) return;
    @synchronized (sg_spotifyHas) {
        NSNumber *noted = sg_spotifyHas[trackID];
        if (noted && noted.boolValue == has) return;
        if (sg_spotifyHas.count >= kNotedTracks) [sg_spotifyHas removeAllObjects];
        sg_spotifyHas[trackID] = @(has);
    }
}

NSString *const SGLyricsOwnRequestKey = @"spotifyglass.ownRequest";

// The cards under the player load together, and the list is shown without any card still loading
// once this many milliseconds have passed (NowPlaying_ScrollImpl's scrollCardsAsyncLoadingTimeoutMs,
// 2 s unless the server says otherwise, 1 s at the least). The lyrics card is one of them and waits
// for the color-lyrics reply, which with a source of the mod's on comes after the chain has answered;
// so the wait is set to the most the flag allows.
id SGLyricsForcedFlag(NSString *key) {
    static BOOL on;
    static dispatch_once_t once;
    dispatch_once(&once, ^{ on = SGLyricsEnabled(); });
    if (!on) return nil;
    if ([key isEqualToString:@"ios-nowplaying-scroll-impl.scroll_cards_async_loading_timeout_ms"]) return @5000;
    return nil;
}

// After an override; no row shows the timeout, so nothing is locked.
__attribute__((constructor)) static void registerForcer(void) {
    SGRegisterFlagForcer(NO, ^id(NSString *key) { return SGLyricsForcedFlag(key); }, nil);
}

#pragma mark - the language of translations

NSArray<NSString *> *SGLyricsTranslationLanguages(void) {
    return @[@"", @"ar", @"zh-Hans", @"zh-Hant", @"cs", @"da", @"nl", @"en", @"fi", @"fr", @"de", @"el", @"he",
             @"hi", @"hu", @"id", @"it", @"ja", @"ko", @"nb", @"pl", @"pt", @"ro", @"ru", @"sk", @"es", @"sv",
             @"th", @"tr", @"uk", @"vi"];
}

NSArray<NSString *> *SGLyricsTranslationLanguageNames(void) {
    NSLocale *english = [NSLocale localeWithLocaleIdentifier:@"en"];
    NSMutableArray<NSString *> *names = [NSMutableArray array];
    for (NSString *tag in SGLyricsTranslationLanguages()) {
        [names addObject:tag.length ? [english localizedStringForLocaleIdentifier:tag] ?: tag : @"Any · iPhone's language"];
    }
    return names;
}

NSString *SGLyricsTranslationLanguage(void) {
    NSArray<NSString *> *tags = SGLyricsTranslationLanguages();
    NSInteger index = SGInt(SGKeyLyricsTranslationLanguage, 0);
    return index > 0 && index < (NSInteger)tags.count ? tags[(NSUInteger)index] : nil;
}

NSString *SGLyricsCreditFor(NSString *trackID) {
    setUp();
    @synchronized (sg_credits) { return trackID ? sg_credits[trackID] : nil; }
}

void SGLyricsSetCredit(NSString *trackID, NSString *name) {
    setUp();
    if (!trackID.length) return;
    @synchronized (sg_credits) {
        if (sg_credits.count >= kKeptTracks) [sg_credits removeAllObjects];
        sg_credits[trackID] = name ?: @"Spotify";
    }
}

// Once, at launch: the keys Musixmatch owned alone become an order, so the Lyrics page opens on what
// the install was already doing rather than on nothing.
void SGLyricsMigrateLegacyKeys(void) {
    NSUserDefaults *defaults = NSUserDefaults.standardUserDefaults;
    if ([defaults objectForKey:SGKeyLyricsProviders]) return;
    NSArray<NSString *> *order = fromLegacyKeys();
    if (!order.count) return;
    SGLyricsSetOrder(order);
    SGSetEnabled(SGKeyLyricsAllTracks, SGFlag(kLegacyAllTracks, NO));
    SGLog(@"lyrics: carried the Musixmatch switches over as %@", [order componentsJoinedByString:@", "]);
}

UIViewController *SGLyricsSourcesPage(void) {
    NSMutableArray<SGSource *> *all = [NSMutableArray array];
    for (SGLyricsProvider *provider in SGLyricsAllProviders()) {
        // The page is made on every open, so a key refused since the last one says so here.
        NSString *detail = [provider.key isEqualToString:SGSpicyLyricsKey] ? SGSpicyLyricsStatus() ?: provider.detail : provider.detail;
        [all addObject:[SGSource sourceWithKey:provider.key name:provider.name detail:detail]];
    }
    NSString *note = SGFlag(SGKeyLyricsPreferWordTiming, NO)
        ? @"Asked top to bottom until one has word timing. Sources get only the track, never your account."
        : @"Asked top to bottom until one has timed lyrics. Sources get only the track, never your account.";
    return SGSourcesPageMake(@"Lyrics sources", note,
                             all, ^NSArray<NSString *> * { return SGLyricsOrder(); }, ^(NSArray<NSString *> *keys) { SGLyricsSetOrder(keys); });
}

#pragma mark - a source picked for a track (LyricsPick.m)

NSUInteger SGLyricsFailures(void) {
    return atomic_load(&sg_failures);
}

// The picked answer stands in for the walk's, so a later request for the track, Spotify's own page's included,
// gets the same lines. A source that times words but has no page text gets the page lines made from its own.
void SGLyricsKeepChosen(NSString *trackID, SGLyricsResult *result) {
    setUp();
    if (!result.texts.count && result.karaokeLines.count) {
        NSArray<NSNumber *> *starts;
        NSArray<NSString *> *texts;
        SGLyricsPageLines(result.karaokeLines, &starts, &texts);
        result.starts = starts;
        result.texts = texts;
        result.synced = SGKaraokeLinesTiming(result.karaokeLines) != SGKaraokeTimingNone;
    }
    noteCredit(result);
    result.picked = YES;
    if (sg_kept.count >= kKeptTracks) [sg_kept removeAllObjects];
    sg_kept[trackID] = result;
    @synchronized (sg_missing) { [sg_missing removeObject:trackID]; }
}

id SGLyricsKeptAnswer(NSString *trackID) {
    setUp();
    return sg_kept[trackID];
}

void SGLyricsRestoreKept(NSString *trackID, id kept) {
    setUp();
    if (kept) sg_kept[trackID] = kept;
    else [sg_kept removeObjectForKey:trackID];
    @synchronized (sg_missing) {
        if (kept == NSNull.null) [sg_missing addObject:trackID];
        else [sg_missing removeObject:trackID];
    }
}