transloadit

Fantastic file uploading for your web application.

Description

This is the official Ruby gem for Transloadit. It allows you to automate uploading files through the Transloadit REST API.

Install

gem install transloadit

Getting started

To get started, you need to require the 'transloadit' gem:

$ irb -rubygems
>> require 'transloadit'
=> true

Then create a Transloadit instance, which will maintain your authentication credentials and allow us to make requests to the API.

transloadit = Transloadit.new(
  key:    'transloadit-auth-key',
  secret: 'transloadit-auth-secret'
)

1. Resize and store an image

This example demonstrates how you can create an assembly to resize an image and store the result on Amazon S3.

First, we create two steps: one to resize the image to 320x240, and another to store the image in our S3 bucket.

resize = transloadit.step '/image/resize',
  width:  320,
  height: 240

store  = transloadit.step '/s3/store',
  key:    'aws-access-key-id',
  secret: 'aws-secret-access-key
  bucket: 'bucket-name'

Now that we have the steps, we create an assembly (which is just a request to process a file or set of files) and let Transloadit do the rest.

assembly = transloadit.assembly(
  steps: [ resize, store ]
)

response = assembly.submit! open('lolcat.jpg')

When the submit! method returns, the file has been uploaded but may not yet be done processing. We can use the returned object to check if processing has completed, or examine other attributes of the request.

# returns the unique API ID of the assembly
response[:assembly_id] # => '9bd733a...'

# returns the API URL endpoint for the assembly
response[:assembly_url] # => 'http://api2.vivian.transloadit.com/assemblies/9bd733a...'

# checks how many bytes were expected / received by transloadit
response[:bytes_expected] # => 92933
response[:bytes_received] # => 92933

# checks if all processing has been completed
response.completed? # => false

# cancels further processing on the assembly
response.cancel! # => true

It's important to note that none of these queries are "live" (with the exception of the cancel! method). They all check the response given by the API at the time the assembly was created. You have to explicitly ask the assembly to reload its results from the API.

# reloads the response's contents from the REST API
response.reload!

In general, you use hash accessor syntax to query any direct attribute from the response. Methods suffixed by a question mark provide a more readable way of quering state (e.g., assembly.completed? vs. checking the result of assembly[:ok]). Methods suffixed by a bang make a live query against the Transloadit HTTP API.

2. Uploading multiple files

Multiple files can be given to the submit! method in order to upload more than one file in the same request. You can also pass a single step for the steps parameter, without having to wrap it in an Array.

assembly = transloadit.assembly(steps: store)

response = assembly.submit!(
  open('puppies.jpg'),
  open('kittens.jpg'),
  open('ferrets.jpg')
)

3. Parallel Assembly

Transloadit allows you to perform several processing steps in parallel. You simply need to use other steps. Following their example:

encode = transloadit.step '/video/encode', { ... }
thumbs = transloadit.step '/video/thumbs', { ... }
export = transloadit.step '/s3/store',     { ... }

export.use [ encode, thumbs ]

transloadit.assembly(
  steps: [ encode, thumbs, export ]
).submit! open('ninja-cat.mpg')

You can also use the original uploaded file by passing the Symbol :original.

Check the YARD documentation for more information on using use.

Documentation

Up-to-date YARD documentation is automatically generated. You can view the docs for the released gem or for the latest git master.

Compatibility

At a minimum, this gem should work on MRI 1.9.2, 1.8.7, 1.8.6, and Rubinius 1.2.0. If it doesn't, please file a bug report. Compatibility patches for other Rubies are welcomed.

You can run rake test:multiruby to test transloadit against all supported Rubies. Run rake test:multiruby:setup once beforehand, though, to set up the RVM environments. RVM must be installed in order to test against multiple Rubies.