Skip to content

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.

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 — editing main.js does not require restarting Obsidian.
  • Separate from the plugin core: main.js is a self-contained CommonJS file. There is no require and no Node / Electron API at runtime. Network access, settings, and logging are injected by the host through ctx.
  • 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.
TypeWhat it doesTypical use
video-sourceTurns a web address into a playable video streamBilibili, Xiaohongshu, a self-hosted video site
audio-sourceTurns a web address into a playable audio streamRSS podcasts, internet radio
agent-sessionExports and restores an agent’s local sessions between this machine and the managed repositoryContinue 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.

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"]
  1. Load: scan connectors/, validate manifest.json, evaluate main.js, call create(ctx), and register the instance.
  2. 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.
  3. Resolve: resolve(url) calls the platform API through ctx.request and returns a MediaStreamInfo. Host requests are not subject to browser CORS.
  4. 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.
  5. Lifecycle: dispose() is called on reload or plugin disable. If a video URL expires, the host calls resolve() 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.

  • The directory name is the connector id and also determines load and match order; manifest.id must 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 .disabled marker inside the directory: a disabled connector is not evaluated or matched, but its files and settings.json are kept. Uninstalling deletes the whole directory.
  1. Open the Sync Vault dashboard, click ➕ at the bottom right of the workbench, and add the Connectors widget from the widget library.
  2. Click Install and paste the URL of a manifest.json; GitHub page links are converted to raw automatically.
  3. Or click Choose files and select manifest.json and main.js from your machine.
  4. 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.

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.

WARNING

Only 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.

The official SDK repository ships a set of installable examples: https://github.com/abcamus/sync-vault-connector-sdk

ExampleTypeDescription
web-videovideo-sourcePublicly accessible direct-link / HLS video
bilibilivideo-sourceBilibili videos and multi-part videos; requires a Referer header, desktop only
xiaohongshuvideo-sourceXiaohongshu video notes; plays on desktop and mobile
web-audioaudio-sourcePublicly accessible direct-link / HLS audio
rss-podcastaudio-sourceRSS podcasts and Apple Podcasts links, with episode selection
qoderagent-sessionExport 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.json

The plugin fetches main.js from the same directory.