BiliNote Sync

Import selected notes and screenshots generated by a local BiliNote installation into an Obsidian desktop vault. This is an independent importer, not an official BiliNote or Obsidian product. It does not transcribe videos or call an AI model.

中文说明

Requirements

• Obsidian desktop 1.13.7 or later. Mobile is not supported because the plugin uses Node.js filesystem APIs.
• A local BiliNote installation with note_results and static/screenshots directories. The tested result format is BiliNote desktop 2.4.5: <task UUID>.json contains markdown and audio_meta; the matching .status.json contains status: "SUCCESS".
• Windows is the platform tested in a real Obsidian vault. macOS and Linux have not been independently tested. Remote-server-only and online BiliNote installations are not supported by this filesystem importer.
• The interface is currently in Chinese. The command palette prefixes commands with BiliNote Sync.

Use

1. Install the plugin through the community directory once it is published. Until then, copy main.js, manifest.json and styles.css into <vault configuration directory>/plugins/bilinote-sync/ and enable it in Community plugins.
2. In Settings → BiliNote Sync, set BiliNote 安装目录 to the full path of the directory containing note_results. This path starts empty and must be configured by you.
3. Generate a note successfully in BiliNote.
4. Open 选择导入 BiliNote 笔记 from the command palette, the ribbon or the settings button. Select the notes you want, then click 导入选中. No notes are selected initially. Closing before starting an import or choosing 暂不导入 imports nothing.

Notes are saved in the configured vault folder (BiliNote笔记 by default) with relative image links. If a source changes, it is imported as a separate file; existing files and your edits are not overwritten. Missing screenshots defer the entire import until they are available. Renamed or moved notes are recovered from their frontmatter. Keep bilinote_task and bilinote_source_hash if you want deduplication to survive moves or a lost settings file.

If an imported note is deleted, the picker offers an explicit re-import. Automatic mode does not repeatedly recreate a deleted note for the same task and source version. The source result must still exist. A new task or a changed source version is treated as a new import.

Modes

• Automatic import off (default): imports only confirmed selections.
• Startup reminder on (default): when opening the vault with pending notes, shows the picker. It does not import anything without confirmation. New notes generated while the vault is open can be selected manually.
• Automatic import on: checks every 10 seconds and imports all new completed results; also checks when the vault opens. Turn it off for per-note control.

The plugin does not run while Obsidian is closed. All settings are saved per vault. Moving the BiliNote installation requires updating the source directory setting. Changing a source, destination folder or image setting invalidates an open selection; reopen the picker before importing.

Optional shared images

共用图片数据 is off for new installations. Turning it on creates filesystem hard links when BiliNote and the vault are on the same filesystem, with a copy fallback when linking is unavailable. Two names then point to the same image bytes. Editing shared image content in either application affects both. Removing one name does not remove the other name's data. Vault backups or sync tools may copy image bytes independently; this plugin does not control their storage accounting.

合并图片 converts only byte-identical existing copies to links, verifies the replacement, and retains modified images. New installs can leave these features off and use independent copies.

Optional downloaded-media cleanup

完成后清理下载音视频 is off for new installations. It is destructive when enabled: after checking saved notes and all referenced screenshots, the plugin permanently deletes eligible downloaded audio/video files directly inside BiliNote's data folder. It does not use a trash bin. Regeneration, retranscription or additional screenshots may require downloading the video again.

Only normal audio/video files with a filename stem matching a completed video's ID are eligible; the legacy bare Bilibili ID and its explicit first-episode name are treated as aliases. Each episode can be cleaned independently of unrelated active tasks. Media shared with queued, running, failed/retryable or unimported tasks is retained. Explicitly removed failed tasks release their references; removing a still-running history entry does not.

Unknown names, redirected directories, symbolic links, changed files and recent writes are retained. Damaged results and missing status records protect their identified media. An unresolved task identity or malformed series receipt defers deletion conservatively. A final scan catches new references before the last file checks, but there is no shared transaction/lock with BiliNote; keep cleanup disabled when another program is directly modifying cached files. A manual selection scopes automatic cleanup to the selected videos. 立即清理 checks already imported notes without importing others. Only enable cleanup if you are comfortable deleting these cached downloads; keep your original videos outside this cache.

Existing installations retain their previously saved image-sharing and cleanup preferences when upgrading.

Privacy and filesystem access

This plugin has no network requests, analytics, telemetry, account requirement or model/API charge. It does not access BiliNote's API keys, cookies, database, .env or provider configuration. BiliNote's own model calls and fees are separate.

The plugin reads files outside the vault, in the source directory you configure: completed result/status JSON files and referenced screenshot files. Cleanup additionally reads audio metadata, note_results/task_requests, note_results/series_batches and note_results/series_task_removals.json to identify pending or removed tasks. These records are read locally and never uploaded. It writes Markdown and images into the selected vault folder and persists preferences, import receipts and cleanup history in its own plugin data.json. Reading receipts can scan vault Markdown files to recover moved imports. It does not sync your edits back to BiliNote.

Shared-image mode additionally links source screenshot files to vault paths. The explicit image-merging action replaces only verified identical vault image copies. Cleanup, when enabled or explicitly requested, deletes the verified source cache files described above. No screenshots, result JSON, credentials or personal configuration belong in this public repository.

Remote links and images already present in source Markdown are preserved. Obsidian may load external images when rendering a note according to its own behavior; the importer itself does not fetch those URLs.

Development

The readable CommonJS source is src/plugin.cjs, with source styles in src/plugin.css. There is no bundled runtime dependency. Node.js 22+ is required only for development and fixture tests. npm run build recreates the root main.js and styles.css from source, including when a reviewer removes previous build outputs.

npm ci
npm run check
npm run build

The checks cover import filtering, missing images, state recovery, personal-edit preservation, selection/cancellation, shared-file identity, fallback/rollback, deleted/moved notes, encoded image paths, vault path boundaries, settings changes, cleanup ownership, independent episode cleanup, shared/retry cache retention, corrupt records, final-scan file changes and serialized persistence. Test fixtures contain synthetic content, live inside ignored *test-* directories, and do not access a real vault.

npm run build prepares exactly main.js, manifest.json and styles.css in .release/1.4.3/. The build regression test starts without root installation assets and checks exact, repeatable output.

GitHub Actions runs the checks on Windows and Linux. Pushing tag 1.4.3 triggers a release build, creates GitHub artifact attestations for all three files, verifies the signed provenance, and publishes the files as individual release attachments. The workflow uses short-lived GitHub credentials; no personal API key or signing key is required. See PUBLISHING.md.

The community scanner reports direct filesystem access because this importer reads the configured BiliNote directory outside the vault. Vault enumeration supports recovery of moved imports. These capabilities are disclosed above and remain visible in the review.

License and support

MIT, see LICENSE. BiliNote is a separate dependency; its code and executable are not bundled. Its result format may change in a future release. Report the BiliNote/Obsidian versions and a redacted error or synthetic result when filing an issue; do not include cookies, API keys or private notes.