Downloads and the sink
Your source type never writes a file. When the user downloads something, the app gives you a one-time address on this computer, and you send the bytes there.
The request
The app calls download with the item and a sink: an address, the headers to send with it, and the largest size it will take. track names a subtitle track from getCaptions, or is null for the file itself.
{
"jsonrpc": "2.0",
"id": 9,
"method": "download",
"params": {
"id": "v:Qm81",
"track": null,
"sink": {
"kind": "http",
"url": "http://127.0.0.1:51234/in/5f0c9e…",
"headers": { "Authorization": "Bearer 3f9a…" },
"max_size": 68719476736
}
}
}Send the file, then answer
Get the file however the site needs — follow redirects, refresh an expired link, join a stream that comes in parts, convert captions. Then send it with one HTTP PUT:
PUT /in/5f0c9e… HTTP/1.1
Host: 127.0.0.1:51234
Authorization: Bearer 3f9a…
Content-Type: audio/mp4
Content-Length: 41943040
<the bytes>When the app answers 201, answer the request with a name for the file:
{ "jsonrpc": "2.0", "id": 9, "result": { "file_name": "Lecture 3 — Indexes.m4a", "mime": "audio/mp4", "size": 41943040 } }Order matters
If you answer before the app has the whole file, the download fails.
| The app answers the PUT | Means |
|---|---|
201 | Stored. Now answer the download request. |
401 | Missing or wrong Authorization. |
404 | No such sink — it was closed, after a cancel for example. |
409 | This sink already has a file. A sink takes exactly one. |
410 | The user cancelled while the bytes were arriving. |
413 | Larger than max_size. |
Good habits
Send the smallest file that is enough. Orbuzo needs speech, not pictures. If the site has an audio-only version, send that.
Send
Content-Lengthwhen you know it. The app shows a percentage from it. Without it, send the body chunked.Send
progressduring a long download. It keeps the download alive: a download fails after 60 seconds with no bytes arriving and noprogress. There is no limit on the total time.json{ "jsonrpc": "2.0", "method": "progress", "params": { "request_id": 9, "percent": 40 } }Stop on
$/cancelRequest. The app closes the sink; answer with-32800.Treat the sink as a secret. Its address and token are for this one download. Never log them.
Send only to a loopback address. Refuse a sink that is not on
127.0.0.1or[::1].
What the app does with it
The app writes the bytes to a temporary file in the source's folder, and gives it its final name only when the download worked; otherwise it deletes it. A text file is imported as text. For a media file, the app takes the audio out with FFmpeg and uploads only that.
Errors
| Code | When |
|---|---|
-32002 | The item or track is not there. |
-32602 | The item is a folder, or the sink kind is one you do not know. |
-32003 | The site refused. |
-32004 | The site is unavailable for now. |
-32001 | The user needs to sign in. |
-32800 | Cancelled. |
-32603 | The file could not be sent to the app. |
An error's message is shown to the user, so write a plain sentence: "This video is private." Put details in your log.