Liquid Glass and Apple Music touches for the Spotify iOS app. A GPL-3.0 fork of spoti.pw 0.21.1.
C
// Lyrics from Musixmatch. It is the catalog Spotify licenses, and for part of it Musixmatch also
// has the time of every word (richsync), which Spotify never sends. The token is an anonymous one
// asked for as Musixmatch's iOS app, so Musixmatch learns the track's id and nothing of the Spotify
// account. It is the one source that matches by Spotify's own track id, so it never has to guess at
// a title, and what it learns about the track is passed to the sources asked after it. A local file has
// no id, so for one the matcher searches by its names and length (q_track, q_artist, q_album, q_duration).
#import "Core/SGCore.h"
#import "LyricsSources.h"
#import "Shared/LocalFiles/LocalFiles.h"
static NSString *const kAPI = @"https://apic-appmobile.musixmatch.com/ws/1.1/";
static NSString *const kAppID = @"mac-ios-v2.0";
static NSString *const kTokenKey = @"spotifyglass.musixmatch.token";
static const NSTimeInterval kTimeout = 5;
// After Musixmatch refused a token, typically with a captcha, it is not asked again for this long.
static const NSTimeInterval kTokenPause = 600;
// A pause this long between two richsync lines gets a ♪ line, so Spotify's page does not hold the last one.
static const NSInteger kBreakMs = 3000;
static const NSUInteger kKeptTracks = 40;
// Main queue only. NSNull is kept for a track Musixmatch has nothing for.
static NSMutableDictionary<NSString *, id> *sg_kept;
static NSMutableDictionary<NSString *, NSMutableArray *> *sg_waiting;
static NSMutableArray<void (^)(NSString *)> *sg_tokenWaiting;
static NSDate *sg_tokenRefused;
// Musixmatch's own id of a track, by Spotify's, as the lyrics call matched it; translations go by it.
static NSMutableDictionary<NSString *, NSString *> *sg_commontracks;
// The community translations, by track and language: those answered, and those still being asked for.
static NSMutableDictionary<NSString *, NSDictionary *> *sg_translations;
static NSMutableDictionary<NSString *, NSMutableArray *> *sg_translationsWaiting;
static void setUp(void) {
static dispatch_once_t once;
dispatch_once(&once, ^{
sg_kept = [NSMutableDictionary dictionary];
sg_waiting = [NSMutableDictionary dictionary];
sg_tokenWaiting = [NSMutableArray array];
sg_commontracks = [NSMutableDictionary dictionary];
sg_translations = [NSMutableDictionary dictionary];
sg_translationsWaiting = [NSMutableDictionary dictionary];
});
}
// Keys contain dots ("track.richsync.get"), so the path is split on slashes.
static id dig(id value, NSString *path) {
for (NSString *key in [path componentsSeparatedByString:@"/"]) {
if (![value isKindOfClass:NSDictionary.class]) return nil;
value = value[key];
}
return value;
}
static BOOL truthy(id value) {
return [value respondsToSelector:@selector(boolValue)] && [value boolValue];
}
static NSInteger intOf(id value) {
return [value respondsToSelector:@selector(integerValue)] ? [value integerValue] : 0;
}
static NSInteger msOf(id seconds) {
return [seconds respondsToSelector:@selector(doubleValue)] ? (NSInteger)llround([seconds doubleValue] * 1000) : 0;
}
static id jsonOf(id text) {
if ([text isKindOfClass:NSString.class]) text = [text dataUsingEncoding:NSUTF8StringEncoding];
return [text isKindOfClass:NSData.class] ? [NSJSONSerialization JSONObjectWithData:text options:0 error:nil] : nil;
}
// token.get answers a request without the app's headers with a captcha.
static NSURLRequest *requestFor(NSString *method, NSDictionary<NSString *, NSString *> *query) {
NSURLComponents *url = [NSURLComponents componentsWithString:[kAPI stringByAppendingString:method]];
NSMutableArray<NSURLQueryItem *> *items = [NSMutableArray arrayWithObjects:
[NSURLQueryItem queryItemWithName:@"format" value:@"json"],
[NSURLQueryItem queryItemWithName:@"app_id" value:kAppID], nil];
[query enumerateKeysAndObjectsUsingBlock:^(NSString *name, NSString *value, BOOL *stop) {
[items addObject:[NSURLQueryItem queryItemWithName:name value:value]];
}];
url.queryItems = items;
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url.URL cachePolicy:NSURLRequestReloadIgnoringLocalCacheData timeoutInterval:kTimeout];
[request setValue:@"application/json" forHTTPHeaderField:@"Accept"];
[request setValue:@"10.1.1" forHTTPHeaderField:@"x-mxm-app-version"];
[request setValue:@"Musixmatch/2025120901 CFNetwork/3860.300.31 Darwin/25.2.0" forHTTPHeaderField:@"X-User-Agent"];
return request;
}
static void call(NSString *method, NSDictionary<NSString *, NSString *> *query, void (^done)(NSDictionary *message)) {
[[NSURLSession.sharedSession dataTaskWithRequest:requestFor(method, query) completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
SGLyricsNoteReply(response, error);
id message = dig(jsonOf(data), @"message");
if (error || !message) SGLog(@"musixmatch: %@ failed: status %ld, error %@", method, (long)[(NSHTTPURLResponse *)response statusCode], error);
dispatch_async(dispatch_get_main_queue(), ^{ done([message isKindOfClass:NSDictionary.class] ? message : nil); });
}] resume];
}
static void withToken(void (^use)(NSString *token)) {
NSString *token = [NSUserDefaults.standardUserDefaults stringForKey:kTokenKey];
if (token.length) {
use(token);
return;
}
if (sg_tokenRefused && -sg_tokenRefused.timeIntervalSinceNow < kTokenPause) {
use(nil);
return;
}
[sg_tokenWaiting addObject:use];
if (sg_tokenWaiting.count > 1) return;
call(@"token.get", @{}, ^(NSDictionary *message) {
id fresh = dig(message, @"body/user_token");
BOOL usable = [fresh isKindOfClass:NSString.class] && [fresh length] && ![fresh isEqualToString:@"UpgradeRequired"];
SGLog(@"musixmatch: token %@ (status %@, hint %@)", usable ? @"received" : @"refused", dig(message, @"header/status_code"), dig(message, @"header/hint"));
if (usable) [NSUserDefaults.standardUserDefaults setObject:fresh forKey:kTokenKey];
else sg_tokenRefused = NSDate.date;
NSArray<void (^)(NSString *)> *waiting = [sg_tokenWaiting copy];
[sg_tokenWaiting removeAllObjects];
for (void (^waiter)(NSString *) in waiting) waiter(usable ? fresh : nil);
});
}
#pragma mark - the three shapes Musixmatch has lyrics in
// [{ "ts": 27.16, "te": 28.25, "x": "I've been tryna call", "l": [{ "c": "I've", "o": 0.03 }, { "c": " ", "o": 0.41 }, …] }]
// o is from the line's start. A space entry ends the word before it; a word can come in more than
// one entry ("Milion", "+", ","), so everything between two spaces is one word.
static SGKaraokeLine *richsyncLine(NSDictionary *entry, NSInteger start, NSInteger end) {
NSMutableArray<SGKaraokePiece *> *pieces = [NSMutableArray array];
id parts = entry[@"l"];
for (NSDictionary *part in [parts isKindOfClass:NSArray.class] ? parts : @[]) {
id text = dig(part, @"c");
if (![text isKindOfClass:NSString.class]) continue;
SGKaraokePiece *piece = [SGKaraokePiece new];
piece.text = [text stringByTrimmingCharactersInSet:NSCharacterSet.whitespaceAndNewlineCharacterSet];
piece.start = start + msOf(part[@"o"]);
[pieces addObject:piece];
}
// An entry has no end of its own: a word is sung until the next one starts, past any space between
// them, and the last until the space after it or the line's end.
NSInteger until = end;
BOOL passed = NO; // a word or a space comes after this entry
for (SGKaraokePiece *piece in pieces.reverseObjectEnumerator) {
if (piece.text.length) piece.end = MAX(until, piece.start);
if (piece.text.length || !passed) until = piece.start;
passed = YES;
}
return SGKaraokePieceLine(pieces, start, end);
}
SGLyricsResult *SGMusixmatchRichsyncResult(id body) {
if (![body isKindOfClass:NSArray.class]) return nil;
NSMutableArray<NSNumber *> *starts = [NSMutableArray array];
NSMutableArray<NSString *> *texts = [NSMutableArray array];
NSMutableArray<SGKaraokeLine *> *karaoke = [NSMutableArray array];
for (NSDictionary *entry in body) {
if (![entry isKindOfClass:NSDictionary.class]) continue;
SGKaraokeLine *line = richsyncLine(entry, msOf(entry[@"ts"]), msOf(entry[@"te"]));
if (!line) continue;
if (karaoke.count && line.start - karaoke.lastObject.end >= kBreakMs) {
[starts addObject:@(karaoke.lastObject.end)];
[texts addObject:@"♪"];
}
id text = entry[@"x"];
[starts addObject:@(line.start)];
[texts addObject:[text isKindOfClass:NSString.class] ? text : SGKaraokeLineText(line)];
[karaoke addObject:line];
}
if (!karaoke.count) return nil;
[starts addObject:@(karaoke.lastObject.end)];
[texts addObject:@""];
SGLyricsResult *lyrics = [SGLyricsResult new];
lyrics.synced = lyrics.wordTimed = YES;
lyrics.starts = starts;
lyrics.texts = texts;
lyrics.karaokeLines = karaoke;
return lyrics;
}
// [{ "text": "Yeah, yeah", "time": { "total": 3.32 } }, …, { "text": "", "time": { "total": 241.15 } }]
// An empty text is a break, and the last one marks the end.
static SGLyricsResult *fromSubtitles(id body) {
if (![body isKindOfClass:NSArray.class] || ![body count]) return nil;
NSMutableArray<NSNumber *> *starts = [NSMutableArray array];
NSMutableArray<NSString *> *texts = [NSMutableArray array];
NSArray *lines = body;
for (NSUInteger i = 0; i < lines.count; i++) {
id text = dig(lines[i], @"text");
BOOL last = i + 1 == lines.count;
if (![text isKindOfClass:NSString.class]) text = @"";
[starts addObject:@(msOf(dig(lines[i], @"time/total")))];
[texts addObject:last ? @"" : ([text length] ? text : @"♪")];
}
SGLyricsResult *lyrics = [SGLyricsResult new];
lyrics.synced = YES;
lyrics.starts = starts;
lyrics.texts = texts;
lyrics.karaokeLines = SGKaraokeEstimatedLines(starts, texts);
return lyrics.karaokeLines ? lyrics : nil;
}
static SGLyricsResult *fromPlain(id body) {
if (![body isKindOfClass:NSString.class] || ![body length]) return nil;
return SGLyricsPlainResult([body componentsSeparatedByString:@"\n"]);
}
// macro.subtitles.get runs the matcher and every lookup in one call; the best shape it has wins.
static SGLyricsResult *fromCalls(NSDictionary *calls) {
if (truthy(dig(calls, @"matcher.track.get/message/body/track/instrumental"))) return nil;
id richsync = dig(calls, @"track.richsync.get/message/body/richsync");
SGLyricsResult *lyrics = nil;
if (richsync && !truthy(dig(richsync, @"restricted"))) lyrics = SGMusixmatchRichsyncResult(jsonOf(dig(richsync, @"richsync_body")));
if (lyrics) return lyrics;
id list = dig(calls, @"track.subtitles.get/message/body/subtitle_list");
id subtitle = [list isKindOfClass:NSArray.class] && [list count] ? dig([list firstObject], @"subtitle") : nil;
if (subtitle && !truthy(dig(subtitle, @"restricted"))) lyrics = fromSubtitles(jsonOf(dig(subtitle, @"subtitle_body")));
if (lyrics) return lyrics;
id plain = dig(calls, @"track.lyrics.get/message/body/lyrics");
return plain && !truthy(dig(plain, @"restricted")) ? fromPlain(dig(plain, @"lyrics_body")) : nil;
}
#pragma mark - asking
static void noteCommontrack(NSString *trackID, id commontrack) {
if ([commontrack respondsToSelector:@selector(stringValue)]) commontrack = [commontrack stringValue];
if (![commontrack isKindOfClass:NSString.class] || ![commontrack length] || [commontrack isEqualToString:@"0"]) return;
if (sg_commontracks.count >= kKeptTracks) [sg_commontracks removeAllObjects];
sg_commontracks[trackID] = commontrack;
}
static void finish(NSString *trackID, SGLyricsResult *lyrics, BOOL answered) {
if (answered) {
if (sg_kept.count >= kKeptTracks) [sg_kept removeAllObjects];
sg_kept[trackID] = lyrics ?: NSNull.null;
}
NSArray *waiting = sg_waiting[trackID];
[sg_waiting removeObjectForKey:trackID];
for (void (^done)(SGLyricsResult *) in waiting) done(lyrics);
}
// What the matcher settled on, kept even when Musixmatch may show no lyrics: the sources asked after
// this one search by name, and this is the best name anyone has.
static SGLyricsResult *withTrack(SGLyricsResult *lyrics, id track) {
if (![track isKindOfClass:NSDictionary.class]) return lyrics;
SGLyricsResult *result = lyrics ?: [SGLyricsResult new];
id title = track[@"track_name"], artist = track[@"artist_name"], album = track[@"album_name"];
if ([title isKindOfClass:NSString.class]) result.title = title;
if ([artist isKindOfClass:NSString.class]) result.artist = artist;
if ([album isKindOfClass:NSString.class]) result.album = album;
result.seconds = intOf(track[@"track_length"]);
result.instrumental = truthy(track[@"instrumental"]);
return result;
}
// `match` is what the matcher goes by: Spotify's id, or a local file's names.
static void ask(NSString *trackID, NSDictionary<NSString *, NSString *> *match, BOOL renewToken) {
withToken(^(NSString *token) {
if (!token) {
finish(trackID, nil, NO);
return;
}
NSMutableDictionary<NSString *, NSString *> *query = [@{
@"usertoken": token,
@"namespace": @"lyrics_richsynched",
@"subtitle_format": @"mxm",
@"optional_calls": @"track.richsync",
@"richsync_compact_type": @"words",
} mutableCopy];
[query addEntriesFromDictionary:match];
call(@"macro.subtitles.get", query, ^(NSDictionary *message) {
NSInteger status = intOf(dig(message, @"header/status_code"));
if (status == 401 && renewToken) {
SGLog(@"musixmatch: token no longer accepted (hint %@), asking for a new one", dig(message, @"header/hint"));
[NSUserDefaults.standardUserDefaults removeObjectForKey:kTokenKey];
ask(trackID, match, NO);
return;
}
id calls = dig(message, @"body/macro_calls");
if (status != 200 || ![calls isKindOfClass:NSDictionary.class]) {
finish(trackID, nil, NO);
return;
}
noteCommontrack(trackID, dig(calls, @"matcher.track.get/message/body/track/commontrack_id"));
SGLyricsResult *lyrics = fromCalls(calls);
SGLog(@"musixmatch: %@ has %@", trackID, !lyrics ? @"no lyrics it may show"
: lyrics.wordTimed ? [NSString stringWithFormat:@"%lu word timed lines", (unsigned long)lyrics.karaokeLines.count]
: lyrics.synced ? [NSString stringWithFormat:@"%lu line timed lines", (unsigned long)lyrics.karaokeLines.count]
: [NSString stringWithFormat:@"%lu untimed lines", (unsigned long)lyrics.texts.count]);
finish(trackID, withTrack(lyrics, dig(calls, @"matcher.track.get/message/body/track")), YES);
});
});
}
// What the matcher goes by: Spotify's id, or for a local file, which has none, its names and length to
// search by. nil when there is nothing to go by.
static NSDictionary<NSString *, NSString *> *matchFor(NSString *trackID, NSString *title, NSString *artist, NSString *album, NSInteger seconds) {
if (!trackID.length) return nil;
if (!SGLocalFileIs(trackID)) return @{@"track_spotify_id": trackID};
if (!title.length) return nil;
NSMutableDictionary<NSString *, NSString *> *match = [NSMutableDictionary dictionaryWithObject:title forKey:@"q_track"];
match[@"q_artist"] = artist;
match[@"q_album"] = album;
if (seconds > 0) match[@"q_duration"] = [NSString stringWithFormat:@"%ld", (long)seconds];
return match;
}
SGLyricsAsk SGMusixmatchAsk = ^(SGLyricsQuery *query, void (^done)(SGLyricsResult *lyrics)) {
setUp();
NSString *trackID = query.trackID;
NSDictionary<NSString *, NSString *> *match = matchFor(trackID, query.title, query.artist, query.album, query.seconds);
if (!match) {
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]];
ask(trackID, match, YES);
};
#pragma mark - translations
// The community's translations of a track's lines, by the line's text as SGMusixmatchLineKey makes it.
// Musixmatch pages them; a page that brings no line not seen yet ends the paging, whatever the API
// does with the page number.
static const NSInteger kTranslationPage = 100, kTranslationPages = 5;
// Musixmatch's codes for the Lyrics page's languages where they differ, tried in turn until one has
// lines. Asked on 5 October 2026: zh-Hans and zh-Hant had no lines where zh (Simplified) and z1
// (Traditional) had, and Norwegian is kept under nb on some tracks and no on others.
static NSArray<NSString *> *codesFor(NSString *language) {
NSDictionary<NSString *, NSArray<NSString *> *> *codes = @{@"zh-Hans": @[@"zh"], @"zh-Hant": @[@"z1"], @"nb": @[@"nb", @"no"]};
return codes[language] ?: @[language];
}
// What a page's status says about the answer: lost on the way or to a busy server is asked again later.
static BOOL lostStatus(NSInteger status) {
return status == 0 || status == 429 || status >= 500;
}
NSString *SGMusixmatchLineKey(NSString *text) {
if (![text isKindOfClass:NSString.class]) return @"";
NSString *folded = [text stringByFoldingWithOptions:NSCaseInsensitiveSearch | NSDiacriticInsensitiveSearch locale:nil];
NSMutableArray<NSString *> *words = [NSMutableArray array];
for (NSString *word in [folded componentsSeparatedByCharactersInSet:NSCharacterSet.alphanumericCharacterSet.invertedSet]) {
if (word.length) [words addObject:word];
}
return [words componentsJoinedByString:@" "];
}
// done gets Musixmatch's status for the paging: 200 once it is over, the first other one where it stopped,
// 0 for a page that never came.
static void translationPage(NSString *token, NSString *commontrack, NSString *code, NSInteger page,
NSMutableDictionary<NSString *, NSString *> *found, void (^done)(NSInteger status)) {
call(@"crowd.track.translations.get", @{
@"usertoken": token, @"commontrack_id": commontrack, @"selected_language": code,
@"comment_format": @"text", @"part": @"user", @"translation_fields_set": @"minimal",
@"page": @(page).stringValue, @"page_size": @(kTranslationPage).stringValue,
}, ^(NSDictionary *message) {
NSInteger status = intOf(dig(message, @"header/status_code"));
if (status != 200) {
done(status);
return;
}
id list = dig(message, @"body/translations_list");
NSUInteger before = found.count;
for (id entry in [list isKindOfClass:NSArray.class] ? list : @[]) {
id snippet = dig(entry, @"translation/snippet"), text = dig(entry, @"translation/description");
if (![snippet isKindOfClass:NSString.class] || ![text isKindOfClass:NSString.class] || ![text length]) continue;
NSString *key = SGMusixmatchLineKey(snippet);
if (key.length && ![text isEqualToString:snippet]) found[key] = text;
}
BOOL more = found.count > before && [list count] >= 20 && page < kTranslationPages;
if (more) translationPage(token, commontrack, code, page + 1, found, done);
else done(200);
});
}
// Each of the language's codes in turn, until one has lines.
static void translationsIn(NSString *token, NSString *commontrack, NSArray<NSString *> *codes,
NSMutableDictionary<NSString *, NSString *> *found, void (^done)(NSInteger status)) {
translationPage(token, commontrack, codes.firstObject, 1, found, ^(NSInteger status) {
if (status == 200 && !found.count && codes.count > 1) {
translationsIn(token, commontrack, [codes subarrayWithRange:NSMakeRange(1, codes.count - 1)], found, done);
return;
}
done(status);
});
}
// done gets what was found, and whether it is Musixmatch's whole answer rather than one cut short.
static void askTranslations(NSString *trackID, NSString *language, BOOL renewToken,
void (^done)(NSDictionary<NSString *, NSString *> *found, BOOL answered)) {
// A local file is matched by the names it goes by, its key's edit over its tags, as its lyrics were.
NSDictionary *local = SGLocalFileInfo(trackID);
NSDictionary<NSString *, NSString *> *match = matchFor(trackID, local[@"title"], local[@"artist"], local[@"album"], [local[@"seconds"] integerValue]);
if (!match) {
done(nil, YES);
return;
}
withToken(^(NSString *token) {
if (!token) {
done(nil, NO);
return;
}
// As ask() does: a token Musixmatch no longer takes is dropped and a new one asked for, once.
void (^ended)(NSInteger, NSDictionary *) = ^(NSInteger status, NSDictionary *found) {
if (status == 401 && renewToken) {
SGLog(@"musixmatch: token no longer accepted for translations, asking for a new one");
[NSUserDefaults.standardUserDefaults removeObjectForKey:kTokenKey];
askTranslations(trackID, language, NO, done);
return;
}
done(found, !lostStatus(status) && status != 401);
};
void (^translate)(NSString *) = ^(NSString *commontrack) {
NSMutableDictionary<NSString *, NSString *> *found = [NSMutableDictionary dictionary];
translationsIn(token, commontrack, codesFor(language), found, ^(NSInteger status) { ended(status, found); });
};
// The lyrics call has usually matched the track already; the matcher is asked only when it has not.
NSString *known = sg_commontracks[trackID];
if (known) {
translate(known);
return;
}
NSMutableDictionary<NSString *, NSString *> *query = [match mutableCopy];
query[@"usertoken"] = token;
call(@"matcher.track.get", query, ^(NSDictionary *message) {
NSInteger status = intOf(dig(message, @"header/status_code"));
noteCommontrack(trackID, dig(message, @"body/track/commontrack_id"));
NSString *commontrack = status == 200 ? sg_commontracks[trackID] : nil;
if (commontrack) translate(commontrack);
else ended(status, nil);
});
});
}
void SGMusixmatchTranslations(NSString *trackID, NSString *language, void (^done)(NSDictionary<NSString *, NSString *> *byLine)) {
setUp();
if (!trackID.length || !language.length) {
done(nil);
return;
}
NSString *memo = [NSString stringWithFormat:@"%@|%@", trackID, language];
NSDictionary *known = sg_translations[memo];
if (known) {
done(known.count ? known : nil);
return;
}
NSMutableArray *waiting = sg_translationsWaiting[memo];
if (waiting) {
[waiting addObject:[done copy]];
return;
}
sg_translationsWaiting[memo] = [NSMutableArray arrayWithObject:[done copy]];
askTranslations(trackID, language, YES, ^(NSDictionary<NSString *, NSString *> *found, BOOL answered) {
// Only a whole answer is kept: a page lost on the way leaves the track to be asked again.
if (answered) {
if (sg_translations.count >= kKeptTracks) [sg_translations removeAllObjects];
sg_translations[memo] = [found copy] ?: @{};
}
SGLog(@"musixmatch: %lu translated lines in %@ for %@%@", (unsigned long)found.count, language, trackID,
answered ? @"" : @", cut short; not kept, so the next lines ask again");
NSArray *waiters = sg_translationsWaiting[memo];
[sg_translationsWaiting removeObjectForKey:memo];
for (void (^waiter)(NSDictionary *) in waiters) waiter(found.count ? found : nil);
});
}
NSArray<SGKaraokeLine *> *SGMusixmatchTranslatedLines(NSArray<SGKaraokeLine *> *lines, NSDictionary<NSString *, NSString *> *byLine) {
NSMutableArray<SGKaraokeLine *> *translated = nil;
for (NSUInteger i = 0; i < lines.count; i++) {
SGKaraokeLine *line = lines[i];
NSString *text = byLine[SGMusixmatchLineKey(SGKaraokeLineText(line))];
if (!text.length || line.translation.length) continue;
if (!translated) translated = [lines mutableCopy];
SGKaraokeLine *copy = [line copy];
copy.translation = text;
translated[i] = copy;
}
return translated;
}