Concepts

If we peel away layers of technology, at its core, Transloadit operates by running a tool on a file, for instance: convert avatar.png avatar.webp. We call this process a Job and this particular job would be performed by a Robot called 🤖/image/resize. Of course, it could be the case that you want us to convert five images. Or perhaps turn five images into one slideshow video, and then add an audio track to it. We call the execution of a number of Jobs that belong together an Assembly.

Below, you'll see our Robots working on an Assembly line. In this case, Transloadit was integrated into a customer's website. Our Robots accept a video upload, convert it to an optimal format, burn a copyright logo into it, extract thumbnails, and export all of it to the customer's cloud storage. The media is now ready to be consumed optimally by all visitors of the website, regardless of their device and connection.

Assemblies are the bread and butter at Transloadit and we process many millions of these logical units each day.

But how do we know which Robots to put to work on incoming files? What should your Assembly line look like?

Customers specify this in a declarative JSON recipe. This document contains the Assembly Instructions, and they describe each Step of the workflow. At the very least, a Step defines which Robot should be put to work, and what other Step to use as its input. For example, the thumbnail Robot should take its input from the Robot that burned logos into the video.

Your app can bundle Assembly Instructions with the request to start an Assembly. Alternatively, you can save the Instructions in your account — that's what we call a Template. Many Assemblies can be spawned based on a single Template. When your app wants Transloadit to encode something, instead of sending the entire recipe each time, it only has to pass along a template_id . The advantages of this approach are that:

• Assembly Instructions could contain secrets that you either don't want to transmit, or client-side integrations to even be aware of. Kept in a Template, they are encrypted at rest.
• If an Assembly should ever error out, when using Templates, we can replay them (automatically if you opt into this).
• It helps to prevent bad actors from tampering with Instructions residing on a client, or using Transloadit on your behalf. Using Templates in conjunction with Signature Authentication is the best way to avoid this.

If Transloadit is unix, our Robots are tools that do one thing well. Pipe them together to create value greater than the sum of its parts. This is an Assembly.

When an Assembly is created, an endpoint that exposes the current Assembly Status JSON is returned that your app can subscribe to until all Jobs are completed (every SDK supports this out of the box). We call this Sync Mode. Alternatively, you can add a notify_url to your Instructions and set waitForEncoding to false. In that case, Transloadit posts the Assembly Status JSON to your back-end when all is done, and the app/end-user does not have to wait on any encoding. When all is done, we ping your back-end, and then you ping your end-user. We call this Async Mode. Async requires more work to set up, but pays off in the form of a better user experience when long processing times are involved, such as when you have us encode large video files. Async is also more reliable, because it allows you enable Assembly Replays in case there was a problem, since we already have a way to notify end-users/systems in an indirect way.

Many of our customers use Transloadit for large batch imports and have server-side languages orchestrate that process. Even more customers, however, integrate Transloadit into websites. We used to offer a jQuery SDK for this, but in 2018, we launched the open source file uploader Uppy 🐶 With over 29,000 stargazers on GitHub, it is now the #1 file uploader in the world. Uppy allows recording from Webcam, picking files from Dropbox or other remote without hitting your local device (thereby preserving battery life and data plans), and resuming uploads after a network hiccup, an accidental navigate-away, or even a browser crash. It works great with 🤖 Transloadit (via its Transloadit Plugin), and it works great without.

Now, if anything is ever unclear, just hit the speech balloon in the lower right corner of the site to talk to a human. We're staring at it all day and enjoy it even if you just want to say hi or have a quick remote coffee with us ☕️

To see all of Transloadit's Terminology in one place, check out the Glossary.

🙏💥 That's it, you made it! You're now as proficient in Transloadit vocabulary as any of us. Any further documentation is going to be a piece of cake after this. Ready?

Let's build something!