Execute worker jobs

Install from source

Use Node.js 22.13 or newer and the repository's pinned package manager, [email protected] for the documented v0.2.0 release.

git clone https://github.com/MediaFilez/media-worker.git
cd media-worker
pnpm install --frozen-lockfile
pnpm run build

Run the examples from the worker repository root after building. They do not assume the package has been published to npm.

Native media tools, including FFmpeg and FFprobe, must also be available to the worker. pnpm install installs JavaScript dependencies, not these tools. The repository's Docker image includes its toolchain; for a native installation, follow the tool settings in the worker README.

Execute in your own process

Save this as example.mjs at the repository root:

import { resolve } from "node:path";
import { WorkerRuntime, LocalStorageAdapter } from "./dist/index.js";

const runtime = new WorkerRuntime({
    storage: new LocalStorageAdapter(resolve("./media-output")),
    timeoutMs: 120_000
});
const result = await runtime.execute(
    {
        type: "download",
        jobId: "local-example-001",
        url: "https://example.com/video.mp4",
        output: { type: "auto", format: "original", quality: "best" }
    },
    {
        signal: AbortSignal.timeout(120_000),
        onProgress: (update) => console.error(update)
    }
);
console.log(result.items ?? (result.output ? [result.output] : []));

Replace the URL and use a new jobId for different input. Stable identities help recover a redelivery; reusing an ID with different input is rejected rather than overwriting stored media.

CLI jobs

Write job.json:

{
    "type": "download",
    "jobId": "cli-example-001",
    "url": "https://example.com/video.mp4",
    "output": {
        "type": "video",
        "format": "original",
        "quality": "best"
    }
}

With private local storage configured:

LOCAL_STORAGE_DIR=./media-output node dist/worker.js job.json

That command uses Bash environment syntax. In PowerShell:

$env:LOCAL_STORAGE_DIR = './media-output'
node dist/worker.js job.json

Progress is JSON Lines on stderr. The final structured result goes to stdout. This differs from pnpm start, which launches the connected queue consumer.

Results and collections

WorkerResult includes jobId, type, attempts, startedAt, completedAt, and durationMs. Download results use output; collections can also contain items. Use all items when present.

Stored metadata includes key, location, fileName, sizeBytes, and contentType. These are storage identities and locations, not hosted API fileId values. A local path is not a public download endpoint.

Batch archives

The runtime's batch job accepts 1 to 100 explicit items and produces a streamed ZIP. Items use download options without their own type or jobId.

{
    "type": "batch",
    "jobId": "archive-example-001",
    "archiveName": "media.zip",
    "items": [
        {
            "url": "https://example.com/one.mp4"
        },
        {
            "url": "https://example.com/two.jpg"
        }
    ]
}

Per-transfer and aggregate limits apply. Missing required inputs fail the archive instead of silently omitting files. The hosted HTTP /batches endpoint instead accepts at most 10 items and returns separate jobs.

Cancellation and cleanup

Pass an AbortSignal to execute(). The runtime owns temporary job directories and cleans failed attempts. Progress callbacks are best effort and must not repeat a completed upload.

The deadline includes retries and backoff. Custom engines and storage adapters must honor the signal; a deadline cannot forcibly stop an adapter that ignores it. Cleanup jobs remove abandoned temporary work, not all stored artifacts.