@chronicle.app/apple-voice-memos 0.4.0 → 0.5.0

package/README.md

@@ -18,7 +18,7 @@ Recordings come out newest first, and `--since` and `--until` bound when each on
 
 | 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)                                                   |
+| Recording a memo              | `RecordAction`    | `@type`, `source`, `result.sourceId` (the recording it made)                                                        | `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) |
@@ -50,7 +50,7 @@ Recordings come out newest first, and `--since` and `--until` bound when each on
 
 **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 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 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.
 

package/dist/connectors/AppleVoiceMemosExtractor.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 Transcript } from '../transcript.js';
 import AppleVoiceMemosTransformer from './AppleVoiceMemosTransformer.js';
@@ -36,6 +36,11 @@ export declare class AppleVoiceMemosExtractor extends SqliteExtractor<typeof App
     static default: boolean;
     static defaultTransformer: typeof AppleVoiceMemosTransformer;
     static newestFirst: boolean;
+    static databases: {
+        tables: {
+            ZCLOUDRECORDING: string[];
+        };
+    }[];
     static schema: any;
     private libraryChanged;
     private unreadable;
@@ -61,5 +66,7 @@ export declare class AppleVoiceMemosExtractor extends SqliteExtractor<typeof App
      */
     private hintUnreadable;
     determineCount(): Promise<number | null>;
+    /** The recordings a run reads and when they started, with how long they last, to the second. */
+    survey(options?: SurveyOptions): Promise<Survey | null>;
 }
 //# sourceMappingURL=AppleVoiceMemosExtractor.d.ts.map

package/dist/connectors/AppleVoiceMemosExtractor.js

@@ -1,7 +1,7 @@
 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 { 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 { readRecordingMetadata } from '../mp4.js';
 import { parseTranscript } from '../transcript.js';
@@ -25,6 +25,22 @@ export class AppleVoiceMemosExtractor extends SqliteExtractor {
     static default = true;
     static defaultTransformer = AppleVoiceMemosTransformer;
     static newestFirst = true;
+    // What extract() and survey() read, which a CloudRecordings.db must have.
+    static databases = [
+        {
+            tables: {
+                ZCLOUDRECORDING: [
+                    'ZUNIQUEID',
+                    'ZDATE',
+                    'ZDURATION',
+                    'ZENCRYPTEDTITLE',
+                    'ZPATH',
+                    'ZFLAGS',
+                    'ZEVICTIONDATE',
+                ],
+            },
+        },
+    ];
     static schema = SqliteExtractor.schema.omit({ input: true }).extend({
         input: z.string().describe('Path to CloudRecordings.db').default(DEFAULT_DB),
         account: z
@@ -157,6 +173,28 @@ export class AppleVoiceMemosExtractor extends SqliteExtractor {
             return null;
         }
     }
+    /** The recordings a run reads and when they started, with how long they last, to the second. */
+    async survey(options = {}) {
+        if (!this.db)
+            return null;
+        const { sql, values } = this.query(`COUNT(*) AS n, MIN(ZDATE) AS first, MAX(ZDATE) AS last,
+       COALESCE(ROUND(SUM(ZDURATION)), 0) AS seconds`);
+        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 {
+            recordings: {
+                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: 'recordingSeconds', label: 'recordings', value: row.seconds, unit: 'seconds' },
+                ],
+            },
+        };
+    }
 }
 /**
  * The file, when it's on this Mac. A recording iCloud hasn't downloaded has

package/dist/connectors/AppleVoiceMemosTransformer.js

@@ -1,6 +1,6 @@
 import { extname } from 'node:path';
 import { ChronicleTransformer } from '@chronicle.app/etl';
-import { buildICloudPersonSchema } from '@chronicle.app/icloud';
+import { buildICloudPersonSchema } from '@chronicle.app/apple';
 import { readEncoder } from '../encoder.js';
 const SOURCE = 'apple-voice-memos';
 // What each kind of recording file is. `.qta` is a QuickTime audio movie,
@@ -29,9 +29,9 @@ export default class AppleVoiceMemosTransformer extends ChronicleTransformer {
         // recording's duration isn't always the end.
         const action = {
             '@type': 'RecordAction',
-            '@key': ['@type', 'source', 'sourceId'],
+            // Keyed by the recording it made, which has the memo's ID.
+            '@key': ['@type', 'source', 'result.sourceId'],
             source: SOURCE,
-            sourceId: memo.uniqueID,
             timestamp: new Date(memo.date),
             ...(recorder && { agent: recorder }),
             ...(instrument.length > 0 && { instrument }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronicle.app/apple-voice-memos",
-  "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 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",
+    "@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,11 +68,34 @@
             "recordTypes": [
               "recordings"
             ],
-            "default": true
+            "default": true,
+            "locations": [
+              {
+                "path": "~/Library/Group Containers/group.com.apple.VoiceMemos.shared/Recordings/CloudRecordings.db"
+              }
+            ],
+            "databases": [
+              {
+                "tables": {
+                  "ZCLOUDRECORDING": [
+                    "ZUNIQUEID",
+                    "ZDATE",
+                    "ZDURATION",
+                    "ZENCRYPTEDTITLE",
+                    "ZPATH",
+                    "ZFLAGS",
+                    "ZEVICTIONDATE"
+                  ]
+                }
+              }
+            ]
           }
         },
         "platforms": [
           "darwin"
+        ],
+        "requires": [
+          "full-disk-access"
         ]
       }
     }