Brain Vox

Your voice, your journal.

Brain Vox synchronizes approved Brain Vox Markdown publications and managed tasks with an Obsidian vault. It validates server responses and hashes, confines writes to a configured folder, and preserves conflicting local note edits instead of overwriting them.

Requirements

• Obsidian 1.11.4 or newer.
• An account on, or access token for, a Brain Vox-compatible server.
• Network access to that configured server.
• HTTPS for remote servers. Plain HTTP is accepted only for loopback development addresses.

The plugin supports desktop and mobile Obsidian. API tokens require Obsidian SecretStorage and are never stored in plugin data.json.

Install

Community plugins

After the plugin is accepted into the Obsidian Community directory:

1. Open Settings > Community plugins.
2. Select Browse and search for Brain Vox.
3. Install and enable the plugin.

BRAT

1. Install and enable the BRAT community plugin.
2. In BRAT, choose Add Beta plugin.
3. Enter https://github.com/dutz-ro/audio-journal-obsidian.
4. Enable Brain Vox under Community plugins.

Manual

Place these release files in <vault>/.obsidian/plugins/audio-journal-companion/:

• main.js
• manifest.json
• styles.css

Restart Obsidian, then enable Brain Vox. Release files are published in the dutz-ro/audio-journal-obsidian GitHub repository.

Configure

1. In Brain Vox, choose Connect Obsidian on this device, or paste its pairing link into the plugin settings.
2. Confirm the server inside Obsidian. The device token is stored in SecretStorage and the first synchronization starts automatically.
3. Set Sync root if notes should be written outside the default Brain Vox folder.
4. Set Poll interval in minutes. Use 0 to disable scheduled polling.
5. Select Sync now, use the ribbon icon, or run Brain Vox: Sync now from the command palette.

Duplex task synchronization is enabled by default. It can be disabled in settings. An explicitly disabled setting remains disabled during upgrades.

Note Synchronization

Protocol v1 downloads approved Markdown publications. It does not upload arbitrary local notes. A tracked note is replaced only when its current hash still matches the last downloaded version. Otherwise, the local note remains unchanged and the remote version is written below <sync root>/.conflicts/ for manual resolution.

Duplex Tasks

Duplex mode watches only <sync root>/To Do/Inbox.md. It recognizes task blocks delimited by audio-journal:todo comments and never uploads prose, unmanaged checklists, or other notes.

For managed tasks, the plugin may send title, description, status, priority, due date, category, project, recurrence, estimated minutes, archive/review state, task identifiers, revisions, hashes, operation identifiers, and deletion timestamps. Writes use revision-based compare-and-swap operations. Concurrent local and remote changes are retained as conflicts.

Use Brain Vox: Create synchronized task to create a task from Obsidian. Removing a managed task block or the Inbox file starts a 12-hour deletion grace period. A later rescan is required, and bulk-loss protection prevents mass deletion.

Privacy And Network Use

Brain Vox requires a user-configured Brain Vox-compatible server and does not include advertising or client-side analytics.

The plugin contacts only the configured server for:

• pairing a device with a one-time code;
• downloading approved Markdown publications and acknowledging safe writes;
• downloading, uploading, acknowledging, and resolving managed task changes.

Pairing sends the one-time code, a persistent random device identifier, and a platform-derived device label. Synchronization sends the scoped bearer token plus cursors, publication/task identifiers, revisions, hashes, operation identifiers, acknowledgments, and timestamps. Duplex mode additionally sends only the managed task fields listed above. Tokens are stored under a device-and-server-specific SecretStorage key and are not reused after the configured server changes.

The server may retain pairing records, device metadata, task/publication revisions, acknowledgments, audit records, and operational usage metadata according to the server operator's policy. Self-hosted operators control their own storage and retention. Revoking a token stops future access but does not remove Markdown already copied into a vault or its backups. Plugin data.json also retains full managed task snapshots, pending operation payloads, and both sides of conflicts; vault synchronization and backups may copy that state. See PRIVACY.md for the plugin-specific disclosure.

Security

• Paths cannot be absolute, traverse parent folders, target .obsidian, or escape the sync root.
• Incoming Markdown and task payloads are checked against SHA-256 hashes.
• Remote HTTP, URL credentials, URL query strings, and fragments are rejected.
• Tokens are bearer credentials stored only through Obsidian SecretStorage.
• Networking uses Obsidian requestUrl; vault access uses Obsidian Vault APIs.

The manifest ID audio-journal-companion, protocol action audio-journal-pair, repository/package naming, token key, and CSS classes remain unchanged for compatibility with existing installations and pairing links. New installations use Brain Vox as the sync root; legacy root folders are merged automatically without overwriting existing files.

Development

npm install
npm run check
npm run package

npm run check runs the Obsidian ESLint rules, typechecking, tests, and a production build. Packaging verifies package.json, manifest.json, and versions.json, then recreates release/ with only main.js, manifest.json, and styles.css.

License

Brain Vox is licensed under the MIT License. See LICENSE.