@chronicle.app/apple-voice-memos 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,59 @@
-# Temporary Holding Version
+# @chronicle.app/apple-voice-memos
 
-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.
+Your Voice Memos recordings and the transcripts Voice Memos made of them, from the library macOS keeps in step with iCloud.
+
+## Usage
+
+```sh
+chronicle extract apple-voice-memos
+chronicle extract apple-voice-memos --since 2024-01-01 --until 2025-01-01
+chronicle extract apple-voice-memos --input "/path/to/Recordings/CloudRecordings.db"
+```
+
+The library is `~/Library/Group Containers/group.com.apple.VoiceMemos.shared/Recordings/CloudRecordings.db`, opened read-only with built-in `node:sqlite`, and the audio files sit beside it. Voice Memos syncs the library through iCloud, so it holds the recordings made on every device signed in to your account: your iPhone, iPad, Apple Watch, and Mac. With `--input`, the audio files are read from the folder the database is in.
+
+Recordings come out newest first, and `--since` and `--until` bound when each one started. A run reads only the library and its files, offline.
+
+## Schema
+
+| Voice Memos thing             | Chronicle node    | Key                                                                                                                 | Properties                                                                                                                                                                            |
+| ----------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Recording a memo              | `RecordAction`    | `@type`, `source`, `sourceId` (the recording's UUID)                                                                | `agent` (you), `instrument` (the OS release and the kind of device), `result` (the recording), `timestamp` (when recording started)                                                   |
+| The OS release the file names | `OperatingSystem` | `@type`, `source` (`apple-voice-memos`), `handle` (the tag as written, such as `Watch Version 11.5 (Build 22T572)`) |                                                                                                                                                                                       |
+| The kind of device            | `ProductModel`    | `source` (`wikidata`), `sourceId` (its Wikidata ID, such as `Q2766`)                                                | `name` (`iPhone`, `Apple Watch`, or `Mac`), `url` (its Wikidata page)                                                                                                                 |
+| The recording                 | `AudioObject`     | `@type`, `source` (`apple-voice-memos`), `sourceId` (its UUID)                                                      | `name` (its title), `duration`, `contentPath` and `mimeType` (its audio file, when it's on this Mac: `audio/mp4` for `.m4a`, `audio/x-quicktime` for `.qta`), `transcript` (its text) |
+| 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
+
+**Recording a memo is a `RecordAction`.** Its `result` is the recording, keyed by the recording's UUID. Voice Memos writes the same UUID into the audio file, so the recording keeps its key wherever its file is read from. The action's `timestamp` is when recording started, which the audio file's own `date` tag agrees with.
+
+**No `endTime`.** Voice Memos keeps the recording's duration but not when recording stopped. A memo can be paused, resumed later, or trimmed, so the start plus the duration isn't always when recording stopped, and the action has none. The recording's `duration` is its length.
+
+**A file or transcript that doesn't read is reported.** The memo is kept, and the run's summary says how many didn't read, since that's how a format Voice Memos changed would show.
+
+**Each record is read as of the library's last change.** A title or transcript can change long after the recording is made, so a record's observation time is when the library, or its write-ahead log, last changed, not when recording started. An unchanged library gives the same records on every run.
+
+**The recording's file, when it's on this Mac.** A recording's `contentPath` is its audio file, captured at ingest. iCloud can keep a recording's audio in the cloud alone, leaving no file or an empty one; that recording has no `contentPath`. Older recordings are `.m4a` files, and newer ones `.qta`, QuickTime audio, which macOS declares as `audio/x-quicktime`.
+
+**Deleted memos are left out.** A memo in Recently Deleted has an eviction date in the library, and isn't extracted.
+
+**The instrument is what the file says, not which device.** The audio file's encoder tag, such as `com.apple.VoiceMemos (Watch Version 11.5 (Build 22T572))`, names the kind of device and the OS release that wrote the file, but never which device: no device name, model, or serial. The action's `instrument` is that release, an `OperatingSystem` whose `handle` is the tag as written, without the app's name, which the source already implies. Beside it is the kind of device, a `ProductModel` keyed by its Wikidata ID, so other sources can name the same one: [iPhone](https://www.wikidata.org/wiki/Q2766), [Apple Watch](https://www.wikidata.org/wiki/Q18010946), or [Mac](https://www.wikidata.org/wiki/Q75687) for an older `Mac OS X` tag. A device identified only by its kind would merge every iPhone you've owned into one, so there is no `Device`. Another source that knows which device it was can add it to the action's instruments.
+
+- A tag that doesn't name the kind of device gives only the release. `iOS 13.1.2` could be an iPhone or an iPad, and `iPad Version …` could be a Mac: Voice Memos on a Mac is the iPad app, so a Mac's tag says `iPad`, with macOS's version and build.
+- A tag that doesn't name an OS release, such as `aphone5 (null)`, which appears on memos from 2020 to 2022, gives no instrument.
+- The tag is from whichever device last wrote the file. iOS 13 rewrote older recordings with its own tag, in the older `iOS 13.1.2` form. A tag in an older form (`iOS …` or `Mac OS X …`) naming a release that came out after the recording was made is from that rewrite, and gives no instrument. Voice Memos stopped writing those forms in 2020, so the plugin's list of their release dates is complete. A tag in the current form (`iPhone Version …`) is taken as written, with no dates to keep up.
+- Editing a memo on another device, such as trimming it on a Mac, rewrites the tag with that device's release, and nothing in the file tells. The memo is then credited to the device that edited it.
+- The extracted record keeps the whole tag.
+
+**The words spoken are the recording's `transcript`.** Voice Memos transcribes recordings itself, from iOS 18 on. The text is the recording's `transcript`, plain text with no timings, not its `body`, since it's a machine's reading of what was said rather than text anyone wrote. It's Voice Memos' own transcript: when Voice Memos makes a new one, such as after a trim, it takes the old one's place. A transcript from another speech recognizer belongs to that source's own record of the recording, so it never replaces Apple's. A recording Voice Memos heard no speech in has an empty transcript, or only spaces, which is left out. The extracted record keeps when each word was spoken and the transcript's locale, which have no Chronicle terms yet.
+
+**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 files are read in the plugin.** A transcript is JSON inside the audio file: a `.m4a` keeps it in its audio track's `tsrp` box, and a `.qta` in its track's QuickTime metadata under `com.apple.VoiceMemos.tsrp`. `mp4.ts` reads only the movie header, not the audio. The transcript lists its text in runs, each with when it was spoken; the extracted record keeps the runs and the locale. A file or transcript that doesn't read is logged and left out; the recording is kept.
+
+## Tests
+
+The tests are smoke tests over a synthetic `CloudRecordings.db` and synthetic `.m4a` and `.qta` files with no real audio, written by the fixture, and pass an explicit iCloud account. They never read the host's Voice Memos library or iCloud account.

package/dist/connectors/AppleVoiceMemosExtractor.d.ts

@@ -0,0 +1,65 @@
+import { Record } from '@chronicle.app/etl';
+import { SqliteExtractor } from '@chronicle.app/etl-sqlite';
+import { type Transcript } from '../transcript.js';
+import AppleVoiceMemosTransformer from './AppleVoiceMemosTransformer.js';
+/** One recording as the library row and its file give it, named after the row's Core Data attributes. */
+export interface VoiceMemo {
+    /** The recording's UUID, which Voice Memos also writes into the audio file. */
+    uniqueID: string;
+    /** When recording started, in UTC. */
+    date: string;
+    /** How long the recording lasts, in seconds, when the library says. */
+    duration: number | null;
+    /** The title. `New Recording 3` and the like until it's renamed. */
+    title: string | null;
+    /** The audio file's name in the library's folder, which starts with the local start time. */
+    path: string | null;
+    flags: number;
+    /** The audio file's absolute path, when it's on this Mac. */
+    file: string | null;
+    /** The file's `©too` tag: the app, and the kind of device and OS version that last wrote the file. */
+    encoder: string | null;
+    /** The transcript Voice Memos made, when the file has one. */
+    transcript: Transcript | null;
+}
+/**
+ * The Voice Memos library. It syncs through iCloud, so it holds the
+ * recordings made on every device signed in to the account. Their audio
+ * files sit beside the database.
+ */
+export declare class AppleVoiceMemosExtractor extends SqliteExtractor<typeof AppleVoiceMemosExtractor> {
+    static source: string;
+    static description: string;
+    static delivery: "local";
+    static strategy: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static defaultTransformer: typeof AppleVoiceMemosTransformer;
+    static newestFirst: boolean;
+    static schema: any;
+    private libraryChanged;
+    private unreadable;
+    setup(): Promise<void>;
+    /**
+     * When the library last changed, not when the run started. A recording's
+     * title and transcript can change after it's recorded, so each record is
+     * observed as of the library it was read from. An unchanged library gives
+     * the same time on every run, so its records come out the same.
+     */
+    protected asOfTime(): Date;
+    /** The recording's UUID: the same in the library and in the audio file. */
+    keyOf(record: Record): string | null;
+    occurredAt(record: Record): Date | undefined;
+    private query;
+    extract(): AsyncGenerator<Record>;
+    private memoOf;
+    private readFile;
+    private parse;
+    /**
+     * Say when files or transcripts didn't read. The memos are kept, but a
+     * format Voice Memos changed would otherwise only show in the log.
+     */
+    private hintUnreadable;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=AppleVoiceMemosExtractor.d.ts.map

package/dist/connectors/AppleVoiceMemosExtractor.js

@@ -0,0 +1,190 @@
+import { statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+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 { readRecordingMetadata } from '../mp4.js';
+import { parseTranscript } from '../transcript.js';
+import AppleVoiceMemosTransformer from './AppleVoiceMemosTransformer.js';
+const DEFAULT_DB = `${process.env.HOME}/Library/Group Containers/group.com.apple.VoiceMemos.shared/Recordings/CloudRecordings.db`;
+// since/until bounds land on ZDATE, which is seconds since the Apple epoch.
+const appleBound = (date) => unixToSafariTimestamp(date.getTime() / 1000);
+// A memo moved to Recently Deleted has an eviction date. It's left out.
+const NOT_DELETED = 'ZEVICTIONDATE IS NULL';
+/**
+ * The Voice Memos library. It syncs through iCloud, so it holds the
+ * recordings made on every device signed in to the account. Their audio
+ * files sit beside the database.
+ */
+export class AppleVoiceMemosExtractor extends SqliteExtractor {
+    static source = 'apple-voice-memos';
+    static description = 'Your Voice Memos recordings and their transcripts';
+    static delivery = 'local';
+    static strategy = 'app-db';
+    static recordTypes = ['recordings'];
+    static default = true;
+    static defaultTransformer = AppleVoiceMemosTransformer;
+    static newestFirst = true;
+    static schema = SqliteExtractor.schema.omit({ input: true }).extend({
+        input: z.string().describe('Path to CloudRecordings.db').default(DEFAULT_DB),
+        account: z
+            .object({
+            accountID: z.string(),
+            email: z.string(),
+            displayName: z.string(),
+            dsid: z.string().optional(),
+        })
+            .nullable()
+            .optional(),
+    });
+    libraryChanged = null;
+    // Files and transcripts that didn't read this run, for the run's summary.
+    unreadable = { files: 0, transcripts: 0 };
+    async setup() {
+        await super.setup();
+        this.libraryChanged = lastChanged(this.config.input);
+    }
+    /**
+     * When the library last changed, not when the run started. A recording's
+     * title and transcript can change after it's recorded, so each record is
+     * observed as of the library it was read from. An unchanged library gives
+     * the same time on every run, so its records come out the same.
+     */
+    asOfTime() {
+        return this.libraryChanged ?? super.asOfTime();
+    }
+    /** The recording's UUID: the same in the library and in the audio file. */
+    keyOf(record) {
+        return record.data.uniqueID ?? null;
+    }
+    occurredAt(record) {
+        return new Date(record.data.date);
+    }
+    query(select) {
+        const range = timeRangeConditions('ZDATE', this.config, { convert: appleBound });
+        const where = [
+            'ZUNIQUEID IS NOT NULL',
+            'ZDATE IS NOT NULL',
+            NOT_DELETED,
+            ...range.conditions,
+        ].join(' AND ');
+        return { sql: `SELECT ${select} FROM ZCLOUDRECORDING WHERE ${where}`, values: range.values };
+    }
+    async *extract() {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const { sql, values } = this.query(`
+      ZUNIQUEID AS uniqueID, ZDATE AS date, ZDURATION AS duration,
+      ZENCRYPTEDTITLE AS title, ZPATH AS path, ZFLAGS AS flags`);
+        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;
+        const folder = dirname(resolve(this.config.input));
+        this.unreadable = { files: 0, transcripts: 0 };
+        for (const row of iterateRows(this.db.prepare(ordered), ...values)) {
+            yield this.createRecord(this.memoOf(row, folder), { account }, { assertedAt: this.asOfTime() });
+        }
+        this.hintUnreadable();
+    }
+    memoOf(row, folder) {
+        const file = row.path ? onDisk(join(folder, row.path)) : null;
+        const metadata = file ? this.readFile(file) : null;
+        return {
+            uniqueID: row.uniqueID,
+            date: appleDate(row.date),
+            duration: row.duration ?? null,
+            title: row.title ?? null,
+            path: row.path ?? null,
+            flags: row.flags ?? 0,
+            file,
+            encoder: metadata?.encoder ?? null,
+            transcript: metadata?.transcript ? this.parse(metadata.transcript) : null,
+        };
+    }
+    // A file that doesn't read loses only its tags and transcript, not the memo.
+    readFile(file) {
+        try {
+            return readRecordingMetadata(file);
+        }
+        catch (error) {
+            this.logger.warn(`Can't read a voice memo's audio file: ${error.message}`);
+            this.unreadable.files++;
+            return null;
+        }
+    }
+    parse(json) {
+        try {
+            return parseTranscript(json);
+        }
+        catch (error) {
+            this.logger.warn(`Can't read a voice memo's transcript: ${error.message}`);
+            this.unreadable.transcripts++;
+            return null;
+        }
+    }
+    /**
+     * Say when files or transcripts didn't read. The memos are kept, but a
+     * format Voice Memos changed would otherwise only show in the log.
+     */
+    hintUnreadable() {
+        const { files, transcripts } = this.unreadable;
+        const action = 'Voice Memos may have changed how it stores recordings. Update Chronicle, and report it if that doesn’t help.';
+        if (files > 0) {
+            const memos = files === 1
+                ? '1 audio file couldn’t be read, so its memo has'
+                : `${files} audio files couldn’t be read, so their memos have`;
+            this.hint(`${memos} no transcript or device`, { action });
+        }
+        if (transcripts > 0) {
+            const memos = transcripts === 1
+                ? '1 transcript couldn’t be read, so its memo has'
+                : `${transcripts} transcripts couldn’t be read, so their memos have`;
+            this.hint(`${memos} none`, { action });
+        }
+    }
+    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;
+        }
+    }
+}
+/**
+ * The file, when it's on this Mac. A recording iCloud hasn't downloaded has
+ * no file, or an empty one.
+ */
+function onDisk(file) {
+    try {
+        return statSync(file).size > 0 ? file : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * When the library last changed: the database, or its write-ahead log, which
+ * holds changes Core Data hasn't yet written back.
+ */
+function lastChanged(database) {
+    const times = [database, `${database}-wal`].flatMap(file => {
+        try {
+            return [statSync(file).mtime.getTime()];
+        }
+        catch {
+            return [];
+        }
+    });
+    return new Date(Math.max(...times));
+}
+function appleDate(seconds) {
+    return new Date((seconds + APPLE_EPOCH_OFFSET_SECONDS) * 1000).toISOString();
+}

package/dist/connectors/AppleVoiceMemosTransformer.d.ts

@@ -0,0 +1,13 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+/**
+ *   RecordAction  agent: you   timestamp (when recording started)
+ *     instrument?: OperatingSystem  (the release the file names, as written)
+ *                  ProductModel?    (the kind of device, by its Wikidata ID)
+ *     result: AudioObject  (the recording, by its UUID)   transcript?
+ */
+export default class AppleVoiceMemosTransformer extends ChronicleTransformer {
+    static source: string;
+    transform(record: Record): Promise<ActionAndChildren[]>;
+}
+//# sourceMappingURL=AppleVoiceMemosTransformer.d.ts.map

package/dist/connectors/AppleVoiceMemosTransformer.js

@@ -0,0 +1,95 @@
+import { extname } from 'node:path';
+import { ChronicleTransformer } from '@chronicle.app/etl';
+import { buildICloudPersonSchema } from '@chronicle.app/icloud';
+import { readEncoder } from '../encoder.js';
+const SOURCE = 'apple-voice-memos';
+// What each kind of recording file is. `.qta` is a QuickTime audio movie,
+// which macOS declares as `audio/x-quicktime`.
+const MIME_TYPES = {
+    '.m4a': 'audio/mp4',
+    '.qta': 'audio/x-quicktime',
+};
+/**
+ *   RecordAction  agent: you   timestamp (when recording started)
+ *     instrument?: OperatingSystem  (the release the file names, as written)
+ *                  ProductModel?    (the kind of device, by its Wikidata ID)
+ *     result: AudioObject  (the recording, by its UUID)   transcript?
+ */
+export default class AppleVoiceMemosTransformer extends ChronicleTransformer {
+    static source = SOURCE;
+    async transform(record) {
+        if (record.extraction.recordType !== 'recordings')
+            return [];
+        const memo = record.data;
+        // Without an iCloud account the recorder can't be identified, so omit them.
+        const recorder = await buildICloudPersonSchema(record.context.account);
+        const instrument = buildInstrument(memo);
+        // Voice Memos keeps when recording started but not when it stopped: a
+        // memo can be paused, resumed later, or trimmed, so the start plus the
+        // recording's duration isn't always the end.
+        const action = {
+            '@type': 'RecordAction',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: SOURCE,
+            sourceId: memo.uniqueID,
+            timestamp: new Date(memo.date),
+            ...(recorder && { agent: recorder }),
+            ...(instrument.length > 0 && { instrument }),
+            result: buildRecording(memo),
+        };
+        return [action];
+    }
+}
+/**
+ * What the recording was made on, from its file's encoder tag: the OS release,
+ * as the tag writes it, and the kind of device when the tag names one. The
+ * tag never says which device. A tag that doesn't name an OS release, or that
+ * iOS 13 left when it rewrote an older file, gives none.
+ */
+function buildInstrument(memo) {
+    const recorder = memo.encoder ? readEncoder(memo.encoder, new Date(memo.date)) : null;
+    if (!recorder)
+        return [];
+    const release = {
+        '@type': 'OperatingSystem',
+        '@key': ['@type', 'source', 'handle'],
+        source: SOURCE,
+        handle: recorder.release,
+    };
+    if (!recorder.line)
+        return [release];
+    const { wikidataId, name } = recorder.line;
+    return [
+        release,
+        // Keyed like an ISBN: by the ID alone, so anything naming the same item
+        // merges with it. Its page's address, as a browser records it, joins a
+        // visit to that page.
+        {
+            '@type': 'ProductModel',
+            '@key': ['source', 'sourceId'],
+            source: 'wikidata',
+            sourceId: wikidataId,
+            name,
+            url: `https://www.wikidata.org/wiki/${wikidataId}`,
+        },
+    ];
+}
+/**
+ * The recording, keyed by its UUID, with its file when it's on this Mac and
+ * the transcript Voice Memos made, unless it heard no speech.
+ */
+function buildRecording(memo) {
+    const mimeType = memo.file ? MIME_TYPES[extname(memo.file).toLowerCase()] : undefined;
+    const transcript = memo.transcript?.text.trim();
+    return {
+        '@type': 'AudioObject',
+        '@key': ['@type', 'source', 'sourceId'],
+        source: SOURCE,
+        sourceId: memo.uniqueID,
+        ...(memo.title && { name: memo.title }),
+        ...(memo.duration !== null && { duration: `PT${Math.floor(memo.duration)}S` }),
+        ...(memo.file && { contentPath: memo.file }),
+        ...(mimeType && { mimeType }),
+        ...(transcript && { transcript }),
+    };
+}

package/dist/encoder.d.ts

@@ -0,0 +1,21 @@
+/** What a recording's encoder tag says about where it was recorded. */
+export interface Recorder {
+    /** The OS release, as the tag inside `com.apple.VoiceMemos (…)` writes it, such as `Watch Version 11.5 (Build 22T572)`. */
+    release: string;
+    /** The kind of device, when the tag names one. */
+    line: ProductLine | null;
+}
+export interface ProductLine {
+    /** Its Wikidata ID, such as `Q2766`, which other sources can name too. */
+    wikidataId: string;
+    name: string;
+}
+/**
+ * Read a recording's encoder tag, such as
+ * `com.apple.VoiceMemos (Watch Version 11.5 (Build 22T572))`. The tag names
+ * the OS release that wrote the file, and sometimes the kind of device, but
+ * never which device. `null` when it isn't Voice Memos' tag, when it doesn't
+ * name an OS release, or when it's from iOS 13's rewrite of an older file.
+ */
+export declare function readEncoder(tag: string, recorded: Date): Recorder | null;
+//# sourceMappingURL=encoder.d.ts.map

package/dist/encoder.js

@@ -0,0 +1,54 @@
+const LINES = {
+    iPhone: { wikidataId: 'Q2766', name: 'iPhone' },
+    Watch: { wikidataId: 'Q18010946', name: 'Apple Watch' },
+    Mac: { wikidataId: 'Q75687', name: 'Mac' },
+};
+// The tag's forms. `<device> Version <version> (Build <build>)` is the
+// current one, and `iOS <version>` and `Mac OS X <version>` are older ones.
+const TAG = /^com\.apple\.VoiceMemos \((.+)\)$/;
+const VERSIONED = /^(iPhone|iPad|Watch) Version \d/;
+const IOS = /^iOS (\d+)/;
+const MAC_OS_X = /^Mac OS X (10\.\d+)/;
+// When each release that wrote an older form came out. iOS 13 rewrote older
+// recordings with its own tag, so an older-form tag naming a release that
+// came out after the recording was made is from that rewrite. Voice Memos
+// stopped writing these forms in 2020, so the list doesn't grow.
+const OLDER_FORM_RELEASED = {
+    'iOS 12': '2018-09-17',
+    'iOS 13': '2019-09-19',
+    'Mac OS X 10.14': '2018-09-24',
+    'Mac OS X 10.15': '2019-10-07',
+};
+/**
+ * Read a recording's encoder tag, such as
+ * `com.apple.VoiceMemos (Watch Version 11.5 (Build 22T572))`. The tag names
+ * the OS release that wrote the file, and sometimes the kind of device, but
+ * never which device. `null` when it isn't Voice Memos' tag, when it doesn't
+ * name an OS release, or when it's from iOS 13's rewrite of an older file.
+ */
+export function readEncoder(tag, recorded) {
+    const release = TAG.exec(tag)?.[1];
+    if (!release)
+        return null;
+    const versioned = VERSIONED.exec(release);
+    if (versioned) {
+        // `iPad` names no kind of device: Voice Memos on a Mac is the iPad app, so
+        // a Mac's tag says `iPad` too.
+        const device = versioned[1];
+        return { release, line: device === 'iPad' ? null : LINES[device] };
+    }
+    const ios = IOS.exec(release);
+    const macOSX = MAC_OS_X.exec(release);
+    let older;
+    if (ios)
+        older = `iOS ${ios[1]}`;
+    else if (macOSX)
+        older = `Mac OS X ${macOSX[1]}`;
+    else
+        return null;
+    const released = OLDER_FORM_RELEASED[older];
+    if (released && recorded < new Date(released))
+        return null;
+    // `iOS 13.1.2` doesn't say whether it was an iPhone or an iPad.
+    return { release, line: macOSX ? LINES.Mac : null };
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/mp4.d.ts

@@ -0,0 +1,16 @@
+/** What Voice Memos writes into a recording's file besides the audio. */
+export interface RecordingMetadata {
+    /** The `©too` tag: the app, and the kind of device and OS version that last wrote the file. */
+    encoder: string | null;
+    /** The transcript's JSON, as Voice Memos stores it. */
+    transcript: string | null;
+}
+/**
+ * Read the encoder tag and the transcript from a recording. Both formats are
+ * QuickTime movies: an `.m4a` keeps its transcript in a track's `udta/tsrp`
+ * box, and a `.qta` in a track's metadata under `com.apple.VoiceMemos.tsrp`.
+ * Only the movie header (`moov`) is read, not the audio. Null when the file is
+ * missing, empty, or has no movie header.
+ */
+export declare function readRecordingMetadata(path: string): RecordingMetadata | null;
+//# sourceMappingURL=mp4.d.ts.map

package/dist/mp4.js

@@ -0,0 +1,172 @@
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
+// The metadata key a `.qta` file stores its transcript under.
+const TRANSCRIPT_KEY = 'com.apple.VoiceMemos.tsrp';
+// A movie header far larger than any recording's is a damaged file.
+const MAX_MOOV = 64 * 1024 * 1024;
+/**
+ * Read the encoder tag and the transcript from a recording. Both formats are
+ * QuickTime movies: an `.m4a` keeps its transcript in a track's `udta/tsrp`
+ * box, and a `.qta` in a track's metadata under `com.apple.VoiceMemos.tsrp`.
+ * Only the movie header (`moov`) is read, not the audio. Null when the file is
+ * missing, empty, or has no movie header.
+ */
+export function readRecordingMetadata(path) {
+    const moov = readMoov(path);
+    if (!moov)
+        return null;
+    return { encoder: encoderOf(moov), transcript: transcriptOf(moov) };
+}
+/** The `moov` box's contents, found by reading only the top-level box headers. */
+function readMoov(path) {
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    try {
+        const length = fstatSync(fd).size;
+        const header = Buffer.alloc(16);
+        let at = 0;
+        while (at + 8 <= length) {
+            readSync(fd, header, 0, 16, at);
+            const box = boxAt(header, 0, length - at);
+            if (!box)
+                throw new Error(`Damaged box at byte ${at}`);
+            if (box.type === 'moov') {
+                const size = box.end - box.start;
+                if (size > MAX_MOOV)
+                    throw new Error(`Movie header too large (${size} bytes)`);
+                const moov = Buffer.alloc(size);
+                readSync(fd, moov, 0, size, at + box.start);
+                return moov;
+            }
+            at += box.end;
+        }
+        return null;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * The box at `at`, with offsets relative to `buf`. A 32-bit size of 1 means a
+ * 64-bit size follows the type, and 0 means the box runs to `end`. Null when
+ * the header doesn't fit.
+ */
+function boxAt(buf, at, end) {
+    if (at + 8 > end)
+        return null;
+    let size = buf.readUInt32BE(at);
+    const type = buf.toString('latin1', at + 4, at + 8);
+    let header = 8;
+    if (size === 1) {
+        if (at + 16 > buf.length)
+            return null;
+        size = Number(buf.readBigUInt64BE(at + 8));
+        header = 16;
+    }
+    else if (size === 0) {
+        size = end - at;
+    }
+    if (size < header || at + size > end)
+        return null;
+    return { type, offset: at, start: at + header, end: at + size };
+}
+/** The boxes inside `start`..`end`, optionally only those of one type. */
+function childrenOf(buf, start, end, type) {
+    const boxes = [];
+    for (let at = start; at < end;) {
+        const box = boxAt(buf, at, end);
+        if (!box)
+            break;
+        if (!type || box.type === type)
+            boxes.push(box);
+        at = box.end;
+    }
+    return boxes;
+}
+/**
+ * Where a `meta` box's children start. An ISO `meta` box opens with a version
+ * and flags word, which is zero; a QuickTime one starts with its first child,
+ * whose size isn't.
+ */
+function metaChildrenStart(buf, meta) {
+    return meta.end - meta.start >= 4 && buf.readUInt32BE(meta.start) === 0
+        ? meta.start + 4
+        : meta.start;
+}
+/** A metadata item's value: its `data` box, after the type and locale words. */
+function dataOf(buf, item) {
+    const data = childrenOf(buf, item.start, item.end, 'data')[0];
+    if (!data || data.end - data.start < 8)
+        return null;
+    return buf.subarray(data.start + 8, data.end);
+}
+/** The `©too` tag in the movie's `udta/meta/ilst`. */
+function encoderOf(moov) {
+    for (const udta of childrenOf(moov, 0, moov.length, 'udta')) {
+        for (const meta of childrenOf(moov, udta.start, udta.end, 'meta')) {
+            for (const ilst of childrenOf(moov, metaChildrenStart(moov, meta), meta.end, 'ilst')) {
+                for (const item of childrenOf(moov, ilst.start, ilst.end, '©too')) {
+                    const value = dataOf(moov, item);
+                    if (value)
+                        return value.toString('utf8');
+                }
+            }
+        }
+    }
+    return null;
+}
+/** The transcript JSON from the first track that has one. */
+function transcriptOf(moov) {
+    for (const trak of childrenOf(moov, 0, moov.length, 'trak')) {
+        for (const udta of childrenOf(moov, trak.start, trak.end, 'udta')) {
+            const tsrp = childrenOf(moov, udta.start, udta.end, 'tsrp')[0];
+            if (tsrp)
+                return moov.toString('utf8', tsrp.start, tsrp.end);
+        }
+        for (const meta of childrenOf(moov, trak.start, trak.end, 'meta')) {
+            const value = mdtaValue(moov, meta, TRANSCRIPT_KEY);
+            if (value)
+                return value.toString('utf8');
+        }
+    }
+    return null;
+}
+/**
+ * The value of a QuickTime metadata key. The `keys` box lists the keys, and
+ * each `ilst` item's type is the 1-based index of its key.
+ */
+function mdtaValue(buf, meta, key) {
+    const start = metaChildrenStart(buf, meta);
+    const keys = childrenOf(buf, start, meta.end, 'keys')[0];
+    const ilst = childrenOf(buf, start, meta.end, 'ilst')[0];
+    if (!keys || !ilst || keys.end - keys.start < 8)
+        return null;
+    // After the version and flags word, a count, then each key's size,
+    // namespace, and name.
+    const count = buf.readUInt32BE(keys.start + 4);
+    let index = 0;
+    for (let i = 1, at = keys.start + 8; i <= count && at + 8 <= keys.end; i++) {
+        const size = buf.readUInt32BE(at);
+        if (size < 8 || at + size > keys.end)
+            break;
+        const namespace = buf.toString('latin1', at + 4, at + 8);
+        if (namespace === 'mdta' && buf.toString('utf8', at + 8, at + size) === key) {
+            index = i;
+            break;
+        }
+        at += size;
+    }
+    if (!index)
+        return null;
+    for (const item of childrenOf(buf, ilst.start, ilst.end)) {
+        if (buf.readUInt32BE(item.offset + 4) === index)
+            return dataOf(buf, item);
+    }
+    return null;
+}

package/dist/transcript.d.ts

@@ -0,0 +1,23 @@
+/** A transcript Voice Memos made of a recording. */
+export interface Transcript {
+    /** The text: every run joined. Empty when Voice Memos heard no speech. */
+    text: string;
+    /** The locale it was transcribed in, such as `en_CA`. */
+    locale: string | null;
+    /** Each run with when it was spoken, in seconds from the start of the recording. */
+    segments: TranscriptSegment[];
+}
+export interface TranscriptSegment {
+    text: string;
+    start: number;
+    end: number;
+}
+/**
+ * Parse the transcript JSON Voice Memos stores in a recording. Its
+ * `attributedString` is a run of text, each followed by its attributes: either
+ * `{runs: [text, i, …], attributeTable: [attributes, …]}`, where `i` indexes
+ * the table, or `[text, attributes, …]` with the attributes inline. A
+ * recording with no speech has `""`. Throws on any other shape.
+ */
+export declare function parseTranscript(json: string): Transcript;
+//# sourceMappingURL=transcript.d.ts.map

package/dist/transcript.js

@@ -0,0 +1,55 @@
+/**
+ * Parse the transcript JSON Voice Memos stores in a recording. Its
+ * `attributedString` is a run of text, each followed by its attributes: either
+ * `{runs: [text, i, …], attributeTable: [attributes, …]}`, where `i` indexes
+ * the table, or `[text, attributes, …]` with the attributes inline. A
+ * recording with no speech has `""`. Throws on any other shape.
+ */
+export function parseTranscript(json) {
+    const parsed = JSON.parse(json);
+    const locale = localeOf(parsed.locale);
+    const string = parsed.attributedString;
+    if (typeof string === 'string')
+        return { text: string, locale, segments: [] };
+    let pairs;
+    if (Array.isArray(string)) {
+        pairs = alternate(string).map(([text, attributes]) => [text, attributes]);
+    }
+    else if (isObject(string) && Array.isArray(string.runs)) {
+        const table = Array.isArray(string.attributeTable) ? string.attributeTable : [];
+        pairs = alternate(string.runs).map(([text, index]) => [
+            text,
+            typeof index === 'number' ? table[index] : undefined,
+        ]);
+    }
+    else {
+        throw new Error('Unknown transcript shape');
+    }
+    let text = '';
+    const segments = [];
+    for (const [run, attributes] of pairs) {
+        if (typeof run !== 'string')
+            throw new Error('Unknown transcript shape');
+        text += run;
+        const range = attributes?.timeRange;
+        if (Array.isArray(range) && typeof range[0] === 'number' && typeof range[1] === 'number') {
+            segments.push({ text: run, start: range[0], end: range[1] });
+        }
+    }
+    return { text, locale, segments };
+}
+/** `[a, b, c, d]` as `[[a, b], [c, d]]`. */
+function alternate(items) {
+    const pairs = [];
+    for (let i = 0; i < items.length; i += 2)
+        pairs.push([items[i], items[i + 1]]);
+    return pairs;
+}
+function localeOf(locale) {
+    if (!isObject(locale))
+        return null;
+    return typeof locale.identifier === 'string' ? locale.identifier : null;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/package.json

@@ -1,6 +1,80 @@
 {
   "name": "@chronicle.app/apple-voice-memos",
-  "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",
+    "apple-voice-memos",
+    "audio"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle plugin for your Voice Memos recordings and their transcripts, from the library macOS keeps in step with iCloud",
+  "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/apple-voice-memos"
+  },
+  "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": {
+      "apple-voice-memos": {
+        "strategies": {
+          "app-db": {
+            "delivery": "local",
+            "recordTypes": [
+              "recordings"
+            ],
+            "default": true
+          }
+        },
+        "platforms": [
+          "darwin"
+        ]
+      }
+    }
+  }
+}