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.
TIPLet 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.
1. Create the directory
Section titled “1. Create the directory”A connector is one directory with two files:
my-connector/├── manifest.json└── main.jsThe directory name is the connector id and must match the id in manifest.json.
2. Write manifest.json
Section titled “2. Write 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"}| Field | Required | Description |
|---|---|---|
id | Yes | Unique identifier; must match the directory name; lowercase letters, digits, -, _ only |
name | Yes | Display name |
version | Yes | The connector’s own version |
apiVersion | Yes | Target contract version. The host is currently on 0.4; only the first segment has to match |
type | Yes | video-source, audio-source, or agent-session |
description / author / homepage | No | Display and provenance information |
3. Write main.js
Section titled “3. Write main.js”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
matchconservative: it decides whether an address belongs entirely to your connector. Do not match everyhttp(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
resolvefor 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. UseAutoor a quality name for HLS.
See the Connector API reference for every field.
4. Debug locally
Section titled “4. Debug locally”No Obsidian needed — run the SDK mock through load → match → resolve:
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.
5. Install it in Obsidian
Section titled “5. 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.jsonandmain.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:
```cloudvideohttps://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.
6. Add some settings
Section titled “6. Add some settings”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.
7. Support multiple parts
Section titled “7. Support multiple parts”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[].urlmust be handled by yourmatch/resolve— the host callsresolveagain with it when switching parts. - Each part is an independent entry in the host, with its own playback progress and annotations.
8. Audio connectors
Section titled “8. Audio connectors”Change manifest.type to audio-source; the method shape stays the same. Differences:
- Audio has no resolution. Set
width: 0andheight: 0in eachmediaInfoitem, withresolutionset to原画or a display name. - The host does not re-resolve expired audio URLs, so return addresses that stay valid long enough.
- When
partsis 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.
9. Mobile checklist
Section titled “9. Mobile checklist”- No Node / Electron APIs:
fs,path, andhttpare unavailable. Use Web standards such ascrypto.subtlefor randomness or digests. - Access files only through
ctx: usegetSettings/saveSettingsinside the vault. Local paths outside the vault are available only toagent-sessionconnectors, and only throughctx.desktopon desktop. - Addresses that need anti-hotlink headers: the local proxy behind
proxy: trueexists only on desktop. On mobile it degrades to a direct connection andheadersare 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 returnAccess-Control-Allow-Origin; otherwise playback fails withMEDIA_ELEMENT_ERROR: Format error. On desktop,proxy: truelets the local proxy add the headers; on mobile there is no proxy.
10. Share it with others
Section titled “10. Share it with others”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.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause |
|---|---|
Load error about manifest.id and the directory name | Directory name and id differ |
Load error mentioning ESM import / export | ESM syntax used; switch to module.exports |
Load error about exporting create(ctx) | The factory function is missing |
Player shows Unsupported file type | No connector matched; check whether match is too narrow |
403 / Format error during playback | Anti-hotlink headers or CORS; check proxy / headers and mobile differences |
| A resolve failed but you cannot tell where | Search the log for [connector.my-connector] |
For every field and lifecycle detail, see the Connector API reference.