Skip to content

How source types work ​

A source type is a small program that lets Orbuzo's desktop app browse a site or service and download from it. You can write one in any language that reads and writes lines.

Words ​

  • A source type is the program: "VidHost", "Podcast archive".
  • A source is one the user set up from it, with their own settings: "My channel", "Conference talks". A user can make many sources from one source type.
  • The host is the Orbuzo desktop app, which starts your program and talks to it.

Local Files is not a source type. Files on the user's own disks are part of the app itself.

What a source type does ​

It lists what is in a place, says what each file is, and downloads a file when the user asks. That is all. It does not transcribe, summarise or talk to Orbuzo's servers — the app does those.

text
your source type ──JSON-RPC over stdin/stdout──► Orbuzo desktop app ──HTTPS──► Orbuzo
        │                                              ▲
        └──────── one HTTP PUT per download ───────────┘  (to 127.0.0.1)

How it talks to the app ​

  • JSON-RPC 2.0 over stdio. One JSON message per line on stdin and stdout. The app sends requests; you answer them, and send a few notifications of your own.
  • stdout is for messages only. Anything else you print there breaks the stream. Log to stderr: the app keeps it in a log file on the user's computer and never sends it anywhere.
  • One process per source. Three sources made from your source type are three copies of your program, each started with its own settings. A process never sees another source's settings.
  • Settings arrive once. The app saves the user's settings and passes them in every time it starts you, with setOptions. When the user edits a source, the app starts a fresh process. Store nothing.

The network, and nothing else ​

A source type gets nothing from the computer but the network:

  • no files — you never read or write the user's disk;
  • no paths, in either direction;
  • no file bytes in JSON-RPC messages.

To hand over a file, the app gives you a one-time address on 127.0.0.1, and you PUT the bytes there. The app decides where the file is saved. See Downloads and the sink.

This keeps source types ready for a sandbox. A later version of the app can start them with access to the network and their own folder, and nothing else, without breaking a source type that follows these rules.

The calls ​

The app callsYou answer with
getSourceTypeInfowho you are, and the settings a source needs
setOptionswhether those settings work
getItemsa page of what is in a folder
getItemone item, in full
searchitems matching a query, if you offer search
getCaptionsa file's subtitle tracks
downloada file or a track, sent to the sink
ping, shutdownyour status; stopping

Every message, field and error is in the protocol reference.

Next ​

Your first source type builds a working one in about 250 lines of Go.