Introducing Transloadify: access Transloadit from your command line

Adrian Sinclair

Developer · Baltimore, USA ·

On February 14, 2017, we announced the beta of Transloadify, a command-line tool for accessing Transloadit’s encoding platform. It let people automate media processing without first writing an SDK integration. This walkthrough by Adrian originally appeared on transloadify.io.

Transloadify has since been deprecated. Its CLI moved into the Node.js SDK, now published as @transloadit/node. The examples below use version 4.12.0 of that package. The original motivation and video-watermarking workflow still apply; the old beta registration commands and package installation instructions do not.

Introduction

Imagine a Raspberry Pi that records videos for an Internet-of-Things project. You want to watermark each video before publishing it to YouTube, while leaving the device’s CPU available for its other work. Uploading the finished recording to Transloadit lets you do that encoding remotely.

The same approach can help with a large media library on a more powerful machine. Transloadit’s presets and processing Robots let you describe the output you need, while a CLI script handles the local files. Upload and processing times still depend on your files, connection, and Instructions.

We’ll first process one video, then watch a directory, and finally export the result directly to YouTube. Commands that create Assemblies use your account and may incur processing charges.

Installation

Install Node.js 24 or newer for this walkthrough. Run the pinned CLI without a global installation:

npx -y @transloadit/node@4.12.0 --help
npx -y @transloadit/node@4.12.0 assemblies create --help

Other sources

The original announcement mentioned an Arch Linux AUR package and a planned Docker image. Those were historical distribution notes, not prerequisites for this updated walkthrough. Use the official Node.js SDK for the CLI contract shown here.

Registration & authentication

Create an account through the Transloadit website and obtain an Auth Key and Auth Secret from your account. Have your secret manager supply TRANSLOADIT_KEY and TRANSLOADIT_SECRET to the CLI process. Do not put their values into shell history, source control, or a client app.

The CLI also reads a .env file in its current directory and ~/.transloadit/credentials in dotenv format; shell environment variables take precedence. Keep credential files private. The original transloadify register, transloadify authenticate, .transloadify file, and TRANSLOADIT_AUTH_* variable names are not the setup used by these commands.

Run the CLI only on a machine you trust with your Auth Secret. Templates keep storage credentials on Transloadit, but do not make it safe to distribute an Auth Secret to untrusted devices. Browser and mobile integrations should obtain short-lived signed Instructions from an authenticated server.

Specifying Assembly Instructions

Save this steps object as steps.json. Replace the watermark URL with a publicly reachable HTTPS image you control before processing a video:

{
  "video_encode": {
    "robot": "/video/encode",
    "use": ":original",
    "preset": "webm",
    "watermark_url": "https://example.org/watermark.png",
    "result": true
  }
}

--steps accepts this object. The explicit WebM preset matches the output filename below. See the /video/encode documentation for watermark placement and other output settings, and Assembly Instructions for composing Steps.

Processing a video

Create the output directory and process a finished recording:

mkdir -p watermarked
npx -y @transloadit/node@4.12.0 assemblies create \
  --steps steps.json -i originals/recording.webm -o watermarked/recording.webm

The command uploads the input, waits for the Assembly, and downloads the selected result. Check its exit status and any diagnostic output; silence is not the success contract. This Template produces one result per input, so a single output filename is appropriate. For multiple result files, use an output directory and consult the CLI’s output options.

Automation

The most predictable integration is to invoke the command after your recorder closes its output file. Alternatively, watch an existing directory:

mkdir -p originals watermarked
npx -y @transloadit/node@4.12.0 assemblies create \
  --watch --steps steps.json -i originals/ -o watermarked/

Watching includes existing inputs and subsequent changes. Record outside the watched directory, then move the completed recording into it on the same filesystem. A filesystem event alone does not prove a recording has finished. Keep outputs outside the input directory to avoid processing your own results, and stop the watcher with Ctrl+C when finished.

This can also fit a shared-folder workflow, such as Dropbox: one person contributes completed recordings, while a trusted machine processes them into a separate output folder. Account for the sync client’s partial-file behavior before enabling a watcher. A watcher is not a durable job queue; restarts or file changes can cause another Assembly. For reliable retries and auditing, track jobs and Assembly IDs in your application. The Ruby and Go SDKs are alternatives when you need tighter integration.

Templates

A local steps file is convenient for one machine. A Template lets several trusted workers share centrally managed Instructions. Create one in the web interface or with:

npx -y @transloadit/node@4.12.0 templates create watermarker steps.json

The command prints the new Template ID. Set TEMPLATE_ID to that ID in your shell; the Template’s name is a human-readable label, not its identifier. Then replace --steps with --template:

npx -y @transloadit/node@4.12.0 assemblies create \
  --watch --template "$TEMPLATE_ID" -i originals/ -o watermarked/

Templates can reference Template Credentials so storage secrets stay in your Transloadit account. Keep the CLI’s own account credentials private as well.

Making the most of Transloadit

If the final destination is YouTube, Transloadit can export the watermarked video directly. That avoids downloading it to the Raspberry Pi and uploading it again. It does not eliminate the original upload or guarantee a particular transfer speed.

Authorize YouTube through the Template Credentials interface, then reference that credential’s name in your Template. See /youtube/store for account requirements and export options. Replace steps.json with:

{
  "video_encode": {
    "robot": "/video/encode",
    "use": ":original",
    "preset": "webm",
    "watermark_url": "https://example.org/watermark.png"
  },
  "youtube": {
    "robot": "/youtube/store",
    "use": "video_encode",
    "credentials": "my_youtube_credentials",
    "title": "Watermarked Raspberry Pi recording",
    "description": "A recording processed with Transloadit.",
    "category": "science & technology",
    "keywords": "raspberry pi, transloadit",
    "visibility": "private"
  }
}

The example exports privately so you can inspect the result before publishing it. Customize the title, description, category, keywords, and visibility for your workflow. Update the Template by ID, retaining its name explicitly:

npx -y @transloadit/node@4.12.0 templates modify "$TEMPLATE_ID" steps.json --name watermarker

Then omit -o to avoid downloading results locally:

npx -y @transloadit/node@4.12.0 assemblies create \
  --watch --template "$TEMPLATE_ID" -i originals/

You now have the workflow the original Transloadify announcement set out to demonstrate: local recording, remote watermarking, and direct publishing, coordinated from the command line. Review the resulting Assembly status and YouTube output before leaving an automation unattended.

The original walkthrough appeared first on transloadify.io. The commands above have been updated for the Node.js SDK CLI.