Skip to content

misterdownloadmanager: The ultimate open-source, clean-room download manager written from scratch in pure Rust for Windows, Mac, and Linux

27.9 KB
Raw Blame
{
  "$defs": {
    "ActAnswer": {
      "description": "`{\"action\": …, \"ids\": […]}`: what was done, and what was skipped and why.",
      "properties": {
        "done": {
          "items": {
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          },
          "type": "array"
        },
        "skipped": {
          "items": {
            "$ref": "#/$defs/Skipped"
          },
          "type": "array"
        }
      },
      "required": [
        "done",
        "skipped"
      ],
      "type": "object"
    },
    "AddAnswer": {
      "description": "An address added (`url`): the download's id, or `pending` while a torrent's files are looked\nup (it joins the list once they are known).",
      "properties": {
        "id": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "pending": {
          "default": false,
          "type": "boolean"
        }
      },
      "type": "object"
    },
    "ApiAnswer": {
      "description": "`{\"api\": true}` / `{\"api\": false}`: the API's new state.",
      "properties": {
        "api": {
          "type": "boolean"
        }
      },
      "required": [
        "api"
      ],
      "type": "object"
    },
    "BrowserCookie": {
      "description": "One cookie as the browser keeps it (`cookies.getAll`'s fields, under the extension's names\ntoo: `hostOnly`, `expirationDate`).",
      "properties": {
        "domain": {
          "default": "",
          "description": "`.youtube.com` (sent to its subdomains too) or a host name.",
          "type": "string"
        },
        "expires": {
          "default": null,
          "description": "When it expires, in seconds since 1970; none: when the browser closes.",
          "format": "double",
          "type": [
            "number",
            "null"
          ]
        },
        "host_only": {
          "default": false,
          "description": "Sent to `domain` itself only, never its subdomains.",
          "type": "boolean"
        },
        "name": {
          "default": "",
          "type": "string"
        },
        "path": {
          "default": "",
          "type": "string"
        },
        "secure": {
          "default": false,
          "description": "Sent over HTTPS only.",
          "type": "boolean"
        },
        "value": {
          "default": "",
          "type": "string"
        }
      },
      "type": "object"
    },
    "CategoryInfo": {
      "description": "One category of the list.",
      "properties": {
        "key": {
          "description": "What `category` takes and a download's `category` says (a built-in category's English\nname, as shipped).",
          "type": "string"
        },
        "name": {
          "description": "Its name as the user sees it: a built-in one's English name (translated where it is\nshown) unless the user renamed it.",
          "type": "string"
        }
      },
      "required": [
        "key",
        "name"
      ],
      "type": "object"
    },
    "DownloadInfo": {
      "description": "One download of the list.",
      "properties": {
        "added": {
          "description": "When it was added, as the list shows it; null for downloads from before that column.",
          "type": [
            "string",
            "null"
          ]
        },
        "category": {
          "default": "",
          "description": "Its category's `key` (see [`CategoryInfo`]).",
          "type": "string"
        },
        "downloaded": {
          "description": "Bytes downloaded so far.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "error": {
          "description": "Why it failed, for a download in `Error`.",
          "type": [
            "string",
            "null"
          ]
        },
        "file": {
          "description": "The file's name.",
          "type": "string"
        },
        "id": {
          "description": "What the actions take (`ids`); never reused.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "path": {
          "description": "Where it is saved: the file, or a torrent's folder.",
          "type": "string"
        },
        "size": {
          "description": "Its size in bytes; null while unknown.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "speed": {
          "description": "Bytes per second; 0 when it isn't running.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "status": {
          "description": "`Queued` (added, never started), `Downloading`, `Stopped`, `Complete` or `Error`.",
          "type": "string"
        },
        "url": {
          "description": "Its address (a video's page, a torrent's magnet link).",
          "type": "string"
        }
      },
      "required": [
        "id",
        "file",
        "url",
        "path",
        "status",
        "downloaded",
        "speed"
      ],
      "type": "object"
    },
    "ErrorAnswer": {
      "description": "An unknown question or action, or a question while the API is off.",
      "properties": {
        "code": {
          "description": "For programs: `\"api-off\"` while the API is off.",
          "type": [
            "string",
            "null"
          ]
        },
        "error": {
          "description": "For people; its wording may change.",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object"
    },
    "ListAnswer": {
      "description": "`{\"query\": \"list\"}`: every download, and the total speed.",
      "properties": {
        "categories": {
          "default": [],
          "description": "The categories a new download can go to (General first).",
          "items": {
            "$ref": "#/$defs/CategoryInfo"
          },
          "type": "array"
        },
        "downloads": {
          "items": {
            "$ref": "#/$defs/DownloadInfo"
          },
          "type": "array"
        },
        "free": {
          "default": null,
          "description": "Free space where downloads go (the General category's folder), bytes; null when unknown.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "queues": {
          "default": [],
          "description": "The queues, in the Scheduler's order (the first is the main queue).",
          "items": {
            "$ref": "#/$defs/QueueInfo"
          },
          "type": "array"
        },
        "speed": {
          "description": "The total download speed, bytes per second.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "downloads",
        "speed"
      ],
      "type": "object"
    },
    "PairAnswer": {
      "description": "`{\"pair\": true}` (#157): a new pairing code for the remote control, while it is on.",
      "properties": {
        "code": {
          "description": "The 8-digit code; it works once, for `minutes`.",
          "type": "string"
        },
        "minutes": {
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "qr": {
          "description": "A QR code of the first address with the code, drawn with text blocks for a terminal.",
          "type": "string"
        },
        "urls": {
          "description": "The page's addresses, the one a phone most likely reaches first.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "code",
        "minutes",
        "urls",
        "qr"
      ],
      "type": "object"
    },
    "QueueInfo": {
      "description": "One queue of the list.",
      "properties": {
        "ids": {
          "description": "Its downloads' ids, in its order.",
          "items": {
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          },
          "type": "array"
        },
        "name": {
          "description": "Its name: what `queue` takes (a built-in queue's in English, as shipped).",
          "type": "string"
        },
        "running": {
          "description": "Is it running?",
          "type": "boolean"
        }
      },
      "required": [
        "name",
        "running",
        "ids"
      ],
      "type": "object"
    },
    "Request": {
      "description": "One request line: the token from ipc.json and the command's fields.",
      "properties": {
        "action": {
          "default": null,
          "description": "Automation API: `\"pause\"`, `\"start\"`, `\"remove\"` (off the list, its file kept) or\n`\"delete\"` (with its file) the downloads `ids`; answered with what was done and skipped.\n`\"start_queue\"` / `\"stop_queue\"` start or stop the queue named `queue`.",
          "type": [
            "string",
            "null"
          ]
        },
        "api": {
          "default": null,
          "description": "Automation API: turn it on or off.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "category": {
          "default": null,
          "description": "A category for `url` (its `key` in the list's `categories`); none: by the file's type.",
          "type": [
            "string",
            "null"
          ]
        },
        "cookie_jar": {
          "description": "From the browser: the same cookies, each with the domain, path and flags the browser\nkeeps for it, for yt-dlp's cookie file. yt-dlp may ask another host than the page's (a\nYouTube Music page is looked up on www.youtube.com), and a cookie of `.youtube.com` goes\nthere too. An older extension sends `cookies` only.",
          "items": {
            "$ref": "#/$defs/BrowserCookie"
          },
          "type": "array"
        },
        "cookies": {
          "default": null,
          "type": [
            "string",
            "null"
          ]
        },
        "dir": {
          "default": null,
          "description": "Save folder (`/p`) and file name (`/f`).",
          "type": [
            "string",
            "null"
          ]
        },
        "exclude_site": {
          "default": null,
          "description": "From the browser's toolbar button: leave this site's downloads (a host name) to the\nbrowser from now on (Options → File types → excluded sites).",
          "type": [
            "string",
            "null"
          ]
        },
        "exit": {
          "default": false,
          "description": "`/exit` (beyond IDM): the running app saves and quits (the installer, before an upgrade\nor an uninstall). Starts nothing when no app runs.",
          "type": "boolean"
        },
        "final_url": {
          "default": null,
          "description": "From the browser: where its redirects from `url` ended (`url` stays the address asked\nfor, so an expired signed link can be renewed from it).",
          "type": [
            "string",
            "null"
          ]
        },
        "ids": {
          "default": [],
          "items": {
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          },
          "type": "array"
        },
        "later": {
          "default": false,
          "description": "`/a`: add to the main queue, don't start.",
          "type": "boolean"
        },
        "links": {
          "default": [],
          "description": "From the browser's right-click menu: the links of a page or a selection, offered in the\nlist window to pick from (the browser's `referer` and `cookies` go with them).",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "mime": {
          "default": null,
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "default": null,
          "type": [
            "string",
            "null"
          ]
        },
        "pair": {
          "default": false,
          "description": "The remote control (#157, `misterdownloadmanager-cli pair`): show a new pairing code;\nanswered with it, the page's addresses and a QR code to scan ([`api::PairAnswer`]).",
          "type": "boolean"
        },
        "panel_hide_site": {
          "default": null,
          "description": "From that button's menu: never show it on this site (a host name) again.",
          "type": [
            "string",
            "null"
          ]
        },
        "panel_show_site": {
          "default": null,
          "description": "From that button's \"Turn on\" (after \"Never on <site>\"): show it on this site again.",
          "type": [
            "string",
            "null"
          ]
        },
        "post": {
          "default": null,
          "description": "From the browser: a form's download, re-sent as a POST with this body and its\nContent-Type (`post_type`).",
          "type": [
            "string",
            "null"
          ]
        },
        "post_type": {
          "default": null,
          "type": [
            "string",
            "null"
          ]
        },
        "private": {
          "default": false,
          "description": "From a private (incognito) window: the download is never written to the saved list.",
          "type": "boolean"
        },
        "proxy": {
          "default": null,
          "description": "From the browser (#42): the proxy it uses for this address (\"http://host:port\",\n\"https://…\", \"socks5h://…\", \"socks4://…\"), set by a VPN or proxy extension or its\nsettings; or its proxy auto-config script's text. The app downloads through the same\none (Options → Proxy / Socks → \"Use proxy/socks from a browser's request\").",
          "type": [
            "string",
            "null"
          ]
        },
        "proxy_login": {
          "default": false,
          "description": "That proxy asked the browser for a login, which the extension that set it answers with\nits own: no other program can have it.",
          "type": "boolean"
        },
        "proxy_pac": {
          "default": null,
          "type": [
            "string",
            "null"
          ]
        },
        "query": {
          "default": null,
          "description": "Automation API (off by default, beyond IDM): `\"list\"` asks for every download as JSON.",
          "type": [
            "string",
            "null"
          ]
        },
        "queue": {
          "default": null,
          "description": "A queue by name: where `url` waits (with `later`), or the one `action` starts or stops.",
          "type": [
            "string",
            "null"
          ]
        },
        "referer": {
          "default": null,
          "description": "From the browser: request context to reuse.",
          "type": [
            "string",
            "null"
          ]
        },
        "show": {
          "default": null,
          "description": "`/show <window>` (beyond IDM): the running app opens one of its windows by name, for\nscreenshots and scripted checks (tools/lab/docs-shots.ps1): `addurl`, `batch`, `find`,\n`scheduler`, `about`, `language`, `shortcuts`, `speedlimit`, `properties`, `delete`,\n`progress`, `existing-files`, `video-page`, `video-helpers`, `video-subs`,\n`torrent-settings`, `add-trackers`, `menu` (the first download's right-click menu),\n`options[:general|types|saveto|downloads|connection|proxy|logins|sounds|regional|panels]`.",
          "type": [
            "string",
            "null"
          ]
        },
        "show_download": {
          "default": null,
          "description": "That button's \"Show\", once a download was added: the main window comes up with the newest\ndownload of this address (the video's page as it was looked up, or its file) selected.",
          "type": [
            "string",
            "null"
          ]
        },
        "silent": {
          "default": false,
          "description": "`/n`: silent — no Download File Info dialog.",
          "type": "boolean"
        },
        "size": {
          "default": null,
          "description": "From the browser: the size and type its own download had (no need to look them up).",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "start_queue": {
          "default": false,
          "description": "`/s`: start the main queue.",
          "type": "boolean"
        },
        "startup": {
          "default": false,
          "description": "`/startup` (beyond IDM): started with the session (Options → General → Launch on\nstartup, or the installer's \"Start when Windows starts\", #226): MDM starts in the\nnotification area, its window hidden. Changes nothing in a running app.",
          "type": "boolean"
        },
        "token": {
          "description": "The `token` from ipc.json (it changes at every start of the app).",
          "type": "string"
        },
        "url": {
          "default": null,
          "description": "The URL to download (`/d`).",
          "type": [
            "string",
            "null"
          ]
        },
        "user_agent": {
          "default": null,
          "type": [
            "string",
            "null"
          ]
        },
        "video_direct": {
          "default": false,
          "description": "With `video_page`, from that button over a video that plays a plain file (no stream, no\npage to read): `video_page` is that file, downloaded as any file at once, with no window.",
          "type": "boolean"
        },
        "video_lookup": {
          "anyOf": [
            {
              "$ref": "#/$defs/VideoLookup"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "From the browser's quality menu over a video (the button's click): look this video up\nwith yt-dlp, off the window, and answer at once with a token to ask about it\n([`api::VideoLookupAnswer`], `pending`). The browser's request context (`referer`,\n`cookies`, `cookie_jar`, `user_agent`, `private`) goes with it and stays the look-up's."
        },
        "video_page": {
          "default": null,
          "description": "From the browser's download button over a video: open the Download video window for this\npage (its address; an embedded player's own).",
          "type": [
            "string",
            "null"
          ]
        },
        "video_pick": {
          "anyOf": [
            {
              "$ref": "#/$defs/VideoPick"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The quality menu: download the choice made there, with the look-up's own selector and\ncontext (`private` must be the look-up's); answered `started` or `queued`, or\n`use-window` when it can't be (the Download video window then does it)."
        },
        "video_poll": {
          "default": null,
          "description": "The quality menu: how is the look-up of this token going (`pending`, `ready` with the\nchoices, `failed`, `list`, `gone`)?",
          "type": [
            "string",
            "null"
          ]
        },
        "video_title": {
          "default": null,
          "description": "The title of the page the button was clicked on: a video yt-dlp knows only by its address\nis named by it.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "token"
      ],
      "type": "object"
    },
    "Skipped": {
      "properties": {
        "id": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "why": {
          "description": "\"no such download\", \"not running\", \"already running\", \"complete\" or \"running: pause it\nfirst\".",
          "type": "string"
        }
      },
      "required": [
        "id",
        "why"
      ],
      "type": "object"
    },
    "VideoChoice": {
      "description": "One quality the browser's quality menu offers.",
      "properties": {
        "approx": {
          "description": "`size` is an estimate (a stream's bitrate times its length, a conversion's), shown as\nabout (\"~532 MB\"); otherwise it is the bytes of exactly the streams this downloads (#801).",
          "type": "boolean"
        },
        "audio": {
          "default": false,
          "description": "Only the sound (an audio file, a conversion to MP3, Opus or FLAC): the menu lists these\napart from the videos. False from an app older than the field.",
          "type": "boolean"
        },
        "codec": {
          "description": "The picture's codec as people name it: `AV1`, `VP9`, `H.264`, `H.265`… (#755). None\nfrom an app older than the field.",
          "type": [
            "string",
            "null"
          ]
        },
        "ext": {
          "default": "",
          "description": "The file's type (`mp4`, `mp3`).",
          "type": "string"
        },
        "fps": {
          "description": "Frames a second, rounded (an app older than #755 said it only above 31).",
          "format": "uint32",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "height": {
          "description": "The picture's height in pixels (the button's chip: 1080p, 4K); none for the sound, or a\nfile known only by its type.",
          "format": "uint32",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "kbps": {
          "description": "The sound's bitrate in kbit/s, for the sound as the site has it.",
          "format": "uint32",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "label": {
          "default": "",
          "description": "What the menu shows (\"720p mp4\"), in MDM's language.",
          "type": "string"
        },
        "original": {
          "description": "The sound as the site sends it (not converted): the button's list says \"original\".",
          "type": "boolean"
        },
        "range": {
          "description": "The picture's dynamic range when worth saying: `HDR`, `Dolby Vision`, or `SDR` beside an\nHDR choice of the same height (#755).",
          "type": [
            "string",
            "null"
          ]
        },
        "size": {
          "default": null,
          "description": "Bytes, exact or estimated (`approx`); null when unknown.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "VideoLookup": {
      "description": "The video the browser's quality menu asks about ([`Command::video_lookup`]).",
      "properties": {
        "address": {
          "default": "",
          "description": "What yt-dlp looks up: the video's own file or its stream's manifest when the page plays\none, else the page.",
          "type": "string"
        },
        "store_id": {
          "default": null,
          "description": "The browser's cookie store the page is in (Firefox's containers): a choice is only taken\nfrom the same one.",
          "type": [
            "string",
            "null"
          ]
        },
        "title": {
          "default": null,
          "description": "The title of the page the button was clicked on: a video yt-dlp knows only by its address\nis named by it (as [`Command::video_title`]).",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "VideoLookupAnswer": {
      "description": "The browser's quality menu (`video_lookup`, `video_poll`, `video_pick`): where a look-up is,\nor what became of a choice. Answered whatever the automation API's switch (the browser's\nhost asks, not a program).",
      "properties": {
        "choices": {
          "description": "`ready`: the qualities to choose from, labelled in MDM's language; `video_pick` takes a\nplace in this list.",
          "items": {
            "$ref": "#/$defs/VideoChoice"
          },
          "type": "array"
        },
        "message": {
          "description": "`failed` with [`lookup::ERROR`]: why, in MDM's words and language.",
          "type": [
            "string",
            "null"
          ]
        },
        "notice": {
          "anyOf": [
            {
              "$ref": "#/$defs/VideoNotice"
            },
            {
              "type": "null"
            }
          ],
          "description": "`ready` (and `failed` with [`lookup::NO_CHOICES`]): what the look-up lacked and how to\nmend it, shown with the choices (#852: YouTube's qualities need a JavaScript runtime).\nNone from an app older than the field."
        },
        "reason": {
          "description": "`failed`: [`lookup::NO_YTDLP`], [`lookup::NO_CHOICES`] or [`lookup::ERROR`].",
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "default": "",
          "description": "One of [`lookup`]'s states.",
          "type": "string"
        },
        "title": {
          "description": "`ready`: the video's title, the file's name: the page's when yt-dlp knows the video only\nby its address, as the Download video window names it ([`crate::Command::video_title`]).",
          "type": [
            "string",
            "null"
          ]
        },
        "token": {
          "description": "`pending` and `ready`: the look-up's token, to ask about it and to pick from it.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "VideoNotice": {
      "description": "A word in the browser's quality menu on what the look-up lacked (#852), in MDM's language.",
      "properties": {
        "link": {
          "default": "",
          "description": "The link's words (\"How to install one\").",
          "type": "string"
        },
        "text": {
          "default": "",
          "description": "What is wrong and what to do (\"YouTube needs a JavaScript runtime…\").",
          "type": "string"
        },
        "url": {
          "default": "",
          "description": "The help page it opens, on MDM's website.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "VideoPick": {
      "description": "A choice made in the browser's quality menu ([`Command::video_pick`]).",
      "properties": {
        "choice": {
          "default": 0,
          "description": "The choice's place in the look-up's `choices`.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "store_id": {
          "default": null,
          "description": "The cookie store the choice was made in: the look-up's, or it isn't taken.",
          "type": [
            "string",
            "null"
          ]
        },
        "token": {
          "default": "",
          "description": "The look-up's token.",
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "$id": "https://misterdownloadmanager.com/automation-api.schema.json",
  "$ref": "#/$defs/Request",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "One JSON line to the port in ipc.json (on 127.0.0.1), one line back. A request is `Request`. A command (an address to add, start_queue) is answered `ok`; a question is answered with the JSON object for it (`ListAnswer`, `ActAnswer`, `ApiAnswer`) or an `ErrorAnswer`. A wrong token is answered `denied`, an app that doesn't answer within 2 seconds `timeout`. The browser's quality menu (`video_lookup`, `video_poll`, `video_pick`, sent by its native host) is answered with a `VideoLookupAnswer`. Guide: https://misterdownloadmanager.com/help/command-line.html#the-automation-api",
  "title": "Mister Download Manager automation API"
}