Skip to content

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.

json
{
  "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:

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>

When the app answers 201, answer the request with a name for the file:

json
{ "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 PUTMeans
201Stored. Now answer the download request.
401Missing or wrong Authorization.
404No such sink — it was closed, after a cancel for example.
409This sink already has a file. A sink takes exactly one.
410The user cancelled while the bytes were arriving.
413Larger 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-Length when you know it. The app shows a percentage from it. Without it, send the body chunked.

  • Send progress during a long download. It keeps the download alive: a download fails after 60 seconds with no bytes arriving and no progress. 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.1 or [::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 ​

CodeWhen
-32002The item or track is not there.
-32602The item is a folder, or the sink kind is one you do not know.
-32003The site refused.
-32004The site is unavailable for now.
-32001The user needs to sign in.
-32800Cancelled.
-32603The 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.