Listed workers
Processing workers written by the community, and how to list yours.
A worker is any program that speaks the worker contract: it registers with a manifest, claims jobs of its kinds, reads the input file, and sends one output back. This page lists workers that people have published for others to run.
No community workers are listed yet.
Yours could be the first: write a worker against the contract, then open a pull request that adds it to docs/data/community-workers.json as described below.
Workers listed here are not reviewed or endorsed by the Shotstash maintainers. A worker only reads the files of the jobs it claims and never gets storage or database credentials, but it does see those files: run only workers you trust with your media.
The manifest
Every worker describes itself with a manifest, sent on registration and on every heartbeat:
{
"name": "acme-whisper-1",
"version": "1.2.0",
"kinds": ["acme/whisper-transcript"],
"contract": 1
}| Field | Rules |
|---|---|
name | 1 to 100 characters; one name per running process (the reference worker reads WORKER_NAME) |
version | 1 to 50 characters; your release version |
kinds | 1 to 32 kind names, <namespace>/<name> in lowercase letters, digits, ., - and _ |
contract | the contract major you speak: 1 |
Use your own namespace for kinds (acme/...), and leave shotstash/... to the project's built-in kinds.
Listing your worker
The list above is the file docs/data/community-workers.json in the repository. To add your worker, open a pull request that appends one entry:
{
"name": "Whisper transcripts",
"description": "Speech to WebVTT subtitles with OpenAI Whisper, CPU or CUDA.",
"repository": "https://github.com/acme/shotstash-whisper",
"kinds": ["acme/whisper-transcript"],
"contract": 1,
"license": "MIT",
"maintainer": "@acme"
}| Field | Rules |
|---|---|
name | what people call it, at most 60 characters |
description | one sentence, at most 160 characters: what it makes and what it needs (GPU, model download) |
repository | an https:// URL of the public source repository, listed once |
kinds | the kinds it registers, exactly as in its manifest |
contract | 1, the only contract major so far |
license | an SPDX identifier, for example MIT or Apache-2.0 |
maintainer | a GitHub user or organisation handle (@name) |
Before you open the pull request, check that:
- the repository is public and its README says how to run the worker next to docker compose (image or command,
SHOTSTASH_URL,WORKER_BOOTSTRAP_TOKEN); - the worker follows the contract: heartbeats every 30 seconds, backs off on
401and503, drops jobs on409, releases its job on shutdown; - the kinds use your own namespace.
The docs build validates the file (npm test in docs/), so a malformed entry fails CI with the reason.
Writing one
Start with Bring your own AI: it has every route with curl examples, a minimal Python worker, and the loop every worker follows. The reference worker in worker/ is a complete Node.js example with ffmpeg.