# 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. [中文说明](README.zh-CN.md) ## 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**: `.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 `/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. ```sh 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](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](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.