Transloadit

The @sme-uploader/transloadit plugin can be used to upload files to Transloadit for all kinds of processing, such as transcoding video, resizing images, zipping/unzipping, and much more.

If you’re okay to trade some flexibility for ergonomics, consider using
the Robodog Plugin instead, which is a higher-level abstraction for
encoding files with SME Uploader and Transloadit.

Try it live

const Transloadit = require('@sme-uploader/transloadit')

uploader.use(Transloadit, {
  service: 'https://api2.transloadit.com',
  params: null,
  waitForEncoding: false,
  waitForMetadata: false,
  importFromUploadURLs: false,
  alwaysRunAssembly: false,
  signature: null,
  fields: {},
  limit: 0
})

As of SME Uploader version 0.24, the Transloadit plugin includes the Tus plugin to handle the uploading, so you no longer have to add it manually.

Installation

This plugin is published as the @sme-uploader/transloadit package.

Install from NPM:

npm install @sme-uploader/transloadit

In the CDN package, it is available on the SmeUploader global object:

const Transloadit = SmeUploader.Transloadit

Properties

`Transloadit.COMPANION`

The main endpoint for Transloadit’s hosted companions. You can use this constant in remote provider options, like so:

const Dropbox = require('@sme-uploader/dropbox')
const Transloadit = require('@sme-uploader/transloadit')

uploader.use(Dropbox, {
  companionUrl: Transloadit.COMPANION
  companionAllowedHosts: Transloadit.COMPANION_PATTERN
})

When using Transloadit.COMPANION, you should also configure companionAllowedHosts: Transloadit.COMPANION_PATTERN.

The value of this constant is https://api2.transloadit.com/companion. If you are using a custom service option, you should also set a custom host option in your provider plugins, by taking a Transloadit API url and appending /companion:

uploader.use(Dropbox, {
  companionUrl: 'https://api2-us-east-1.transloadit.com/companion'
})

`Transloadit.COMPANION_PATTERN`

A RegExp pattern matching Transloadit’s hosted companion endpoints. The pattern is used in remote provider companionAllowedHosts options, to ensure that third party authentication messages cannot be faked by an attacker’s page, but can only originate from Transloadit’s servers.

Use it whenever you use companionUrl: Transloadit.COMPANION, like so:

const Dropbox = require('@sme-uploader/dropbox')
const Transloadit = require('@sme-uploader/transloadit')

uploader.use(Dropbox, {
  companionUrl: Transloadit.COMPANION
  companionAllowedHosts: Transloadit.COMPANION_PATTERN
})

The value of this constant covers all Transloadit’s Companion servers, so it does not need to be changed if you are using a custom service option. However, if you are not using the Transloadit Companion servers at *.transloadit.com, make sure to set the companionAllowedHosts option to something that matches what you do use.

Options

The @sme-uploader/transloadit plugin has the following configurable options:

`id: 'Transloadit'`

A unique identifier for this plugin. It defaults to 'Transloadit'.

`service`

The Transloadit API URL to use. It defaults to https://api2.transloadit.com, which will attempt to route traffic efficiently based on the location of your users. You can set this to something like https://api2-us-east-1.transloadit.com if you want to use a particular region.

`params`

The Assembly parameters to use for the upload. See the Transloadit documentation on Assembly Instructions for further information. params should be a plain JavaScript object, or a JSON string if you are using the signature option.

The auth.key Assembly parameter is required. You can also use the steps or template_id options here as described in the Transloadit documentation.

uploader.use(Transloadit, {
  params: {
    auth: { key: 'YOUR_TRANSLOADIT_KEY' },
    steps: {
      encode: {
        robot: '/video/encode',
        use: {
          steps: [':original'],
          fields: ['file_input_field2']
        },
        preset: 'iphone'
      }
    }
  }
})

`waitForEncoding: false`

By default, the Transloadit plugin uploads files to Assemblies and then marks the files as complete in SME Uploader. The Assemblies will complete (or error) in the background but SME Uploader won’t know or care about it.

When waitForEncoding is set to true, the Transloadit plugin waits for Assemblies to complete before the files are marked as completed. This means users have to wait for a potentially long time, depending on how complicated your Assembly instructions are. But, you can receive transcoding results on the client side, and have a fully client-side experience this way.

When this is enabled, you can listen for the transloadit:result and transloadit:complete events.

`waitForMetadata: false`

When waitForMetadata is set to true, the Transloadit plugin waits for Transloadit’s backend to extract metadata from all the uploaded files. This is mostly handy if you want to have a quick user experience (so your users don’t necessarily need to wait for all the encoding to complete), but you do want to let users know about some types of errors that can be caught early on, like file format issues.

When this is enabled, you can listen for the transloadit:upload event.

`importFromUploadURLs`

Instead of uploading to Transloadit’s servers directly, allow another plugin to upload files, and then import those files into the Transloadit Assembly. This is set to false by default.

When enabling this option, Transloadit will not configure the Tus plugin to upload to Transloadit. Instead, a separate upload plugin must be used. Once the upload completes, the Transloadit plugin adds the uploaded file to the Assembly.

For example, to upload files to an S3 bucket and then transcode them:

uploader.use(AwsS3, {
  getUploadParameters (file) {
    return { /* upload parameters */ }
  }
})
uploader.use(Transloadit, {
  importFromUploadURLs: true,
  params: {
    auth: { key: 'YOUR_API_KEY' },
    template_id: 'YOUR_TEMPLATE_ID'
  }
})

In order for this to work, the upload plugin must assign a publically accessible uploadURL property to the uploaded file object. The Tus and S3 plugins both do this automatically. For the XHRUpload plugin, you may have to specify a custom getUploadResponse function.

`alwaysRunAssembly`

When set to true, always create and run an Assembly when uploader.upload() is called, even if no files were selected. This allows running Assemblies that do not receive files, but instead use a robot like /s3/import to download the files from elsewhere, for example, for a bulk transcoding job.

`signature`

An optional signature for the Assembly parameters. See the Transloadit documentation on Signature Authentication for further information.

If a signature is provided, params should be a JSON string instead of a JavaScript object, as otherwise the generated JSON in the browser may be different from the JSON string that was used to generate the signature.

`fields`

An object of form fields to send along to the Assembly. Keys are field names, and values are field values. See also the Transloadit documentation on Form Fields In Instructions.

uploader.use(Transloadit, {
  ...,
  fields: {
    message: 'This is a form field'
  }
})

You can also pass an array of field names to send global or file metadata along to the Assembly. Global metadata is set using the meta option in the SME Uploader constructor, or using the setMeta method. File metadata is set using the setFileMeta method. The Form plugin also sets global metadata based on the values of <input />s in the form, providing a handy way to use values from HTML form fields:

uploader.use(Form, { target: 'form#upload-form', getMetaFromForm: true })
uploader.use(Transloadit, {
  fields: ['field_name', 'other_field_name'],
  params: { ... }
})

Form fields can also be computed dynamically using custom logic, by using the getAssemblyOptions(file) option.

`getAssemblyOptions(file)`

While params, signature, and fields must be determined ahead of time, the getAssemblyOptions allows using dynamically generated values for these options. This way, it is possible to use different Assembly parameters for different files, or to use some user input in an Assembly.

A custom getAssemblyOptions() option should return an object or a Promise for an object with properties { params, signature, fields }. For example, to add a field with some user-provided data from the MetaData plugin:

uploader.use(MetaData, {
  fields: [
    { id: 'caption' }
  ]
})
uploader.use(Transloadit, {
  getAssemblyOptions (file) {
    return {
      params: {
        auth: { key: 'TRANSLOADIT_AUTH_KEY_HERE' },
        template_id: 'xyz'
      },
      fields: {
        caption: file.meta.caption
      }
    }
  }
})

Now, the ${fields.caption} variable will be available in the Assembly template.

Combine the getAssemblyOptions() option with the Form plugin to pass user input from a <form> to a Transloadit Assembly:

// This will add form field values to each file's `.meta` object:
uploader.use(Form, { getMetaFromForm: true })
uploader.use(Transloadit, {
  getAssemblyOptions (file) {
    return {
      params: { ... },
      // Pass through the fields you need:
      fields: {
        message: file.meta.message
      }
    }
  }
})

getAssemblyOptions() may also return a Promise, so it could retrieve signed Assembly parameters from a server. For example, assuming an endpoint /transloadit-params that responds with a JSON object with { params, signature } properties:

uploader.use(Transloadit, {
  getAssemblyOptions (file) {
    return fetch('/transloadit-params').then((response) => {
      return response.json()
    })
  }
})

`limit: 0`

Limit the amount of uploads going on at the same time. Setting this to 0 means there is no limit on concurrent uploads. This option is passed through to the @sme-uploader/tus plugin that Transloadit plugin uses internally.

`locale: {}`

Localize text that is shown to the user.

The default English strings are:

strings: {
  // Shown while Assemblies are being created for an upload.
  creatingAssembly: 'Preparing upload...'
  // Shown if an Assembly could not be created.
  creatingAssemblyFailed: 'Transloadit: Could not create Assembly',
  // Shown after uploads have succeeded, but when the Assembly is still executing.
  // This only shows if `waitForMetadata` or `waitForEncoding` was enabled.
  encoding: 'Encoding...'
}

Errors

If an error occurs when an Assembly has already started, you can find the Assembly Status on the error object’s assembly property.

uploader.on('error', (error) => {
  if (error.assembly) {
    console.log(`Assembly ID ${error.assembly.assembly_id} failed!`)
    console.log(error.assembly)
  }
})

Events

`transloadit:assembly-created`

Fired when an Assembly is created.

Parameters

assembly - The initial Assembly Status.
fileIDs - The IDs of the files that will be uploaded to this Assembly.

uploader.on('transloadit:assembly-created', (assembly, fileIDs) => {
  console.group('Created', assembly.assembly_id, 'for files:')
  for (const id of fileIDs) {
    console.log(uploader.getFile(id).name)
  }
  console.groupEnd()
})

`transloadit:upload`

Fired when Transloadit has received an upload.

Parameters

file - The Transloadit file object that was uploaded.
assembly - The Assembly Status of the Assembly to which the file was uploaded.

`transloadit:assembly-executing`

Fired when Transloadit has received all uploads, and is currently executing the Assembly.

Parameters

assembly - The Assembly Status of the Assembly that is currently executing.

`transloadit:result`

Fired when a result came in from an Assembly.

Parameters

stepName - The name of the Assembly step that generated this result.
result - The result object from Transloadit.
This result object contains one additional property, namely localId.
This is the ID of the file in SME Uploader’s local state, and can be used with uploader.getFile(id).
assembly - The Assembly Status of the Assembly that generated this result.

uploader.on('transloadit:result', (stepName, result) => {
  const file = uploader.getFile(result.localId)
  document.body.appendChild(html`
    <div>
      <h2>From ${file.name}</h2>
      <a href=${result.ssl_url}> View </a>
    </div>
  `)
})

`transloadit:complete`

Fired when an Assembly completed.

Parameters

assembly - The final Assembly Status of the completed Assembly.

uploader.on('transloadit:complete', (assembly) => {
  // Could do something fun with this!
  console.log(assembly.results)
})

Docs

UI Elements

Sources

Destinations

File Processing

Miscellaneous

Contributing

Transloadit

Installation

Properties

`Transloadit.COMPANION`

`Transloadit.COMPANION_PATTERN`

Options

`id: 'Transloadit'`

`service`

`params`

`waitForEncoding: false`

`waitForMetadata: false`

`importFromUploadURLs`

`alwaysRunAssembly`

`signature`

`fields`

`getAssemblyOptions(file)`

`limit: 0`

`locale: {}`

Errors

Events

`transloadit:assembly-created`

`transloadit:upload`

`transloadit:assembly-executing`

`transloadit:result`

`transloadit:complete`