@verygoodffmpeg/sdk

TypeScript SDK for the Very Good FFmpeg API — run FFmpeg jobs in the cloud.

Homepage · API Docs · GitHub

Usage

npm install @verygoodffmpeg/sdk

import VGF from "@verygoodffmpeg/sdk";

const client = new VGF(process.env.VGF_API_KEY);

// Create a job and wait for it to complete
const job = await client.run(
  {
    input_files: {
      "input.mp4": "https://example.com/input.mp4",
    },
    output_files: ["output.mp4"],
    ffmpeg_commands: ["-i inputs/input.mp4 -vf scale=1280:720 outputs/output.mp4"],
  },
  { wait: true },
);

// Fetch the job again by ID
const fetched = await client.jobs.get(job.id);
console.log(fetched.status); // "succeeded"
console.log(fetched.output_files); // { "output.mp4": "https://..." }

Reference

Client — new VGF(apiKey, options?)

Options: baseUrl overrides the API host, and userAgentSuffix appends a product token to the SDK's User-Agent (sent as verygoodffmpeg-sdk/<version> <suffix>).

const client = new VGF(process.env.VGF_API_KEY, {
  userAgentSuffix: "my-app/2.0",
});

Create a job — client.run(params, options?)

Submits an FFmpeg job. Pass { wait: true } to block until the job reaches a terminal state.

const job = await client.run(
  {
    input_files: { "input.mp4": "https://example.com/input.mp4" },
    output_files: ["output.mp4"],
    ffmpeg_commands: ["-i inputs/input.mp4 -c:v libx264 outputs/output.mp4"],
    webhook_url: "https://example.com/webhook", // optional
    machine: "nvidia", // optional: "cpu" | "nvidia"
  },
  { wait: true }, // optional
);

See Running Commands for how commands are executed.

Get a job — client.jobs.get(id)

Fetches a single job by ID.

const job = await client.jobs.get("job_abc123");
console.log(job.status); // "queued" | "running" | "succeeded" | "failed" | "cancelled"

List jobs — client.jobs.list(params?)

Returns a paginated list of jobs.

const { data, pagingParams } = await client.jobs.list({ limit: 20, offset: 0 });
console.log(data); // Job[]
console.log(pagingParams); // { limit, offset, total, hasMore }

Cancel a job — client.jobs.cancel(id)

Cancels a queued or running job.

const job = await client.jobs.cancel("job_abc123");
console.log(job.status); // "cancelled"

Upload a file — client.files.upload(data, contentType?)

Uploads a file to temporary storage and returns a URL you can use as an input_files value.

import { readFileSync } from "fs";

const url = await client.files.upload(readFileSync("input.mp4"), "video/mp4");

const job = await client.run({
  input_files: { "input.mp4": url },
  output_files: ["output.mp4"],
  ffmpeg_commands: ["-i inputs/input.mp4 -vf scale=1280:720 outputs/output.mp4"],
});

Prepare upload — client.files.prepareUpload()

Returns a presigned upload_url and download_url directly, useful when you need to stream a large file yourself rather than buffering it in memory.

import { createReadStream, statSync } from "fs";

const { upload_url, download_url } = await client.files.prepareUpload();

await fetch(upload_url, {
  method: "PUT",
  headers: {
    "Content-Type": "video/mp4",
    "Content-Length": String(statSync("large.mp4").size),
  },
  body: createReadStream("large.mp4"),
  duplex: "half",
});

const job = await client.run({
  input_files: { "input.mp4": download_url },
  output_files: ["output.mp4"],
  ffmpeg_commands: ["-i inputs/input.mp4 -vf scale=1280:720 outputs/output.mp4"],
});

Referencing files in commands

Every job runs in a workspace with two directories. Each entry in input_files is downloaded into inputs under its key name, and every file your commands write to outputs that is listed in output_files is uploaded and returned as a download URL.

Reference files with plain paths — inputs/<name> to read, outputs/<name> to write:

await client.run({
  input_files: { "input.mp4": "https://example.com/video.mp4" },
  output_files: ["output.wav"],
  ffmpeg_commands: ["-i inputs/input.mp4 -vn outputs/output.wav"],
});

Paths work anywhere in the command string, including inside -filter_complex, and they are real paths on the worker, so the command is the same one you would run locally.

See File Reference Styles for more.

Complete examples

See the examples/ folder for minimal runnable examples:

• examples/node-cjs — Node.js CommonJS
• examples/ts-esm — TypeScript ESM

Support

Open an issue at github.com/verygoodffmpeg/Very-Good-FFmpeg-Typescript-SDK or email [email protected].