@chronicle.app/shazam 0.4.0 → 0.5.0

package/README.md

@@ -40,7 +40,7 @@ A run reads only the library, offline. With `--link-artists`, it also looks up e
 
 **Where you were, when the device knew.** A Shazam made without a location fix records 0, 0 or -180, -180, which is left out.
 
-**The agent is your iCloud account,** whose library this is, from `@chronicle.app/icloud`. It's omitted when no account can be read. An explicit `account` object (or null) describes a copied library without a host account lookup.
+**The agent is your iCloud account,** whose library this is, from `@chronicle.app/apple`. It's omitted when no account can be read. An explicit `account` object (or null) describes a copied library without a host account lookup.
 
 **The archived fields are decoded in the plugin.** Core Data keeps a song's genres and Apple Music response as NSKeyedArchiver archives in binary property lists. `archive.ts` reads them. A field that doesn't decode is logged and left out; the Shazam is kept.
 

package/dist/archive.d.ts

@@ -1,20 +1,3 @@
-/**
- * Core Data keeps a transformable attribute, such as a track's genres, as an
- * NSKeyedArchiver archive in a binary property list (`bplist00`). This reads
- * the archives shazamd writes: arrays, dictionaries, strings, numbers, dates,
- * and data. Other classes come back as `null`.
- */
-/** A reference to an entry in an archive's `$objects`. */
-declare class Uid {
-    readonly index: number;
-    constructor(index: number);
-}
-type PlistValue = null | boolean | number | string | Date | Uint8Array | Uid | PlistValue[] | {
-    [key: string]: PlistValue;
-};
-/** Parse a binary property list. */
-export declare function parseBinaryPlist(bytes: Uint8Array): PlistValue;
 /** Decode an NSKeyedArchiver archive to plain values. */
 export declare function unarchive(bytes: Uint8Array): unknown;
-export {};
 //# sourceMappingURL=archive.d.ts.map

package/dist/archive.js

@@ -1,3 +1,4 @@
+import { parseBinaryPlist, Uid } from '@chronicle.app/apple';
 import { APPLE_EPOCH_OFFSET_SECONDS } from '@chronicle.app/etl-sqlite';
 /**
  * Core Data keeps a transformable attribute, such as a track's genres, as an
@@ -5,84 +6,8 @@ import { APPLE_EPOCH_OFFSET_SECONDS } from '@chronicle.app/etl-sqlite';
  * the archives shazamd writes: arrays, dictionaries, strings, numbers, dates,
  * and data. Other classes come back as `null`.
  */
-/** A reference to an entry in an archive's `$objects`. */
-class Uid {
-    index;
-    constructor(index) {
-        this.index = index;
-    }
-}
 // Nested containers deeper than this are a malformed (or cyclic) file.
 const MAX_DEPTH = 64;
-/** Parse a binary property list. */
-export function parseBinaryPlist(bytes) {
-    const buf = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-    if (buf.length < 40 || buf.toString('latin1', 0, 8) !== 'bplist00') {
-        throw new Error('Not a binary property list');
-    }
-    const trailer = buf.length - 32;
-    const offsetSize = buf[trailer + 6];
-    const refSize = buf[trailer + 7];
-    const count = Number(buf.readBigUInt64BE(trailer + 8));
-    const top = Number(buf.readBigUInt64BE(trailer + 16));
-    const offsetTable = Number(buf.readBigUInt64BE(trailer + 24));
-    const uint = (at, size) => {
-        let n = 0;
-        for (let i = 0; i < size; i++)
-            n = n * 256 + buf[at + i];
-        return n;
-    };
-    const read = (index, depth) => {
-        if (index >= count || depth > MAX_DEPTH)
-            throw new Error('Malformed binary property list');
-        const at = uint(offsetTable + index * offsetSize, offsetSize);
-        // A marker byte holds the object's type in its high four bits and its
-        // size or count in its low four.
-        const type = Math.floor(buf[at] / 16);
-        const info = buf[at] % 16;
-        // A count of 15 or more follows the marker as an integer object.
-        let length = info;
-        let start = at + 1;
-        if (info === 0xf) {
-            const size = 2 ** (buf[at + 1] % 16);
-            length = uint(at + 2, size);
-            start = at + 2 + size;
-        }
-        const refs = (offset, n) => Array.from({ length: n }, (_, i) => read(uint(start + (offset + i) * refSize, refSize), depth + 1));
-        switch (type) {
-            case 0x0:
-                return info === 0x9 ? true : info === 0x8 ? false : null;
-            case 0x1:
-                return info === 3 ? Number(buf.readBigInt64BE(at + 1)) : uint(at + 1, 2 ** info);
-            case 0x2:
-                return info === 2 ? buf.readFloatBE(at + 1) : buf.readDoubleBE(at + 1);
-            case 0x3:
-                return new Date((buf.readDoubleBE(at + 1) + APPLE_EPOCH_OFFSET_SECONDS) * 1000);
-            case 0x4:
-                return buf.subarray(start, start + length);
-            case 0x5:
-                return buf.toString('latin1', start, start + length);
-            case 0x6:
-                // UTF-16 big-endian; Node decodes only little-endian.
-                return Buffer.from(buf.subarray(start, start + length * 2))
-                    .swap16()
-                    .toString('utf16le');
-            case 0x8:
-                return new Uid(uint(at + 1, info + 1));
-            case 0xa:
-            case 0xc:
-                return refs(0, length);
-            case 0xd: {
-                const keys = refs(0, length);
-                const values = refs(length, length);
-                return Object.fromEntries(keys.map((key, i) => [String(key), values[i]]));
-            }
-            default:
-                throw new Error(`Unsupported binary property list type 0x${type.toString(16)}`);
-        }
-    };
-    return read(top, 0);
-}
 /** Decode an NSKeyedArchiver archive to plain values. */
 export function unarchive(bytes) {
     const archive = parseBinaryPlist(bytes);

package/dist/connectors/ShazamExtractor.d.ts

@@ -1,4 +1,4 @@
-import { Record } from '@chronicle.app/etl';
+import { Record, type Survey, type SurveyOptions } from '@chronicle.app/etl';
 import { SqliteExtractor } from '@chronicle.app/etl-sqlite';
 import { type AppleMusicArtist } from '../appleMusic.js';
 import ShazamTransformer from './ShazamTransformer.js';
@@ -49,6 +49,11 @@ export declare class ShazamExtractor extends SqliteExtractor<typeof ShazamExtrac
     static default: boolean;
     static defaultTransformer: typeof ShazamTransformer;
     static newestFirst: boolean;
+    static databases: {
+        tables: {
+            ZSHTRACKMO: string[];
+        };
+    }[];
     static schema: any;
     private lookup?;
     setup(): Promise<void>;
@@ -62,5 +67,10 @@ export declare class ShazamExtractor extends SqliteExtractor<typeof ShazamExtrac
     private decode;
     private parseSong;
     determineCount(): Promise<number | null>;
+    /**
+     * The Shazams a run reads and when, of how many songs, by how many artists:
+     * by Shazam's artist line, as a run without linkArtists keys them.
+     */
+    survey(options?: SurveyOptions): Promise<Survey | null>;
 }
 //# sourceMappingURL=ShazamExtractor.d.ts.map

package/dist/connectors/ShazamExtractor.js

@@ -1,5 +1,5 @@
-import { APPLE_EPOCH_OFFSET_SECONDS, SqliteExtractor, getRow, iterateRows, timeRangeConditions, unixToSafariTimestamp, } from '@chronicle.app/etl-sqlite';
-import { getICloudAccount } from '@chronicle.app/icloud';
+import { APPLE_EPOCH_OFFSET_SECONDS, SqliteExtractor, allRows, countsByMonth, getRow, iterateRows, monthSql, timeRangeConditions, unixToSafariTimestamp, } from '@chronicle.app/etl-sqlite';
+import { getICloudAccount } from '@chronicle.app/apple';
 import { z } from 'zod';
 import { AppleMusicLookup, LOOKUP_BATCH, countryOf } from '../appleMusic.js';
 import { unarchive } from '../archive.js';
@@ -21,6 +21,36 @@ export class ShazamExtractor extends SqliteExtractor {
     static default = true;
     static defaultTransformer = ShazamTransformer;
     static newestFirst = true;
+    // What extract() and survey() read, which a ShazamLibrary.sqlite must have.
+    static databases = [
+        {
+            tables: {
+                ZSHTRACKMO: [
+                    'Z_PK',
+                    'ZRECOGNITIONID',
+                    'ZSYNCID',
+                    'ZDATE',
+                    'ZMODIFIEDDATE',
+                    'ZTITLE',
+                    'ZSUBTITLE',
+                    'ZSHAZAMKEY',
+                    'ZSHAZAMURL',
+                    'ZPROVIDERNAME',
+                    'ZLATITUDE',
+                    'ZLONGITUDE',
+                    'ZARTWORKURL',
+                    'ZAPPLEMUSICID',
+                    'ZAPPLEMUSICURL',
+                    'ZISRC',
+                    'ZALBUMNAME',
+                    'ZRELEASEDATE',
+                    'ZEXPLICIT',
+                    'ZGENRES',
+                    'ZRAWSONGRESPONSE',
+                ],
+            },
+        },
+    ];
     static schema = SqliteExtractor.schema.omit({ input: true }).extend({
         input: z.string().describe('Path to ShazamLibrary.sqlite').default(DEFAULT_DB),
         account: z
@@ -177,6 +207,32 @@ export class ShazamExtractor extends SqliteExtractor {
             return null;
         }
     }
+    /**
+     * The Shazams a run reads and when, of how many songs, by how many artists:
+     * by Shazam's artist line, as a run without linkArtists keys them.
+     */
+    async survey(options = {}) {
+        if (!this.db)
+            return null;
+        const { sql, values } = this.query(`COUNT(*) AS n, MIN(ZDATE) AS first, MAX(ZDATE) AS last,
+       COUNT(DISTINCT ZSHAZAMKEY) AS songs, COUNT(DISTINCT ZSUBTITLE) AS artists`);
+        const row = getRow(this.db.prepare(sql), ...values);
+        const months = this.query(`${monthSql(`ZDATE + ${APPLE_EPOCH_OFFSET_SECONDS}`)} AS month, COUNT(*) AS n`);
+        const byMonth = options.byMonth &&
+            countsByMonth(allRows(this.db.prepare(`${months.sql} GROUP BY month`), ...months.values));
+        return {
+            listens: {
+                count: row.n,
+                ...(row.first !== null && { earliest: new Date(appleDate(row.first)) }),
+                ...(row.last !== null && { latest: new Date(appleDate(row.last)) }),
+                ...(byMonth && { byMonth }),
+                measures: [
+                    { key: 'songs', label: 'songs', value: row.songs },
+                    { key: 'artists', label: 'artists', value: row.artists },
+                ],
+            },
+        };
+    }
 }
 function appleDate(seconds) {
     return new Date((seconds + APPLE_EPOCH_OFFSET_SECONDS) * 1000).toISOString();

package/dist/connectors/ShazamTransformer.js

@@ -1,5 +1,5 @@
 import { ChronicleTransformer, ISRC_SOURCE, createImageObject, normalizeIsrc, } from '@chronicle.app/etl';
-import { buildICloudPersonSchema } from '@chronicle.app/icloud';
+import { buildICloudPersonSchema } from '@chronicle.app/apple';
 const SOURCE = 'shazam';
 /** Apple Music's catalog: the namespace of its song, album, and artist IDs. */
 const APPLE_MUSIC = 'apple-music';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronicle.app/shazam",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -24,9 +24,9 @@
   "type": "module",
   "description": "Chronicle plugin for the songs you identified with Shazam, from the library macOS keeps for Music Recognition",
   "devDependencies": {
-    "@chronicle.app/etl": "0.4.0",
-    "@chronicle.app/schema": "0.4.0",
-    "@chronicle.app/tsconfig": "0.4.0",
+    "@chronicle.app/etl": "0.5.0",
+    "@chronicle.app/schema": "0.5.0",
+    "@chronicle.app/tsconfig": "0.5.0",
     "@types/node": "^22.10.1",
     "typescript": "^5.7.2"
   },
@@ -41,8 +41,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@chronicle.app/etl-sqlite": "0.4.0",
-    "@chronicle.app/icloud": "0.4.0",
+    "@chronicle.app/etl-sqlite": "0.5.0",
+    "@chronicle.app/apple": "0.5.0",
     "zod": "^3.24.1"
   },
   "peerDependencies": {
@@ -68,7 +68,41 @@
             "recordTypes": [
               "listens"
             ],
-            "default": true
+            "default": true,
+            "locations": [
+              {
+                "path": "~/Library/Application Support/com.apple.shazamd/ShazamLibrary.sqlite"
+              }
+            ],
+            "databases": [
+              {
+                "tables": {
+                  "ZSHTRACKMO": [
+                    "Z_PK",
+                    "ZRECOGNITIONID",
+                    "ZSYNCID",
+                    "ZDATE",
+                    "ZMODIFIEDDATE",
+                    "ZTITLE",
+                    "ZSUBTITLE",
+                    "ZSHAZAMKEY",
+                    "ZSHAZAMURL",
+                    "ZPROVIDERNAME",
+                    "ZLATITUDE",
+                    "ZLONGITUDE",
+                    "ZARTWORKURL",
+                    "ZAPPLEMUSICID",
+                    "ZAPPLEMUSICURL",
+                    "ZISRC",
+                    "ZALBUMNAME",
+                    "ZRELEASEDATE",
+                    "ZEXPLICIT",
+                    "ZGENRES",
+                    "ZRAWSONGRESPONSE"
+                  ]
+                }
+              }
+            ]
           }
         },
         "platforms": [