Skip to content

Orbuzo source protocol — version 1 ​

Status: Draft of protocol 1.0. Breaking changes are allowed until the first source type is published. After that, 1.x only grows by additions, and anything that breaks goes to 2.0. The reference implementation is source-types/demo.

A source type is an adapter for one kind of place where media lives — a video site, a podcast service, a media server. It lists what is there, says what each item is, and on request downloads a file and hands its bytes to the host. It does not transcribe, summarize, index, or talk to the Orbuzo backend.

Files on the user's own computer are not a source type. Local Files is part of the app (sources.md). A source type gets nothing from the computer it runs on except the network: no file access through the host, and no paths.

In this document the host is the Orbuzo desktop app. The source type is the separate program it starts. Each running copy of that program serves one source.

Contents ​

  1. Source types and sources
  2. Transport
  3. Lifecycle
  4. Method summary
  5. Setup: getSourceTypeInfo, setOptions
  6. Content: getItems, getItem, search, getCaptions
  7. Files: download
  8. Housekeeping: ping, shutdown
  9. Notifications
  10. Types
  11. Errors
  12. Timeouts and limits
  13. Installing a source type
  14. Walkthrough: adding a source and downloading a file
  15. Rules for source type authors
  16. Sandboxing
  17. Not in version 1
  18. Design notes

Source types and sources ​

A source type is a program. A source is an instance of it that the user set up.

"VidHost" might be one source type. From it a user might create three sources: "My channel", "Conference talks", "Work account" — each set up differently.

The host runs one process per source (sources.md). Three VidHost sources means three processes of the same program. Each one gets its own options. A process never serves two sources, and never sees another source's settings.

Each source also has two settings the app keeps for itself and never passes to the source type: the folder its downloaded files are saved to, and whether they are deleted after import (sources.md).

So a source type never thinks about instances. It is started, given its options, and serves one source until it is told to stop.

Transport ​

JSON-RPC 2.0 over stdio.

  • stdin and stdout carry protocol messages. One JSON object per line, UTF-8, ending in \n. No raw newlines inside a message, no headers, no byte-order mark.
  • stdout is protocol only. Anything else a source type prints there breaks the stream. The host treats a line it cannot parse as a crash and kills the process.
  • stderr is for logs. The host keeps it in a local log file on the user's machine, tagged with the source type id, and rate-limited. It is never sent to the Orbuzo servers and never parsed.
  • The host sends requests; the source type sends notifications. Version 1 has no methods a source type can call on the host — the host answers any request from a source type with -32601. The transport still allows requests in both directions, so later versions can add host services without changing it. Host ids in the examples are numbers.
  • Requests can overlap. The host may send a new request before the last one is answered, and the source type may answer in any order. A source type that handles one request at a time is legal, just slower.
  • No batches. Neither side sends JSON-RPC batch arrays.
  • Exit code 0 means a clean shutdown. Anything else is reported as a crash.

Binary data never crosses this channel. A file travels out of band, from the source type to a one-time address the host opens for it (download). Filesystem paths never cross it either, in either direction.

The examples are pretty-printed and use // comments to explain fields. On the wire, each message is a single line of plain JSON with no comments.

Lifecycle ​

text
host starts the process
  │
  ├─► getSourceTypeInfo  who are you, which protocol, which options do you need
  ├─► setOptions         here is how the user configured this source
  │     (repeat only if it failed; once it succeeds, options are fixed)
  │
  ├─► getItems / getItem / search / getCaptions / download / ping     normal work
  │        ◄─ itemsChanged / progress / statusChanged                  source type tells the host
  │
  └─► shutdown           source type stops and exits with code 0
  • Before setOptions succeeds, the only methods a source type must answer are getSourceTypeInfo, setOptions, ping and shutdown. Anything else fails with -32005 (not configured).
  • Options are set once per process. When the user edits a source, the host shuts the process down and starts a new one with the new options. A source type never has to handle options changing under it.
  • The host starts a source's process when the source is first opened, not at app launch. It may stop an idle process and start it again later. A source type must not assume it lives long.
  • To show the "add a source" form, the host starts a process, calls getSourceTypeInfo, and then either continues with setOptions or calls shutdown. The host caches the getSourceTypeInfo answer per source type binary.
  • A source type that crashes is restarted by the host with the same options. Repeated crashes put the source in an error state the user can see.

Method summary ​

Host → source type requests:

MethodWhenResult
getSourceTypeInfoalways, firstSourceTypeInfo
setOptionsalways, secondStatus
getItemsafter setupItemPage
getItemafter setupItem
searchafter setup, if the source type has the search featureItemPage
getCaptionsafter setup{ tracks: CaptionTrack[] }
downloadafter setupDownloaded
pingany timeStatus
shutdownany timenull

Notifications (no reply):

NotificationDirection
itemsChangedsource type → host
progresssource type → host
statusChangedsource type → host
$/cancelRequesthost → source type

Calling a method the other side does not have returns -32601 (method not found). So does calling search on a source type that did not list the search feature, and so does any request a source type sends the host.

Setup ​

getSourceTypeInfo ​

The first request. The host says which protocol it speaks; the source type says who it is and what options a source of this type needs.

Host → source type:

jsonc
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getSourceTypeInfo",
    "params": {
        "protocol": "1.0",            // highest version the host speaks
        "host": {
            "name": "Orbuzo Desktop",
            "version": "0.1.0",
            "os": "windows"           // windows | darwin | linux
        },
        "locale": "en-US"             // for labels and messages; the source type may ignore it
    }
}

Source type → host:

jsonc
{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "versions": {
            "protocol": "1.0",        // highest version the source type speaks
            "source_type": "1.0.23"   // the source type's own version, semver
        },
        "about": {
            "id": "example.vidhost",       // stable forever; sources are linked to it
            "name": "VidHost",
            "author": "Example Ltd",
            "description": "Browse your channel and playlists on VidHost.",
            "url": "https://github.com/example/robolib-vidhost"   // only https://github.com/ allowed
        },
        "features": ["search"],       // optional abilities, see below
        "options": [
            {
                "name": "server",
                "label": "Server",
                "type": "string",
                "required": true,
                "value": "https://vidhost.example.com"
            },
            {
                "name": "include_private",
                "label": "Include private videos",
                "type": "bool",
                "value": false
            },
            {
                "name": "audio_quality",
                "label": "Audio quality",
                "type": "select",
                "value": "low",
                "choices": [
                    { "value": "low", "label": "Low (faster)" },
                    { "value": "high", "label": "High" }
                ]
            }
        ]
    }
}

Versions. A version is MAJOR.MINOR. The two sides can work together if the majors match. They then use the lower of the two minors — a minor version only adds things, so the lower one is a subset of the higher. If the majors differ, the host calls shutdown and tells the user the source type needs an update (or the app does).

about

FieldRequiredMeaning
idyesStable identifier, lowercase, [a-z0-9.-], 3–64 characters. Never changes between source type versions — the host links saved sources to it. A fork that is a different source type must pick a new id.
nameyesShown to the user as the source type. Up to 64 characters.
authoryesPerson or organisation. Up to 64 characters.
descriptionnoOne or two sentences. Up to 300 characters.
urlnoMust start with https://github.com/. Anything else is dropped by the host. Shown as a link, opened in the user's browser.

features — optional abilities. The host must not use a feature the source type did not list.

FeatureMeaning
searchThe source type answers search.
watchThe source type sends itemsChanged when content changes. Without it, the host refreshes only when the user asks.

Unknown feature names are ignored, so a newer source type works with an older host.

options is an array of OptionSpec, in the order the form should show them. A source type that needs no options sends an empty array.

setOptions ​

Tells the source type how the user configured this source. Params are an object: option name → value. Every option the source type declared is present, with the user's value or the default.

Host → source type:

jsonc
{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "setOptions",
    "params": {
        "server": "https://vidhost.example.com",
        "include_private": false,
        "audio_quality": "low"
    }
}

Source type → host, success:

jsonc
{
    "jsonrpc": "2.0",
    "id": 2,
    "result": {
        "status": "ready"             // see Status
    }
}

Source type → host, when an option is wrong:

jsonc
{
    "jsonrpc": "2.0",
    "id": 2,
    "error": {
        "code": -32602,
        "message": "Some settings need fixing.",
        "data": {
            "fields": {               // option name → message shown next to that field
                "server": "This server does not answer."
            }
        }
    }
}
  • The host has already checked types, required, min and max. The source type checks what only it can know — that a server answers, that a login works.
  • The result can also be "auth_required" or "unavailable" (see Status). The source is then saved, but shown as needing attention.
  • After a failed setOptions the host may call it again with corrected values. After a successful one, it never calls it again in this process.
  • An option added in a later version of the source type is missing for sources saved before it: the host sends what the user saved. Treat a missing option as its value. The settings form shows that default, and the option arrives once the user saves the settings.
  • password values arrive in plain text. The source type must never log them, echo them back, or put them in an item, error message or URL.

Content ​

getItems ​

Lists the children of a folder, one page at a time. A folder is whatever groups items on the source: a channel, a playlist, an album, a show.

Host → source type:

jsonc
{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "getItems",
    "params": {
        "parent_id": null,            // null = the top of this source
        "limit": 200,                 // optional; default 200, max 1000
        "cursor": null                // optional; from the previous page's next_cursor
    }
}

Source type → host:

jsonc
{
    "jsonrpc": "2.0",
    "id": 3,
    "result": {
        "items": [
            {
                "id": "uploads",
                "parent_id": null,
                "label": "My uploads",
                "type": "folder",     // folder | file
                "items_count": 312    // optional; null or absent if counting is expensive
            },
            {
                "id": "pl:42",
                "parent_id": null,
                "label": "Lectures 2026",
                "type": "folder",
                "items_count": 24
            }
        ],
        "next_cursor": null           // null or absent = this was the last page
    }
}

Next level down — host → source type:

jsonc
{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "getItems",
    "params": { "parent_id": "pl:42", "limit": 200, "cursor": null }
}

Source type → host:

jsonc
{
    "jsonrpc": "2.0",
    "id": 4,
    "result": {
        "items": [
            {
                "id": "v:9fK2",
                "parent_id": "pl:42",
                "label": "Lecture 2 — Query planning",
                "type": "file",
                "mime": "video/mp4",
                "duration_ms": 3725000,
                "modified_at": "2026-03-12T09:00:00Z",
                "caps": ["stt", "cc"] // has speech, and captions are available
            },
            {
                "id": "v:Qm81",
                "parent_id": "pl:42",
                "label": "Lecture 3 — Indexes",
                "type": "file",
                "mime": "video/mp4",
                "caps": ["stt"]       // has speech; needs transcription
            },
            {
                "id": "doc:17",
                "parent_id": "pl:42",
                "label": "Reading list",
                "type": "file",
                "mime": "text/plain",
                "caps": ["text"]      // imported as text, no transcription
            }
        ],
        "next_cursor": "t:CAoQAA"     // the site's own page token, wrapped; the host passes it back
    }
}

Unknown folder — source type → host:

jsonc
{
    "jsonrpc": "2.0",
    "id": 5,
    "error": { "code": -32002, "message": "This playlist no longer exists." }
}
  • The source type chooses the order, and keeps it stable across pages.
  • A cursor is the source type's own string. The host passes it back untouched and never reads it.
  • Listing must be fast. Do not download anything here — caps in a listing may be a best guess (from a "has captions" flag in the site's listing, say). getItem gives the exact answer.
  • A source type may list items the host can do nothing with, with no caps, so the source looks the way the user knows it. The host shows them greyed out.

getItem ​

Returns one item, with full detail. The host calls it before importing, and to refresh a single row. This is where a source type may do slower work, like fetching the item's full record from the site.

Host → source type:

jsonc
{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "getItem",
    "params": { "id": "v:9fK2" }
}

Source type → host:

jsonc
{
    "jsonrpc": "2.0",
    "id": 6,
    "result": {
        "id": "v:9fK2",
        "parent_id": "pl:42",
        "label": "Lecture 2 — Query planning",
        "type": "file",
        "mime": "video/mp4",
        "modified_at": "2026-03-12T09:00:00Z",
        "duration_ms": 3725000,
        "caps": ["stt", "cc"],        // exact, not a guess
        "meta": {                     // optional; shown in the item's details
            "title": "Lecture 2 — Query planning",
            "author": "Dr. A. Stone",
            "language": "en",
            "published_at": "2026-03-12T09:00:00Z"
        }
    }
}

getItem works for folders too, and returns the same fields as the listing.

Only if the source type listed the search feature. Finds items anywhere in this source. How matching works is up to the source type — by title, by tag, by whatever the source supports.

Host → source type:

jsonc
{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "search",
    "params": {
        "query": "lecture",
        "limit": 50,
        "cursor": null
    }
}

Source type → host:

jsonc
{
    "jsonrpc": "2.0",
    "id": 7,
    "result": {
        "items": [
            {
                "id": "v:9fK2",
                "parent_id": "pl:42",        // where it lives, so the host can show the path
                "label": "Lecture 2 — Query planning",
                "type": "file",
                "mime": "video/mp4",
                "caps": ["stt", "cc"]
            }
        ],
        "next_cursor": null
    }
}

The query is the user's words. The source type must not log it.

getCaptions ​

Lists the caption tracks available for a file. An item without cc returns an empty list, not an error. To get a track's text, the host downloads it.

Host → source type:

jsonc
{
    "jsonrpc": "2.0",
    "id": 8,
    "method": "getCaptions",
    "params": { "id": "v:9fK2" }
}

Source type → host:

jsonc
{
    "jsonrpc": "2.0",
    "id": 8,
    "result": {
        "tracks": [
            {
                "id": "en",                   // source type's own id for the track
                "language": "en",             // BCP 47, or null if unknown
                "label": "English",
                "format": "vtt",              // srt | vtt | ass | ssa | ttml | dfxp
                "generated": false            // true = machine-made (automatic captions)
            },
            {
                "id": "en-auto",
                "language": "en",
                "label": "English (automatic)",
                "format": "vtt",
                "generated": true
            }
        ]
    }
}
  • format is what the source type will send. A site with a caption format of its own must convert it to one of these first.
  • Only text captions count. Image-based subtitles cannot become text and must not be listed.
  • The host picks a track; the user can override it. If there is more than one, the source type should list the best one first.
  • The host calls this when the user opens a file's captions, to fill the track picker — so answer quickly, from the site's listing, without downloading anything. The text comes later, through download, and only when the user asks for it.
  • Give the same tracks, with the same ids, on every call. The host lists the tracks with one call and downloads one by its id with the next, maybe seconds later. A track picked from an unordered map, or chosen differently from one site answer to the next, fails as "not found" at download.

Files ​

download ​

Asks the source type for one file's bytes — the item itself, or one of its caption tracks. The source type downloads it, then sends it to the host; the host decides where it is saved (sources.md).

For each download the host opens a sink: a one-time address on this computer, with its own token and a size limit. The source type sends the file there with one HTTP PUT, and only then answers the request.

Host → source type:

jsonc
{
    "jsonrpc": "2.0",
    "id": 9,
    "method": "download",
    "params": {
        "id": "v:Qm81",
        "track": null,                // or a track id from getCaptions: send that track instead
        "sink": {
            "kind": "http",           // the only kind in 1.0; see below
            "url": "http://127.0.0.1:51234/in/5f0c9e…",
            "headers": { "Authorization": "Bearer 3f9a…" },
            "max_size": 68719476736   // bytes; a larger file is refused
        }
    }
}

The source type gets the file however its site requires — following redirects, refreshing an expired link, joining the parts of a segmented stream, converting captions. Then:

http
PUT /in/5f0c9e… HTTP/1.1
Host: 127.0.0.1:51234
Authorization: Bearer 3f9a…
Content-Type: audio/mp4
Content-Length: 41943040

<the bytes>

The host answers the PUT:

StatusMeaning
201Stored. Now answer the download request.
401Missing or wrong Authorization.
404No such sink — it was closed, for example after a cancel.
409This sink already received a file. A sink takes exactly one.
410The download was cancelled while the bytes were arriving.
413Larger than max_size.

Source type → host, after the 201:

jsonc
{
    "jsonrpc": "2.0",
    "id": 9,
    "result": {
        "file_name": "Lecture 3 — Indexes.m4a",  // a suggestion; the host cleans it up
        "mime": "audio/mp4",
        "size": 41943040
    }
}
  • Send the file first, answer second. If the source type answers before the host has the whole file, the download fails.
  • Send Content-Length when you know it. The app shows the download's percent from it. Without it, send chunked; the host still stops at max_size, and shows the percent from your progress notifications if you send them.
  • Pick the smallest file that is enough. Orbuzo needs speech, not pictures. If the site offers an audio-only version, send that.
  • Send progress notifications during a long download. Together with the bytes arriving they keep the download alive (see Timeouts). Their percent shows in the app when there is no Content-Length and the source has only this one download running.
  • On $/cancelRequest, stop. The host closes the sink; answer with -32800.
  • The sink is a secret. Its URL and token are for this one download. Never log them.
  • Accept only a loopback sink. A source type should refuse to send a file anywhere but 127.0.0.1 or [::1].
  • The host does the rest: it writes the bytes to a temporary file in the source's files folder, gives the file its final name only when the download succeeded, and deletes it otherwise. A text item's file is imported as text; a media file's audio is extracted by FFmpeg.

sink.kind is "http" in version 1. A later version may add other kinds — for example a named pipe for sandboxed source types. A source type that gets a kind it does not know answers -32602.

Errors: -32002 (item or track not found), -32602 (the item is a folder, or the sink kind is unknown), -32003 (the site refused), -32004 (the site is unavailable), -32001 (sign-in needed), -32800 (cancelled), -32603 (the file could not be sent to the host).

Housekeeping ​

ping ​

Checks the source type is alive and returns its current status. Allowed at any time, even before setOptions.

Host → source type:

jsonc
{ "jsonrpc": "2.0", "id": 11, "method": "ping" }

Source type → host:

jsonc
{ "jsonrpc": "2.0", "id": 11, "result": { "status": "ready" } }

Before setOptions succeeds, the status is "not_configured".

shutdown ​

Asks the source type to stop. The source type stops work in progress, answers, and exits with code 0.

Host → source type:

jsonc
{ "jsonrpc": "2.0", "id": 12, "method": "shutdown" }

Source type → host:

jsonc
{ "jsonrpc": "2.0", "id": 12, "result": null }
  • Requests still in flight may be answered with -32800 (cancelled) or left unanswered; the host has already given up on them.
  • The host closes the source type's stdin after the reply. A source type that reaches end of stdin at any time must exit, as if told to shut down.
  • If the process has not exited 3 seconds after shutdown, the host kills it.

Notifications ​

A notification has no id and gets no reply.

itemsChanged ​

Source type → host. Something in this source changed; the host should list it again. Only source types with the watch feature send it.

jsonc
{
    "jsonrpc": "2.0",
    "method": "itemsChanged",
    "params": {
        "parent_id": "pl:42"          // this folder changed; null = the top; absent = anything
    }
}

The host waits a moment and merges bursts, so a source type need not throttle it much. More than one per second is still too many.

progress ​

Source type → host. A slow request is still working. Each one also resets that request's timeout, and keeps a download alive (see Timeouts).

jsonc
{
    "jsonrpc": "2.0",
    "method": "progress",
    "params": {
        "request_id": 7,              // the host's id of the request in progress
        "percent": 40,                // optional, 0–100
        "message": "Downloading…"     // optional, shown to the user
    }
}

statusChanged ​

Source type → host. The source's health changed after setup — the site went down, a login expired, things are back to normal.

jsonc
{
    "jsonrpc": "2.0",
    "method": "statusChanged",
    "params": {
        "status": "unavailable",
        "message": "VidHost is not answering. Orbuzo will try again shortly."
    }
}

When a login is needed:

jsonc
{
    "jsonrpc": "2.0",
    "method": "statusChanged",
    "params": {
        "status": "auth_required",
        "message": "Sign in to continue.",
        "url": "https://example.com/oauth/authorize?client_id=…"   // opened in the user's browser
    }
}

The host shows the message on the source, and opens url only when the user clicks. The source type notices the sign-in finished by its own means, and then sends "status": "ready".

$/cancelRequest ​

Host → source type. The host no longer wants the answer to a request — the user closed the folder, typed a new search, or stopped a download.

jsonc
{
    "jsonrpc": "2.0",
    "method": "$/cancelRequest",
    "params": { "id": 7 }
}

The source type should stop and answer that request with an error:

jsonc
{
    "jsonrpc": "2.0",
    "id": 7,
    "error": { "code": -32800, "message": "Cancelled." }
}

If the request already finished, the source type ignores the notification. The host ignores any answer to a request it cancelled.

Types ​

All field names are snake_case. All times are RFC 3339 in UTC (2026-03-11T09:00:00Z). All sizes are bytes. All durations are milliseconds. Unknown fields must be ignored by both sides — that is how a minor version adds things.

SourceTypeInfo ​

The result of getSourceTypeInfo: versions, about, features, options. Described there.

OptionSpec ​

One field in the "add a source" form.

FieldRequiredMeaning
nameyesKey used in setOptions. [a-z0-9_], unique within the source type.
labelyesField label.
descriptionnoHelp text under the field.
typeyesOne of the types below.
valuenoDefault value, of the option's type. Not allowed for password. Also what a source saved before the option existed should assume.
requirednotrue = the form cannot be saved empty. Default false.
min, maxnoFor int and float: allowed range, inclusive. For string: length.
choicesselect onlyArray of { "value", "label" }. value is a string or a number.
TypeValue in setOptionsForm control
stringstringtext box
passwordstringpassword box; stored in the OS credential store, never shown again
intintegernumber box, whole numbers
floatnumbernumber box
booltrue / falsecheckbox
selectone of the choices valuesdrop-down

There is no folder type: a source type gets no access to this computer's files. (Protocol drafts had a directory type; a host refuses a source type that still asks for one.)

An optional field the user left empty arrives as null.

Every type, in one example:

jsonc
"options": [
    { "name": "server",   "label": "Server address", "type": "string", "required": true,
      "value": "https://media.example.com" },
    { "name": "username", "label": "User name", "type": "string" },
    { "name": "password", "label": "Password",  "type": "password" },
    { "name": "page_size","label": "Items per request", "type": "int", "value": 100,
      "min": 10, "max": 500 },
    { "name": "min_minutes", "label": "Hide recordings shorter than (minutes)", "type": "float",
      "value": 0.5, "min": 0 },
    { "name": "archived", "label": "Include archived", "type": "bool", "value": false },
    { "name": "quality",  "label": "Audio quality", "type": "select", "value": "low",
      "choices": [ { "value": "low", "label": "Low (faster)" },
                   { "value": "high", "label": "High" } ] }
]

Status ​

jsonc
{ "status": "ready", "message": null, "url": null }
statusMeaning
not_configuredsetOptions has not succeeded yet. Only ping returns this.
readyWorking normally.
unavailableTemporarily cannot reach its content. Content calls fail with -32004.
auth_requiredNeeds the user to sign in. url may say where. Content calls fail with -32001.

message is shown to the user, so it is a plain sentence.

Item ​

FieldRequiredMeaning
idyesThe source type's id for the item. Opaque, non-empty string, up to 1024 characters.
parent_idyesThe containing folder's id, or null at the top.
labelyesName shown in the tree.
typeyesfolder or file.
items_countnoFolders only. Number of children, if cheap to know.
sizenoFiles only.
mimenoFiles only.
modified_atno
duration_msnoFiles with audio or video.
capsnoFiles only. What the host can do with it — see below.
metanotitle, author, language (BCP 47), published_at, description. All optional.

Ids. The host never parses an id, and passes it back exactly. Ids should stay the same across restarts — the host uses them to remember what was already imported. Build them from the site's own stable ids, not from positions or titles. folder and file are general: a playlist, an album or a channel is a folder.

caps — how an item can be imported:

CapMeaningImport
ccCaption tracks are available from getCaptions.Fast and free: a track is downloaded, and its text uploaded.
sttThe file has speech in an audio track.The file is downloaded, the host extracts the audio, the server transcribes it. Costs money and takes minutes.
textThe file is a text document.The file is downloaded, and its text uploaded as an untimed transcript.

A file can have both cc and stt; the host prefers captions. A file with no caps is not importable. Unknown caps are ignored.

Unknown metadata is better left out than guessed. Every optional field may be absent.

ItemPage ​

jsonc
{ "items": [ /* Item */ ], "next_cursor": "opaque-or-null" }

CaptionTrack ​

FieldRequiredMeaning
idyesThe source type's id for the track. Passed back as track in download.
languageyesBCP 47 tag, or null if unknown.
labelnoShown in the track picker.
formatyessrt, vtt, ass, ssa, ttml or dfxp — the format download sends.
generatednotrue if machine-made. Default false.

Sink ​

Where download sends a file. Opened by the host for one download, and closed after it.

FieldMeaning
kind"http" in version 1.
urlhttp://127.0.0.1:<port>/… or http://[::1]:<port>/…. Send one PUT here.
headersSend these with the PUT. Secret.
max_sizeThe most bytes the host accepts.

Downloaded ​

The result of download.

FieldRequiredMeaning
file_nameyesA name for the file, with its extension: the item's label as listed, so the file is named the way the user saw it. The host removes characters no OS allows, and numbers it if the name is taken.
mimenoThe file's media type.
sizenoBytes sent.

Errors ​

Error responses follow JSON-RPC: { "code", "message", "data"? }.

message is shown to the user. It is a plain sentence — "This playlist no longer exists." — not a stack trace, an exception name or a URL. Details go to stderr.

Standard codes:

CodeMeaning
-32700The message was not valid JSON. The receiver may also treat this as a crash.
-32600Not a valid request.
-32601Method not found, or a feature the source type did not declare.
-32602Invalid params. For setOptions, data.fields maps option names to messages.
-32603Internal error.

Source type errors:

CodeMeaningHost does
-32800Request cancelled.Nothing.
-32001Sign-in needed.Shows the source as needing sign-in.
-32002Item not found.Refreshes the parent folder.
-32003The source refused access to this item.Shows the message on the item.
-32004Source temporarily unavailable. Retrying later is reasonable.Retries with back-off.
-32005Not configured — setOptions has not succeeded.Treats as a host bug.

data is optional and free-form, except for data.fields above. Neither side may put secrets or file contents in it.

Timeouts and limits ​

The host enforces these. A source type that goes over them is not warned — its request fails, or its process is killed.

WhatLimit
getSourceTypeInfo answered after start5 s, or the process is killed
ping2 s
setOptions, getItems, getItem, search, getCaptions30 s each
Each progress notificationresets that request's 30 s, up to 5 minutes in total
downloadno total limit; fails after 60 s with no bytes arriving and no progress notification
File sent to a sinkat most max_size bytes
Process exit after shutdown3 s, then killed
One message (one line)1 MiB — a bigger line from the source type kills the process
Page sizegetItems and search return at most limit items
stderrrate-limited; lines past the limit are dropped

A source type that fails 3 times in 5 minutes (crash, kill or garbage on stdout) is not restarted again until the user asks.

Installing a source type ​

A source type is a folder inside source-types/, next to the Orbuzo program. The folder holds one program named source-type.exe on Windows, or source-type on macOS and Linux, and anything else the source type needs.

text
Orbuzo.exe
source-types/
  vidhost/
    source-type.exe
    README.md
  podcast-archive/
    source-type.exe
  • The folder's name does not matter to the protocol; the source type's about.id does. Two folders that report the same id: the first by folder name is used, the other is shown as a problem.
  • The host starts the program with the source type's folder as its working directory.
  • When the user clicks "Add a source", the host looks at every folder, starts each program it has not seen, and calls getSourceTypeInfo. It remembers the answer until the program file changes.
  • A folder that cannot be used — no program, no answer in time, a protocol version this host does not speak — is still listed, with the reason, rather than hidden.
  • Debug builds of Orbuzo include source-types/demo, a source type for a made-up site. It is the reference implementation of this document.

Walkthrough ​

A user adds a "Lectures" source from the VidHost source type and downloads two files. Only the key messages are shown; … means "as in the examples above".

1. Add a source. The user picks "VidHost". The host starts a process.

jsonc
// host → source type
{"jsonrpc":"2.0","id":1,"method":"getSourceTypeInfo","params":{"protocol":"1.0", …}}
// source type → host
{"jsonrpc":"2.0","id":1,"result":{"versions":{"protocol":"1.0","source_type":"0.3.0"}, …}}

The host builds the form from options, under its own fields: the source's name, and where its downloaded files go. The user fills it in and saves.

jsonc
// host → source type
{"jsonrpc":"2.0","id":2,"method":"setOptions",
 "params":{"server":"https://vidhost.example.com","include_private":false,"audio_quality":"low"}}
// the source type checks the server answers — its own HTTPS, not part of this protocol
// source type → host
{"jsonrpc":"2.0","id":2,"result":{"status":"ready"}}

The host saves the source: source type id, name, options (passwords in the OS credential store), and its files folder. This process now serves "Lectures".

2. Browse. The user expands the source.

jsonc
// host → source type
{"jsonrpc":"2.0","id":3,"method":"getItems","params":{"parent_id":null,"limit":200}}
// source type → host: the user's playlists, as folders
{"jsonrpc":"2.0","id":3,"result":{"items":[ … ],"next_cursor":null}}

3. Download captions. The user imports v:9fK2, which shows cc.

jsonc
// host → source type
{"jsonrpc":"2.0","id":4,"method":"getCaptions","params":{"id":"v:9fK2"}}
// source type → host
{"jsonrpc":"2.0","id":4,"result":{"tracks":[{"id":"en","language":"en","format":"vtt", …}]}}
// host → source type
{"jsonrpc":"2.0","id":5,"method":"download","params":{"id":"v:9fK2","track":"en",
 "sink":{"kind":"http","url":"http://127.0.0.1:51234/in/5f0c…","headers":{ … },"max_size":68719476736}}}
// the source type fetches the captions from the site and PUTs them to the sink → 201
// source type → host
{"jsonrpc":"2.0","id":5,"result":{"file_name":"Lecture 2 — Query planning.en.vtt","mime":"text/vtt","size":48211}}

The host saves the file in the source's files folder and uploads the subtitle text. No audio leaves the machine.

4. Download a file that needs transcription. The user imports v:Qm81, which shows only stt.

jsonc
// host → source type
{"jsonrpc":"2.0","id":6,"method":"download","params":{"id":"v:Qm81","sink":{ … }}}
// the source type picks the site's audio-only version and PUTs it to the sink, reporting progress
{"jsonrpc":"2.0","method":"progress","params":{"request_id":6,"percent":40}}
// … → 201
// source type → host
{"jsonrpc":"2.0","id":6,"result":{"file_name":"Lecture 3 — Indexes.m4a","mime":"audio/mp4","size":41943040}}

The host saves the file, extracts the audio with FFmpeg, and uploads it for transcription. The source type's part ended with the 201.

5. Close. The user quits the app.

jsonc
// host → source type
{"jsonrpc":"2.0","id":7,"method":"shutdown"}
// source type → host
{"jsonrpc":"2.0","id":7,"result":null}
// source type exits with code 0

Rules for source type authors ​

  1. Write nothing but protocol messages to stdout. Log to stderr.
  2. Serve one source. Your options arrive once, in setOptions. Do not store them — the host passes them in on every start.
  3. Do not touch the user's files. You never need a path: to hand over a file, send it to the sink. A source type that needs nothing but the network will keep working when source types are sandboxed.
  4. Keep getItems and search fast. Download only in download.
  5. Keep item ids stable. The host uses them to remember what was imported.
  6. Answer every request — with a result or an error. Fail rather than hang: the host's timeout gives the user a worse message than yours.
  7. In download, send the file first and answer second. Send progress while a long file is on its way.
  8. Stop quickly on $/cancelRequest, shutdown, or end of stdin.
  9. Never log passwords, tokens, search queries, sink addresses, or the contents of files. Prefer not to log titles — the log file may end up attached to a bug report.
  10. Ignore fields and caps you do not recognise, so a newer host does not break you.

Sandboxing ​

Today the host does not restrict what a source process can do. A source type runs as the user, and could open any file the user can. Only install source types you trust.

Version 1 is built so that this can change without breaking any source type (sources.md). A source type gets everything it needs through the protocol or the network: its settings from setOptions, a place for files through the sink, a log through stderr. So a later host can start source types in an OS sandbox — AppContainer on Windows, Seatbelt on macOS, Landlock on Linux — that allows the network and the source type's own folder, and nothing else: not the user's files, and not the OS credential store.

A sandbox will not stop a source type from lying — returning junk items, or sending junk bytes. The host checks what it receives either way.

Not in version 1 ​

Kept out on purpose. Each can arrive in a 1.x minor version, because they are all additions.

  • Thumbnails. Orbuzo stores no images (CLAUDE.md rule 2), and the tree does not need them yet.
  • Source type storage — a place for a source type to keep a login token between runs, backed by the OS credential store. Needed by the first source type that signs in to a service. Until then, a source type signs in again whenever its process restarts.
  • A sandbox. See Sandboxing. On Windows it needs a second sink kind, because AppContainer blocks connections to 127.0.0.1 by default.
  • Resuming a download. A failed download starts again from the beginning, with a new sink.

Design notes ​

Why version 1 looks the way it does.

  • Setup is two calls, not one. getSourceTypeInfo works without any configuration, so the host can use it to build the "add a source" form. setOptions then configures the same process. There is no separate manifest file: the source type describes itself.
  • Options are an array, not an object keyed by name. Many JSON libraries (Go maps among them) do not keep key order, and the form must show fields in the order the author intended.
  • Choices are choices, not options, so the word "options" means one thing.
  • Failure is a JSON-RPC error, not result: 0. Errors then look the same for every method, and setOptions can say which field is wrong.
  • Ids are strings everywhere. Mixing numbers and strings makes every host and source type handle both.
  • getItems returns a page, not a bare array, so a channel with 50,000 videos does not produce one enormous message.
  • The source type downloads, not the host. The source type knows its site: redirects, segmented streams, expiring links, logins. Earlier drafts had the host fetch a URL the source type gave it, which put all of that in the host, and the site's token with it (sources.md).
  • Bytes go to a sink, not over stdio. JSON lines are no place for a gigabyte, and a separate one-time address lets the host stop at a size limit, and throw away a half-sent file.
  • Local Files is not a source type. It was the only source type that needed the disk, and it needed a whole set of host services to do it safely. In the app, it needs none of them, and source types need no file access at all (sources.md).