Plugins

Three official plugins ship with the project, alongside the runtime and bootstrap infrastructure. The core remains protocol-agnostic.

Official plugins

backend.hls

HLS VOD Backend

Treats an `.m3u8` URL as a stream to assemble rather than a text file to save: playlist resolution, variant selection, concurrent segments with per-segment retry, AES-128 decryption, byte ranges.

Category: turbodl-protocol
Protocols: hls
Artifact: turbo-plugin-hls

Inspect

loader.js

JavaScript Plugin Loader

Loads TurboDL plugins written in JavaScript. One QuickJS runtime and context per script, a stable `host`/`plugin` ABI, and a load/unload sequence that never closes a runtime while its script is still executing.

Category: turbodl-loader
Protocols: none
Artifact: turbo-plugin-js

Inspect

parser.platforms

Platform Link Parser

Turns a share link into download requests: Weibo (best available MP4 + image sets), Xiaohongshu (watermark-free video + original images), Pixiv (every page's `urls.original`). Registers one `LinkParser` plus one `ProtocolClaim` per platform — the engine knows nothing about these three sites.

Category: turbodl-parser
Protocols: weibo, xhs, pixiv
Artifact: turbo-plugin-parser

Inspect

Capabilities, and what is refused

Between them the three official plugins declare 5 capabilities. Everything they will not do is listed beside it — a refusal is a feature when the alternative is a corrupt file.

declared capabilities

turbodl-protocol · backend.hls2 capabilities · hls

turbodl-loader · loader.js2 capabilities · no protocols

turbodl-parser · parser.platforms1 capabilities · weibo, xhs, pixiv

Read from each plugin's turbodl-plugin.json.

explicitly refused

HLS VOD BackendLive playlists (no `EXT-X-ENDLIST`) · DRM / `SAMPLE-AES` · fMP4 `EXT-X-MAP` · Discontinuities

JavaScript Plugin LoaderRegistering a `DownloadBackend` (the byte plane stays in Kotlin) · Publishing a service (a service is a Kotlin object graph) · `require` / npm / `fetch` — the host ABI is the entire surface · `jar:` or remote script sources (local file / `inline:` / `data:` only, for now)

Platform Link ParserLogging in — a platform that needs a session returns null and the host's own account handling takes over · Pixiv animations (ugoira): a zip plus a frame-timing table needs image processing · Pixiv novels · Signed APIs (Douyin, Kuaishou, Bilibili): per-platform signature algorithms stay in the host

An unsupported stream fails loudly rather than producing a file that looks fine.

Plugin categories

A plugin declares one category in its manifest. The category says what it is allowed to plug into — nothing else.

turbodl-plugin.json · category

turbodl-backendA protocol backend (replaces or extends the built-in HTTP engine).

turbodl-protocolDeclares the protocols/schemes it handles (the manifest `protocols` list).

turbodl-adapterBridges an external downloader.

turbodl-parserTurns a share link / magnet / kouling into download requests.

turbodl-hookObserves or rewrites requests and results.

turbodl-loaderLoads plugins written in another language — this is what the JS loader is.

The category is the whole of the runtime's authorization: it decides which extension points the plugin may register.

Writing your own

A plugin is an ordinary class implementing one interface. Third-party plugins are discovered through a GitHub topic plus a manifest — there is no registry to sign up to.

Kotlin

class MyPlugin : Plugin {
    override val id = "parser.example"

    override fun onLoad(context: PluginContext) {
        context.registerExtension(ExtensionPoints.LINK_PARSER, LinkParser { input ->
            input.takeIf { it.startsWith("example://") }
                ?.let { listOf(DownloadRequest(url = it, destination = File("out.bin"))) }
        })
    }
}

Plugin authoring guide Development convention Marketplace

turbodl-plugin.json

{
  "manifestVersion": "1.0",
  "id": "parser.example",
  "name": "Example parser",
  "description": "Turns example:// links into download requests.",
  "version": "0.1.0",
  "author": "you",
  "homepage": "https://github.com/you/turbodl-plugin-example",
  "license": "MIT",
  "category": "turbodl-parser",
  "capabilities": [
    "dev.turbodl.cap.parser"
  ],
  "protocols": [
    "example"
  ],
  "turbodl": {
    "apiMajor": 1,
    "requiredApiVersion": "1.0.0"
  },
  "entry": {
    "language": "kotlin",
    "pluginClass": "com.example.ExamplePlugin"
  },
  "extensionPoints": [
    "turbo.linkParser"
  ]
}

Six required fields, one category, one entry point. The reference page lists every field and its allowed values.

Plugins

Official plugins

HLS VOD Backend

JavaScript Plugin Loader

Platform Link Parser

Capabilities, and what is refused

Plugin categories

Writing your own

Safety, stated plainly