Repository navigation
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.
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.
| 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.
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.
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.
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.
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.
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"}}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 callA 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.
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.BodyThe 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.
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 errorCount is the number of tracks holding a file on disk. Without the grant both return an error.
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
Mountand noCaller. No client can send one, so checkr.Mount == ""and nothing else: under your own mount/hooks/libraryis an ordinary path anyone may ask for. -
MoviesandSeriesare titles (added, refreshed, re-identified, deleted);Episodesare 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.
-
Fullnames 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.
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-secretEvery 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
settingsinhooks. Streamline then callsPOST /hooks/settings(emptyMount, as forlibrary) withSettings,SecretsandHosts, 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.
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.
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.
| 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 |
- 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 grantedffmpegis 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
Authorizationon aselfmount). - 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.
🎬 Operating Streamline
- Installation
- First-Run Setup
- Adding Movies and TV
- Importing an Existing Library
- Activity and Calendar
- Requests and Users
- Music and Books
- Uploading files
- Extensions
- Send to Kindle
- NixOS and Nix
- Proxmox VE (LXC)
- Troubleshooting
- Roadmap
⚙️ Advanced
- Configuration Reference
- Authentication and SSO
- Quality Profiles and Naming
- Quality Profiles and Custom Formats
- Scheduled Jobs
- REST API
- Writing an extension
- Observability and Logging
- GitOps and Kubernetes