Convertrilo

io.github.serkandrgn由 GitHub 帳號 serkandrgn 發布v0.1.2更新於 Oct 24, 2026

Create and manage Convertrilo video encoding jobs from MCP clients and agent workflows.

已驗證STDIO僅桌面雲端與基礎設施檔案與儲存媒體與設計

概覽

AI 產生的概覽

讓助理建立與管理 Convertrilo 雲端影片編碼工作，包括查詢狀態、取消工作與交付輸出。

可以做什麼
Convertrilo 除了提供 CLI 與 TypeScript SDK 外，還提供 stdio MCP 伺服器 convertrilo-mcp，用來呼叫 Convertrilo 影片編碼 API。助理可以提交來自 URL、S3 或 Google Drive 的編碼工作，設定編解碼器、解析度、品質、音訊與影格率策略，並輪詢工作狀態直到完成。它也支援批次資料夾匯入、儲存編碼預設集、儲存輸出目標、取消工作、清理檔案，以及查看 webhook 遞送紀錄。
適用情境
當代理或工作流程需要轉碼影片而不想自行建置編碼流程時適用，例如壓縮上傳檔案、產生 1080p 網頁 MP4，或為儲存資料夾中的每支影片排入一個工作。它適合伺服器端自動化，而不是瀏覽器應用程式。
執行需求
透過 npm 套件 @convertrilo/sdk 以本機 Node.js 程序執行，鎖定提供全域 fetch 的現代 Node.js 執行環境。需要 Convertrilo API 金鑰，透過環境變數 CONVERTRILO_API_KEY 提供，或用 convertrilo login 或 convertrilo init 儲存在本機。輸出到 S3 或 Google Drive 需要客戶自己的儲存憑證或服務帳戶。
安裝前請注意
編碼會計費，定價回應會提供 requestedPasses 與 effectivePasses，因此工作數量與 pass 設定會影響費用。API 金鑰以及客戶儲存憑證（例如 CUSTOMER_S3_ACCESS_KEY_ID、CUSTOMER_S3_SECRET_ACCESS_KEY 或 GOOGLE_SERVICE_ACCOUNT_JSON）必須留在伺服器端，絕不能放進前端程式碼。工作會將輸出寫入你的儲存空間，deleteJobFiles 會刪除代管的輸入與輸出物件，因此應先取消進行中的工作。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Convertrilo，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

Convertrilo TypeScript SDK

Type-safe client for the Convertrilo API.

VMAF And Encoding Passes

When optimize: "vmaf" is requested, Convertrilo performs VMAF sampling and one optimized final encode. A supplied passes: 2 value remains accepted for backward compatibility, but the API uses and bills one effective pass.

Pricing responses expose requestedPasses and effectivePasses. New integrations should use passes: 1 with VMAF.

Install

bash
pnpm add @convertrilo/sdk

The package currently targets modern Node.js runtimes with global fetch. If your runtime does not provide fetch, pass fetchImpl to the client.

CLI And MCP Automation

The package includes two executable automation tools:

bash
export CONVERTRILO_API_KEY="cvr_..."
convertrilo encode https://example.com/input.mp4 \  --codec h264 \  --resolution 1080p \  --audio-policy transcode-aac \  --frame-rate-policy cap \  --scale-policy no-upscale \  --quality better \  --wait \  --json
convertrilo-mcp

Use convertrilo for scripts, CI, cron, and local operations. Use convertrilo-mcp as a stdio MCP server for agent and workflow integrations.

Run convertrilo login or convertrilo init to save an API key locally, or run convertrilo with no arguments to start the interactive encode wizard. Waiting commands show terminal progress by default and keep --json clean for scripts.

Shell completion snippets are available with:

bash
convertrilo completion zsh

See docs/CLI-AND-MCP.md for commands, MCP client config, S3 output examples, VMAF, two-pass, status, cancel, and balance workflows.

If you want the simplest terminal walkthrough, start with docs/CLI-QUICKSTART.md.

For agent/client setup, use docs/MCP-QUICKSTART.md.

MCP registry metadata lives in server.json.

Create A Client

ts
import { ConvertriloClient } from "@convertrilo/sdk";
const client = new ConvertriloClient({  baseUrl: "https://api.convertrilo.com",  apiKey: process.env.CONVERTRILO_API_KEY,});

Use an API key for server-to-server integrations. Browser apps should call your own backend, then your backend calls Convertrilo.

Examples

The examples/ directory contains starter scripts for the main integration paths:

  • node-url-to-cdn.ts - encode a public URL and receive a signed CDN download URL
  • node-url-to-s3.ts - encode a public URL and upload the result to S3/S3-compatible storage
  • google-drive-byo-token.ts - upload output to Google Drive using a customer-owned service account
  • folder-ingest-s3.ts - queue one encode job per video in an S3 prefix
  • idempotency.ts - safely retry createJob and createJobsBulk
  • webhook-receiver-hmac.ts - verify managed webhook HMAC signatures from a Node receiver

Local SDK smoke tests use .env, but published SDK users should provide credentials through their own server environment. Do not put Convertrilo API keys or customer storage tokens in frontend code.

For a complete server-to-server walkthrough covering URL, S3, folder ingest, Google Drive service accounts, polling, and webhooks, see docs/API-INTEGRATION-GUIDE.md.

Idempotent Job Creation

Use an idempotency key when retrying create calls from your backend. Reusing the same key with the same body returns the original response instead of creating duplicate jobs.

ts
const job = await client.createJob({  externalId: "upload-123",  metadata: { customerId: "cus_123" },  codec: "h264",  resolution: "1080p",  fps: 30,}, {  idempotencyKey: "job-upload-123",});
const batch = await client.createJobsBulk({  jobs: [    {      externalId: "batch-42:clip-1",      codec: "h264",      resolution: "1080p",      fps: 30,      sourceS3: { bucket: "source", key: "clip-1.mp4" },    },  ],  settings: { confirm: true },}, {  idempotencyKey: "bulk-batch-42",});

Job File Cleanup

Delete managed upload and output objects after a job reaches a terminal state:

ts
await client.cancelJob(jobId); // required first for created, queued, or running jobs
const result = await client.deleteJobFiles(jobId);console.log(result.objectsDeleted, result.jobRetained);

The job record and billing history remain available for auditing. Active jobs return the stable job_active error until they are canceled.

Saved Encode Presets

Save reusable encode settings without storing source URLs, storage credentials, or output secrets:

ts
const preset = await client.createEncodePreset({  name: "Default 1080p web MP4",  settings: {    codec: "h264",    resolution: "1080p",    fps: 30,    preset: "standard",    bitrateTier: "medium",    passes: 1,    policy: "fastest",    container: "mp4",    quality: "better",    optimize: "none",    vmafTarget: 93,    audioPolicy: "transcode-aac",    frameRatePolicy: "cap",    scalePolicy: "no-upscale",  },});
const { presets } = await client.getEncodePresets();

Saved Output Destinations

Save reusable delivery targets without storing raw storage secrets in the destination itself. S3 destinations reference an encrypted saved S3 credential:

ts
const destination = await client.createOutputDestination({  name: "Customer uploads bucket",  config: {    type: "s3",    credentialId: "0f5a7f2b-4ff2-45d4-b76f-1f7b6e98d4d1",    keyPrefix: "processed/",  },});
const { destinations } = await client.getOutputDestinations();

URL Source To CDN Output

ts
const job = await client.onDemandEncode({  sourceUrl: "https://example.com/input.mp4",  externalId: "customer-video-123",  metadata: {    customerId: "cus_123",    workflow: "daily-compression",  },  codec: "h264",  resolution: "1080p",  quality: "better",  audioPolicy: "transcode-aac",  frameRatePolicy: "cap",  scalePolicy: "no-upscale",}, {  idempotencyKey: "encode-customer-video-123",});
let finalStatus;while (true) {  finalStatus = await client.onDemandStatus(job.jobId);
  if (finalStatus.status === "success") break;  if (finalStatus.status === "failed") {    throw new Error(finalStatus.failureMessage || "Encoding failed");  }
  await new Promise((resolve) => setTimeout(resolve, 5000));}
console.log(finalStatus.downloadUrl);console.log(finalStatus.requestedExecution);console.log(finalStatus.effectiveExecution);console.log(finalStatus.sourceProbe?.color);console.log(finalStatus.outputProbe);

Terminal users can inspect the same report with:

bash
convertrilo status JOB_ID --jsonconvertrilo wait JOB_ID --json

URL Source To S3 Output

ts
const job = await client.onDemandEncode({  sourceUrl: "https://example.com/input.mp4",  codec: "h264",  resolution: "1080p",  outputS3: {    bucket: "customer-output-bucket",    key: "encoded/input-1080p.mp4",    region: "us-east-1",    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,  },});
console.log(job.jobId);

For S3-compatible services, pass endpoint and usually forcePathStyle: true.

URL Source To Google Drive Output

For headless API integrations, save a customer-owned Google service account once. Use a Google Shared Drive for output and add the returned service-account email as a member with permission to create files.

ts
const credential = await client.createGoogleDriveCredential({  name: "Production Drive",  serviceAccount: JSON.parse(process.env.GOOGLE_SERVICE_ACCOUNT_JSON!),});
const job = await client.onDemandEncode({  sourceUrl: "https://example.com/input.mp4",  codec: "h264",  resolution: "1080p",  outputGoogleDrive: {    folderId: "GOOGLE_DRIVE_FOLDER_ID",    fileName: "input-1080p.mp4",    credentialId: credential.id,  },});
console.log(job.jobId);

Dashboard Google Picker authorization is separate from SDK automation.

Folder Ingest

Queue one job per video in an S3 prefix:

ts
const batch = await client.onDemandIngestFolder({  externalIdPrefix: "batch-2026-06-09",  metadata: {    customerId: "cus_123",    workflow: "folder-compression",  },  sourceS3: {    bucket: "customer-source-bucket",    prefix: "incoming/",    region: "us-east-1",    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,  },  outputDestination: "s3",  outputS3: {    bucket: "customer-output-bucket",    prefix: "encoded/",    region: "us-east-1",    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,  },  codec: "h264",  maxFiles: 25,  resolution: "1080p",}, {  idempotencyKey: "folder-batch-2026-06-09",});
for (const job of batch.jobs || []) {  console.log(job.jobId, job.externalId, job.fileName);}

Use maxFiles to cap how many discovered videos are queued from a folder.

Queue one job per video in a Google Drive folder:

ts
const batch = await client.onDemandIngestFolder({  sourceGoogleDrive: {    folderId: "SOURCE_FOLDER_ID",    credentialId: credential.id,  },  outputDestination: "google-drive",  outputGoogleDrive: {    folderId: "OUTPUT_FOLDER_ID",    credentialId: credential.id,  },  codec: "h264",  maxFiles: 25,  resolution: "1080p",});
for (const job of batch.jobs || []) {  console.log(job.jobId, job.fileName);}

Convertrilo mints short-lived Google tokens from the encrypted service-account credential when each worker starts.

Poll each returned jobId with client.onDemandStatus(jobId).

Webhook Delivery History

Managed webhooks are HMAC signed. You can test a webhook and inspect recent delivery attempts:

ts
await client.testWebhook(webhookId);
const history = await client.getWebhookDeliveries(webhookId);for (const delivery of history.deliveries || []) {  console.log(delivery.status, delivery.statusCode, delivery.event);}

Regenerate Types

The SDK types are generated from openapi.yaml.

bash
pnpm run generatepnpm run build

The generate script uses --default-non-nullable false so OpenAPI defaults remain optional in TypeScript request bodies.

來源：README.md，提交 d4ff8b2

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

1
  1. v0.1.2最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分