Connector Architecture
Beyond its built-in features, Sync Vault offers a pluggable extension path: connectors. A connector is a piece of JavaScript you write to bring external sources the plugin does not support into the existing playback, timestamp, and note workflows. No plugin rebuild is needed — drop it into the vault, reload, and it works.
What a connector is
Section titled “What a connector is”A connector is a directory with two files:
<vault>/.obsidian/plugins/sync-vault-ce/connectors/my-connector/├── manifest.json Metadata: id, type, contract version└── main.js Entry point: exports a create(ctx) function- Loaded at runtime: the plugin scans the
connectors/directory on startup. Run Reload user connectors from the command palette any time — editingmain.jsdoes not require restarting Obsidian. - Separate from the plugin core:
main.jsis a self-contained CommonJS file. There is norequireand no Node / Electron API at runtime. Network access, settings, and logging are injected by the host throughctx. - One codebase, both platforms: connectors are loaded and executed on desktop and mobile (iOS / Android) alike, so plan for mobile from the first line — there is no local proxy there.
Three extension types
Section titled “Three extension types”| Type | What it does | Typical use |
|---|---|---|
video-source | Turns a web address into a playable video stream | Bilibili, Xiaohongshu, a self-hosted video site |
audio-source | Turns a web address into a playable audio stream | RSS podcasts, internet radio |
agent-session | Exports and restores an agent’s local sessions between this machine and the managed repository | Continue Qoder CLI sessions across devices (desktop only) |
Video and audio sources share the same return type, MediaStreamInfo, so direct links, HLS, covers, and parts work the same for both. The differences are which player the host uses and whether a proxy is available on mobile (see the API reference).
If an address matches both a video source and an audio source, the host asks video sources first and treats it as video.
How an address becomes a playable stream
Section titled “How an address becomes a playable stream”flowchart LR A["Address in a note"] --> B{"Ask match(url) in directory order"} B -- match --> C["connector.resolve"] C <-->|"ctx.request"| D["Platform API / origin"] C --> E["MediaStreamInfo"] E --> F["Player"] B -- no match --> G["Built-in logic / explicit error"]- Load: scan
connectors/, validatemanifest.json, evaluatemain.js, callcreate(ctx), and register the instance. - Match: when an external address enters the playback pipeline, the host calls
match(url)in ascending directory-name order. The first connector that matches owns the address. - Resolve:
resolve(url)calls the platform API throughctx.requestand returns aMediaStreamInfo. Host requests are not subject to browser CORS. - Play: from here it is the normal playback path — quality switching, cover, parts, progress, and timestamp annotations do not care where the stream came from.
- Lifecycle:
dispose()is called on reload or plugin disable. If a video URL expires, the host callsresolve()again (up to 2 times per player).
Failures are explicit: once a connector matches, a failed resolve does not fall back to built-in logic or try the next connector. The error is shown to the user and written to the log.
Loading, reloading, and failure isolation
Section titled “Loading, reloading, and failure isolation”- The directory name is the connector
idand also determines load and match order;manifest.idmust match the directory name. - One failing connector only affects itself: other connectors and the plugin still start. The failure reason appears in the Connectors widget and in the log.
- Reloading calls
dispose()on the old instance before creating the new one, so two instances never coexist. - Disabling is controlled by a
.disabledmarker inside the directory: a disabled connector is not evaluated or matched, but its files andsettings.jsonare kept. Uninstalling deletes the whole directory.
Installing and managing connectors
Section titled “Installing and managing connectors”Install from the dashboard
Section titled “Install from the dashboard”- Open the Sync Vault dashboard, click ➕ at the bottom right of the workbench, and add the Connectors widget from the widget library.
- Click Install and paste the URL of a
manifest.json; GitHub page links are converted to raw automatically. - Or click Choose files and select
manifest.jsonandmain.jsfrom your machine. - Use the list to enable / disable / uninstall, or click Reload to rescan connectors placed in the directory manually.
Install only writes manifest.json and main.js. Installing over an existing connector with the same id overwrites those two files and keeps settings.json; a connector that was disabled stays disabled after install.
Place the directory manually
Section titled “Place the directory manually”Copy the connector directory to:
<vault>/.obsidian/plugins/sync-vault-ce/connectors/<connector id>/Then run Reload user connectors from the command palette. Accessing the plugin directory is inconvenient on mobile, so prefer the install flow above — it works from a URL or local files on both platforms.
WARNINGOnly install connectors you trust Connector code runs directly inside the plugin with the same privileges as the plugin, and can make network requests through the host channel. Do not install connectors from untrusted sources.
Ready-made examples
Section titled “Ready-made examples”The official SDK repository ships a set of installable examples: https://github.com/abcamus/sync-vault-connector-sdk
| Example | Type | Description |
|---|---|---|
web-video | video-source | Publicly accessible direct-link / HLS video |
bilibili | video-source | Bilibili videos and multi-part videos; requires a Referer header, desktop only |
xiaohongshu | video-source | Xiaohongshu video notes; plays on desktop and mobile |
web-audio | audio-source | Publicly accessible direct-link / HLS audio |
rss-podcast | audio-source | RSS podcasts and Apple Podcasts links, with episode selection |
qoder | agent-session | Export and restore Qoder CLI sessions, desktop only |
For example, paste this into the install dialog:
https://github.com/abcamus/sync-vault-connector-sdk/blob/main/examples/bilibili/manifest.jsonThe plugin fetches main.js from the same directory.
Next steps
Section titled “Next steps”- Build your own connector — the full path from directory and manifest to resolve.
- Connector API reference — fields, lifecycle, and desktop/mobile differences.