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

feat: Listening stats shows your top tracks, artists and albums over time

My-Name-Is-Jeff2db666e274c6
diff --git a/docs/tweaks.md b/docs/tweaks.md
index 7957013b..44dcb0ac 100644
--- a/docs/tweaks.md
+++ b/docs/tweaks.md
@@ -149,6 +149,13 @@ Shared:
by the attributes' type in LiveActivityShared.swift, compiled into both. It starts only with Spotify
in front; its switch and its view apply at once
+ ListeningStats/ listening stats kept on the phone (ListeningStats.h lists its files): each music track timed while
+ it plays through PlayerState's observer and written to a text log in Application Support once it ran 30 s
+ or half the track (ListeningStats.x), Spotify's data export read in, either shape, loose or zipped, plays
+ already there skipped (SGPlayLog.m), and a page of the top tracks, artists and albums of a week, a month,
+ a year and all time. Tested on the Mac against harness/listening-stats/, the page and the recorder in the
+ simulator against its sim/
+
Native:
Appearance/ AMOLED (Amoled.x), the accent colour (Accent.x), the soft top edge (EdgeEffect.x), and Repaint.x, which
diff --git a/harness/listening-stats/README.md b/harness/listening-stats/README.md
new file mode 100644
index 00000000..74a90125
--- /dev/null
+++ b/harness/listening-stats/README.md
@@ -0,0 +1,30 @@
+# Listening stats harness
+
+`SGPlayLog.m` run on the Mac against synthetic files in both shapes of Spotify's data export
+(`StreamingHistory_music_*.json` and the extended `Streaming_History_Audio_*.json`), loose and inside zips
+made by `/usr/bin/zip` both stored and deflated. Checks podcasts, nulls and plays under 30 s are left out,
+that a play already recorded, the same play in both shapes and a second import of the same files add
+nothing, that the log reads back what it wrote, and that the week, month, year and all-time tops add up.
+It also times parsing, merging, loading and adding up 100k extended rows.
+
+ ./build.sh && build/listening-stats
+
+## The page and the recorder in the simulator (`sim/`)
+
+`ListeningStatsPage.m` on the real Settings/ framework, `ListeningStats.x` through Logos with `sim/stubs.m` standing in
+for PlayerState.x and Spotify's player classes, and the page's picker kept rather than presented (the simulator's
+picker is a remote service), so `pick` hands its delegate a JSON file and a zip as the system would.
+
+ THEOS=$HOME/theos ./build-sim.sh
+ xcrun simctl install <udid> build/sim/ListeningStatsHarness.app
+ xcrun simctl launch <udid> com.vitrine.listeningstatsharness erase seed select=1.0 dump
+ xcrun simctl spawn <udid> log show --last 2m --predicate 'eventMessage CONTAINS "[harness]"' --style compact
+
+2026-10-05, iPhone 17 Pro on iOS 27.0: the page with seeded plays (week 1 h 36 min, month 2 h 12 min, as the seed
+adds up), the Past week and All time pages (a long title wraps), an import of an extended file and a zip holding
+`Spotify Account Data/StreamingHistory_music_0.json` (2 added, 1 skipped; the same again adds 0; the import row reads
+Importing… until the merge, a second tap on it ignored meanwhile), and `record`: a
+31 s play and one of 35 s around a 10 s pause written down (32.5 s and 36.8 s, `dispatch_after` running late), a
+5 s skip left out.
+
+What it does not cover: Spotify's real player reporting, and a real export from Spotify.
diff --git a/harness/listening-stats/build-sim.sh b/harness/listening-stats/build-sim.sh
new file mode 100755
index 00000000..196fe7af
--- /dev/null
+++ b/harness/listening-stats/build-sim.sh
@@ -0,0 +1,42 @@
+#!/bin/sh
+# Builds the listening stats page harness for the simulator: Shared/ListeningStats as it is in the tweak (its .x
+# through Logos), the Settings/ framework, stubs.m for the player.
+set -e
+SRC=$(cd "$(dirname "$0")/../../tweak/Sources" && pwd)
+OUT=$(dirname "$0")/build/sim
+rm -rf "$OUT"; mkdir -p "$OUT/gen" "$OUT/ListeningStatsHarness.app"
+"$THEOS/bin/logos.pl" -c generator=internal "$SRC/Shared/ListeningStats/ListeningStats.x" > "$OUT/gen/ListeningStats.m"
+
+SDK=$(xcrun --sdk iphonesimulator --show-sdk-path)
+xcrun -sdk iphonesimulator clang -target arm64-apple-ios17.0-simulator -fobjc-arc -g -O0 \
+ -I"$SRC" -I"$SRC/Shared/ListeningStats" -isysroot "$SDK" -Wall -Werror -Wno-deprecated-declarations \
+ "$(dirname "$0")/sim/main.m" "$(dirname "$0")/sim/stubs.m" "$(dirname "$0")/../scene.m" "$OUT/gen/ListeningStats.m" \
+ "$SRC"/Shared/ListeningStats/ListeningStatsPage.m "$SRC"/Shared/ListeningStats/SGPlayLog.m \
+ "$SRC"/Settings/SGPage.m "$SRC"/Settings/SGPageStyle.m "$SRC"/Settings/SGModPage.m "$SRC"/Settings/SGGlowSwitch.m \
+ "$SRC"/Core/SGLog.m "$SRC"/Core/SGPrefs.m "$SRC"/Core/SGViewTree.m "$SRC"/Core/SGFlagForce.m "$SRC"/Core/SGUIMode.m \
+ -framework UIKit -framework QuartzCore -framework CoreGraphics -framework Foundation -framework UniformTypeIdentifiers \
+ -o "$OUT/ListeningStatsHarness.app/ListeningStatsHarness"
+
+cat > "$OUT/ListeningStatsHarness.app/Info.plist" <<'PLIST'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>CFBundleExecutable</key><string>ListeningStatsHarness</string>
+<key>CFBundleIdentifier</key><string>com.vitrine.listeningstatsharness</string>
+<key>CFBundleName</key><string>ListeningStatsHarness</string>
+<key>CFBundleVersion</key><string>1</string>
+<key>CFBundleShortVersionString</key><string>1.0</string>
+<key>UIUserInterfaceStyle</key><string>Dark</string>
+<key>UILaunchScreen</key><dict/>
+<key>UIApplicationSceneManifest</key><dict>
+ <key>UIApplicationSupportsMultipleScenes</key><false/>
+ <key>UISceneConfigurations</key><dict>
+ <key>UIWindowSceneSessionRoleApplication</key><array><dict>
+ <key>UISceneConfigurationName</key><string>Default</string>
+ <key>UISceneDelegateClassName</key><string>SGRHarnessScene</string>
+ </dict></array>
+ </dict>
+</dict>
+</dict></plist>
+PLIST
+echo "built $OUT/ListeningStatsHarness.app"
diff --git a/harness/listening-stats/build.sh b/harness/listening-stats/build.sh
new file mode 100755
index 00000000..4c99ae51
--- /dev/null
+++ b/harness/listening-stats/build.sh
@@ -0,0 +1,7 @@
+#!/bin/sh
+# Builds the listening stats harness for the Mac: SGPlayLog.m as the tweak compiles it, and main.m.
+set -e
+cd "$(dirname "$0")"
+mkdir -p build
+xcrun clang -fobjc-arc -O2 -Wall -Werror -I ../../tweak/Sources -framework Foundation \
+ main.m ../../tweak/Sources/Shared/ListeningStats/SGPlayLog.m -o build/listening-stats
diff --git a/harness/listening-stats/main.m b/harness/listening-stats/main.m
new file mode 100644
index 00000000..149cd418
--- /dev/null
+++ b/harness/listening-stats/main.m
@@ -0,0 +1,191 @@
+// Runs SGPlayLog.m on the Mac against synthetic export files, loose and zipped, and checks what the stats
+// page would read out. Exits non-zero when a check fails.
+//
+// ./build.sh && build/listening-stats
+#import <Foundation/Foundation.h>
+#import "Shared/ListeningStats/SGPlayLog.h"
+
+static int failures = 0;
+#define CHECK(cond, ...) do { if (cond) printf("ok "); else { printf("FAIL "); failures++; } printf(__VA_ARGS__); printf("\n"); } while (0)
+
+static NSData *json(id object) {
+ return [NSJSONSerialization dataWithJSONObject:object options:0 error:nil];
+}
+
+static NSString *stamp(int64_t t, BOOL extended) {
+ NSDateFormatter *f = [NSDateFormatter new];
+ f.timeZone = [NSTimeZone timeZoneWithAbbreviation:@"UTC"];
+ f.locale = [NSLocale localeWithLocaleIdentifier:@"en_US_POSIX"];
+ f.dateFormat = extended ? @"yyyy-MM-dd'T'HH:mm:ss'Z'" : @"yyyy-MM-dd HH:mm";
+ return [f stringFromDate:[NSDate dateWithTimeIntervalSince1970:t]];
+}
+
+static NSDictionary *extendedRow(int64_t end, int64_t ms, NSString *title, NSString *artist, NSString *album) {
+ return @{@"ts": stamp(end, YES), @"platform": @"ios", @"ms_played": @(ms), @"conn_country": @"CZ",
+ @"master_metadata_track_name": title ?: (id)NSNull.null, @"master_metadata_album_artist_name": artist ?: (id)NSNull.null,
+ @"master_metadata_album_album_name": album ?: (id)NSNull.null,
+ @"spotify_track_uri": title ? [@"spotify:track:" stringByAppendingString:title] : (id)NSNull.null,
+ @"episode_name": NSNull.null, @"spotify_episode_uri": NSNull.null, @"reason_end": @"trackdone"};
+}
+
+static NSDictionary *basicRow(int64_t end, int64_t ms, NSString *title, NSString *artist) {
+ return @{@"endTime": stamp(end, NO), @"artistName": artist, @"trackName": title, @"msPlayed": @(ms)};
+}
+
+static SGPlay *play(int64_t end, int64_t ms, NSString *title, NSString *artist, NSString *album) {
+ SGPlay *p = [SGPlay new];
+ p.end = end; p.ms = ms; p.title = title; p.artist = artist; p.album = album ?: @""; p.uri = @"";
+ return p;
+}
+
+static void zip(NSString *dir, NSString *out, NSArray<NSString *> *names, BOOL stored) {
+ NSTask *task = [NSTask new];
+ task.executableURL = [NSURL fileURLWithPath:@"/usr/bin/zip"];
+ task.currentDirectoryURL = [NSURL fileURLWithPath:dir];
+ NSMutableArray *args = [NSMutableArray arrayWithObjects:@"-q", stored ? @"-0" : @"-9", out, nil];
+ [args addObjectsFromArray:names];
+ task.arguments = args;
+ [task launchAndReturnError:nil];
+ [task waitUntilExit];
+}
+
+static double since(NSDate *start) {
+ return -start.timeIntervalSinceNow * 1000;
+}
+
+int main(void) {
+ @autoreleasepool {
+ NSString *dir = [NSTemporaryDirectory() stringByAppendingPathComponent:@"listening-stats-harness"];
+ NSString *exportDir = [dir stringByAppendingPathComponent:@"export"];
+ [NSFileManager.defaultManager removeItemAtPath:dir error:nil];
+ [NSFileManager.defaultManager createDirectoryAtPath:[exportDir stringByAppendingPathComponent:@"__MACOSX"] withIntermediateDirectories:YES attributes:nil error:nil];
+
+ // A fixed "now" on a whole minute, so the basic export's minute stamps land exactly.
+ int64_t now = 1790000000 - 1790000000 % 60, day = 86400;
+
+ // Extended: Song A twice and Song B 3 days ago, Song C 20 days ago, Song D 200 days ago, Song A
+ // 2 years ago; then a podcast row (nulls), a 10 s skip and a row without a ts.
+ NSArray *extended = @[
+ extendedRow(now - 3 * day, 200000, @"Song A", @"Artist 1", @"Album X"),
+ extendedRow(now - 3 * day + 300, 180000, @"Song A", @"Artist 1", @"Album X"),
+ extendedRow(now - 3 * day + 600, 60000, @"Song B", @"Artist 2", @"Album Y"),
+ extendedRow(now - 20 * day, 240000, @"Song C", @"Artist 1", @"Album Z"),
+ extendedRow(now - 200 * day, 210000, @"Song D", @"Artist 3", @"Album W"),
+ extendedRow(now - 730 * day, 200000, @"Song A", @"Artist 1", @"Album X"),
+ extendedRow(now - 4 * day, 1800000, nil, nil, nil),
+ extendedRow(now - 4 * day + 100, 10000, @"Song E", @"Artist 4", @"Album V"),
+ @{@"ms_played": @50000, @"ts": NSNull.null},
+ ];
+ NSArray<SGPlay *> *ext = SGPlaysFromExport(json(extended));
+ CHECK(ext.count == 6, "extended: 6 music plays kept of 9 rows (podcast, skip, no ts out): %lu", (unsigned long)ext.count);
+ CHECK(ext.firstObject.end == now - 3 * day, "extended: ts read as UTC to the second");
+ CHECK([ext.firstObject.album isEqualToString:@"Album X"] && [ext.firstObject.uri isEqualToString:@"spotify:track:Song A"],
+ "extended: album and URI read");
+
+ // Basic: the same two Song A plays 20 s later than the extended ts (minute stamps and drift), a play
+ // only the basic file has, a 5 s skip and a podcast-shaped row.
+ NSArray *basic = @[
+ basicRow(now - 3 * day + 20, 200000, @"Song A", @"Artist 1"),
+ basicRow(now - 3 * day + 300 + 20, 180000, @"Song A", @"Artist 1"),
+ basicRow(now - 1 * day, 100000, @"Song F", @"Artist 2"),
+ basicRow(now - 1 * day + 400, 5000, @"Song F", @"Artist 2"),
+ @{@"endTime": stamp(now, NO), @"podcastName": @"Pod", @"episodeName": @"Ep", @"msPlayed": @900000},
+ ];
+ NSArray<SGPlay *> *bas = SGPlaysFromExport(json(basic));
+ CHECK(bas.count == 3, "basic: 3 music plays kept of 5 rows: %lu", (unsigned long)bas.count);
+ CHECK(bas.firstObject.end == now - 3 * day, "basic: endTime read as UTC, to the minute");
+ CHECK(SGPlaysFromExport(json(@[@{@"spotify": @"settings"}])) == nil, "a JSON array that is not an export is refused");
+ CHECK(SGPlaysFromExport(json(@{@"settings": @{}})) == nil, "a JSON object is refused");
+ CHECK(SGPlaysFromExport([@"not json" dataUsingEncoding:NSUTF8StringEncoding]) == nil, "not JSON is refused");
+
+ // Zips as the export arrives, stored and deflated, with a PDF and a __MACOSX twin beside the JSON.
+ [json(extended) writeToFile:[exportDir stringByAppendingPathComponent:@"Streaming_History_Audio_2023.json"] atomically:YES];
+ [json(basic) writeToFile:[exportDir stringByAppendingPathComponent:@"StreamingHistory_music_0.json"] atomically:YES];
+ [@"readme" writeToFile:[exportDir stringByAppendingPathComponent:@"ReadMeFirst.pdf"] atomically:YES encoding:NSUTF8StringEncoding error:nil];
+ [@"junk" writeToFile:[exportDir stringByAppendingPathComponent:@"__MACOSX/._StreamingHistory_music_0.json"] atomically:YES encoding:NSUTF8StringEncoding error:nil];
+ NSArray *names = @[@"Streaming_History_Audio_2023.json", @"StreamingHistory_music_0.json", @"ReadMeFirst.pdf", @"__MACOSX/._StreamingHistory_music_0.json"];
+ for (NSNumber *stored in @[@YES, @NO]) {
+ NSString *path = [dir stringByAppendingPathComponent:stored.boolValue ? @"stored.zip" : @"deflated.zip"];
+ zip(exportDir, path, names, stored.boolValue);
+ NSArray<NSData *> *files = SGJSONFilesInZip([NSData dataWithContentsOfFile:path]);
+ NSUInteger plays = 0;
+ for (NSData *file in files) plays += SGPlaysFromExport(file).count;
+ CHECK(files.count == 2 && plays == 9, "%s zip: 2 JSON files, 9 plays: %lu files, %lu plays",
+ stored.boolValue ? "stored" : "deflated", (unsigned long)files.count, (unsigned long)plays);
+ }
+ CHECK(SGJSONFilesInZip(json(extended)).count == 0, "a file that is not a zip has no files in it");
+ NSData *deflated = [NSData dataWithContentsOfFile:[dir stringByAppendingPathComponent:@"deflated.zip"]];
+ CHECK(SGJSONFilesInZip([deflated subdataWithRange:NSMakeRange(0, deflated.length / 2)]).count == 0, "a cut-off zip reads as empty");
+
+ // The log: Song B recorded on the phone 30 s after the export's, then both files merged, twice.
+ NSString *logPath = [dir stringByAppendingPathComponent:@"Vitrine/plays.tsv"];
+ SGPlayLog *log = [[SGPlayLog alloc] initWithPath:logPath];
+ SGPlay *recorded = play(now - 3 * day + 630, 61000, @"Song B", @"Artist 2", @"Album Y");
+ recorded.uri = @"spotify:track:b";
+ [log record:recorded];
+ NSUInteger added = [log merge:ext];
+ CHECK(added == 5, "merge extended: 5 added, the recorded Song B already there: %lu", (unsigned long)added);
+ added = [log merge:bas];
+ CHECK(added == 1, "merge basic: only Song F is new: %lu", (unsigned long)added);
+ added = [log merge:ext] + [log merge:bas];
+ CHECK(added == 0, "importing the same files again adds nothing: %lu", (unsigned long)added);
+ CHECK([log merge:@[play(now, 40000, @"Tab\there", @"New\nline", @"")]] == 1, "a title with a tab and an artist with a newline merge");
+
+ SGPlayLog *reread = [[SGPlayLog alloc] initWithPath:logPath];
+ CHECK(reread.plays.count == 8, "the log reads back 8 plays: %lu", (unsigned long)reread.plays.count);
+ SGPlay *last = reread.plays.lastObject;
+ CHECK([last.title isEqualToString:@"Tab here"] && [last.artist isEqualToString:@"New line"], "tab and newline become spaces");
+ CHECK([reread.plays.firstObject.uri isEqualToString:@"spotify:track:b"] && reread.plays.firstObject.ms == 61000, "the recorded play round-trips");
+
+ // Periods from the fixed now. Week: Song A x2, Song B, Song F, Tab here. Month adds Song C, year
+ // Song D, all time the old Song A.
+ NSArray *plays = reread.plays;
+ SGStats *week = SGStatsSince(plays, now - 7 * day, 10), *month = SGStatsSince(plays, now - 30 * day, 10);
+ SGStats *year = SGStatsSince(plays, now - 365 * day, 10), *all = SGStatsSince(plays, 0, 10);
+ CHECK(week.plays == 5 && month.plays == 6 && year.plays == 7 && all.plays == 8, "plays per period 5/6/7/8: %lu/%lu/%lu/%lu",
+ (unsigned long)week.plays, (unsigned long)month.plays, (unsigned long)year.plays, (unsigned long)all.plays);
+ CHECK(week.ms == 200000 + 180000 + 61000 + 100000 + 40000, "week: listening time adds up: %lld", week.ms);
+ CHECK([week.tracks.firstObject.name isEqualToString:@"Song A"] && week.tracks.firstObject.plays == 2, "week: Song A tops the tracks with 2 plays");
+ CHECK([week.artists[0].name isEqualToString:@"Artist 1"] && [week.artists[1].name isEqualToString:@"Artist 2"] && week.artists[1].plays == 2,
+ "week: Artists 1 and 2 tie on 2 plays, and the one listened to longer leads");
+ CHECK(all.tracks.firstObject.plays == 3 && [all.tracks.firstObject.name isEqualToString:@"Song A"], "all time: Song A x3");
+ CHECK([all.artists.firstObject.name isEqualToString:@"Artist 1"] && all.artists.firstObject.plays == 4, "all time: Artist 1 x4");
+ CHECK(all.albums.count == 4 && [all.albums.firstObject.name isEqualToString:@"Album X"], "all time: 4 albums (basic plays have none), Album X first");
+ CHECK(SGStatsSince(plays, 0, 2).tracks.count == 2, "a top list is capped");
+
+ CHECK(SGPlayCounts(30, 300) && !SGPlayCounts(29, 300) && SGPlayCounts(20, 40) && !SGPlayCounts(19, 40) && !SGPlayCounts(10, 0),
+ "a play counts past 30 s or half the track");
+
+ // An export's size: 100k extended rows.
+ NSMutableArray *big = [NSMutableArray arrayWithCapacity:100000];
+ for (int i = 0; i < 100000; i++) {
+ [big addObject:extendedRow(now - i * 200, 120000, [NSString stringWithFormat:@"Track %d", i % 3000],
+ [NSString stringWithFormat:@"Artist %d", i % 400], [NSString stringWithFormat:@"Album %d", i % 900])];
+ }
+ NSData *bigData = json(big);
+ NSString *bigPath = [dir stringByAppendingPathComponent:@"big.tsv"];
+ NSDate *start = [NSDate date];
+ NSArray *bigPlays = SGPlaysFromExport(bigData);
+ double parse = since(start);
+ SGPlayLog *bigLog = [[SGPlayLog alloc] initWithPath:bigPath];
+ start = [NSDate date];
+ NSUInteger bigAdded = [bigLog merge:bigPlays];
+ double merge = since(start);
+ start = [NSDate date];
+ NSUInteger again = [bigLog merge:bigPlays];
+ double remerge = since(start);
+ start = [NSDate date];
+ SGPlayLog *bigReread = [[SGPlayLog alloc] initWithPath:bigPath];
+ NSUInteger readBack = bigReread.plays.count;
+ double load = since(start);
+ start = [NSDate date];
+ SGStatsSince(bigReread.plays, 0, 10);
+ double stats = since(start);
+ CHECK(bigAdded == 100000 && again == 0 && readBack == 100000, "100k rows: all added, none twice, all read back");
+ printf(" 100k rows (%.1f MB JSON): parse %.0f ms, merge %.0f ms, merge again %.0f ms, load %.0f ms, add up %.0f ms\n",
+ bigData.length / 1e6, parse, merge, remerge, load, stats);
+
+ printf(failures ? "\n%d FAILED\n" : "\nall passed\n", failures);
+ return failures ? 1 : 0;
+ }
+}
diff --git a/harness/listening-stats/sim/main.m b/harness/listening-stats/sim/main.m
new file mode 100644
index 00000000..43da0034
--- /dev/null
+++ b/harness/listening-stats/sim/main.m
@@ -0,0 +1,223 @@
+// Mod Settings > Listening stats (Shared/ListeningStats) in the simulator: the page on the real Settings/ framework,
+// the recorder of ListeningStats.x fed player states by hand, and an export picked through the page's own picker
+// delegate. The launch line plays actions, one every 0.7 s from 1 s in; screenshot after.
+//
+// THEOS=$HOME/theos ./build-sim.sh && xcrun simctl install <udid> build/sim/ListeningStatsHarness.app
+// xcrun simctl launch <udid> com.vitrine.listeningstatsharness [action...]
+//
+// Actions: erase (the log emptied), seed (a week, a month and a year of plays merged in), record (a track played
+// 31 s, one played 5 s, one paused after 10 s for 10 s and played 25 s more, then playback stopped: takes 82 s, so put it
+// last), pick (an extended export and a zip of a basic one handed to the picker's delegate as if picked),
+// select=<section>.<row> (a tap on a row of the page on top), pop, bottom, dump (the rows each section shows).
+#import <UIKit/UIKit.h>
+#import <objc/runtime.h>
+#import "Core/SGCore.h"
+#import "Settings/SGModPage.h"
+#import "Shared/Player/PlayerState.h"
+#import "Shared/ListeningStats/ListeningStats.h"
+#import "Shared/ListeningStats/SGPlayLog.h"
+
+extern id<SGPlayerStateObserver> SGHarnessObserver;
+
+static void findViews(UIView *root, Class kind, NSMutableArray *found) {
+ if ([root isKindOfClass:kind]) [found addObject:root];
+ for (UIView *sub in root.subviews) findViews(sub, kind, found);
+}
+
+static SGPlay *play(int64_t end, int64_t ms, NSString *title, NSString *artist, NSString *album) {
+ SGPlay *p = [SGPlay new];
+ p.end = end; p.ms = ms; p.title = title; p.artist = artist; p.album = album; p.uri = @"";
+ return p;
+}
+
+static SPTPlayerState *state(NSString *uri, NSString *title, NSString *artist, double duration, BOOL playing) {
+ SPTPlayerTrack *track = [SPTPlayerTrack new];
+ [track setValue:uri forKey:@"URI"];
+ [track setValue:title forKey:@"trackTitle"];
+ [track setValue:artist forKey:@"artistName"];
+ [track setValue:@{@"artist_name": artist ?: @"", @"album_title": @"Harness Album"} forKey:@"metadata"];
+ SPTPlayerState *s = [SPTPlayerState new];
+ [s setValue:track forKey:@"track"];
+ [s setValue:@(playing) forKey:@"isPlaying"];
+ [s setValue:@(!playing) forKey:@"isPaused"];
+ [s setValue:@(duration) forKey:@"duration"];
+ return s;
+}
+
+// The simulator's picker is a remote service that may never appear, so the page's picker is kept rather than
+// presented, and pick hands its delegate the files.
+static UIDocumentPickerViewController *SGHarnessPicker;
+
+@implementation UIViewController (Harness)
+- (void)harness_present:(UIViewController *)page animated:(BOOL)animated completion:(void (^)(void))completion {
+ if ([page isKindOfClass:UIDocumentPickerViewController.class]) SGHarnessPicker = (UIDocumentPickerViewController *)page;
+ else [self harness_present:page animated:animated completion:completion];
+}
+@end
+
+@interface AppDelegate : UIResponder <UIApplicationDelegate>
+@property (nonatomic, strong) UIWindow *window;
+@property (nonatomic, strong) UINavigationController *nav;
+@end
+
+@implementation AppDelegate
+
+- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)options {
+ NSArray<NSString *> *args = NSProcessInfo.processInfo.arguments;
+ method_exchangeImplementations(class_getInstanceMethod(UIViewController.class, @selector(presentViewController:animated:completion:)),
+ class_getInstanceMethod(UIViewController.class, @selector(harness_present:animated:completion:)));
+ self.window = [[UIWindow alloc] initWithFrame:UIScreen.mainScreen.bounds];
+ self.window.overrideUserInterfaceStyle = UIUserInterfaceStyleDark;
+ NSArray<NSString *> *actions = [args subarrayWithRange:NSMakeRange(1, args.count - 1)];
+ // erase and seed go before the page is built, so it opens on them.
+ for (NSString *action in actions) if ([@[@"erase", @"seed"] containsObject:action]) [self run:action];
+ self.nav = [[UINavigationController alloc] initWithRootViewController:SGListeningStatsPage()];
+ self.window.rootViewController = self.nav;
+ [self.window makeKeyAndVisible];
+ __block NSUInteger i = 0;
+ for (NSString *action in actions) {
+ if ([@[@"erase", @"seed"] containsObject:action]) continue;
+ dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)((1 + 0.7 * i++) * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
+ NSLog(@"[harness] %@", action);
+ [self run:action];
+ });
+ }
+ return YES;
+}
+
+- (UITableView *)table {
+ return ((UITableViewController *)self.nav.topViewController).tableView;
+}
+
+// Each step of the script after the one before, in seconds from now.
+- (void)after:(double)seconds do:(void (^)(void))block {
+ dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(seconds * NSEC_PER_SEC)), dispatch_get_main_queue(), block);
+}
+
+- (void)record {
+ id<SGPlayerStateObserver> o = SGHarnessObserver;
+ NSUInteger before = SGListeningLog().plays.count;
+ [o playerStateDidChange:state(@"spotify:track:long", @"Played Long", @"Recorder", 200, YES)];
+ [self after:31 do:^{ [o playerStateDidChange:state(@"spotify:track:skip", @"Skipped", @"Recorder", 200, YES)]; }];
+ [self after:36 do:^{ [o playerStateDidChange:state(@"spotify:track:paused", @"Paused Between", @"Recorder", 200, YES)]; }];
+ [self after:46 do:^{ [o playerStateDidChange:state(@"spotify:track:paused", @"Paused Between", @"Recorder", 200, NO)]; }];
+ [self after:56 do:^{ [o playerStateDidChange:state(@"spotify:track:paused", @"Paused Between", @"Recorder", 200, YES)]; }];
+ [self after:81 do:^{ [o playerStateDidChange:state(nil, nil, nil, 0, NO)]; }];
+ [self after:82 do:^{
+ NSArray<SGPlay *> *plays = SGListeningLog().plays;
+ NSLog(@"[harness] record: %lu new plays (expected 2: Played Long about 31 s, Paused Between about 35 s; timers run late by up to a few percent)", (unsigned long)(plays.count - before));
+ for (SGPlay *p in [plays subarrayWithRange:NSMakeRange(before, plays.count - before)]) {
+ NSLog(@"[harness] recorded %@ / %@ / %@ / %@, %lld ms", p.uri, p.title, p.artist, p.album, p.ms);
+ }
+ [self.table reloadData];
+ }];
+}
+
+// An extended export and a zip holding a basic one with one play the extended has and one it has not.
+- (void)pick {
+ NSString *dir = NSTemporaryDirectory();
+ int64_t now = time(NULL);
+ NSDateFormatter *f = [NSDateFormatter new];
+ f.timeZone = [NSTimeZone timeZoneWithAbbreviation:@"UTC"];
+ f.locale = [NSLocale localeWithLocaleIdentifier:@"en_US_POSIX"];
+ f.dateFormat = @"yyyy-MM-dd'T'HH:mm:ss'Z'";
+ NSString *ts = [f stringFromDate:[NSDate dateWithTimeIntervalSince1970:now - 3600]];
+ NSArray *extended = @[@{@"ts": ts, @"ms_played": @180000, @"master_metadata_track_name": @"Imported Song",
+ @"master_metadata_album_artist_name": @"Exporter", @"master_metadata_album_album_name": @"Export Album",
+ @"spotify_track_uri": @"spotify:track:imported"}];
+ NSURL *json = [NSURL fileURLWithPath:[dir stringByAppendingPathComponent:@"Streaming_History_Audio_2026.json"]];
+ [[NSJSONSerialization dataWithJSONObject:extended options:0 error:nil] writeToURL:json atomically:YES];
+ // A stored zip of one file, written by hand: the simulator has no zip tool to run.
+ f.dateFormat = @"yyyy-MM-dd HH:mm";
+ NSArray *basic = @[@{@"endTime": [f stringFromDate:[NSDate dateWithTimeIntervalSince1970:now - 3600]], @"artistName": @"Exporter",
+ @"trackName": @"Imported Song", @"msPlayed": @180000},
+ @{@"endTime": [f stringFromDate:[NSDate dateWithTimeIntervalSince1970:now - 7200]], @"artistName": @"Exporter",
+ @"trackName": @"Only In Basic", @"msPlayed": @90000}];
+ NSData *body = [NSJSONSerialization dataWithJSONObject:basic options:0 error:nil];
+ NSData *name = [@"Spotify Account Data/StreamingHistory_music_0.json" dataUsingEncoding:NSUTF8StringEncoding];
+ uint32_t crc = 0; // not checked by the reader
+ NSMutableData *zip = [NSMutableData data];
+ void (^u16)(uint32_t) = ^(uint32_t v) { uint16_t x = (uint16_t)v; [zip appendBytes:&x length:2]; };
+ void (^u32)(uint32_t) = ^(uint32_t v) { [zip appendBytes:&v length:4]; };
+ u32(0x04034b50); u16(10); u16(0); u16(0); u16(0); u16(0); u32(crc); u32((uint32_t)body.length); u32((uint32_t)body.length);
+ u16((uint32_t)name.length); u16(0); [zip appendData:name]; [zip appendData:body];
+ uint32_t central = (uint32_t)zip.length;
+ u32(0x02014b50); u16(20); u16(10); u16(0); u16(0); u16(0); u16(0); u32(crc); u32((uint32_t)body.length); u32((uint32_t)body.length);
+ u16((uint32_t)name.length); u16(0); u16(0); u16(0); u16(0); u32(0); u32(0); [zip appendData:name];
+ uint32_t centralSize = (uint32_t)zip.length - central;
+ u32(0x06054b50); u16(0); u16(0); u16(1); u16(1); u32(centralSize); u32(central); u16(0);
+ NSURL *zipURL = [NSURL fileURLWithPath:[dir stringByAppendingPathComponent:@"my_spotify_data.zip"]];
+ [zip writeToURL:zipURL atomically:YES];
+
+ // The import row presents the picker; it is handed the files the way the system would.
+ UIDocumentPickerViewController *picker = SGHarnessPicker;
+ NSLog(@"[harness] presented %@, multiple %d", NSStringFromClass(picker.class), picker.allowsMultipleSelection);
+ [picker.delegate documentPicker:picker didPickDocumentsAtURLs:@[json, zipURL]];
+ // The import row while the files are read, before the merge comes back, and the guard against a second pick.
+ UITableView *table = self.table;
+ UITableViewCell *row = [table.dataSource tableView:table cellForRowAtIndexPath:[NSIndexPath indexPathForRow:1 inSection:2]];
+ SGHarnessPicker = nil;
+ [table.delegate tableView:table didSelectRowAtIndexPath:[NSIndexPath indexPathForRow:1 inSection:2]];
+ NSLog(@"[harness] importing: the row reads \"%@\", a second tap %@", [(UILabel *)row.accessoryView text],
+ SGHarnessPicker ? @"opens the picker again" : @"is ignored");
+ [self after:1.5 do:^{
+ UITableViewCell *after = [table.dataSource tableView:table cellForRowAtIndexPath:[NSIndexPath indexPathForRow:1 inSection:2]];
+ NSLog(@"[harness] imported: the row reads \"%@\"", [(UILabel *)after.accessoryView text]);
+ }];
+ [self after:2 do:^{
+ UIAlertController *alert = (UIAlertController *)self.nav.presentedViewController;
+ NSLog(@"[harness] import says \"%@\": %@", alert.title, alert.message);
+ }];
+}
+
+- (void)run:(NSString *)action {
+ NSArray<NSString *> *parts = [action componentsSeparatedByString:@"="];
+ NSString *verb = parts.firstObject, *value = parts.count > 1 ? parts[1] : @"";
+ UITableView *table = self.table;
+ if ([verb isEqualToString:@"erase"]) {
+ [SGListeningLog() erase];
+ } else if ([verb isEqualToString:@"seed"]) {
+ int64_t now = time(NULL), day = 86400;
+ NSMutableArray *plays = [NSMutableArray array];
+ for (int i = 0; i < 12; i++) [plays addObject:play(now - day - i * 400, 210000, @"Midnight City", @"M83", @"Hurry Up, We're Dreaming")];
+ for (int i = 0; i < 7; i++) [plays addObject:play(now - 2 * day - i * 400, 250000, @"Windowlicker", @"Aphex Twin", @"Windowlicker")];
+ for (int i = 0; i < 5; i++) [plays addObject:play(now - 3 * day - i * 400, 300000, @"Teardrop", @"Massive Attack", @"Mezzanine")];
+ for (int i = 0; i < 9; i++) [plays addObject:play(now - 20 * day - i * 400, 240000, @"Angel", @"Massive Attack", @"Mezzanine")];
+ for (int i = 0; i < 30; i++) [plays addObject:play(now - 200 * day - i * 400, 200000, @"Xtal", @"Aphex Twin", @"Selected Ambient Works 85-92")];
+ [plays addObject:play(now - 500 * day, 3600000, @"A Very Long Title That Will Not Fit On One Line Of The Row", @"Someone With A Long Name", @"")];
+ NSLog(@"[harness] seeded %lu", (unsigned long)[SGListeningLog() merge:plays]);
+ } else if ([verb isEqualToString:@"record"]) {
+ [self record];
+ } else if ([verb isEqualToString:@"pick"]) {
+ [self pick];
+ } else if ([verb isEqualToString:@"select"]) {
+ NSArray<NSString *> *at = [value componentsSeparatedByString:@"."];
+ [table.delegate tableView:table didSelectRowAtIndexPath:[NSIndexPath indexPathForRow:at[1].integerValue inSection:at[0].integerValue]];
+ } else if ([verb isEqualToString:@"pop"]) {
+ [self.nav popViewControllerAnimated:YES];
+ } else if ([verb isEqualToString:@"bottom"]) {
+ CGFloat max = MAX(-table.adjustedContentInset.top, table.contentSize.height - table.bounds.size.height + table.adjustedContentInset.bottom);
+ [table setContentOffset:CGPointMake(0, max) animated:NO];
+ } else if ([verb isEqualToString:@"dump"]) {
+ for (NSInteger section = 0; section < table.numberOfSections; section++) {
+ NSMutableArray<NSString *> *rows = [NSMutableArray array];
+ for (NSInteger row = 0; row < [table numberOfRowsInSection:section]; row++) {
+ UITableViewCell *cell = [table.dataSource tableView:table cellForRowAtIndexPath:[NSIndexPath indexPathForRow:row inSection:section]];
+ NSMutableArray<UILabel *> *labels = [NSMutableArray array];
+ findViews(cell, UILabel.class, labels);
+ NSMutableArray<NSString *> *texts = [NSMutableArray array];
+ for (UILabel *label in labels) if (label.text.length) [texts addObject:label.text];
+ [rows addObject:[texts componentsJoinedByString:@" | "]];
+ }
+ NSLog(@"[harness] section %ld: %@", (long)section, [rows componentsJoinedByString:@", "]);
+ }
+ }
+}
+
+@end
+
+int main(int argc, char *argv[]) {
+ @autoreleasepool {
+ return UIApplicationMain(argc, argv, nil, NSStringFromClass(AppDelegate.class));
+ }
+}
diff --git a/harness/listening-stats/sim/stubs.m b/harness/listening-stats/sim/stubs.m
new file mode 100644
index 00000000..dc7da41a
--- /dev/null
+++ b/harness/listening-stats/sim/stubs.m
@@ -0,0 +1,23 @@
+// What ListeningStats.x takes from Shared/Player/PlayerState.x and Spotify: the observer is kept so main.m can
+// report states to it, and the player's classes are plain objects main.m fills through KVC.
+#import "Core/SGCore.h"
+#import "Shared/Player/PlayerState.h"
+
+@implementation SPTPlayerTrack
+@end
+
+@implementation SPTPlayerState
+@end
+
+@implementation SPTPlayerOptions
+@end
+
+id<SGPlayerStateObserver> SGHarnessObserver;
+
+void SGAddPlayerStateObserver(id<SGPlayerStateObserver> observer) {
+ SGHarnessObserver = observer;
+}
+
+NSString *SGURIString(id uri) {
+ return [uri isKindOfClass:NSString.class] ? uri : nil;
+}
diff --git a/tweak/Sources/App/ModSettings.x b/tweak/Sources/App/ModSettings.x
index 84518cbd..23a98731 100644
--- a/tweak/Sources/App/ModSettings.x
+++ b/tweak/Sources/App/ModSettings.x
@@ -21,6 +21,7 @@
#import "Shared/Flags/Flags.h"
#import "Shared/AudioEffects/AudioEffectsPage.h"
#import "Shared/LiveActivity/LiveActivity.h"
+#import "Shared/ListeningStats/ListeningStats.h"
#import "App/About/About.h"
#import "Redesigned/Album/Album.h"
#import "Pages.h"
@@ -57,6 +58,7 @@ static UIViewController *modSettingsPage(void) {
liveActivity.value = ^NSString *{ return SGLiveActivitySummary(); };
[parts addObject:liveActivity];
}
+ [parts addObject:pageRow(@"Listening stats", @"chart.bar", ^UIViewController *{ return SGListeningStatsPage(); })];
if (!SGRedesignedUIStored()) [parts addObject:pageRow(@"Home & Library", @"house", ^UIViewController *{ return SGHomeSettingsPage(); })];
else [parts addObject:pageRow(@"Albums & artists", @"square.stack", ^UIViewController *{ return SGRAlbumSettingsPage(); })];
[sections addObjectsFromArray:@[
diff --git a/tweak/Sources/Shared/ListeningStats/ListeningStats.h b/tweak/Sources/Shared/ListeningStats/ListeningStats.h
new file mode 100644
index 00000000..b238e508
--- /dev/null
+++ b/tweak/Sources/Shared/ListeningStats/ListeningStats.h
@@ -0,0 +1,19 @@
+// Listening stats (Mod Settings > Listening stats), under either look: plays counted on the phone as they
+// happen, Spotify's own data export merged in, and the top tracks, artists and albums of a week, a month,
+// a year and all time.
+//
+// SGPlayLog.m the log, the export's parsers and the adding up; the Mac harness runs it
+// ListeningStats.x the player watched, a play written down once it counts
+// ListeningStatsPage.m the page, and the export picked and imported
+//
+// Nothing leaves the phone: the log is a file in Application Support, out of the settings backup.
+// Threading: main thread only.
+#import <UIKit/UIKit.h>
+
+@class SGPlayLog;
+
+// Plays are written down unless this is switched off; it applies at once.
+#define SGKeyListeningStats @"spotifyglass.stats.record"
+
+SGPlayLog *SGListeningLog(void);
+UIViewController *SGListeningStatsPage(void);
diff --git a/tweak/Sources/Shared/ListeningStats/ListeningStats.x b/tweak/Sources/Shared/ListeningStats/ListeningStats.x
new file mode 100644
index 00000000..a3459aa1
--- /dev/null
+++ b/tweak/Sources/Shared/ListeningStats/ListeningStats.x
@@ -0,0 +1,90 @@
+// ListeningStats.h says what Listening stats is. This is the recording: PlayerState's observer is told
+// when the track or playing changes, never the position, so a play's length is the wall-clock time it
+// spent playing, and it is written down when the next track takes over.
+//
+// ponytail: a track on repeat one never changes the state's track, so its replays are not counted, and a
+// play cut off by Spotify being killed is lost; position polling would catch both.
+#import "Core/SGCore.h"
+#import "Shared/Player/PlayerState.h"
+#import "ListeningStats.h"
+#import "SGPlayLog.h"
+
+SGPlayLog *SGListeningLog(void) {
+ static SGPlayLog *log;
+ if (!log) {
+ NSString *support = NSSearchPathForDirectoriesInDomains(NSApplicationSupportDirectory, NSUserDomainMask, YES).firstObject;
+ log = [[SGPlayLog alloc] initWithPath:[support stringByAppendingPathComponent:@"Vitrine/Listening.tsv"]];
+ }
+ return log;
+}
+
+static NSString *stringIn(id value) {
+ return [value isKindOfClass:NSString.class] ? value : nil;
+}
+
+@interface SGPlayRecorder : NSObject <SGPlayerStateObserver>
+@end
+
+@implementation SGPlayRecorder {
+ SGPlay *_play;
+ double _duration, _listened;
+ CFAbsoluteTime _since; // when it started playing, 0 while it is not
+}
+
+// Songs and local files; not ads, episodes or the silence between.
+static BOOL isMusic(NSString *uri) {
+ return [uri hasPrefix:@"spotify:track:"] || [uri hasPrefix:@"spotify:local:"];
+}
+
+// The metadata can come after the track does, so what is missing is filled in on every report.
+- (void)fill:(SPTPlayerState *)state {
+ SPTPlayerTrack *track = state.track;
+ NSDictionary *metadata = [track respondsToSelector:@selector(metadata)] ? track.metadata : nil;
+ if (!_play.title.length) _play.title = stringIn(track.trackTitle) ?: stringIn(metadata[@"title"]) ?: @"";
+ if (!_play.artist.length) _play.artist = stringIn(metadata[@"artist_name"]) ?: stringIn(track.artistName) ?: @"";
+ if (!_play.album.length) _play.album = stringIn(metadata[@"album_title"]) ?: @"";
+ if (_duration <= 0) _duration = state.duration;
+}
+
+- (void)finish {
+ if (_play && _play.title.length && _play.artist.length && SGPlayCounts(_listened, _duration) && SGEnabled(SGKeyListeningStats)) {
+ _play.end = (int64_t)time(NULL);
+ _play.ms = (int64_t)(_listened * 1000);
+ [SGListeningLog() record:_play];
+ }
+ _play = nil;
+}
+
+- (void)playerStateDidChange:(SPTPlayerState *)state {
+ CFAbsoluteTime now = CFAbsoluteTimeGetCurrent();
+ if (_since) _listened += now - _since;
+ _since = 0;
+ NSString *uri = SGURIString(state.track.URI);
+ if (![uri isEqualToString:_play.uri]) {
+ [self finish];
+ if (isMusic(uri)) {
+ _play = [SGPlay new];
+ _play.uri = uri;
+ _duration = _listened = 0;
+ }
+ }
+ if (!_play) return;
+ [self fill:state];
+ BOOL loading = [state respondsToSelector:@selector(isLoading)] && state.isLoading;
+ if (state.isPlaying && !state.isPaused && !loading) _since = now;
+}
+
+- (void)terminate {
+ if (_since) _listened += CFAbsoluteTimeGetCurrent() - _since;
+ _since = 0;
+ [self finish];
+}
+
+@end
+
+%ctor {
+ static SGPlayRecorder *recorder;
+ recorder = [SGPlayRecorder new];
+ SGAddPlayerStateObserver(recorder);
+ [NSNotificationCenter.defaultCenter addObserver:recorder selector:@selector(terminate) name:UIApplicationWillTerminateNotification object:nil];
+}
diff --git a/tweak/Sources/Shared/ListeningStats/ListeningStatsPage.m b/tweak/Sources/Shared/ListeningStats/ListeningStatsPage.m
new file mode 100644
index 00000000..872e9a10
--- /dev/null
+++ b/tweak/Sources/Shared/ListeningStats/ListeningStatsPage.m
@@ -0,0 +1,168 @@
+// ListeningStats.h says what Listening stats is. This is its page: the switch, a row per period opening
+// its tops, the export picked and merged in, and the log erased. Built from SGModPage's rows, so it looks
+// the same under either look.
+#import <UniformTypeIdentifiers/UniformTypeIdentifiers.h>
+#import "Core/SGCore.h"
+#import "Settings/SGModPage.h"
+#import "Settings/SGPageStyle.h"
+#import "ListeningStats.h"
+#import "SGPlayLog.h"
+
+static const int64_t kDay = 86400;
+
+static NSString *duration(int64_t ms) {
+ int64_t minutes = ms / 60000;
+ if (minutes < 60) return [NSString stringWithFormat:@"%lld min", minutes];
+ return [NSString stringWithFormat:@"%lld h %lld min", minutes / 60, minutes % 60];
+}
+
+static NSString *playsText(NSUInteger plays) {
+ return [NSString stringWithFormat:plays == 1 ? @"%lu play" : @"%lu plays", (unsigned long)plays];
+}
+
+static void showAlert(NSString *title, NSString *message) {
+ UIAlertController *alert = [UIAlertController alertControllerWithTitle:title message:message preferredStyle:UIAlertControllerStyleAlert];
+ [alert addAction:[UIAlertAction actionWithTitle:@"OK" style:UIAlertActionStyleCancel handler:nil]];
+ [SGTopController() presentViewController:alert animated:YES completion:nil];
+}
+
+static SGModSection *topSection(NSString *title, NSArray<SGStatEntry *> *entries) {
+ NSMutableArray<SGModRow *> *rows = [NSMutableArray array];
+ [entries enumerateObjectsUsingBlock:^(SGStatEntry *entry, NSUInteger i, BOOL *stop) {
+ NSString *plays = playsText(entry.plays);
+ SGModRow *row = SGStatRow([NSString stringWithFormat:@"%lu. %@", (unsigned long)i + 1, entry.name], ^NSString *{ return plays; });
+ row.subtitle = entry.detail;
+ [rows addObject:row];
+ }];
+ if (!rows.count) [rows addObject:SGStatRow(@"Nothing yet", nil)];
+ return SGSection(title, rows);
+}
+
+// Added up once, as the page opens: the rows hand back what was worked out then.
+static UIViewController *periodPage(NSString *title, int64_t since) {
+ SGStats *stats = SGStatsSince(SGListeningLog().plays, since, 25);
+ NSString *time = duration(stats.ms), *plays = playsText(stats.plays);
+ return [[SGModPage alloc] initWithTitle:title intro:nil sections:@[
+ SGSection(nil, @[
+ SGStatRow(@"Listening time", ^NSString *{ return time; }),
+ SGStatRow(@"Plays", ^NSString *{ return plays; }),
+ ]),
+ topSection(@"Top tracks", stats.tracks),
+ topSection(@"Top artists", stats.artists),
+ topSection(@"Top albums", stats.albums),
+ ] footer:nil];
+}
+
+// The period rows' values are asked each time the page appears, so they sum without the tops.
+static int64_t msSince(int64_t since) {
+ int64_t ms = 0;
+ for (SGPlay *play in SGListeningLog().plays) if (play.end >= since) ms += play.ms;
+ return ms;
+}
+
+#pragma mark - import
+
+// From the pick until the plays are merged: the import row reads Importing… and takes no second pick.
+static BOOL sg_importing;
+
+@interface SGExportPicker : NSObject <UIDocumentPickerDelegate>
+@property (nonatomic, weak) UITableViewController *page;
+@end
+
+@implementation SGExportPicker
+
+// The export runs to tens of megabytes, so it is unzipped and parsed off the main thread; the log is
+// the main thread's, so the merge comes back to it.
+- (void)documentPicker:(UIDocumentPickerViewController *)picker didPickDocumentsAtURLs:(NSArray<NSURL *> *)urls {
+ UITableViewController *page = self.page;
+ sg_importing = YES;
+ [page.tableView reloadData];
+ UIAccessibilityPostNotification(UIAccessibilityAnnouncementNotification, @"Importing");
+ dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
+ NSMutableArray<SGPlay *> *plays = [NSMutableArray array];
+ NSUInteger files = 0;
+ for (NSURL *url in urls) {
+ NSData *data = [NSData dataWithContentsOfURL:url options:NSDataReadingMappedIfSafe error:nil];
+ NSArray<NSData *> *jsons = [url.pathExtension.lowercaseString isEqualToString:@"zip"] ? SGJSONFilesInZip(data) : (data ? @[data] : @[]);
+ for (NSData *json in jsons) {
+ NSArray<SGPlay *> *found = SGPlaysFromExport(json);
+ if (!found) continue;
+ files++;
+ [plays addObjectsFromArray:found];
+ }
+ }
+ dispatch_async(dispatch_get_main_queue(), ^{
+ sg_importing = NO;
+ [page.tableView reloadData];
+ if (!files) {
+ showAlert(@"No listening history found", @"Pick the StreamingHistory_music or Streaming_History_Audio files of Spotify's data export, or the zip they came in.");
+ return;
+ }
+ NSUInteger added = [SGListeningLog() merge:plays];
+ SGLog(@"stats: %lu plays in %lu files, %lu new", (unsigned long)plays.count, (unsigned long)files, (unsigned long)added);
+ [page.tableView reloadData];
+ showAlert(@"Imported", [NSString stringWithFormat:@"%@ added from %lu %@, %lu skipped as already here.", playsText(added),
+ (unsigned long)files, files == 1 ? @"file" : @"files", (unsigned long)(plays.count - added)]);
+ });
+ });
+}
+
+@end
+
+static void pickExport(UITableViewController *page) {
+ if (sg_importing) return;
+ static SGExportPicker *delegate;
+ if (!delegate) delegate = [SGExportPicker new];
+ delegate.page = page;
+ UIDocumentPickerViewController *picker = [[UIDocumentPickerViewController alloc] initForOpeningContentTypes:@[UTTypeJSON, UTTypeZIP] asCopy:YES];
+ picker.allowsMultipleSelection = YES;
+ picker.delegate = delegate;
+ [SGTopController() presentViewController:picker animated:YES completion:nil];
+}
+
+static void confirmErase(UITableViewController *page) {
+ UIAlertController *alert = [UIAlertController alertControllerWithTitle:@"Erase listening history?"
+ message:@"Every play recorded on this phone and every one imported is deleted. Spotify's own history is untouched."
+ preferredStyle:UIAlertControllerStyleAlert];
+ [alert addAction:[UIAlertAction actionWithTitle:@"Erase" style:UIAlertActionStyleDestructive handler:^(UIAlertAction *action) {
+ [SGListeningLog() erase];
+ [page.tableView reloadData];
+ }]];
+ [alert addAction:[UIAlertAction actionWithTitle:@"Cancel" style:UIAlertActionStyleCancel handler:nil]];
+ [SGTopController() presentViewController:alert animated:YES completion:nil];
+}
+
+#pragma mark - page
+
+UIViewController *SGListeningStatsPage(void) {
+ NSMutableArray<SGModRow *> *periods = [NSMutableArray array];
+ NSArray *names = @[@"Past week", @"Past month", @"Past year", @"All time"];
+ NSArray *days = @[@7, @30, @365, @0];
+ for (NSUInteger i = 0; i < names.count; i++) {
+ NSString *name = names[i];
+ int64_t back = [days[i] longLongValue] * kDay;
+ int64_t (^since)(void) = ^int64_t { return back ? (int64_t)time(NULL) - back : 0; };
+ SGModRow *row = SGPageRow(name, ^UIViewController *{ return periodPage(name, since()); });
+ row.value = ^NSString *{ return duration(msSince(since())); };
+ [periods addObject:row];
+ }
+
+ SGModRow *import = SGWithSymbol(SGStatActionRow(@"Import Spotify's data export", nil,
+ ^NSString *{ return sg_importing ? @"Importing…" : nil; }, nil), @"square.and.arrow.down");
+ SGModRow *erase = SGWithSymbol(SGActionRow(@"Erase listening history", nil, nil), @"trash");
+ erase.color = SGRed();
+ SGModPage *page = [[SGModPage alloc] initWithTitle:@"Listening stats" intro:nil sections:@[
+ SGNotedSection(nil, @[SGSwitchRow(@"Record plays", nil, SGKeyListeningStats)],
+ @"A play counts once it has run 30 seconds, or half of a shorter track. Everything stays on this phone."),
+ SGSection(nil, periods),
+ SGNotedSection(nil, @[
+ SGStatRow(@"Plays", ^NSString *{ return [NSString stringWithFormat:@"%lu", (unsigned long)SGListeningLog().plays.count]; }),
+ import,
+ ], @"In Spotify's account privacy settings, ask for your data: the account data's StreamingHistory_music files, or the extended streaming history's Streaming_History_Audio files. Pick the JSON files or the zip they came in. Plays already here are skipped."),
+ SGSection(nil, @[erase]),
+ ] footer:nil];
+ __weak SGModPage *weakPage = page;
+ import.action = ^{ pickExport(weakPage); };
+ erase.action = ^{ confirmErase(weakPage); };
+ return page;
+}
diff --git a/tweak/Sources/Shared/ListeningStats/SGPlayLog.h b/tweak/Sources/Shared/ListeningStats/SGPlayLog.h
new file mode 100644
index 00000000..b682c532
--- /dev/null
+++ b/tweak/Sources/Shared/ListeningStats/SGPlayLog.h
@@ -0,0 +1,58 @@
+// The plays Listening stats counts, kept on the phone: recorded as they happen, merged in from Spotify's own
+// data export, and added up into tops for a period. Foundation only, so the Mac harness
+// (harness/listening-stats) builds it as the tweak does.
+//
+// The log is a text file of one play per line, appended to as plays end, so recording costs one write:
+// end <tab> ms <tab> uri <tab> title <tab> artist <tab> album
+// `end` is when the play stopped, in Unix seconds, which is what both of Spotify's export shapes record.
+//
+// Threading: an SGPlayLog is used from one thread (the main one in the tweak). The parsers are pure and
+// run on any.
+#import <Foundation/Foundation.h>
+
+@interface SGPlay : NSObject
+@property (nonatomic) int64_t end; // Unix seconds, when the play stopped
+@property (nonatomic) int64_t ms; // how long it was listened to
+@property (nonatomic, copy) NSString *uri, *title, *artist, *album; // uri and album may be empty, never nil
+@end
+
+// A play counts once it has run 30 s, or half of a track shorter than a minute.
+enum { SGPlayMinimumMs = 30000 };
+BOOL SGPlayCounts(double listenedSeconds, double durationSeconds);
+
+// The plays in one of the export's JSON files, either shape: StreamingHistory_music_*.json (endTime,
+// artistName, trackName, msPlayed) or the extended Streaming_History_Audio_*.json (ts, ms_played,
+// master_metadata_*, spotify_track_uri). Podcasts and plays under SGPlayMinimumMs are left out. Nil when
+// the data is not one of those files.
+NSArray<SGPlay *> *SGPlaysFromExport(NSData *json);
+// The .json files inside a zip, such as the export as Spotify mails it. Empty when it is not a zip.
+NSArray<NSData *> *SGJSONFilesInZip(NSData *zip);
+
+@interface SGPlayLog : NSObject
+- (instancetype)initWithPath:(NSString *)path;
+// Every play, read from the file the first time it is asked for.
+@property (nonatomic, readonly) NSArray<SGPlay *> *plays;
+- (void)record:(SGPlay *)play;
+// Adds the plays the log does not have yet, and answers how many that was: a play it has is the same
+// track and artist ending within 90 s of it, which covers the basic export's whole minutes and a
+// clock's drift, so importing a file twice, or both shapes of one export, adds nothing.
+- (NSUInteger)merge:(NSArray<SGPlay *> *)plays;
+- (void)erase;
+@end
+
+// One line of a top list: a track (detail is its artist), an artist (no detail) or an album (its artist).
+@interface SGStatEntry : NSObject
+@property (nonatomic, copy) NSString *name, *detail;
+@property (nonatomic) NSUInteger plays;
+@property (nonatomic) int64_t ms;
+@end
+
+@interface SGStats : NSObject
+@property (nonatomic) NSUInteger plays;
+@property (nonatomic) int64_t ms;
+// Most played first, then most listened to; at most `top` of each.
+@property (nonatomic, copy) NSArray<SGStatEntry *> *tracks, *artists, *albums;
+@end
+
+// The plays that ended at or after `since` (Unix seconds; 0 for all of them), added up.
+SGStats *SGStatsSince(NSArray<SGPlay *> *plays, int64_t since, NSUInteger top);
diff --git a/tweak/Sources/Shared/ListeningStats/SGPlayLog.m b/tweak/Sources/Shared/ListeningStats/SGPlayLog.m
new file mode 100644
index 00000000..e2148669
--- /dev/null
+++ b/tweak/Sources/Shared/ListeningStats/SGPlayLog.m
@@ -0,0 +1,266 @@
+// SGPlayLog.h says what the log holds and why it is a text file.
+#include <stdio.h>
+#include <time.h>
+#import "SGPlayLog.h"
+
+@implementation SGPlay
+@end
+
+@implementation SGStatEntry
+@end
+
+@implementation SGStats
+@end
+
+BOOL SGPlayCounts(double listened, double duration) {
+ return listened * 1000 >= SGPlayMinimumMs || (duration > 0 && listened >= duration / 2);
+}
+
+static NSString *stringIn(id value) {
+ return [value isKindOfClass:NSString.class] && [value length] ? value : nil;
+}
+
+// Both shapes are UTC. sscanf and timegm rather than NSDateFormatter: an extended export runs to 100k
+// rows and more, and the formatter costs microseconds a row.
+static int64_t timeIn(NSString *text, BOOL seconds) {
+ struct tm tm = {0};
+ const char *c = text.UTF8String;
+ int n = seconds ? sscanf(c, "%d-%d-%dT%d:%d:%d", &tm.tm_year, &tm.tm_mon, &tm.tm_mday, &tm.tm_hour, &tm.tm_min, &tm.tm_sec)
+ : sscanf(c, "%d-%d-%d %d:%d", &tm.tm_year, &tm.tm_mon, &tm.tm_mday, &tm.tm_hour, &tm.tm_min);
+ if (n < (seconds ? 6 : 5)) return 0;
+ tm.tm_year -= 1900;
+ tm.tm_mon -= 1;
+ return (int64_t)timegm(&tm);
+}
+
+// ponytail: the export has no track lengths, so an imported play counts from 30 s only; a full play of
+// a track under 30 s is left out. The extended rows' reason_end could tell a finished track apart.
+static SGPlay *playFrom(NSDictionary *row) {
+ NSString *title, *artist, *album = @"", *uri = @"";
+ int64_t end, ms;
+ if (row[@"ts"]) {
+ title = stringIn(row[@"master_metadata_track_name"]);
+ artist = stringIn(row[@"master_metadata_album_artist_name"]);
+ album = stringIn(row[@"master_metadata_album_album_name"]) ?: @"";
+ uri = stringIn(row[@"spotify_track_uri"]) ?: @"";
+ end = stringIn(row[@"ts"]) ? timeIn(row[@"ts"], YES) : 0;
+ ms = [row[@"ms_played"] isKindOfClass:NSNumber.class] ? [row[@"ms_played"] longLongValue] : 0;
+ } else {
+ title = stringIn(row[@"trackName"]);
+ artist = stringIn(row[@"artistName"]);
+ end = stringIn(row[@"endTime"]) ? timeIn(row[@"endTime"], NO) : 0;
+ ms = [row[@"msPlayed"] isKindOfClass:NSNumber.class] ? [row[@"msPlayed"] longLongValue] : 0;
+ }
+ if (!title || !artist || end <= 0 || ms < SGPlayMinimumMs) return nil;
+ SGPlay *play = [SGPlay new];
+ play.end = end;
+ play.ms = ms;
+ play.uri = uri;
+ play.title = title;
+ play.artist = artist;
+ play.album = album;
+ return play;
+}
+
+NSArray<SGPlay *> *SGPlaysFromExport(NSData *json) {
+ id rows = json ? [NSJSONSerialization JSONObjectWithData:json options:0 error:nil] : nil;
+ if (![rows isKindOfClass:NSArray.class]) return nil;
+ NSMutableArray<SGPlay *> *plays = [NSMutableArray array];
+ BOOL known = NO;
+ for (NSDictionary *row in rows) {
+ if (![row isKindOfClass:NSDictionary.class]) continue;
+ // Podcast files of either shape have their own keys, and the extended one's music rows have
+ // ts and ms_played, so the keys say what a file is whatever it was renamed to.
+ if (!(row[@"ts"] && row[@"ms_played"]) && !(row[@"endTime"] && row[@"msPlayed"])) continue;
+ known = YES;
+ SGPlay *play = playFrom(row);
+ if (play) [plays addObject:play];
+ }
+ return known || [rows count] == 0 ? plays : nil;
+}
+
+#pragma mark - zip
+
+static uint32_t le(const uint8_t *p, int bytes) {
+ uint32_t v = 0;
+ for (int i = bytes - 1; i >= 0; i--) v = v << 8 | p[i];
+ return v;
+}
+
+// The central directory names each entry and where it starts; stored and deflated entries are read,
+// deflate through NSDataCompressionAlgorithmZlib, which is raw DEFLATE (RFC 1951), as zip's method 8 is.
+// ponytail: no ZIP64, so a zip over 4 GB or 65535 entries reads as empty; an export is far smaller.
+NSArray<NSData *> *SGJSONFilesInZip(NSData *zip) {
+ NSMutableArray<NSData *> *files = [NSMutableArray array];
+ const uint8_t *b = zip.bytes;
+ size_t size = zip.length;
+ if (size < 22) return files;
+ size_t eocd = SIZE_MAX;
+ size_t floor = size > 22 + 0xFFFF ? size - 22 - 0xFFFF : 0;
+ for (size_t i = size - 22; ; i--) {
+ if (le(b + i, 4) == 0x06054b50) { eocd = i; break; }
+ if (i == floor) break;
+ }
+ if (eocd == SIZE_MAX) return files;
+ uint32_t count = le(b + eocd + 10, 2);
+ size_t at = le(b + eocd + 16, 4);
+ for (uint32_t n = 0; n < count; n++) {
+ if (at + 46 > size || le(b + at, 4) != 0x02014b50) break;
+ uint32_t method = le(b + at + 10, 2), packed = le(b + at + 20, 4), length = le(b + at + 24, 4);
+ uint32_t nameLength = le(b + at + 28, 2), extra = le(b + at + 30, 2), comment = le(b + at + 32, 2);
+ size_t local = le(b + at + 42, 4);
+ if (at + 46 + nameLength > size) break;
+ NSString *name = [[NSString alloc] initWithBytes:b + at + 46 length:nameLength encoding:NSUTF8StringEncoding];
+ at += 46 + nameLength + extra + comment;
+
+ BOOL json = [name.lowercaseString hasSuffix:@".json"] && ![name hasPrefix:@"__MACOSX/"];
+ if (!json || local + 30 > size || le(b + local, 4) != 0x04034b50) continue;
+ size_t data = local + 30 + le(b + local + 26, 2) + le(b + local + 28, 2);
+ if (data + packed > size || length > 1u << 30) continue;
+ if (method == 0 && packed == length) {
+ [files addObject:[zip subdataWithRange:NSMakeRange(data, packed)]];
+ } else if (method == 8 && length) {
+ NSData *out = [[zip subdataWithRange:NSMakeRange(data, packed)] decompressedDataUsingAlgorithm:NSDataCompressionAlgorithmZlib error:nil];
+ if (out.length == length) [files addObject:out];
+ }
+ }
+ return files;
+}
+
+#pragma mark - the log
+
+static NSString *field(NSString *text) {
+ if (!text) return @"";
+ NSArray *parts = [text componentsSeparatedByCharactersInSet:[NSCharacterSet characterSetWithCharactersInString:@"\t\r\n"]];
+ return [parts componentsJoinedByString:@" "];
+}
+
+static NSString *lineOf(SGPlay *play) {
+ return [NSString stringWithFormat:@"%lld\t%lld\t%@\t%@\t%@\t%@\n", play.end, play.ms, field(play.uri), field(play.title),
+ field(play.artist), field(play.album)];
+}
+
+static NSString *keyOf(SGPlay *play) {
+ return [NSString stringWithFormat:@"%@\x1f%@", play.title.lowercaseString, play.artist.lowercaseString];
+}
+
+@implementation SGPlayLog {
+ NSString *_path;
+ NSMutableArray<SGPlay *> *_plays;
+}
+
+- (instancetype)initWithPath:(NSString *)path {
+ if ((self = [super init])) _path = [path copy];
+ return self;
+}
+
+- (NSArray<SGPlay *> *)plays {
+ if (_plays) return _plays;
+ _plays = [NSMutableArray array];
+ NSString *text = [NSString stringWithContentsOfFile:_path encoding:NSUTF8StringEncoding error:nil];
+ for (NSString *line in [text componentsSeparatedByString:@"\n"]) {
+ NSArray<NSString *> *f = [line componentsSeparatedByString:@"\t"];
+ if (f.count < 6) continue;
+ SGPlay *play = [SGPlay new];
+ play.end = f[0].longLongValue;
+ play.ms = f[1].longLongValue;
+ play.uri = f[2];
+ play.title = f[3];
+ play.artist = f[4];
+ play.album = f[5];
+ [_plays addObject:play];
+ }
+ return _plays;
+}
+
+- (void)append:(NSArray<SGPlay *> *)plays {
+ if (!plays.count) return;
+ [NSFileManager.defaultManager createDirectoryAtPath:_path.stringByDeletingLastPathComponent withIntermediateDirectories:YES attributes:nil error:nil];
+ NSMutableString *text = [NSMutableString string];
+ for (SGPlay *play in plays) [text appendString:lineOf(play)];
+ FILE *file = fopen(_path.fileSystemRepresentation, "a");
+ if (!file) return;
+ fputs(text.UTF8String, file);
+ fclose(file);
+}
+
+// Not loaded for it: a play ending should not read the whole log on the main thread.
+- (void)record:(SGPlay *)play {
+ [_plays addObject:play];
+ [self append:@[play]];
+}
+
+- (NSUInteger)merge:(NSArray<SGPlay *> *)incoming {
+ NSMutableDictionary<NSString *, NSMutableArray<NSNumber *> *> *ends = [NSMutableDictionary dictionary];
+ for (SGPlay *play in self.plays) {
+ NSString *key = keyOf(play);
+ if (!ends[key]) ends[key] = [NSMutableArray array];
+ [ends[key] addObject:@(play.end)];
+ }
+ NSMutableArray<SGPlay *> *added = [NSMutableArray array];
+ for (SGPlay *play in incoming) {
+ NSString *key = keyOf(play);
+ BOOL have = NO;
+ for (NSNumber *end in ends[key]) {
+ if (llabs(end.longLongValue - play.end) <= 90) { have = YES; break; }
+ }
+ if (have) continue;
+ if (!ends[key]) ends[key] = [NSMutableArray array];
+ [ends[key] addObject:@(play.end)];
+ [added addObject:play];
+ }
+ [_plays addObjectsFromArray:added];
+ [self append:added];
+ return added.count;
+}
+
+- (void)erase {
+ [NSFileManager.defaultManager removeItemAtPath:_path error:nil];
+ _plays = [NSMutableArray array];
+}
+
+@end
+
+#pragma mark - stats
+
+static NSArray<SGStatEntry *> *topOf(NSDictionary<NSString *, SGStatEntry *> *entries, NSUInteger top) {
+ NSArray<SGStatEntry *> *sorted = [entries.allValues sortedArrayUsingComparator:^NSComparisonResult(SGStatEntry *a, SGStatEntry *b) {
+ if (a.plays != b.plays) return a.plays > b.plays ? NSOrderedAscending : NSOrderedDescending;
+ if (a.ms != b.ms) return a.ms > b.ms ? NSOrderedAscending : NSOrderedDescending;
+ return [a.name localizedCaseInsensitiveCompare:b.name];
+ }];
+ return [sorted subarrayWithRange:NSMakeRange(0, MIN(top, sorted.count))];
+}
+
+static void count(NSMutableDictionary<NSString *, SGStatEntry *> *entries, NSString *key, NSString *name, NSString *detail, SGPlay *play) {
+ SGStatEntry *entry = entries[key];
+ if (!entry) {
+ entry = [SGStatEntry new];
+ entry.name = name;
+ entry.detail = detail;
+ entries[key] = entry;
+ }
+ entry.plays++;
+ entry.ms += play.ms;
+}
+
+// Tracks go by title and artist rather than URI: the basic export has no URIs, and a track's URI can
+// differ between its single and its album.
+SGStats *SGStatsSince(NSArray<SGPlay *> *plays, int64_t since, NSUInteger top) {
+ NSMutableDictionary<NSString *, SGStatEntry *> *tracks = [NSMutableDictionary dictionary], *artists = [NSMutableDictionary dictionary],
+ *albums = [NSMutableDictionary dictionary];
+ SGStats *stats = [SGStats new];
+ for (SGPlay *play in plays) {
+ if (play.end < since) continue;
+ stats.plays++;
+ stats.ms += play.ms;
+ NSString *artist = play.artist.lowercaseString;
+ count(tracks, keyOf(play), play.title, play.artist, play);
+ count(artists, artist, play.artist, nil, play);
+ if (play.album.length) count(albums, [NSString stringWithFormat:@"%@\x1f%@", play.album.lowercaseString, artist], play.album, play.artist, play);
+ }
+ stats.tracks = topOf(tracks, top);
+ stats.artists = topOf(artists, top);
+ stats.albums = topOf(albums, top);
+ return stats;
+}