Install and test
Where a source type goes, how the app finds it, and how to see what it says.
The folder
A source type is a folder inside source-types/, next to the Orbuzo program. The folder holds one program — source-type.exe on Windows, source-type on macOS and Linux — and anything else it needs.
Orbuzo.exe
source-types/
vidhost/
source-type.exe
README.md- The folder's name does not matter; your
about.iddoes. Keep it the same forever: saved sources are linked to it. - The app starts your program with its folder as the working directory.
- When the user clicks Add a source…, the app 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 the app does not speak — is still listed, with the reason.
To test a build without copying it next to the app each time, set ROBOLIB_SOURCE_TYPES_DIR to the folder that holds your source type's folder.
Your log
Everything you write to stderr goes to a log file on the user's computer, one per source type, in Orbuzo's cache folder (%LOCALAPPDATA%\Orbuzo\logs\source-types\ on Windows). Lines are rate-limited. Never log passwords, tokens, search queries, sink addresses or file contents, and prefer not to log titles: a log may end up attached to a bug report.
Source traffic
Debug builds of Orbuzo record every line between the app and its source types, and show it in View › Source traffic — or a source's Show traffic. You see each request, its answer, how long it took, and your stderr, live. A malformed line shows exactly as it was sent, which is often the bug.
Limits
The app enforces these without warning. A source type that goes over them has its request fail, or its process stopped.
| What | Limit |
|---|---|
Answering getSourceTypeInfo after start | 5 s |
ping | 2 s |
setOptions, getItems, getItem, search, getCaptions | 30 s each; a progress notification resets it, up to 5 minutes |
download | no total limit; fails after 60 s with no bytes and no progress |
Exiting after shutdown | 3 s |
| One message | 1 MiB |
A source type that fails 3 times in 5 minutes — a crash, a kill, or garbage on stdout — is not restarted until the user asks.
Before you publish
- Write nothing but protocol messages to stdout.
- Keep item ids stable across restarts. The app uses them to remember what was imported.
- Answer every request, with a result or an error. Fail rather than hang.
- Keep
getItemsandsearchfast. Download only indownload. - Stop quickly on
$/cancelRequest,shutdown, or the end of stdin. - Ignore fields and caps you do not recognise, so a newer app does not break you.