1. Basics

1.1 Introduction

How it works

  1. You include our jQuery plugin on your page to enable your HTML form to use Transloadit. When your user submits the form, the files are uploaded to Transloadit.
  2. Transloadit processes the uploaded files, such as by encoding videos, resizing images, and storing the results on Amazon S3 for example.
  3. Once processing is completed, the jQuery plugin attaches the result JSON in a hidden field called transloadit to your form. Then, the form is submitted as it would have been normally.
  4. In your backend, you analyze the result JSON from the transloadit form field and store the URLs to the result files in your database. Then you display beautiful videos and images to your users.

While this is the usual workflow, you can also customize it as you see fit.

What we offer

We offer all of the required components to manage file uploads and conversions for your web or mobile application:

  • A RESTful JSON API for managing the encoding/resizing/conversion of images, videos, documents, etc.

  • A jQuery plugin to facilitate enabling Transloadit functionality in your forms and to display a nice File upload progressbar, the upload speed, etc.

  • Development kits for many popular languages and frameworks to send API calls from your backend and to not need to rely on the jQuery plugin.

Terminology

  • Assembly
    An assembly is the execution of file conversion instructions (called assembly instructions) against uploaded and/or imported files. Each assembly has a unique assembly_id identifier that can be used to refer to the assembly in subsequent API requests.
  • Assembly instructions
    The set of assembly steps that the Transloadit backend executes on the uploaded/imported files.
  • Assembly step
    One processing step that files undergo in an assembly. Each step does some type of encoding, resizing or conversion.
  • Robot
    Each assembly step uses exactly one robot. We have a robot for video encoding, one for image manipulation, etc. You can set parameters in your assembly step that define how exactly the specified robot should convert your files.
  • Assembly notification
    The sending of the results of an assembly in a POST request to a URL of your choice. It is optional to use assembly notifications.

1.2 The minimal integration

The following step-by-step guide explains how to implement a minimal image resize upload using Transloadit.

Step 1: Create your account

Create a new account using our signup page. Your API credentials will be generated automatically. Then, log in to your account.

Step 2: Create the upload form

In your web page, edit the source of the page and add the HTML for a form:

<form id="upload-form" action="/uploads" enctype="multipart/form-data" method="POST">
  <input type="file" name="my_file" />
  <input type="submit" value="Upload">
</form>

Make sure that enctype is set to multipart/form-data. If it is not, browsers will not understand that this form is used to upload files.

Also your file input field(s) must contain a name attribute.

Step 3: Add the jQuery plugin

The Transloadit jQuery plugin provides some additional functionality, allowing you to:

  • show file upload progress,
  • get upload results directly without further API queries, and
  • wait for all file conversions to complete before final form submission.

You can use the following HTML/Javascript to add our jQuery plugin:

<!-- You can choose jQuery version 1.9.0 or any newer version here -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
<script src="//assets.transloadit.com/js/jquery.transloadit2-v2-latest.js"></script>
<script type="text/javascript">
   $(function() {
     $('#upload-form').transloadit({
        wait: true,

        params: {
          auth: { key: "YOUR-AUTH-KEY" },
          steps: {
            resize_to_75: {
              robot: "/image/resize",
              use: ":original",
              width: 75,
              height: 75
            }
          }
        }
     });
   });
</script>

Please make sure you replace YOUR-AUTH-KEY with the key found on the API credentials page.

The wait parameter specifies whether Transloadit should wait for all files to be processed before submitting the final form. In this case, it means Transloadit will first wait for all uploaded files to be resized to 75x75 pixels before submitting the final form. If you set it to false you will require Transloadit to notify you when the file processing is done. But more on that later.

The steps object allows you to set the assembly instructions (the set of assembly steps) you want to use. You can use as many steps as you want and you can also name them whatever you like! We only specify one step here, which uses the /image/resize robot, and specifies use: ":original", which means the robot should use the originally uploaded files as input. You can also specify names of other steps for the use parameter, but we'll learn more about that later.

Hint Using the jQuery plugin or one of our other development kits is the advised way of integration. However, by changing a few things, you can also get it to work without JavaScript enabled. Read more about that here.

Step 4: Testing

Now that the form is done, we are ready to upload a file. By default, this will display an overlay with a progress bar when a file is uploaded.

On your backend page, return the incoming POST data to display the results that Transloadit appended to the form. For example, use something like the following for PHP:

<?php
$transloaditData = $_POST['transloadit'];
if (ini_get('magic_quotes_gpc') === '1') {
  $transloaditData = stripslashes($transloaditData);
}
$transloaditData = json_decode($transloaditData, true);
print_r($transloaditData);

foreach ($transloaditData['uploads'] as $upload) {
  // do something with the uploaded file here
}

foreach ($transloaditData['results'] as $encodingResult) {
  // do something with the encoding result here here,
  // like saving its URL to the database
}
?>

The result of the print_r should be something like this.

Transloadit provides information about all uploaded files (the uploads key) as well as about all produced result files (the results key). They are both arrays in the result JSON. This is to support all use cases, including having multiple uploaded files and multiple encoding results.

Hint To see a working example of what we just built, see this demo page. The assembly instructions differ slightly, but should give you a good idea of how things work.

Specifying assembly instructions in the form

Alternatively, you could have also added the assembly instructions in a hidden form field named params. Sometimes, especially when your instructions need to be calculated by a backend language, it's just easier to specify them in the form directly than to add them in the call to the jQuery plugin

The contents of the hidden params field need to be encoded as JSON, with HTML entities escaped. Have your preferred scripting language encode the JSON for you to maintain readability. Here is an example in PHP:

$params = array(
  'auth' => array('key' => 'YOUR-AUTH-KEY'),
  'steps' => array(
    "resize_to_75" => array(
      "robot" => "/image/resize",
      "use" => ":original",
      "width" => 75,
      "height" => 75
    )
  )
);

printf(
  '<input type="hidden" name="params" value="%s" />',
  htmlentities(json_encode($params))
);

Your form should then look like this (just with YOUR-AUTH-KEY replaced with your real Auth key):

<form id="upload-form" action="http://api2.transloadit.com/assemblies" enctype="multipart/form-data" method="POST">
  <input type="hidden" name="params" value="{&quot;auth&quot;:{&quot;key&quot;:&quot;YOUR-AUTH-KEY&quot;},&quot;steps&quot;:{&quot;resize_to_75&quot;:{&quot;robot&quot;:&quot;\/image\/resize&quot;,&quot;use&quot;:&quot;:original&quot;,&quot;width&quot;:75,&quot;height&quot;:75}}}" />
  <input type="file" name="my_file" />
  <input type="submit" value="Upload">
</form>

Both ways of adding the assembly instructions to your form are valid. When you upload a file you should see the same result.


Closing remarks

That's it already for the minimal integration - it was pretty simple wasn't it? If you want to there is a lot more that you can do, though.

For example, specifying your assembly instructions in the form directly or in your Javascript makes them publicly visible. That's why you'll later learn about Templates in order to hide instructions within your Transloadit account.

Also you might have noticed that your auth key is also publicly visible using this integration method, allowing potentially anyone to upload files on your behalf driving your Transloadit bill up. To prevent this we offer signature authentication in order to make sure that only you and your users can create assemblies in your account. After all we want to make sure things are secure.

The jQuery plugin is not the only way you can integrate with Transloadit. We offer software development kits for all major platforms and there are also a lot of community projects that you can use and learn from. And if none of the SDKs and community projects suit your requirements, then you could also write your own code to integrate with our JSON API.


1.3 Building assembly instructions

Basics

Since processing files is the heart of Transloadit, we have crafted a simple JSON format that enables Transloadit to do just about anything with them. Here is a simple example:

{
  auth: { key: "YOUR-API-KEY" },
  steps: {
    encode: {
      robot: "/video/encode",
      use: ":original",
      preset: "iphone"
    },
    export: {
      robot: "/s3/store",
      use: "encode",
      bucket: "your-s3-bucket"
      key: "your-s3-key",
      secret: "your-s3-secret",
    }
  }
}

These instructions consist of two assembly steps, encode and export, but you can name your steps whatever you want. Giving them names (instead of numbers) makes it easier to reference them.

Each step is defined as a JSON object with a robot key and a use. They specify which robot should be used for the assembly step and which other step the robot should use as its conversion input. By using :original you state that the originally uploaded files should be used as input.

All other parameters will be used for the file conversion itself.

Special parameters

Special parameters are those interpreted by the assembly engine itself, controlling the order and behavior of your steps.

Parameter Description
robot Specifies which processing robot to use for the step.
Robots only accept certain file types. File types they cannot process will be ignored, no errors are thrown. The /video/encode robot, for example, will ignore images and the /image/resize robot will ignore videos.
use Specifies which assembly step to use as the input to this step.
Please use the name ":original" to reference uploaded files. See demo
You can also specify an array here to use several steps as the input to your step: use: [ ":original", "my_video_encode" ]
result Controls if the results of this step should be returned.
If set to true this step will occur in the assembly's result JSON with a temporary URL referencing the result file.
For convenience reasons this is automatically set to true for any steps that have no subsequent step.

If you set this to false this step will not occur in the assembly's result JSON, which can be useful if you want to keep the JSON small.

Executing assembly instructions

Transloadit processes as much as possible in parallel. Steps will be executed as soon as their input steps are available. For example, let's say we want to encode a video that was uploaded and would also like to extract thumbnails from it:

{
  steps: {
    encode: {
      use: ":original",
      robot: "/video/encode",
      preset: "iphone"
      width: 320,
      height: 240
    },
    thumbs: {
      use: ":original",
      robot: "/video/thumbs",
      count: 4
    },
    export: {
      use: [ "encode", "thumbs" ],
      robot: "/s3/store",
      bucket: "your-bucket",
      key: "your-key",
      secret: "your-secret"
    }
  }
}

Both the encode and the thumbs step will be executed in parallel as soon as the file upload is finished.

The export step is set up to use the results of encode and thumbs and will spawn an internal job for each file as soon as the results of these steps become available.

As you can see, this format makes it easy to execute instructions as fast as possible.

Examples

Please check out our demo section for a lot of examples of simple and complex assembly instructions.


1.4 Securing assembly instructions

Introducing templates

While specifying assembly instructions directly in the params field of a form is convenient, there are two major problems:

  • Anyone visiting your site can read your HTML source, and see your assembly settings.
  • Embedded secrets such as S3 and SFTP access credentials are completely visible!

Due to these issues, we offer Templates.

They allow you to store assembly instructions securely on our servers, by using 256 bit AES encryption and then just include the template's ID in a template_id key in the hidden params input field (or the call to the jQuery plugin).

This is useful for assembly instructions that use storage robots that require service access credentials (such as the S3 robot). Templates can be used to hide your secret credentials, to keep them from showing up in your HTML source.

The jQuery plugin's params object will be merged into the template that you use, giving you a good means to overwrite your templates on the fly. Think of an image cropping tool that allows your users to select a cropping area. You will want to overwrite the coordinates in your template with the coordinates that your user chose. With this, there really is no reason to not use templates.

How to create a template

  1. Log in to your Transloadit account on the website.
  2. Click on the "Templates" link under "My Account", and then click "Create template".
  3. Give your template a name for future reference.
  4. Provide the JSON assembly instructions for your template and hit save.

Once the template is saved, a page is displayed showing the template you created. At the top of the page the template's template_id is shown, such as "4b62ee4dbb38455d96fe13d972ec3211". Then you can attach this ID to the template_id parameter in your Transloadit form parameters.

Hint The website also has a testing area where you can test your templates with an upload form, without updating your own HTML forms.

How to use a template

Once you have a template_id, you can use the template in a form by replacing the assembly steps in the jQuery plugin's params object with the template id. For example, take the following:

{
  $(function() {
    $('#upload-form').transloadit({
      wait: true,
      params: {
        auth: { key: "YOUR-API-KEY" },
        steps: {
          encode: {
            robot: "/video/encode",
            preset: "iphone"
          },
          store: {
            robot: "/s3/store",
            key: "your-key",
            secret: "your-secret",
            bucket: "your-bucket"
          }
        }
      }
    });
  });
}

With a template, this would become something like this:

{
  $(function() {
    $('#upload-form').transloadit({
      wait: true,
      params: {
        auth: { key: "YOUR-API-KEY" },
        template_id: "4b62ee4dbb38455d96fe13d972ec3211"
      }
    });
  });
}

1.5 Saving and displaying your files

Once your upload form is submitted (or the assembly notification was sent) and you have the results from Transloadit, you can save the URLs of the result files in your database.

In the response JSON you'll find an uploads key and a results key, which contain your original file uploads and the conversion results respectively. You can learn more about the response JSON and how it is formatted here.

Transloadit will save your files only temporarily. These temporary file URLs expire after 24 hours, making them inaccessible. To persist your files, you can use any of the following storage robots:

Transloadit is very good at extracting metadata from uploaded files. So, in addition to saving the URLs of the result files, you may want to consider saving the metadata as well. Users often appreciate seeing more information about the video or image they are looking at.

You are free to integrate any web services or tools for displaying your files on the web as you see fit. For displaying video, we recommend using flowplayer or mediaelementjs.


1.6 Speeding things up

In this section we'll explain how to speed things up and give your end-users a smoother experience.

Uploading times

We have many machines that are dedicated to receiving uploads. We have clusters in Europe and the United states for redundancy and to reduce latency, since your users will be serviced by the machines closest to them.

Queue times

Encoding is hard work for computers, so we use high end machines. We keep an overcapacity of 300% to handle traffic spikes. This ensures we rarely have a queue, but we can't rule it out completely, as customers could send us tough jobs faster than we can process them.

When our scaling software foresees a queue, new machines are launched to drain the queue. It takes 5 minutes for a machine to come online, and we can launch up to 500 of these in parallel.

You can check our current queue times for image conversion and video encoding on our Status Page. You can also programmatically check for them by accessing this JSON API page, which shows them in number of seconds.

Even though queues are a rare thing and we continually optimize for even faster encoding times, sometimes it just takes a few minutes. This is why we recommend to implement Transloadit in an asynchronous way: as soon as your users finish the upload they do not need to wait for file processing to complete. We then contact your app programatically when the processing is done, and you can then notify your user via web / ajax / email and display the files.

If you want to use our jQuery plugin, we advise you to set its wait parameter to false and use assembly notifications instead. By doing this, your users will only have to wait for the uploading of the files to finish and then they can move on. Once Transloadit is done processing your files we will notify you at the notify_url with a POST request and you can start displaying files to your users.

This is the recommended way of integrating Transloadit and you should use it whenever you allow uploading files from a client. It's the best experience for your users and it's also the most reliable way of integrating, because it allows you to replay assemblies (button is available on an assembly detail page on the website) in case there was a problem.


2. Advanced mechanisms

2.1 Dynamic assembly instructions

In addition to template_id, other parameters can be specified params object. These parameters act as variables to be recursively merged into the template. For example, assume the following template:

{
  // the plugin initialization code above this
  steps: {
    encode: {
      robot: "/video/encode",
      preset: "iphone"
    },
    store: {
      robot: "/s3/store",
      key: "your-key",
      secret: "your-secret",
      bucket: "your-bucket"
    }
  }
}

Additional logic can be merged into the template by adding a steps key as well:

{
  // the plugin initialization code above this
  auth: { key : "YOUR-API-KEY"},
  template_id: "4b62ee4dbb38455d96fe13d972ec3211",
  steps: {
    store: {
      bucket: "other-bucket"
    }
  }
}

This is then merged to create the following assembly instructions:

{
  auth: { key: "YOUR-API-KEY" },
  template_id: "4b62ee4dbb38455d96fe13d972ec3211",
  steps: {
    encode: {
      robot: "/video/encode",
      preset: "iphone"
    },
    store: {
      robot: "/s3/store",
      key: "your-key",
      secret: "your-secret",
      bucket: "other-bucket"
    }
  }
}

Note bucket has a value of "other-bucket" now. These additional params are to be passed to the form using the hidden params field.


2.2 Assembly variables

The following is a list of placeholder variables available to assembly instructions. These can be used for any parameter value in any robot:

Variable Description
${account_id} The ID of your Transloadit account (your API key)
${assembly.id} The ID of the assembly representing the current upload.
${unique_prefix} A unique 33-character prefix used to avoid file name collisions, such as "f2/d3eeeb67479f11f8b091b04f6181ad"
${unique_original_prefix} This is like ${unique_prefix} with the exception that two files that are encoding results of the same uploaded file (the original file) will have the same prefix value here.
${previous_step.name} The name of the previous step that produced the current file.
${file.id} The id of the file being processed, which is a 32 char long, unique UUID. It does not contain any periods, slashes or other non-alphanumeric characters.
${file.name} The name of the file being processed, including the file extension.
${file.url_name} The name of the file, with any characters other than A-Za-z0-9-_. replaced with underscores, and with spaces replaced with dashes. This includes the file extension as well.
${file.basename} The name of the file being processed, without the file extension.
${file.url_basename} The basename of the file (the file name without the file extension), with any characters other than A-Za-z0-9-_. replaced with underscores, and with spaces replaced with dashes.
${file.ext} The file extension.
${file.size} The file size.
${file.mime} The file's mime type.
${file.*} Any file property available in the final results array, such as ${file.meta.width}. Not all meta keys are available for all file types.
${fields.*} The form fields submitted with the upload.
For example, ${fields.myvar} would contain a value of 1 for a form with a
<input type="hidden" name="myvar" value="1" />
field.

Example

To see a good example for the use of assembly variables we can take a look at any of our file export robots. We'll use the /s3/store robot here, which allows you to store files on Amazon S3.

The robot has a parameter named path which controls where on S3 the files will be stored. The default value is "${unique_prefix}/${file.url_name}", which makes the files end up on S3 like "f2/my-file-name.png".

We could change the parameter's value to "${previous_step.name}/${unique_prefix}/${file.id}.${file.ext}" for example, which would make the files end up like "video-step-name/a8/d3eeeb67479f11f8b091b04f6181ad.png".

Please note that assembly variables have different levels of uniqueness. For example ${previous_step.name} is the same for all files that are results of the same assembly step. ${file.id} is unique for all files, including results of the same assembly step. ${file.ext} can be the same for all files, or can be totally unique, but ${assembly.id} for example is the same for all files.


2.3 Using form field values in assembly instructions

When you set the jQuery plugin's fields option to '*' (or to an object of key value pairs) and submit a form then the respective form input fields become available in the assembly as variable names. For example, if a form has a textarea named message (using the name attribute), its value could be accessed using ${fields.message} in your path parameter of the store step, such as the following:

{
  auth: { key: "YOUR-API-KEY" },
  template_id: "4b62ee4dbb38455d96fe13d972ec3211",
  steps: {
    encode: {
      robot: "/video/encode",
      preset: "iphone"
    },
    store: {
      robot: "/s3/store",
      key: "your-key",
      secret: "your-secret",
      bucket: "other-bucket",
      path: "${assembly.id}/${fields.message}/356"
    }
  }
}

A fields key can also be added to the params object to inject variables independent of a form into the instructions:

{
  auth: { key: "YOUR-API-KEY" },
  template_id: "4b62ee4dbb38455d96fe13d972ec3211",
  steps: {
    encode: {
      robot: "/video/encode",
      preset: "iphone"
    },
    store: {
      robot: "/s3/store",
      key: "your-key",
      secret: "your-secret",
      bucket: "other-bucket",
      path: "${assembly.id}/${fields.message}/356"
    }
  },
  fields: {
    message: "my value"
  }
}

Variables derived from form fields take precedence over those in the fields key above.


2.4 Assembly notifications

An assembly notification is the sending of the results of an assembly in a POST request to a URL of your choice. It is optional to use assembly notifications.

The script behind the URL of your choice (the notify_url) needs to respond with a 200 header, otherwise Transloadit assumes the notification has failed. If that is the case, the notification is retried up to 5 times over a period of 20 minutes.

Note If you'd like to test assembly notifications locally, we recommend a service like localtunnel.

The browser notifies your app

With this approach visitors wait for both the file uploading and the file conversions to finish.

If you use our jQuery plugin and set its wait parameter to true, the plugin will append the file results to your form as soon as Transloadit has finished processing the upload. It then submits the form to the defined form action.

{
    auth: { key: "your-auth-key" },
    steps: { ... }
}

Unfortunately, this approach has a clear disadvantage; once the file upload is finished, your users must wait for Transloadit to finish all processing, possibly including video encoding and image resizing, before the form is actually submitted to the final destination. This is not usually an issue for image processing, which is very fast in most cases, but definitely harms user experience for video encoding. In this case, consider using notifications, as explained below.

Note For very specific use-cases it may help to take a look at the plugin's source code. You can also always ask us to clarify something or help you with integration.


Letting Transloadit notify your app

With this approach visitors only wait for the file uploading to finish. They do not wait for the file conversions to finish.

Notifications are a good way to obtain file results, since they allow you to specify a URL that Transloadit will use to contact you whenever an assembly is completed, when all uploaded files have been encoded, resized, and otherwise processed.

All notifications are sent as POST requests, with a field called transloadit. For details about this response format, see the API documentation for the Transloadit response format.

They also contain a signature field, with the signature calculated for the notification. This allows you to verify that it was actually Transloadit sending this notification. You can learn more about notification signatures here

To use notifications, simply add a notify_url parameter to your params field or your template:

{
    auth: { key: "your-auth-key" },
    steps: { ... },
    notify_url: "http://example.org/files_ready"
}

One common use case is to include our jQuery plugin, set the wait parameter to false, and use notify_url. This will submit the form to its action attribute as soon as the upload has finished, without waiting for the Transloadit results. Transloadit reports the results to your server once the uploaded files are processed.

This provides the best experience, since it prevents users from waiting unnecessarily when files are uploaded.

If you would like to test your assembly notifications locally we recommend using services such as ngrok. If this is not possible for you, then you could also take a look at this community project.


If you cannot rely on Javascript being enabled

(You can safely ignore this section if you are going to use our jQuery plugin or some other Javascript integration.)

So far we have assumed that you are using the jQuery plugin (or your own plugin). But sometimes (read: very rarely) you cannot rely on Javascript being available in the browser.

In this case, you must set your form's action attribute to "http://api2.transloadit.com/assemblies" and you have to provide a redirect_url parameter in your assembly instructions. The form will then be submitted to Transloadit and we'll then redirect the browser to the redirect_url.

It will also append two GET parameters: assembly_id and assembly_url. The assembly_id parameter contains the unique id of your assembly, and the assembly_url is a Transloadit URL from which the results of the file upload can be fetched. The result is a JSON object that also contains the values of other form fields unrelated to the file upload.

When using assembly notifications, i.e you have provided a notify_url, we'll still send the conversion result JSON to this notify_url via a POST request.

Note We originally built this approach to avoid the need to have Javascript enabled in the browser. Times have changed and one can now assume that Javascript is turned on in the browser.


2.5 Advanced "use" conditions

The special use parameter can also be assigned an object specifying additional conditions determining which files are to be input for a given step. The following parameters are currently supported:

Parameter Description
steps Specifying this has the same effect as providing a string or array for the use parameter.
fields This is an array of one or more field names (from the upload form). When this is specified, the corresponding step will only be executed for files submitted through one of the given fields. The field names here correspond to the strings in the name attribute of the HTML file input field tag. This parameter is true by default, meaning that all fields are accepted.

Example:

{
  auth: { key: "YOUR-API-KEY" },
  steps: {
    encode: {
      robot: "/video/encode",
      use: {
        steps: [ ":original" ],
        fields: [ "file_input_field2" ]
      },
      preset: "iphone"
    }
  }
}

3. Libraries & Example applications

3.1 Our jQuery plugin

Basics

The Transloadit jQuery plugin allows you to

  • show file upload progress,
  • get uploaded results directly without further API queries, and
  • wait for upload processing to complete before redirecting to the result page.

Assuming a form with the id "upload-form" (from the minimal integration), the jQuery plugin can be used like this:

<script src="//assets.transloadit.com/js/jquery.transloadit2-v2-latest.js"></script>
<script type="text/javascript">
   // We call .transloadit() after the DOM is initialized:
   $(function() {
     $('#upload-form').transloadit();
   });
</script>

By default, this will display an overlay with a progress bar.

Important: Your file input fields must each have a proper name attribute for our jQuery SDK to work properly.

Customize the progress bar

If you don't like the Transloadit progress bar, you can render your own, like this:

$('#upload-form').transloadit({
  modal: false,
  onProgress: function(bytesReceived, bytesExpected) {
    // render your own progress bar!
    $('#progress')
      .text((bytesReceived / bytesExpected * 100).toFixed(2)+'%');
  },
  onError: function(assembly) {
    alert(assembly.error+': '+assembly.message);
  }
});

If you like the default Transloadit progress bar but just want to change a few colors, customize these css selectors in your own css.


Unbinding the plugin

You can unbind the plugin by calling

$('#upload-form').unbind('submit.transloadit');

How to access the internal transloadit object

You can access the internal uploader object to call methods directly on it like so:

var $el = $('#upload-form');
$el.transloadit({
  wait: true
});

var uploader = $el.data('transloadit.uploader');

// then call some methods on the uploader object
uploader.start();
uploader.stop();

// alternatively you could also do it like this
$el.transloadit('start');
$el.transloadit('stop');

Please consult the plugin's source code to see all available methods.


Available plugin versions

Latest

This is always the latest version, and for now points to v2.4.2. This is the recommended version to use.
https://assets.transloadit.com/js/jquery.transloadit2-latest.js

Version 2 Latest

This is always the latest version of the 2.x.x branch, and for now points to v2.4.2.
https://assets.transloadit.com/js/jquery.transloadit2-v2-latest.js

v2.4.2

v1.0.0

Has the old progressbar design. Supports IE6, but not jQuery 1.9+:
https://assets.transloadit.com/js/jquery.transloadit2-v1.0.0.js


Plugin parameters

The plugin supports several parameters.

Parameter Description
wait Specifies whether the plugin should wait for files to be processed before submitting the form. This is false by default.
params An object of assembly instructions that should be executed. For examples please check the minimal integration. This is null by default, which means the instructions are read from the hidden input field named params. Here is an example:
$('#upload-form').transloadit({
  wait: true,
  params: {
    auth: { key: "YOUR-AUTH-KEY" },
    steps: {
      resize_to_75: {
        robot: "/image/resize",
        use: ":original",
        width: 75,
        height: 75
      },
      // more steps here
    }
  }
});
signature Specifies the signature string, which is required if signature authentication is enabled in your account. This is null by default. The old way of providing this in a hidden input field named signature is still valid and will not be deprecated. Please make sure the signature is calculated in your backend code, so that your Transloadit auth secret is not exposed in your public Javascript code!
modal Specifies whether to render the Transloadit overlay and progress bar automatically. This is true by default.
autoSubmit Specifies whether to submit the original form automatically once the upload and processing have completed. This is true by default.
processZeroFiles Specifies whether to perform processing when the form is submitted with no files selected using the form inputs. This is true by default.
triggerUploadOnFileSelection When set to true this triggers the upload to Transloadit as soon as the user has selected a file in any of the form's file input fields. This is false by default.
exclude Specifies a selector for which any matching input[type=file] elements in the current form will not be uploaded through Transloadit. This is "" by default.
fields A CSS selector that specifies the form fields to be sent to Transloadit. This is false by default, which means no form fields are submitted with an upload. For example:
$('form').transloadit({
  // send no form fields; this is the default
  fields: false
});
If you would like to only send some fields, set this parameter to a CSS selector string matching the fields to be sent:
$('form').transloadit({
  // only send the fields named "field1" & "field2"
  fields: 'input[name=field1], input[name=field2]'
});
If you would like to send all form fields, set this to true:
$('form').transloadit({
  fields: true
});
You can also set this to an object of key/value pairs:
$('form').transloadit({
  fields: {
    name: "John Doe",
    age: 26
  }
});
The fields that you send here will be available as ${fields.*} variables in your assembly instructions. Learn more about that here.
debug Specifies whether Transloadit errors are displayed to end users. If this is set to false, no Transloadit errors will be displayed. Use the onError callback to perform your own logging or presentation. This is true by default.
onStart(assembly) This is fired whenever an upload begins.
onFileSelect(fileName, $fileInputField) This is fired whenever a user selects a file in file input field.
onProgress(
bytesReceived, bytesExpected
)
This is fired whenever the upload progress is updated, allowing you to render your own upload progress bar.
onUpload(upload) This is fired once for each file uploaded. This is useful for custom renderings of multiple file uploads. Each upload here has an id field. You can map that back to the original_id field of results on the onResult callback.
onResult(step, result) This is fired each time a result becomes available for a given step, and is only available when wait is set to true. This can be used to show thumbnails for videos or images once they are uploaded. Results here contain a key original_id, which maps them back to the id of the originally uploaded file's id.
onCancel() This is fired after an upload has been canceled by the user.
onError(assembly) This is fired when upload errors occur.
onSuccess(assembly) This is fired when the plugin has completed an upload. If wait is set to false, this is fired after the upload finishes. If wait is true, this is fired once all files have been processed.

Note For very specific use-cases it may help to take a look at the plugin's source code. You can also always ask us to clarify something or help you with integration.


3.2 Software development kits


3.3 Community projects

The following is a list of projects created by community members, for community members.

Did you see something cool that others in the community can use? Please get in touch and we'll list your project here.


3.4 Example applications

1. Image Cropping Tool

In this example application you upload an image and then select a cropping area via drag and drop. Submitting the form will crop the uploaded image via Transloadit and give the result image back to you.

You can find a live demo and the source code here.


2. Integration with InkFilepicker

This example application provides a nice and very easy integration with InkFilePicker to allow your users to import files from Facebook, Dropbox, Google Drive, Box, Picasa, Instagram, Flickr, GitHub and more. It even allows your users to take a picture or record a video on the fly and import that into Transloadit.

You can find a live demo and the source code here.


3. Video preview image chooser

In this example application you upload a video and can then select a cover image for the video from 10 thumbnails that are extracted from the video. Your choice will be resized into several formats. The uploaded video will also be encoded into several different web formats.

You can find a live demo and the source code here.