ruby-sdk
A Ruby Integration for 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 Ruby SDK to make it easy to talk to the Transloadit REST API.
If you run Ruby on Rails and are looking to integrate with the browser for file uploads, checkout the rails-sdk.
Install
gem install transloadit
Usage
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 => 'YOUR_TRANSLOADIT_KEY',
:secret => 'YOUR_TRANSLOADIT_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.
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => 'YOUR_TRANSLOADIT_SECRET'
)
# 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 'resize', '/image/resize',
:width => 320,
:height => 240
store = transloadit.step 'store', '/s3/store',
:key => 'YOUR_AWS_KEY',
:secret => 'YOUR_AWS_SECRET',
:bucket => 'YOUR_S3_BUCKET'
# 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.create! open('/PATH/TO/FILE.jpg')
# reloads the response once per second until all processing is finished
response.reload_until_finished!
if response.error?
# handle error
else
# handle other cases
puts response
end
submit!
has been deprecated and replaced with create!
.
The submit!
method remains as an alias of create!
for backward Compatibility.
When the create!
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_ssl_url] # => 'https://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 finished
response.finished? # => false
# cancels further processing on the assembly
response.cancel! # => true
# checks if processing was successfully completed
response.completed? # => true
# checks if the processing returned with an error
response.error? # => false
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!
# reloads once per second until all processing is finished, up to number of
# times specified in :tries option, otherwise will raise ReloadLimitReached
response.reload_until_finished! tries: 300 # default is 600
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 querying
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 create!
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.
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => 'YOUR_TRANSLOADIT_SECRET'
)
assembly = transloadit.assembly(steps: store)
response = assembly.create!(
open('puppies.jpg'),
open('kittens.jpg'),
open('ferrets.jpg')
)
You can also pass an array of files to the create!
method.
Just unpack the array using the splat *
operator.
files = [open('puppies.jpg'), open('kittens.jpg'), open('ferrets.jpg')]
response = assembly.create! *files
3. Parallel Assembly
Transloadit allows you to perform several processing steps in parallel. You
simply need to use
other Steps. Following
their example:
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => 'YOUR_TRANSLOADIT_SECRET'
)
encode = transloadit.step 'encode', '/video/encode', { ... }
thumbs = transloadit.step 'thumbs', '/video/thumbs', { ... }
export = transloadit.step 'store', '/s3/store', { ... }
export.use [ encode, thumbs ]
transloadit.assembly(
:steps => [ encode, thumbs, export ]
).create! open('/PATH/TO/FILE.mpg')
You can also tell a step to use the original uploaded file by passing the
Symbol :original
instead of another step.
Check the YARD documentation for more information on using use.
4. Creating an Assembly with Templates
Transloadit allows you to use custom templates for recurring encoding tasks. In order to use these do the following:
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => 'YOUR_TRANSLOADIT_SECRET'
)
transloadit.assembly(
:template_id => 'YOUR_TEMPLATE_ID'
).create! open('/PATH/TO/FILE.mpg')
You can use your steps together with this template and even use variables. The Transloadit documentation has some nice examples for that.
5. Using fields
Transloadit allows you to submit form field values that you'll get back in the notification. This is quite handy if you want to add additional custom metadata to the upload itself. You can use fields like the following:
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => 'YOUR_TRANSLOADIT_SECRET'
)
transloadit.assembly(
:fields => {
:tag => 'some_tag_name',
:field_name => 'field_value'
}
).create! open('/PATH/TO/FILE.mpg')
6. Notify URL
If you want to be notified when the processing is finished you can provide a Notify URL for the Assembly.
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => 'YOUR_TRANSLOADIT_SECRET'
)
transloadit.assembly(
:notify_url => 'https://example.com/processing_finished'
).create! open('/PATH/TO/FILE.mpg')
Read up more on the Notifications on Transloadit's documentation page
7. Other Assembly methods
Transloadit also provides methods to retrieve/replay Assemblies and their Notifications.
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => 'YOUR_TRANSLOADIT_SECRET'
)
assembly = transloadit.assembly
# returns a list of all assemblies
assembly.list
# returns a specific assembly
assembly.get 'YOUR_ASSEMBLY_ID'
# replays a specific assembly
response = assembly.replay 'YOUR_ASSEMBLY_ID'
# should return true if assembly is replaying and false otherwise.
response.
# returns all assembly notifications
assembly.get_notifications
# replays an assembly notification
assembly.replay_notification 'YOUR_ASSEMBLY_ID'
8. Templates
Transloadit provides a templates api for recurring encoding tasks. Here's how you would create a Template:
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => 'YOUR_TRANSLOADIT_SECRET'
)
template = transloadit.template
# creates a new template
template.create(
:name => 'TEMPLATE_NAME',
:template => {
"steps": {
"encode": {
"use": ":original",
"robot": "/video/encode",
"result": true
}
}
}
)
There are also some other methods to retrieve, update and delete a Template.
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => 'YOUR_TRANSLOADIT_SECRET'
)
template = transloadit.template
# returns a list of all templates.
template.list
# returns a specific template.
template.get 'YOUR_TEMPLATE_ID'
# updates the template whose id is specified.
template.update(
'YOUR_TEMPLATE_ID',
:name => 'CHANGED_TEMPLATE_NAME',
:template => {
:steps => {
:encode => {
:use => ':original',
:robot => '/video/merge'
}
}
}
)
# deletes a specific template
template.delete 'YOUR_TEMPLATE_ID'
9. Getting Bill reports
If you want to retrieve your Transloadit account billing report for a particular month and year
you can use the bill
method passing the required month and year like the following:
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => 'YOUR_TRANSLOADIT_SECRET'
)
# returns bill report for February, 2016.
transloadit.bill(2, 2016)
Not specifying the month
or year
would default to the current month or year.
10. Rate limits
Transloadit enforces rate limits to guarantee that no customers are adversely affected by the usage of any given customer. See Rate Limiting.
While creating an Assembly, if a rate limit error is received, by default, 2 more attempts would be made for a successful response. If after these attempts the rate limit error persists, a RateLimitReached
exception will be raised.
To change the number of attempts that will be made when creating an Assembly, you may pass the tries
option to your Assembly like so.
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => 'YOUR_TRANSLOADIT_SECRET'
)
# would make one extra attempt after a failed attempt.
transloadit.assembly(:tries => 2).create! open('/PATH/TO/FILE.mpg')
# Would make no attempt at all. Your request would not be sent.
transloadit.assembly(:tries => 0).create! open('/PATH/TO/FILE.mpg')
Example
A small sample tutorial of using the Transloadit ruby-sdk to optimize an image, encode MP3 audio, add ID3 tags, and more can be found here.
Documentation
Up-to-date YARD documentation is automatically generated. You can view the docs for the released gem or for the latest git main.
Compatibility
Please see ci.yml for a list of supported ruby versions. It may also work on older Rubies, but support for those is not guaranteed. If it doesn't work on one of the officially supported Rubies, please file a bug report. Compatibility patches for other Rubies are welcome.
Ruby 2.x
If you still need support for Ruby 2.x, 2.0.1 is the last version that supports it.