sercraig / transloadify

🤖☁️📽📦 Transloadit's cloud encoding in a box

Transloadify

Transloadify is a command line interface Transloadit's file uploading and encoding service.

Intro

Transloadit is a service that helps you handle file uploads, resize, crop and watermark your images, make GIFs, transcode your videos, extract thumbnails, generate audio waveforms, and so much more. In short, Transloadit is the Swiss Army Knife for your files.

This is a Command Line Interface to make it easy to talk to the Transloadit REST API.

It is a way for non-programmers to access the service, and serves as the shell script SDK. It can also be used as a cloud-based transcoding and media processing utility.

Features

• Create and manage assemblies, templates, notifications and bills
• Process media in the cloud using any of Transloadit's facilities, including full ffmpeg and ImageMagick support
• Synchronize your Transloadit templates with local files (WIP)
• File watching
• Tab completion

Install

$ npm install -g transloadify

Usage

Transloadify needs Transloadit API authentication information. It looks for it in the environment variables TRANSLOADIT_KEY and TRANSLOADIT_SECRET. Check the API credentials page for these values.

See transloadify --help for complete usage instructions.

Processing media

Transloadify uses the Transloadit API. Transloadit allows you to process media in the cloud by creating Assemblies. An Assembly in an execution of processing instructions on an uploaded file. The simplest way to create Assemblies using Transloadify is to put the processing instructions (called Assembly Instructions) in a JSON file and give it to Transloadify using the --steps option. Transloadify will then upload whatever is passed to it via standard in, and output the result file to standard out.

$ transloadify --steps steps.json < input.jpg > output.jpg

Transloadit supports Templates which are Assembly Instructions stored in the cloud. Templates can be created and managed through Transloadify using the templates commands. If you have a Template that you would like to use to process media, you can specify it with the --template option instead of specifying a --steps.

$ transloadify --template TEMPLATE_ID < input.jpg > output.jpg

If your Template expects certain custom fields to be set, those can be specified using the --field option.

$ transloadify --template TEMPLATE_ID --field size=100 < input.jpg > output.jpg

Rather than use STDIN and STDOUT, you can also pass files to Transloadify using the --input and --output flags. These flags are also more flexible than standard IO because they can take directories, to process media in batch, optionally traversing subdirectories with the --recursive option.

$ transloadify --template TEMPLATE_ID --field size=100 \
    --input images --recursive --output thumbs

Transloadify also has the option to watch inputs for changes, using the --watch option, and reprocessing them whenever a change is detected.

$ transloadify --template TEMPLATE_ID --field size=100 \
    --input images --recursive --output thumbs --watch

All of these flags support shortened versions, to avoid invocations getting too long. See transloadify assemblies create --help for details. The above can be shortened to:

$ transloadify -tTEMPLATE_ID -fsize=100 -i images -o thumbs -wr

Assemblies

The transloadify assemblies subcommand lets you manage assemblies. Using transloadify you can create, cancel, replay, list and fetch Assembly Statuses. See transloadify assemblies --help for a list of available actions, and transloadify assemblies ACTION --help for specific action documentation.

Creation

The usage described in Processing media implicitly uses the transloadify assemblies create command, which has the same behavior as the bare transloadify command.

Listing

You can use Transloadify to list assemblies associated with the account, optionally filtered by date and keywords. For instance:

$ transloadify assemblies list --after 2016-11-08

See transloadify assemblies list --help for a list of accepted options.

One use-case is to recover failed assemblies once the issue has been resolved. If a Template definition contained an error that caused Assemblies to fail, you can salvage them by fixing the Template and using an invocation like this, using the jq JSON utility.

$ transloadify assemblies list --json --after "$AFFECTED_DATE" \
  | jq -r 'select(.error) | .id' \
  | xargs transloadify assemblies get --json \
  | jq -r 'select(.template_id == "'$AFFECTED_TEMPLATE'") | .assembly_id' \
  | xargs transloadify assemblies replay --reparse-template

Templates

transloadify templates is used to create and manage templates. transloadify templates --help gives a list of supported actions.

Modification

transloadify templates modify will read new Template contents from standard in if no file is specified. If you just want to rename a Template using the --name option, the command will ignore empty input:

$ transloadify templates rename $TEMPLATE_ID --name my_template < /dev/null

Assembly Notifications

Support for listing and replaying Assembly Notifications is provided by transloadify assembly-notifications list and transloadify assembly-notifications replay respectively.

Listing

transloadify assembly-notifications list can list, optionally filtered by whether they succeeded or failed, either all Notifications associated with an account, or for a given Assembly. If you would like to see Notifications for a list of Assemblies, it must be called for each one individually.

$ transloadify assemblies list --after 2016-11-08 \
  | xargs -n1 transloadify assembly-notifications list

Bills

Monthly billing information can be fetched with transloadify bills get YYYY-MM.... By default only the total charge is output, but more detailed information can be displayed in JSON format with the --json flag.

$ transloadify bills get 2016-11 --json

Tips

• Command names have aliases, the following are interchangeable
  • assemblies, assembly, a
  • templates, template, t
  • assembly-notifications, assembly-notification, notifications, notification, n
  • bills, bill, b
  • create, new, c
  • delete, cancel, d
  • modify, edit, alter, m
  • replay, r
  • list, l
  • get, info, view, display, g
• All output, from any command, can also be provided in JSON format using the --json flag

Example

An example script written to add watermark to videos can be found here examples/.

Getting Started

Please see the GETTING-STARTED.md file.

Changelog

Please see the CHANGELOG.md file.

Frequently Asked Questions

Please see the FAQ.md file.

Authors

• Adrian Sinclair

License

The MIT License