# Recording Minutes [简体中文](README.zh-CN.md) **Turn microphone recordings into local, timestamped Obsidian minutes.** Recording Minutes is a macOS desktop plugin for a simple, inspectable flow: `Record → local WAV → local Whisper transcript → optional Codex minutes → recoverable Markdown` Click the microphone once to start and again to stop. The plugin saves microphone input as a 16 kHz mono WAV file inside your vault, runs your own local `whisper-cli`, and writes a transcript with links back to the recording. Codex summaries are optional and off by default. The plugin asks for separate consent before it can send a completed transcript to Codex. It does not send audio, note titles, vault names, or file paths. Codex uses your network connection, login, and account quota. Recording, transcription, and note writing are saved as separate stages. If Obsidian exits or a later step fails, the files already written remain available and the Recovery Center can continue from the saved material. > [!IMPORTANT] > Version 0.1.0 records one **microphone input only** on macOS desktop. It does not capture system audio, meeting-app audio channels, or separate speakers. Remote voices are recorded only if your microphone physically picks them up. ## What you get - A local WAV recording stored in your vault. - A local Whisper transcript with clickable source timestamps. - One Markdown note containing status, audio, transcript, optional AI minutes, and a section the plugin never edits. - Optional Codex output for summaries, decisions stated as confirmed in the transcript, tasks, and open questions. Every generated item must point back to transcript segments. - Recovery for saved PCM chunks, pending transcript writes, pending AI writes, and damaged managed regions. AI output can be incomplete or wrong. Review it against the linked transcript and recording before relying on it. ## Requirements | Requirement | Needed for | | -------------------------------------------------------------------------------- | ------------------------------------------------------------ | | macOS desktop | Version 0.1.0. Windows, Linux, and mobile are not supported. | | Obsidian 1.13.4 or later | Plugin host. | | Microphone permission for Obsidian | Recording. | | `whisper-cli` from [whisper.cpp](https://github.com/ggml-org/whisper.cpp) | Local transcription. | | A compatible local GGML Whisper model | Local transcription. Use a multilingual model for Chinese. | | A compatible, authenticated [Codex CLI](https://developers.openai.com/codex/cli) | Optional AI minutes only. | | At least 500 MiB free | Starting a recording. The plugin warns below 2 GiB. | The plugin does not install executables or download models for you. Its release-verification baseline is whisper.cpp 1.9.2 and `codex-cli 0.149.0-alpha.4`. Other versions must pass the built-in capability checks before use. ## Install ### Community plugins 1. Open **Settings → Community plugins → Browse**. 2. Search for **Recording Minutes**. 3. Install and enable it. If the listing is not available yet, install the three files from a GitHub release manually. ### Manual installation 1. Download `main.js`, `manifest.json`, and `styles.css` from the same [GitHub release](https://github.com/songjiajun0209-byte/recording-minutes/releases). 2. Create `/plugins/recording-minutes/` inside your vault. The vault configuration directory is `.obsidian` by default. 3. Put all three files in that folder. 4. Reload Obsidian, then enable **Recording Minutes** under Community plugins. Do not mix files from different releases. ## Install the local dependencies ### Whisper One macOS option is Homebrew: ```sh brew install whisper-cpp command -v whisper-cli whisper-cli --version ``` Download a compatible GGML model by following the [whisper.cpp model instructions](https://github.com/ggml-org/whisper.cpp/tree/master/models). Keep the executable and model paths. Recording Minutes accepts absolute macOS paths and can also look for `whisper-cli` in common Homebrew locations and Obsidian's process `PATH`. For Chinese or mixed-language recordings, choose a multilingual model such as `base`, `small`, or a larger compatible model. Files ending in `.en` are English-only. ### Codex, optional Install and sign in to Codex by following the [official Codex CLI instructions](https://developers.openai.com/codex/cli). Run it once in Terminal and complete sign-in before testing it in the plugin. Recording Minutes checks a path you select, the Codex bundled with the ChatGPT app, and Obsidian's process `PATH`. Codex is not required for recording or local transcription. ## Five-minute setup Once Whisper and its model are installed, the in-plugin setup should take about five minutes. 1. Enable Recording Minutes and open its setup screen. 2. Read the microphone-only and recording-consent notice, then allow Obsidian to use the microphone. If macOS does not prompt, open **System Settings → Privacy & Security → Microphone**. 3. Select the `whisper-cli` executable and model, choose the transcript language, and run the local check. 4. Confirm the vault folder and microphone input. The default folder is `Recording Minutes/`. 5. Leave Codex disabled, or review the separate data notice and grant consent before enabling automatic AI minutes. The microphone is enough to save audio. Automatic transcription starts only after Whisper and a model are ready. Codex can remain disabled permanently. ## Daily use 1. Click the ribbon microphone or run **Start or stop recording**. 2. Speak into the selected microphone. The status bar shows the recording state, elapsed time, and input level. 3. Click the same entry again to stop. The WAV is finalized before local transcription begins. 4. Open the generated note. Timestamp links in the transcript and AI minutes return to the source recording. The plugin registers commands for starting or stopping, pausing or resuming, keeping audio without further processing, retrying transcription, retrying Codex, opening Recovery Center, running setup checks, and importing a legacy index. It does not assign global hotkeys. Add your own under **Settings → Hotkeys**. ## Files created in the vault The default layout is: ```text Recording Minutes/ 2026-08-21 153012 Recording abc12345.md Attachments/ recording-...wav recording-....transcript.json Pending/ recording-.../ session.json chunks/ whisper/ minutes.json ``` Final audio and normalized transcripts live under `Attachments/`. `Pending/` contains only the material needed to finish or recover incomplete work. Plugin settings and a lightweight session index live in `/plugins/recording-minutes/data.json` (`.obsidian` is the default vault configuration directory). Recording Minutes manages four marked body regions and its own `recording-minutes` frontmatter fields. Other body text and non-plugin frontmatter fields are left alone. If markers or identity fields conflict, the plugin creates a separate Recovery note instead of overwriting the original. ## Recovery Open **Recovery Center** from the command palette or plugin settings when a recording, transcript, note write, or Codex run needs attention. It lists what was preserved and the available next action. - Saved PCM chunks can be finalized into a WAV after a restart. - A transcript or AI result that was saved before a note-write failure can be written without calling the provider again. - Whisper and Codex failures leave the completed earlier stage intact. - Deleting intermediate files requires a second confirmation and does not delete final notes or WAV files. Recording chunks are synchronized about every two seconds. An abrupt process or system failure can still affect the latest unsynchronized audio. See [Troubleshooting](TROUBLESHOOTING.md) for recovery steps and force-quit limitations. ## Storage planning The final PCM WAV uses about 115 MB per recorded hour. During finalization, the source chunks and partial WAV can temporarily use about 230 MB per hour, plus a 200 MiB safety allowance. - Below 2 GiB free, Recording Minutes warns before starting. - Below 500 MiB free, it blocks a new recording. - During recording, it checks again and stops safely when remaining space cannot cover the saved PCM plus the finalization allowance. - A recording stops before the classic RIFF WAV data limit near 4 GiB. Cloud-synced vaults can need additional temporary space and time to settle. Do not remove files from `Pending/` while recovery is in progress. ## Privacy, permissions, network, and cost | Capability | When it is used | Data involved | | ----------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | Microphone permission | Only while recording. | One selected microphone input. No system-audio capture. | | Vault file access | Recording, writing notes, transcription sidecars, and recovery. | Files under the configured Recording Minutes folder plus the plugin's own settings and index. | | Local child processes | When you test or run Whisper, and only after consent when you test or run Codex. | Whisper receives the current WAV and selected model. Codex receives the completed numbered transcript through standard input. | | Paths outside the vault | When reading user-selected executables or a model, and while Codex uses a one-time macOS temporary directory. | The Codex directory contains an output schema and result file, never audio. | | Network | The plugin's only designed network path is optional Codex after consent. | The completed transcript and the plugin's fixed instructions. Audio and vault paths are excluded. | | Payment | Never collected by this plugin. | Codex may use eligibility, quota, or a paid plan attached to your OpenAI account. | Recording Minutes itself does not upload audio or provide cloud transcription. It writes WAV and transcript files to the selected vault; sync and backup services may copy those files under their own settings. There is no plugin telemetry, advertising, crash upload, or in-plugin purchase. A local executable you choose still runs with your macOS account permissions and remains outside the plugin's privacy boundary; it may access other files or the network on its own. Select software you trust. Read [Privacy](PRIVACY.md) for the complete boundary and [Third-party notices](THIRD_PARTY_NOTICES.md) for external projects and services. ## Known limits in 0.1.0 - macOS desktop only. - One microphone input, 16 kHz mono PCM16 WAV. - No system audio, multi-track capture, speaker separation, cloud transcription, audio compression, or `ffmpeg` integration. - Whisper and model setup is manual. - Codex is optional, requires explicit consent, and skips transcripts over 100,000 Unicode characters or 1 MiB. Long transcripts are not split automatically. - Closing a laptop, changing devices, revoking permission, or force-quitting Obsidian can interrupt recording. - Force-quitting Obsidian can leave a Whisper or Codex child process running until it exits. The plugin does not kill an old PID on the next launch because the operating system may have reused it. ## Legacy users If `/plugins/codex-recording-minutes/data.json` exists, the new plugin offers a user-initiated, read-only index import. It does not move, rename, or rewrite old notes, audio, or transcripts. Follow [Migration](MIGRATION.md) before disabling the old entry points. ## Support and development Start with [Troubleshooting](TROUBLESHOOTING.md). If the problem remains, open a GitHub issue and include versions, the failing stage, and the exact redacted error. Do not attach private recordings, transcripts, `data.json`, `session.json`, account details, or full personal paths. Build from source with: ```sh npm ci npm run format:check npm run lint npm run typecheck npm test npm run build ``` See [CHANGELOG](CHANGELOG.md), [Privacy](PRIVACY.md), and the [MIT license](LICENSE). Recording Minutes is an independent community project. It is not affiliated with or endorsed by Obsidian or OpenAI.