Skip to content

Build Your Own Connector

This page starts from an empty directory and builds a connector that resolves an external video address into a playable stream, then debugs it locally and installs it in Obsidian. All you need is JavaScript and a reachable API endpoint — no plugin source changes.

TIP

Let AI write it with you The connector interface is small. Hand this page and the API reference to an AI, describe the site you want to support and how to obtain the stream, and have it generate main.js. Then verify it with the local debugger.

A connector is one directory with two files:

my-connector/
├── manifest.json
└── main.js

The directory name is the connector id and must match the id in manifest.json.

{
"id": "my-connector",
"name": "My Connector",
"version": "1.0.0",
"apiVersion": "0.4",
"type": "video-source",
"description": "Resolves video URLs from watch.example.com",
"author": "your-name",
"homepage": "https://github.com/you/my-connector"
}
FieldRequiredDescription
idYesUnique identifier; must match the directory name; lowercase letters, digits, -, _ only
nameYesDisplay name
versionYesThe connector’s own version
apiVersionYesTarget contract version. The host is currently on 0.4; only the first segment has to match
typeYesvideo-source, audio-source, or agent-session
description / author / homepageNoDisplay and provenance information

main.js is a single CommonJS file that exports a create(ctx) factory:

module.exports = {
create(ctx) {
return {
// The host calls this synchronously for every external URL — keep it cheap
match(url) {
return /^https?:\/\/watch\.example\.com\/video\//i.test(url);
},
async resolve(url, onProgress) {
onProgress?.('Resolving playback URL…');
// Requests go through the host channel and are not subject to browser CORS
const resp = await ctx.request({
url: `https://api.example.com/resolve?url=${encodeURIComponent(url)}`,
});
if (resp.status !== 200) {
throw new Error(`Resolve API returned HTTP ${resp.status}`);
}
const data = resp.json;
if (!data.playUrl) {
throw new Error(data.message || 'Resolve response has no playUrl');
}
return {
url: data.playUrl,
urlType: 'm3u8-list',
mediaType: 'hls',
coverUrl: data.cover,
mediaInfo: [{
url: data.playUrl,
width: data.width ?? 0,
height: data.height ?? 0,
resolution: data.quality ?? 'Auto',
}],
};
},
// Optional: clean up timers, connections, etc. on reload or disable
dispose() {},
};
},
};

Key points:

  • Keep match conservative: it decides whether an address belongs entirely to your connector. Do not match every http(s) URL, or you will hijack ordinary web entries into the video player. Return synchronously and do no network work here.
  • Throw on failure in resolve: the host will not fall back to built-in parsing or try another connector. The error is shown to the user and logged. Do not hide failures by returning an empty stream.
  • Returned URLs must be resolvable again: the host re-invokes resolve for part switching and expired URLs, so the implementation must be repeatable and must not accumulate one-shot state on the instance.
  • Do not use resolution: '原画' for HLS: this exact value has special meaning to the player and takes the direct-link path. Use Auto or a quality name for HLS.

See the Connector API reference for every field.

No Obsidian needed — run the SDK mock through load → match → resolve:

Terminal window
npx sync-vault-connector-mock ./my-connector "https://watch.example.com/video/123"

The mock validates manifests and evaluates main.js exactly like the host, so it catches missing fields, ESM syntax, require usage, and similar problems early. There are only two differences: ctx.request uses Node’s fetch (no CORS restrictions), and ctx.dir is a local absolute path.

Fix errors until the command prints a resolve result, then install it in Obsidian.

Add the Connectors widget to the dashboard workbench and click Install:

  • paste the URL of manifest.json (GitHub page links are converted to raw automatically), or
  • click Choose files and select both manifest.json and main.js.

Alternatively, copy the whole directory to <vault>/.obsidian/plugins/sync-vault-ce/connectors/my-connector/ and run Reload user connectors.

Then put the address in a cloudvideo block in a note:

```cloudvideo
https://watch.example.com/video/123 | My video
```

Switch back to Reading view to play. Quality switching, playback progress, timestamp annotations, and the rest of the pipeline work exactly as they do for built-in sources — no extra work needed.

For tokens, cookies, and similar configuration, read settings.json from the connector directory with ctx.getSettings():

const settings = await ctx.getSettings();
const token = settings?.token;
if (!token) {
throw new Error('Configure token in settings.json first');
}

Users can edit the file directly. It is an ordinary JSON file in the vault, stored in plain text, and synced along with the vault. Do not hard-code long-lived secrets in main.js.

For multi-part or multi-episode videos, return parts. The host shows a part list in the player sidebar and auto-continues to the next part when one ends:

return {
url: current.playUrl,
urlType: 'm3u8-list',
mediaType: 'hls',
mediaInfo: [{ url: current.playUrl, width: 0, height: 0, resolution: 'Auto' }],
parts: [
{ name: 'P1 Intro', url: 'https://watch.example.com/video/123?part=1' },
{ name: 'P2 Main', url: 'https://watch.example.com/video/123?part=2' },
],
currentPartIndex: 0,
};
  • The list is shown only when there are at least 2 parts.
  • Every parts[].url must be handled by your match / resolve — the host calls resolve again with it when switching parts.
  • Each part is an independent entry in the host, with its own playback progress and annotations.

Change manifest.type to audio-source; the method shape stays the same. Differences:

  • Audio has no resolution. Set width: 0 and height: 0 in each mediaInfo item, with resolution set to 原画 or a display name.
  • The host does not re-resolve expired audio URLs, so return addresses that stay valid long enough.
  • When parts is returned, the host plays them in order. The part list appears in the player sidebar, not in the embedded player.

Start from the SDK’s web-audio (direct link / HLS) and rss-podcast (RSS podcast) examples.

  • No Node / Electron APIs: fs, path, and http are unavailable. Use Web standards such as crypto.subtle for randomness or digests.
  • Access files only through ctx: use getSettings / saveSettings inside the vault. Local paths outside the vault are available only to agent-session connectors, and only through ctx.desktop on desktop.
  • Addresses that need anti-hotlink headers: the local proxy behind proxy: true exists only on desktop. On mobile it degrades to a direct connection and headers are not applied. Detect this and fail loudly instead of showing a confusing playback error:
if (ctx.platform.isMobile) {
throw new Error('This URL needs anti-hotlink headers and is desktop-only');
}
  • Direct video needs CORS: the player loads direct URLs through <video crossorigin="anonymous">, so the origin must return Access-Control-Allow-Origin; otherwise playback fails with MEDIA_ELEMENT_ERROR: Format error. On desktop, proxy: true lets the local proxy add the headers; on mobile there is no proxy.

Push the directory to GitHub — include only manifest.json and main.js, never settings.json or .disabled. Others can paste the GitHub page URL of manifest.json into the install dialog. For updates, keep the id stable and bump version; reinstalling over the same id keeps the user’s settings.json.

SymptomLikely cause
Load error about manifest.id and the directory nameDirectory name and id differ
Load error mentioning ESM import / exportESM syntax used; switch to module.exports
Load error about exporting create(ctx)The factory function is missing
Player shows Unsupported file typeNo connector matched; check whether match is too narrow
403 / Format error during playbackAnti-hotlink headers or CORS; check proxy / headers and mobile differences
A resolve failed but you cannot tell whereSearch the log for [connector.my-connector]

For every field and lifecycle detail, see the Connector API reference.