@chronicle.app/shazam 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Louis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# @chronicle.app/shazam
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The songs you identified with Shazam, from the library macOS keeps for Music Recognition.
+
+## Usage
+
+```sh
+chronicle extract shazam
+chronicle extract shazam --since 2024-01-01 --until 2025-01-01
+chronicle extract shazam --input "/path/to/ShazamLibrary.sqlite"
+chronicle extract shazam --link-artists
+```
+
+The library is `~/Library/Application Support/com.apple.shazamd/ShazamLibrary.sqlite`, opened read-only with built-in `node:sqlite`. macOS keeps it in step with the Shazam library in your iCloud account, so it holds what you identified on every device: the Shazam app on your iPhone as well as Music Recognition in Control Center. It syncs only when Music Recognition is turned on in your iCloud settings. If the library is empty, open Music Recognition in Control Center to load your history.
+
+Shazams come out newest first, and `--since` and `--until` bound when each song was identified.
+
+A run reads only the library, offline. With `--link-artists`, it also looks up each song's main artist with Apple's public lookup API, which needs no sign-in: two requests for every 200 Shazams.
+
+## Schema
+
+| Shazam thing       | Chronicle node   | Key                                                             | Properties                                                                                                                                           |
+| ------------------ | ---------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Identifying a song | `ListenAction`   | `@type`, `source`, `sourceId` (the recognition ID)              | `agent` (you), `object` (the song), `timestamp` (when it was identified), `location` (a `Location` with its `latitude` and `longitude`)              |
+| The song           | `MusicRecording` | `@type`, `source` (`shazam`), `sourceId` (the Shazam track key) | `name`, `artist`, `inAlbum`, `duration`, `genre`, `datePublished` (the release date), `emblem` (the cover), `sameAs` (its ISRC and Apple Music song) |
+| The artist         | `MusicGroup`     | `@type`, `source` (`apple-music`), `sourceId` (its artist ID)   | `name`, `url`; with `--link-artists`                                                                                                                 |
+| The artist line    | `MusicGroup`     | `@type`, `source` (`shazam`), `name`                            | `name`; without `--link-artists`, or when Apple Music has no artist for the song                                                                     |
+| The album          | `MusicAlbum`     | `@type`, `source` (`apple-music`), `sourceId` (its album ID)    | `name`                                                                                                                                               |
+| You                | `Person`         | `@type`, `source` (`icloud`), `sourceId` (your account's DSID)  | `handle` (your Apple Account email); `sameAs` `@me`                                                                                                  |
+
+`SHAPES.md` sketches the output, generated from the tests.
+
+### Decisions
+
+**Identifying a song is listening to it.** A Shazam is a `ListenAction` of the song, keyed by its recognition ID, which the Shazam app gives it on every device. A sync can leave two copies of one Shazam in the library; they're one action, from the most recently modified copy. A Shazam with no recognition ID is known by its sync ID. Shazaming a song again is another action with the same song.
+
+**A song is Shazam's copy, the same song as its ISRC and Apple Music song.** The song is keyed by its Shazam track key and named as Shazam names it, with the artist line as Shazam words it (`Artist Feat. Guest`) unless its artist is linked. It's `sameAs` its ISRC, in the `isrc` namespace, which every service's copy of the recording shares, and its Apple Music song, in the `apple-music` namespace, with its link. The album, release date, duration, genres, and cover are Apple Music's, so a Shazam with no Apple Music match has none of them. The album is keyed by the album ID in the Apple Music link. Apple's root genre, `Music`, which every song has, is left out. Apple Music covers are stored as HEIC, which most browsers can't show, so the cover is the same size as a JPEG from Apple's image server. The plugin declares a `deepLinks` template for `MusicRecording` (`https://www.shazam.com/track/<key>`).
+
+**An artist is Apple Music's when it's linked, and otherwise Shazam's artist line.** Shazam gives no artist ID, so without `--link-artists` the artist line is a `MusicGroup` keyed by its name. With it, the extractor looks up each song with Apple Music, a batch at a time, and the artist is a `MusicGroup` keyed by the Apple Music ID of the song's main artist, named as Apple Music names that artist. A song's lookup gives the main artist's ID beside the song's whole credit line (`Artist & Guest`), so the artist's own name (`Artist`) comes from a second lookup of the ID. Featured and other credited artists are left out. A Shazam with no Apple Music match keeps its artist line. Lookups are made in the store of the song's Apple Music link. When Apple Music limits lookups, the extractor waits and tries again; when it can't reach Apple Music, the rest of the run keeps artist lines and says so.
+
+**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 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.
+
+## Tests
+
+The tests are smoke tests over a synthetic `ShazamLibrary.sqlite`, with archives written by the fixture, and pass an explicit iCloud account. They never read the host's Shazam library or iCloud account, and never reach Apple Music: `--link-artists`'s lookups aren't tested.

package/dist/appleMusic.d.ts

@@ -0,0 +1,30 @@
+export declare const LOOKUP_BATCH = 200;
+export interface AppleMusicArtist {
+    id: string;
+    name: string;
+    url?: string;
+}
+/** A song to look up: its Apple Music ID and the store (`ca`, `us`) its link is in. */
+export interface AppleMusicSong {
+    id: string;
+    country: string;
+}
+interface LookupLog {
+    info(message: string): void;
+    /** Called once, when a lookup fails; the run stops looking up after it. */
+    failure(error: Error): void;
+}
+export declare class AppleMusicLookup {
+    private readonly artistOfSong;
+    private readonly artists;
+    private failed;
+    private readonly log;
+    constructor(log: LookupLog);
+    /** Each song's main artist, by song ID. Songs Apple has no artist for are absent. */
+    artistsOf(songs: AppleMusicSong[]): Promise<Map<string, AppleMusicArtist>>;
+    private lookup;
+}
+/** The store an Apple Music link is in (`https://music.apple.com/ca/...`), or the US store. */
+export declare function countryOf(link: string | null): string;
+export {};
+//# sourceMappingURL=appleMusic.d.ts.map

package/dist/appleMusic.js

@@ -0,0 +1,115 @@
+/**
+ * Apple's public lookup API (the iTunes Search API's `lookup`), which needs
+ * no sign-in. A song's lookup gives its main artist's ID beside the song's
+ * whole credit line (`Artist & Guest`), so the artist's own name (`Artist`)
+ * comes from looking up that ID.
+ */
+const LOOKUP_URL = 'https://itunes.apple.com/lookup';
+// Apple answers for up to 200 IDs a request.
+export const LOOKUP_BATCH = 200;
+// Apple throttles the API with a 403 or 429; wait longer each time, then give up.
+const BACKOFF_SECONDS = [10, 30, 60];
+export class AppleMusicLookup {
+    // Remembered for the run, including what Apple had no answer for (null).
+    artistOfSong = new Map();
+    artists = new Map();
+    failed = false;
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /** Each song's main artist, by song ID. Songs Apple has no artist for are absent. */
+    async artistsOf(songs) {
+        const newSongs = songs.filter(song => !this.artistOfSong.has(song.id));
+        for (const [country, ids] of byCountry(newSongs)) {
+            for (const result of await this.lookup(ids, country)) {
+                if (result.wrapperType === 'track' && result.trackId && result.artistId) {
+                    this.artistOfSong.set(String(result.trackId), String(result.artistId));
+                }
+            }
+            if (this.failed)
+                return new Map();
+            for (const id of ids)
+                if (!this.artistOfSong.has(id))
+                    this.artistOfSong.set(id, null);
+        }
+        const newArtists = songs
+            .map(song => ({ id: this.artistOfSong.get(song.id), country: song.country }))
+            .filter((artist) => Boolean(artist.id) && !this.artists.has(artist.id));
+        for (const [country, ids] of byCountry(newArtists)) {
+            for (const result of await this.lookup(ids, country)) {
+                if (result.wrapperType === 'artist' && result.artistId && result.artistName) {
+                    this.artists.set(String(result.artistId), {
+                        id: String(result.artistId),
+                        name: result.artistName,
+                        ...(result.artistLinkUrl && { url: withoutQuery(result.artistLinkUrl) }),
+                    });
+                }
+            }
+            if (this.failed)
+                return new Map();
+            for (const id of ids)
+                if (!this.artists.has(id))
+                    this.artists.set(id, null);
+        }
+        const found = new Map();
+        for (const song of songs) {
+            const artist = this.artists.get(this.artistOfSong.get(song.id) ?? '');
+            if (artist)
+                found.set(song.id, artist);
+        }
+        return found;
+    }
+    async lookup(ids, country) {
+        if (this.failed || ids.length === 0)
+            return [];
+        const url = `${LOOKUP_URL}?id=${ids.join(',')}&country=${encodeURIComponent(country)}`;
+        try {
+            for (let attempt = 0;; attempt++) {
+                const response = await fetch(url);
+                if (response.ok)
+                    return (await response.json()).results ?? [];
+                const throttled = response.status === 403 || response.status === 429;
+                if (!throttled || attempt >= BACKOFF_SECONDS.length) {
+                    throw new Error(`Apple Music's lookup answered ${response.status}`);
+                }
+                this.log.info(`Apple Music is limiting lookups; waiting ${BACKOFF_SECONDS[attempt]}s`);
+                await sleep(BACKOFF_SECONDS[attempt] * 1000);
+            }
+        }
+        catch (error) {
+            this.failed = true;
+            this.log.failure(error);
+            return [];
+        }
+    }
+}
+/** IDs grouped by store, in batches Apple answers for in one request. */
+function byCountry(items) {
+    const groups = new Map();
+    for (const { id, country } of items) {
+        const ids = groups.get(country) ?? new Set();
+        ids.add(id);
+        groups.set(country, ids);
+    }
+    const batches = [];
+    for (const [country, ids] of groups) {
+        const all = [...ids];
+        for (let i = 0; i < all.length; i += LOOKUP_BATCH) {
+            batches.push([country, all.slice(i, i + LOOKUP_BATCH)]);
+        }
+    }
+    return batches;
+}
+/** The store an Apple Music link is in (`https://music.apple.com/ca/...`), or the US store. */
+export function countryOf(link) {
+    return link?.match(/^https:\/\/music\.apple\.com\/([a-z]{2})\//)?.[1] ?? 'us';
+}
+function withoutQuery(link) {
+    return link.split('?')[0];
+}
+function sleep(ms) {
+    return new Promise(resolve => {
+        setTimeout(resolve, ms);
+    });
+}

package/dist/archive.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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

@@ -0,0 +1,127 @@
+import { APPLE_EPOCH_OFFSET_SECONDS } from '@chronicle.app/etl-sqlite';
+/**
+ * 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`. */
+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);
+    const objects = archive?.$objects;
+    if (archive?.$archiver !== 'NSKeyedArchiver' || !Array.isArray(objects)) {
+        throw new Error('Not a keyed archive');
+    }
+    const resolve = (value, depth) => {
+        if (depth > MAX_DEPTH)
+            throw new Error('Malformed keyed archive');
+        if (value instanceof Uid) {
+            // Entry 0 is `$null`, the archive's nil.
+            if (value.index === 0)
+                return null;
+            return resolve(objects[value.index], depth + 1);
+        }
+        if (value === null || typeof value !== 'object' || value instanceof Date)
+            return value;
+        if (value instanceof Uint8Array)
+            return value;
+        if (Array.isArray(value))
+            return value.map(item => resolve(item, depth + 1));
+        if (Array.isArray(value['NS.keys']) && Array.isArray(value['NS.objects'])) {
+            const values = value['NS.objects'];
+            return Object.fromEntries(value['NS.keys'].map((key, i) => [
+                String(resolve(key, depth + 1)),
+                resolve(values[i], depth + 1),
+            ]));
+        }
+        if (Array.isArray(value['NS.objects']))
+            return resolve(value['NS.objects'], depth + 1);
+        if ('NS.string' in value)
+            return resolve(value['NS.string'], depth + 1);
+        if ('NS.data' in value)
+            return resolve(value['NS.data'], depth + 1);
+        if (typeof value['NS.time'] === 'number') {
+            return new Date((value['NS.time'] + APPLE_EPOCH_OFFSET_SECONDS) * 1000);
+        }
+        return null;
+    };
+    return resolve(archive.$top?.root ?? null, 0);
+}

package/dist/connectors/ShazamExtractor.d.ts

@@ -0,0 +1,66 @@
+import { Record } from '@chronicle.app/etl';
+import { SqliteExtractor } from '@chronicle.app/etl-sqlite';
+import { type AppleMusicArtist } from '../appleMusic.js';
+import ShazamTransformer from './ShazamTransformer.js';
+/** One Shazam as the library row gives it, named after the row's Core Data attributes. */
+export interface Shazam {
+    recognitionID: string;
+    syncID: string | null;
+    /** When the song was recognized, in UTC. */
+    date: string;
+    /** The title and artist line as Shazam words them. */
+    title: string | null;
+    subtitle: string | null;
+    shazamKey: string | null;
+    shazamURL: string | null;
+    providerName: string | null;
+    latitude: number | null;
+    longitude: number | null;
+    artworkURL: string | null;
+    appleMusicID: string | null;
+    appleMusicURL: string | null;
+    isrc: string | null;
+    albumName: string | null;
+    /** A day, `YYYY-MM-DD`. */
+    releaseDate: string | null;
+    explicit: boolean | null;
+    genres: string[];
+    /** Apple Music's song resource (`id`, `attributes`), decoded from `rawSongResponse`. */
+    song: {
+        id?: string;
+        attributes?: {
+            [key: string]: unknown;
+        };
+    } | null;
+    /** The song's main artist on Apple Music, looked up with `linkArtists`. */
+    appleMusicArtist?: AppleMusicArtist;
+}
+/**
+ * The Shazam library that macOS keeps for Music Recognition (`shazamd`). It
+ * mirrors the iCloud library the Shazam app syncs to, so it holds the songs
+ * recognized on every device signed in to the account.
+ */
+export declare class ShazamExtractor extends SqliteExtractor<typeof ShazamExtractor> {
+    static source: string;
+    static description: string;
+    static delivery: "local";
+    static strategy: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static defaultTransformer: typeof ShazamTransformer;
+    static newestFirst: boolean;
+    static schema: any;
+    private lookup?;
+    setup(): Promise<void>;
+    /** The recognition ID: the same ID the Shazam app gives the Shazam on every device. */
+    keyOf(record: Record): string | null;
+    occurredAt(record: Record): Date | undefined;
+    private query;
+    extract(): AsyncGenerator<Record>;
+    private recordsOf;
+    private shazamOf;
+    private decode;
+    private parseSong;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=ShazamExtractor.d.ts.map

package/dist/connectors/ShazamExtractor.js

@@ -0,0 +1,183 @@
+import { APPLE_EPOCH_OFFSET_SECONDS, SqliteExtractor, getRow, iterateRows, timeRangeConditions, unixToSafariTimestamp, } from '@chronicle.app/etl-sqlite';
+import { getICloudAccount } from '@chronicle.app/icloud';
+import { z } from 'zod';
+import { AppleMusicLookup, LOOKUP_BATCH, countryOf } from '../appleMusic.js';
+import { unarchive } from '../archive.js';
+import ShazamTransformer from './ShazamTransformer.js';
+const DEFAULT_DB = `${process.env.HOME}/Library/Application Support/com.apple.shazamd/ShazamLibrary.sqlite`;
+// since/until bounds land on ZDATE, which is seconds since the Apple epoch.
+const appleBound = (date) => unixToSafariTimestamp(date.getTime() / 1000);
+/**
+ * The Shazam library that macOS keeps for Music Recognition (`shazamd`). It
+ * mirrors the iCloud library the Shazam app syncs to, so it holds the songs
+ * recognized on every device signed in to the account.
+ */
+export class ShazamExtractor extends SqliteExtractor {
+    static source = 'shazam';
+    static description = 'Songs you identified with Shazam';
+    static delivery = 'local';
+    static strategy = 'app-db';
+    static recordTypes = ['listens'];
+    static default = true;
+    static defaultTransformer = ShazamTransformer;
+    static newestFirst = true;
+    static schema = SqliteExtractor.schema.omit({ input: true }).extend({
+        input: z.string().describe('Path to ShazamLibrary.sqlite').default(DEFAULT_DB),
+        account: z
+            .object({
+            accountID: z.string(),
+            email: z.string(),
+            displayName: z.string(),
+            dsid: z.string().optional(),
+        })
+            .nullable()
+            .optional(),
+        linkArtists: z
+            .boolean()
+            .optional()
+            .describe("Look up each song's main artist on Apple Music, to link artists by their Apple Music ID"),
+    });
+    lookup;
+    async setup() {
+        await super.setup();
+        if (!this.config.linkArtists)
+            return;
+        this.lookup = new AppleMusicLookup({
+            info: message => this.logger.info(message),
+            failure: error => {
+                this.logger.warn(`Can't look up artists on Apple Music: ${error.message}`);
+                this.hint("Can't reach Apple Music, so some artists aren't linked", {
+                    action: 'Check your connection and run `chronicle extract shazam --link-artists` again.',
+                });
+            },
+        });
+    }
+    /** The recognition ID: the same ID the Shazam app gives the Shazam on every device. */
+    keyOf(record) {
+        return record.data.recognitionID ?? null;
+    }
+    occurredAt(record) {
+        return new Date(record.data.date);
+    }
+    // A sync can write the same Shazam twice, so take one row per recognition
+    // ID: the most recently modified.
+    query(select) {
+        const range = timeRangeConditions('ZDATE', this.config, { convert: appleBound });
+        const where = ['copy = 1', ...range.conditions].join(' AND ');
+        const sql = `
+      WITH shazams AS (
+        SELECT *, COALESCE(ZRECOGNITIONID, ZSYNCID) AS id,
+               ROW_NUMBER() OVER (
+                 PARTITION BY COALESCE(ZRECOGNITIONID, ZSYNCID)
+                 ORDER BY ZMODIFIEDDATE DESC, Z_PK DESC
+               ) AS copy
+        FROM ZSHTRACKMO
+        WHERE COALESCE(ZRECOGNITIONID, ZSYNCID) IS NOT NULL AND ZDATE IS NOT NULL
+      )
+      SELECT ${select} FROM shazams WHERE ${where}`;
+        return { sql, values: range.values };
+    }
+    async *extract() {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const { sql, values } = this.query(`
+      id, ZSYNCID AS syncID, ZDATE AS date, ZTITLE AS title, ZSUBTITLE AS subtitle,
+      ZSHAZAMKEY AS shazamKey, ZSHAZAMURL AS shazamURL, ZPROVIDERNAME AS providerName,
+      ZLATITUDE AS latitude, ZLONGITUDE AS longitude, ZARTWORKURL AS artworkURL,
+      ZAPPLEMUSICID AS appleMusicID, ZAPPLEMUSICURL AS appleMusicURL, ZISRC AS isrc,
+      ZALBUMNAME AS albumName, ZRELEASEDATE AS releaseDate, ZEXPLICIT AS explicit,
+      ZGENRES AS genres, ZRAWSONGRESPONSE AS rawSongResponse`);
+        let ordered = `${sql} ORDER BY ZDATE DESC`;
+        const limit = this.getEffectiveLimit();
+        if (limit !== null) {
+            ordered += ' LIMIT ?';
+            values.push(limit);
+        }
+        const account = this.config.account === undefined ? await getICloudAccount() : this.config.account;
+        // With linkArtists, Shazams go out a batch at a time, after their lookups.
+        let batch = [];
+        for (const row of iterateRows(this.db.prepare(ordered), ...values)) {
+            batch.push(this.shazamOf(row));
+            if (batch.length < (this.lookup ? LOOKUP_BATCH : 1))
+                continue;
+            yield* await this.recordsOf(batch, account);
+            batch = [];
+        }
+        yield* await this.recordsOf(batch, account);
+    }
+    async recordsOf(shazams, account) {
+        if (this.lookup) {
+            const songs = shazams
+                .filter(shazam => shazam.appleMusicID)
+                .map(shazam => ({ id: shazam.appleMusicID, country: countryOf(shazam.appleMusicURL) }));
+            const artists = await this.lookup.artistsOf(songs);
+            for (const shazam of shazams) {
+                const artist = artists.get(shazam.appleMusicID ?? '');
+                if (artist)
+                    shazam.appleMusicArtist = artist;
+            }
+        }
+        return shazams.map(shazam => this.createRecord(shazam, { account }));
+    }
+    shazamOf(row) {
+        const genres = this.decode(row.genres, 'genres');
+        const response = this.decode(row.rawSongResponse, 'rawSongResponse');
+        const songData = response?.SHMediaLibraryDataStoreRawResponseSongsData;
+        return {
+            recognitionID: row.id,
+            syncID: row.syncID ?? null,
+            date: appleDate(row.date),
+            title: row.title ?? null,
+            subtitle: row.subtitle ?? null,
+            shazamKey: row.shazamKey ?? null,
+            shazamURL: row.shazamURL ?? null,
+            providerName: row.providerName ?? null,
+            latitude: row.latitude ?? null,
+            longitude: row.longitude ?? null,
+            artworkURL: row.artworkURL ?? null,
+            appleMusicID: row.appleMusicID ?? null,
+            appleMusicURL: row.appleMusicURL ?? null,
+            isrc: row.isrc ?? null,
+            albumName: row.albumName ?? null,
+            releaseDate: row.releaseDate === null ? null : appleDate(row.releaseDate).slice(0, 10),
+            explicit: row.explicit === null ? null : row.explicit === 1,
+            genres: Array.isArray(genres) ? genres.filter(g => typeof g === 'string') : [],
+            song: songData instanceof Uint8Array ? this.parseSong(songData) : null,
+        };
+    }
+    // A blob that doesn't decode loses only that field, not the Shazam.
+    decode(blob, field) {
+        if (!blob)
+            return null;
+        try {
+            return unarchive(blob);
+        }
+        catch (error) {
+            this.logger.warn(`Can't read a Shazam's ${field}: ${error.message}`);
+            return null;
+        }
+    }
+    parseSong(data) {
+        try {
+            return JSON.parse(Buffer.from(data).toString('utf8'));
+        }
+        catch (error) {
+            this.logger.warn(`Can't read a Shazam's Apple Music song: ${error.message}`);
+            return null;
+        }
+    }
+    async determineCount() {
+        if (!this.db)
+            return null;
+        try {
+            const { sql, values } = this.query('COUNT(*) AS n');
+            return getRow(this.db.prepare(sql), ...values)?.n ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+function appleDate(seconds) {
+    return new Date((seconds + APPLE_EPOCH_OFFSET_SECONDS) * 1000).toISOString();
+}

package/dist/connectors/ShazamTransformer.d.ts

@@ -0,0 +1,14 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+/**
+ *   ListenAction  agent: you   object: MusicRecording   location?
+ *     MusicRecording  (Shazam's copy, by its Shazam key)
+ *       artist: MusicGroup (Apple Music's, by its ID, or Shazam's artist line)
+ *       inAlbum: MusicAlbum (Apple Music's, by its ID)
+ *       sameAs: MusicRecording (ISRC), MusicRecording (Apple Music)
+ */
+export default class ShazamTransformer extends ChronicleTransformer {
+    static source: string;
+    transform(record: Record): Promise<ActionAndChildren[]>;
+}
+//# sourceMappingURL=ShazamTransformer.d.ts.map

package/dist/connectors/ShazamTransformer.js

@@ -0,0 +1,163 @@
+import { ChronicleTransformer, ISRC_SOURCE, createImageObject, normalizeIsrc, } from '@chronicle.app/etl';
+import { buildICloudPersonSchema } from '@chronicle.app/icloud';
+const SOURCE = 'shazam';
+/** Apple Music's catalog: the namespace of its song, album, and artist IDs. */
+const APPLE_MUSIC = 'apple-music';
+// Apple files every song under its root genre as well as its own.
+const ROOT_GENRE = 'Music';
+// The artwork Shazam shows for a song it has no cover for.
+const NO_ARTWORK = /^https:\/\/images\.shazam\.com\/static\/coverart\/unavailable/;
+/**
+ *   ListenAction  agent: you   object: MusicRecording   location?
+ *     MusicRecording  (Shazam's copy, by its Shazam key)
+ *       artist: MusicGroup (Apple Music's, by its ID, or Shazam's artist line)
+ *       inAlbum: MusicAlbum (Apple Music's, by its ID)
+ *       sameAs: MusicRecording (ISRC), MusicRecording (Apple Music)
+ */
+export default class ShazamTransformer extends ChronicleTransformer {
+    static source = SOURCE;
+    async transform(record) {
+        if (record.extraction.recordType !== 'listens')
+            return [];
+        const shazam = record.data;
+        // Without an iCloud account the listener can't be identified, so omit them.
+        const listener = await buildICloudPersonSchema(record.context.account);
+        const recording = buildRecording(shazam);
+        const location = locationOf(shazam);
+        const action = {
+            '@type': 'ListenAction',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: SOURCE,
+            sourceId: shazam.recognitionID,
+            timestamp: new Date(shazam.date),
+            ...(listener && { agent: listener }),
+            ...(recording && { object: recording }),
+            ...(location && { location }),
+        };
+        return [action];
+    }
+}
+/** Shazam's copy of the song, keyed by its Shazam key and named as Shazam names it. */
+function buildRecording(shazam) {
+    if (!shazam.shazamKey)
+        return null;
+    const attributes = shazam.song?.attributes ?? {};
+    const { durationInMillis } = attributes;
+    const genres = shazam.genres.filter(genre => genre !== ROOT_GENRE);
+    const album = buildAlbum(shazam);
+    const cover = coverOf(shazam.artworkURL);
+    const artist = buildArtist(shazam);
+    const sameAs = [];
+    const isrc = shazam.isrc && normalizeIsrc(shazam.isrc);
+    if (isrc)
+        sameAs.push(reference(ISRC_SOURCE, isrc));
+    if (shazam.appleMusicID) {
+        sameAs.push({
+            ...reference(APPLE_MUSIC, shazam.appleMusicID),
+            ...(shazam.appleMusicURL && { url: withoutTracking(shazam.appleMusicURL) }),
+        });
+    }
+    return {
+        '@type': 'MusicRecording',
+        '@key': ['@type', 'source', 'sourceId'],
+        source: SOURCE,
+        sourceId: shazam.shazamKey,
+        ...(shazam.title && { name: shazam.title }),
+        ...(artist && { artist: [artist] }),
+        ...(album && { inAlbum: album }),
+        ...(typeof durationInMillis === 'number' && {
+            duration: `PT${Math.floor(durationInMillis / 1000)}S`,
+        }),
+        ...(genres.length > 0 && { genre: genres }),
+        ...(shazam.releaseDate && { datePublished: shazam.releaseDate }),
+        ...(cover && { emblem: cover }),
+        ...(sameAs.length > 0 && { sameAs }),
+    };
+}
+/**
+ * The song's main artist on Apple Music, by its ID, when `linkArtists` looked
+ * it up. Otherwise the artist line as Shazam words it, such as `Artist Feat.
+ * Guest`, keyed by that name, since Shazam gives no artist ID.
+ */
+function buildArtist(shazam) {
+    const linked = shazam.appleMusicArtist;
+    if (linked) {
+        return {
+            '@type': 'MusicGroup',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: APPLE_MUSIC,
+            sourceId: linked.id,
+            name: linked.name,
+            ...(linked.url && { url: linked.url }),
+        };
+    }
+    if (!shazam.subtitle)
+        return null;
+    return {
+        '@type': 'MusicGroup',
+        '@key': ['@type', 'source', 'name'],
+        source: SOURCE,
+        name: shazam.subtitle,
+    };
+}
+/** The album is Apple Music's, keyed by the album ID in the song's Apple Music link. */
+function buildAlbum(shazam) {
+    const link = shazam.appleMusicURL ?? shazam.song?.attributes?.url;
+    const albumID = link?.match(/\/album\/(?:[^/?]+\/)?(\d+)/)?.[1];
+    if (!shazam.albumName || !albumID)
+        return null;
+    return {
+        '@type': 'MusicAlbum',
+        '@key': ['@type', 'source', 'sourceId'],
+        source: APPLE_MUSIC,
+        sourceId: albumID,
+        name: shazam.albumName,
+    };
+}
+function reference(source, sourceId) {
+    return {
+        '@type': 'MusicRecording',
+        '@key': ['@type', 'source', 'sourceId'],
+        source,
+        sourceId,
+    };
+}
+/**
+ * Where the song was recognized. A device without a fix records 0, 0 or
+ * -180, -180, which is no place on Earth.
+ */
+function locationOf({ latitude, longitude }) {
+    if (latitude === null || longitude === null)
+        return null;
+    if (latitude === 0 && longitude === 0)
+        return null;
+    if (Math.abs(latitude) > 90 || Math.abs(longitude) > 180)
+        return null;
+    return { '@type': 'Location', latitude, longitude };
+}
+/**
+ * The cover. Apple Music covers are stored as HEIC, which most browsers can't
+ * show, and Apple's image server gives the same size as a JPEG.
+ */
+function coverOf(link) {
+    if (!link || NO_ARTWORK.test(link))
+        return null;
+    const url = link.replace(/^(https:\/\/[^/]+\.mzstatic\.com\/.*bb)\.heic$/, '$1.jpg');
+    const size = url.match(/\/(\d+)x(\d+)bb\.\w+$/);
+    return createImageObject({
+        url,
+        ...(size && { width: Number(size[1]), height: Number(size[2]) }),
+    });
+}
+/** An Apple Music link without its campaign parameters (`itscg`, `itsct`). */
+function withoutTracking(link) {
+    try {
+        const url = new URL(link);
+        const kept = [...url.searchParams].filter(([name]) => !name.startsWith('its'));
+        url.search = new URLSearchParams(kept).toString();
+        return url.toString();
+    }
+    catch {
+        return link;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ShazamExtractor } from './connectors/ShazamExtractor.js';
+export { default as ShazamTransformer } from './connectors/ShazamTransformer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,3 @@
+// Export the extractor and transformer for plugin scanning
+export { ShazamExtractor } from './connectors/ShazamExtractor.js';
+export { default as ShazamTransformer } from './connectors/ShazamTransformer.js';

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "@chronicle.app/shazam",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.lib.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src --ext .ts,.js",
+    "test": "node --test src/*.test.js",
+    "shapes": "node src/shapes.test.js --update"
+  },
+  "keywords": [
+    "chronicle",
+    "shazam",
+    "music"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "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",
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2"
+  },
+  "homepage": "https://chronicle.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chronicle-app/chronicle.git",
+    "directory": "plugins/shazam"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@chronicle.app/etl-sqlite": "0.4.0",
+    "@chronicle.app/icloud": "0.4.0",
+    "zod": "^3.24.1"
+  },
+  "peerDependencies": {
+    "@chronicle.app/etl": ">=0.1.0 <1.0.0",
+    "@chronicle.app/schema": ">=0.1.0 <1.0.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "chronicle": {
+    "plugin": true,
+    "sources": {
+      "shazam": {
+        "strategies": {
+          "app-db": {
+            "delivery": "local",
+            "recordTypes": [
+              "listens"
+            ],
+            "default": true
+          }
+        },
+        "platforms": [
+          "darwin"
+        ]
+      }
+    },
+    "deepLinks": {
+      "shazam": {
+        "MusicRecording": "https://www.shazam.com/track/{sourceId}"
+      }
+    }
+  }
+}