Skip to content

Writing an extension

github-actions[bot] edited this page Nov 17, 2026 · 8 revisions

Writing an extension

For what an extension is and how to add one, see Extensions. This page is the contract: version 2 of the guest API. The reference implementation is the OPDS extension; the SDK it imports is extensions/sdk in the Streamline repository.

Building

A guest is a Go program compiled to WebAssembly with the standard toolchain, using the SDK module github.com/datahearth/streamline/extensions/sdk:

GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o myext.wasm .

task build:extensions does this for the ones in the repository. Keep main empty; the host calls two exports.

package main

import "github.com/datahearth/streamline/extensions/sdk"

func main() {}

//go:wasmexport manifest
func manifest() int32 {
	return sdk.WriteManifest(sdk.Manifest{
		Name:          "myext",
		Version:       "1.0.0",
		StreamlineAPI: sdk.APIVersion,
		Mounts:        []sdk.Mount{{Prefix: "/", Auth: "session"}},
		Views:         []string{"books"},
	})
}

//go:wasmexport handle
func handle() int32 {
	return sdk.Dispatch(func(r sdk.Request) sdk.Response {
		return sdk.Response{Status: 200, Body: []byte("hello")}
	})
}

A fresh instance of the module handles every request, so nothing in memory survives between two: keep state in your database, or files in your cache folder. Your module is served under /extensions/<name>. The request says where it came from: BasePath is that path, Mount the mount of yours it arrived under (both empty on your /api and /cards subtrees) and Origin the scheme and host the client used (https://media.example), worked out by Streamline behind its trusted proxies; build absolute links as Origin + BasePath + Mount + …, never from X-Forwarded-*. ClientIP is the client's address, resolved the same way; X-Forwarded-For in the headers is whatever the client chose to send. Nothing you serve is cached unless you ask: a Cache-Control header on your answer is honoured when it is private with any of max-age=N, immutable, must-revalidate, no-cache (on a body, send_file, serve_file or serve_poster answer that succeeds), and ignored otherwise, public included. Each instance gets random bytes from the operating system, so crypto/rand is safe for tokens.

Manifest

Field Notes
name ^[a-z0-9][a-z0-9-]{0,31}$; must equal the entry's name
version Free text, shown in the API
streamline_api Must be 2 (sdk.APIVersion). A module for another version is refused
mounts[] {prefix, auth}, each relative to /extensions/<name>: prefix is / (all of it) or one plain path segment (/rest: lowercase letters, digits, ., _ and -), each declared once; a request goes to the longest that holds it, and one no mount holds is a 404. auth is session (Streamline signs the user in first and tells you who) or self (you check credentials, e.g. HTTP Basic)
views[] Names from the table below
folders[] music, movies, series, artwork, cache, store, see Folders
services[] serve_file, serve_poster, ffmpeg, library_scan, http
hooks[] library, see Library changes; settings, see Settings and secrets from the config file. Not a grant: nothing to approve
account_cards[] {id, kind, title, mount, username, fields}. kind: credential is a credential the account page manages (mount, username). mount is the address the account page shows, the one a user pastes into their app, relative to your path like a mount (/ is /extensions/<name> itself): name what the app expects to be given, never a path the app adds by itself. A Subsonic app appends /rest to its server address, so the Subsonic card is /; /rest there would send the app to /rest/rest; kind: settings is a set of per-user controls an admin edits (fields, see Settings cards). Your module answers both at /api/v1/extensions/<name>/cards/<id>

Whatever you list must be granted by the admin, exactly, hooks aside. A settings card that declares no field, two fields with one id, a field of another kind or a number whose min is above its max makes the manifest unusable, and the extension fails to start.

Requests and responses

sdk.Request carries Method, Path (relative to your mount: on a / mount /extensions/opds/authors arrives as /authors, on a /rest one /extensions/subsonic/rest/ping as /ping), the raw Query string, Headers, the Body (at most 16 MiB; more is a 413), Caller, Folders and TargetUser. Caller is {ID, Role, KeyID, KeyName} (the last two name the API key the request came with and are zero for a browser session, so with one key per device the key is the device) and is set only on a session mount for a signed-in user; on a self mount it is nil and Authorization is passed through. The Cookie header never reaches you, and Authorization and X-Api-Key are removed on a session mount. Folders lists the granted folders this call has mounted, and TargetUser is set only on a settings card call from the admin endpoints.

sdk.Response is Status (0 means 200; outside 100-599 is a 500), Headers, Body (at most 16 MiB) and, instead of a body, a directive. Set-Cookie, Content-Length, Transfer-Encoding, Connection, Content-Security-Policy and X-Content-Type-Options are dropped from what you send: Streamline sets the last two itself (sandbox; default-src 'none'; img-src 'self' data:; media-src 'self'; style-src 'unsafe-inline' and nosniff), so an HTML page you serve can carry inline styles, images and <audio> or <video> from Streamline's own address, but no script.

Two routes are always Streamline's, whatever your mount: /api/v1/extensions/<name>/cards... and /api/v1/extensions/<name>/api.... Both need a signed-in user, arrive with a Caller, and the path you see starts at /cards or /api.

Directives

A response may name one thing for Streamline to send instead of a body. Each runs after your module has returned, so it holds none of your database connections while the bytes go out.

Directive Fields Needs
ServeFile FileID, Filename, ContentType the serve_file service and the book_files view. The file must be a present row of streamline_book_files; otherwise 404. Streamline streams it with range support
ServePoster Kind (books or authors), ID the serve_poster service and the view of that kind (books or authors)
SendFile Path, Filename, ContentType a granted folder holding Path, see Sending a file
StreamFFmpeg Args, ContentType, Headers, Fallback the ffmpeg service, see ffmpeg

A ServeFile, SendFile or StreamFFmpeg answer lives as long as the client keeps reading; a client that stops for 2 minutes is cut.

Talking to the database

res, err := sdk.Query("SELECT id, title FROM streamline_books WHERE author_name LIKE ?", "%Le Guin%")
// res.Columns, res.Rows ([][]any: numbers are float64, text string, NULL nil)
// res.Error is a statement SQLite refused; err is a failed host call

_, err = sdk.Exec("INSERT INTO tokens(user_id, token_hash) VALUES(?, ?)", id, hash)

sdk.Log("warn", "something odd", "user", id)

Query and Exec run on one connection to your database, so a transaction (BEGIN ... COMMIT) within a request holds. Create your own tables in it freely. Core is attached read-only, and only through the views you were granted: any other read of core, any write to it, and any other ATTACH is refused. A statement that runs more than 5 seconds is interrupted. Log levels are debug, info, warn, error; the line carries your name.

Folders

Each granted folder is mounted into your module for the length of one call:

Folder What it is Mounted at Access
music The music library, library.music_path /folders/music read-only
movies The movie library, library.movie_path /folders/movies read-only
series The series library, library.series_path /folders/series read-only
artwork Streamline's poster cache, laid out <kind>/<id>/poster.jpg /folders/artwork read-only
cache Your own folder, <data_dir>/extensions/<name>/cache /folders/cache read and write
store Your own folder for files you keep, <data_dir>/extensions/<name>/store /folders/store read and write, up to the admin's limit

Read them with the standard library (os.ReadFile, os.Open, os.WriteFile into the cache). r.Folders lists what this call has, each as sdk.Folder{Name, HostPath, GuestPath}: HostPath is the directory on the server, GuestPath where you see it. A folder whose directory is missing when the request arrives is left out, so check r.Folder(name) before using it. The views give paths on the server (music_files.path); turn one into a path you can open with r.GuestPath(hostPath), which answers false for a path outside every folder you have.

f, ok := r.Folder("music")
p, ok := r.GuestPath(row.Path) // "/srv/music/A/B/01.flac" -> "/folders/music/A/B/01.flac"
b, err := os.ReadFile(p)

No path leaves its folder: .., and a symbolic link pointing outside, are refused, and you cannot create a link in the cache. Streamline deletes the oldest files of the cache once it holds more than 1 GiB, checked every hour, so treat it as a cache: anything in it can be gone on the next request.

The store is for what must stay: Streamline never deletes from it. The admin sets how much it may hold with store_bytes on your entry in the config file, so say in your documentation how much you need; without that value you have no store, and r.Folder("store") answers false. Once it holds that much, a call gets it read-only (Folder.ReadOnly is true and writes fail) until you have deleted enough, so delete what you no longer need yourself.

Sending a file

SendFile streams a file from a granted folder with range support. Path is the file's path on the server, as a view or Folder.HostPath gives it, not the guest path; Streamline finds the granted folder holding it. A relative path, a path outside every granted folder, a link leading out or a directory is a 404. ContentType defaults to application/octet-stream, and Filename, when set, makes it an attachment download.

return sdk.Response{SendFile: &sdk.SendFile{Path: row.Path, ContentType: "audio/flac"}}

ffmpeg

The ffmpeg service runs Streamline's own ffmpeg and ffprobe, with the arguments you pass as a list (no shell), in your cache folder, as the server's own process: it is not confined, and the admin is told so when granting it. Paths in the arguments are paths on the server (Folder.HostPath, a view's path), not guest paths, and a relative output path lands in your cache folder. Every run is logged with its full argument list. Nothing runs when ffmpeg is disabled on the server or missing, or when this extension already has 8 runs going; your extension keeps answering either way.

A call runs to completion inside your request, within its 30 seconds:

res, err := sdk.FFmpeg("ffprobe", "-v", "quiet", "-print_format", "json", "-show_format", row.Path)
// res.ExitCode, res.Stdout (at most 16 MiB), res.Stderr (its last 64 KiB)
// res.Error: not granted, not available, every slot busy, a tool other than
//   ffmpeg or ffprobe, more than 16 MiB of output, or the run cut short
// err: a failed host call

A non-zero exit is not an error: it comes back in ExitCode with both outputs.

A stream is a directive: your module returns, then Streamline runs ffmpeg and sends its stdout to the client as it comes, as long as the client keeps reading (a client that stops for 2 minutes is cut, and ffmpeg stopped).

return sdk.Response{StreamFFmpeg: &sdk.StreamFFmpeg{
	Args:        []string{"-i", row.Path, "-map", "0:a:0", "-vn", "-c:a", "libopus", "-f", "ogg", "pipe:1"},
	ContentType: "audio/ogg",
	Fallback:    &sdk.SendFile{Path: row.Path, ContentType: "audio/flac"},
}}

Nothing is sent until ffmpeg's first byte, so a failure before it becomes something else:

What happened With Fallback Without
ffmpeg not granted 404 404
ffmpeg disabled or missing, every slot busy, or it did not start the fallback file 503 with Retry-After: 5
No output within 30 seconds, or it exited having written nothing the fallback file 502

Once the first byte is out the answer is a 200 with your ContentType (default application/octet-stream) and Headers (minus the dropped ones), without range support; if ffmpeg fails after that, the body simply ends early. The fallback is sent like any SendFile, so it needs a folder holding its path.

Calling another server

The http service makes an HTTP request for you; a guest has no socket of its own.

res, err := sdk.Fetch(sdk.FetchRequest{
	Method:  "POST",
	URL:     "http://engine.lan:8097/v1/sessions",
	Headers: map[string][]string{"Authorization": {"Bearer " + secret}},
	Body:    body,
})
// res.Status, res.Headers, res.Body

The URL's host:port must be in the hosts list the admin wrote for your extension in the config file; your manifest cannot ask for a host, so say in your documentation which server to list. err is set when the service is not granted, the host is not listed, or no answer came back. A status of 400 or more is an answer, not an error, and so is a redirect: it is never followed. The call runs inside your request's 30 seconds and the answer is at most 16 MiB.

Library scan

The library_scan service reaches Streamline's library scan, the drift-check job that checks every tracked file is still on disk.

st, err := sdk.ScanStatus() // st.Scanning, st.Count, st.LastScan (*time.Time, nil before the first)
err = sdk.StartScan()       // returns once it is started; one already running is not an error

Count is the number of tracks holding a file on disk. Without the grant both return an error.

Library changes

List library in hooks and Streamline calls you when a movie, a series or a video file is added, changed or removed: about five seconds after the change, with everything that changed in that time in one call.

func route(r sdk.Request) sdk.Response {
	if r.Mount == "" && r.Path == "/hooks/library" && r.Method == "POST" {
		var c sdk.LibraryChange // Full, Movies, Series, Episodes
		_ = json.Unmarshal(r.Body, &c)
		// look at what the views hold for these ids now
		return sdk.Response{Status: 202}
	}
	// ...
}
  • The call has an empty Mount and no Caller. No client can send one, so check r.Mount == "" and nothing else: under your own mount /hooks/library is an ordinary path anyone may ask for.
  • Movies and Series are titles (added, refreshed, re-identified, deleted); Episodes are episodes whose file appeared, moved, went missing or was deleted, and a movie's file reports the movie.
  • An id may be of a row that no longer exists, or of a change that was undone: read your views and drop what you kept for a row that is gone.
  • Full names a folder (movies, series) to look at whole. Streamline sends it in place of more than 500 ids.
  • You have the usual 30 seconds. An answer of 400 or more is logged and the change is not sent again, so keep a way to catch up, such as a scan of your own.

Settings and secrets from the config file

The admin can give your extension settings and secrets in Streamline's config file, next to its grants:

extensions:
  - name: player
    settings:
      engine.url: http://engine.lan:8097
    secret_files:
      engine: /etc/streamline/secrets/player-engine-secret

Every call then carries them: r.Settings holds each setting as raw JSON, as written, and r.Secrets the content of each file by name. Streamline does not read the keys; they mean what you say they mean. Both are empty when the file gives none.

  • Treat a setting from the file as final: let it win over what you stored, and refuse to change it from your own UI.
  • A missing or empty secret file keeps the extension from starting.
  • To refuse a bad value before you run, list settings in hooks. Streamline then calls POST /hooks/settings (empty Mount, as for library) with Settings, Secrets and Hosts, the entry's hosts list, before the extension starts and whenever one of them changes. Any answer but a 2xx stops the extension, and the first 300 bytes of your body are the reason the admin sees. Never put a secret in it.

Settings cards

A settings card is a set of per-user controls for an admin, each field a switch or a whole number between Min and Max:

AccountCards: []sdk.AccountCard{{
	ID: "permissions", Kind: sdk.CardSettings, Title: "Music app permissions",
	Fields: []sdk.CardField{
		{ID: "can_download", Kind: sdk.FieldSwitch, Label: "Download"},
		{ID: "max_bit_rate", Kind: sdk.FieldNumber, Label: "Maximum bit rate", Min: 0, Max: 320},
	},
}},

Streamline calls your module at /cards/<id> on an admin's behalf, with the admin as Caller and the account being edited as TargetUser:

  • GET: answer {"values": {"<field id>": <value>, ...}} for that user, status 200.
  • PUT: the body is {"values": {...}} with some or all of the fields; store them for that user and answer 204. A field left out stays as it is. Streamline has already checked every key is one of your fields, every switch a boolean and every number a whole number within its bounds.

A settings card is reachable only this way: /api/v1/extensions/<name>/cards/<id> answers 404 for it, so every request your module sees for the card carries a TargetUser and values Streamline already checked against the card's fields.

Views

Each granted view appears as streamline_<name>, read-only. Columns are stable within an API version: new ones are added, none renamed or removed.

View Grant text Columns
users See user names and roles id, display_name, role, locked (1 while the account is locked after failed sign-ins; refuse its credentials)
user_logins See users' email addresses user_id, email (lower-cased)
books Read the book library id, title, original_title, sort_title, author_name, kind, genre, release_year, release_date, overview, preferred_language, series_id, series_position, added_at, updated_at
book_series Read the book series id, title, original_title, sort_title, author_name, kind, overview, ongoing
authors Read book authors id, name, sort_name
book_contributions Read who made each book id, author_id, book_id, series_id, role, language, position (one of book_id and series_id is set)
book_files Read which book files exist id, book_id, slot (ebook or audiobook), format, size, filename (the base name, never a path), added_at, updated_at; files marked missing are left out
artists Read the music library id, mbid, name, sort_name, type, origin, since, genre, overview, added_at, updated_at, overview_fr
artist_members Read the music library id, artist_id, name, mbid, instruments, from_year, to_year, ordinal
albums Read the music library id, mbid, artist_id (the album's owner), title, type, release_date, original_date, edition_date, genres, label, country, status, added_at, updated_at
album_artists Read the music library album_id, artist_id, owner (1 for the owner, 0 for every other artist the album is listed under)
tracks Read the music library id, mbid, album_id, title, disc, position, duration (seconds), bonus, artist_credit, added_at, updated_at
music_credits Read the music library id, album_id, track_id, kind, role, name, mbid, instruments, guest, ordinal
music_files Read the music library id, track_id, path (absolute, on the server), format, quality, size, duration (seconds), bitrate, sample_rate (Hz) and bit_depth (a lossless file's, NULL for a lossy one or one not measured yet), channels, missing (1 when the file is gone from disk), added_at (when the file joined the library)
genres Read the music library name, album_count
movies Read the movie and series library id, tmdb_id, imdb_id, title, original_title, year, overview, runtime (minutes), release_date, rating, genres (a JSON list), monitored, certification (the rating in metadata.tmdb_region, empty when unknown), added_at, updated_at
series Read the movie and series library id, tvdb_id, imdb_id, title, original_title, year, first_aired, overview, status, type, network, runtime (minutes), rating, genres (a JSON list), monitored, certification, added_at, updated_at
seasons Read the movie and series library id, series_id, number (0 is the specials), name
episodes Read the movie and series library id, season_id, number, absolute_number, title, overview, air_date, added_at, updated_at
video_files Read the movie and series library id, movie_id, episode_id (one of the two is set), path (absolute, on the server), container, quality, size, duration (seconds), video_codec, width, height, dynamic_range, audio_codec, channels, bitrate, audio_langs, sub_langs, missing (1 when the file is gone from disk), added_at, updated_at; the probe columns are NULL until the file was probed
people Read the movie and series library id, tmdb_id, tvdb_id (0 when that provider gave none), imdb_id, name, biography, known_for, birthday, deathday, place_of_birth (empty when unknown; a guest seen only on episodes has no biography); the photo is people/<id>/poster.jpg in the artwork folder
credits Read the movie and series library id, person_id, movie_id, series_id, episode_id (exactly one of the three is set), character, job (empty for an acting credit, else the crew role: Director, Writer, …), department (Directing, Writing, Production, … when known), order (billing)

The API groups views in bundles for the admin (music, books, video); your manifest still lists each view by name. There is no view of password hashes, sessions, API keys or requests. Two views carry what others never do: music_files.path and video_files.path, so you can open and send the file.

Limits

Memory per instance 64 MiB
Time per request 30 s
Time per SQL statement 5 s
Request and response body 16 MiB each
One SQL value, and one query's result 16 MiB each; page a larger read
Module size 32 MiB
Cache folder 1 GiB, oldest files deleted past it (hourly)
ffmpeg runs at once 8 per extension
sdk.FFmpeg output 16 MiB of stdout, the last 64 KiB of stderr

What a guest cannot do

  • Open a network connection, or read a file outside its granted folders: the only ways out are the host calls above (Query, Exec, Log, FFmpeg, ScanStatus, StartScan) and the four directives. An extension granted ffmpeg is the exception: ffmpeg itself can reach any file and the network.
  • Read core outside its views, or write to core or to a read-only folder at all.
  • Keep memory between requests, or run in the background: it runs only while answering a request.
  • Set cookies, or see the visitor's cookies, bearer token or API key (except Authorization on a self mount).
  • Run script in a visitor's browser.
  • Claim a prefix Streamline or another extension owns, or ask for a view, folder or service that does not exist.

Clone this wiki locally