Assemblies

Processing files is the heart of transloadit. This is why we crafted a simple JSON format that you can use to make transloadit do just about anything with your files.

Step by step Assembly

transloadit's default mode of operation is to take your files through a series of steps, using the result files from the previous steps as the input for the next ones.

Consider this simple assembly that takes a video file, encodes it to 320x240 and stores it in S3:

{ "steps":
  { "encode":
    { "robot": "/video/encode"
    , "width": 320
    , "height": 240
    }
  , "export":
    { "robot": "/s3/store"
    , "bucket": "your-bucket"
    , "key": "your-key"
    , "secret": "your-secret"
    }
  }
}

This assembly consists of two steps: "encode" and "export", but you can name your steps any way you want. Giving them names (instead of numbers), makes it easier to reference them.

Each step is defined as a JSON object that has a "robot" key that tells transloadit which robot to use for this step. Any additional parameters are passed to the robot itself for doing its job.

Parallel Assembly

However, sometimes you might want to do several things at once. For example lets say you would also like to extract thumbnails from your video:

{ "steps":
  { "encode":
    { "use": ":original"
    , "robot": "/video/encode"
    , "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"
    }
  }
}

The difference here is that we are telling transloadit to "use" the ":original" file for the "encode" and the "thumbs" step. This causes them both to start at the same time, running in parallel.

The "export" step is setup to "use" the results from the previous two steps as they come in, spawning 1 internal job for each file.

As you can see, it is quite easy to execute advanced instructions using this format.

Special parameters

Special parameters are those that are interpreted by the assembly engine itself. They control order & behavior of your steps.

Notifications

Notifications allow you to give transloadit a url where it will contact you whenever an assembly / request is completed. To use notifications, simply add a notify_url parameter to your params.

For example:

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

All notifications come in as POST requests, with a parameter called transloadit. The response format information below for the details.

Response format

Transloadit uses a single response format for creating and querying assemblies, as well as sending notifications.

Here is a full example of a transloadit response:

{ ok: 'ASSEMBLY_COMPLETED'
, message: 'The assembly was successfully completed.'
, assembly_id: 'bcb0742359b7e79b9956ea35934d2be7'
, assembly_url: 'http://maynard.api2.transloadit.com/assemblies/bcb0742359b7e79b9956ea35934d2be7'
, bytes_received: 92933
, bytes_expected: 92933
, client_agent: 'Mozilla/5.0 (Windows; U; Windows NT 6.0; en-US) AppleWebKit/533.4 (KHTML, like Gecko) Chrome/5.0.375.86 Safari/533.4'
, client_ip: '127.0.0.1'
, client_referer: 'http://www.tvype.com/de/uploads/add'
, start_date: '2010/07/12 16:11:58 GMT'
, upload_duration: 60.5
, execution_duration: 5.3
, fields: {}
, uploads: 
   [ { id: 'ae52b7f8c1b3426e8c29ea0a9daf8306'
     , name: 'straw-apple.jpg'
     , ext: 'jpg'
     , size: 92230
     , mime: 'image/jpeg'
     , type: 'image'
     , field: 'test_file'
     , url: 'http://maynard.tmp.transloadit.com/upload/1324a798a99fce7f5f8289a95a74f02b.jpg'
     , meta: 
        { width: 1024
        , height: 683
        , date_recorded: '2008/08/10 16:52:06'
        , date_file_created: '2008/08/10 16:52:06'
        , date_file_modified: '2010/06/30 22:16:06 GMT'
        , aperture: 5.7
        , exposure_compensation: '+4/3'
        , exposure_mode: 'Auto'
        , exposure_time: '1/30'
        , flash: 'Off, Did not fire'
        , focal_length: '55.0 mm'
        , f_number: 5.6
        , iso: 800
        , light_value: 6.9
        , metering_mode: 'Multi-segment'
        , shutter_speed: '1/32'
        , white_balance: 'Manual'
        , device_name: 'Canon EOS 450D'
        , device_vendor: 'Canon'
        , device_software: null
        , latitude: null
        , longitude: null
        }
     }
   ]
, results: 
   { resize: 
      [ { id: 'd2ce70297aa45a3bb4080e68c165c523'
        , name: 'straw-apple.jpeg'
        , ext: 'jpeg'
        , size: 136682
        , mime: 'image/jpeg'
        , type: 'image'
        , field: 'test_file'
        , url: 'http://example.s3.amazonaws.com/06/24c798b99f3e7f5a8289a95a74f02b/straw-apple.jpg'
        , meta: 
           { width: 700
           , height: 525
           , date_recorded: null
           , date_file_created: null
           , date_file_modified: '2010/06/30 22:16:09 GMT'
           , aperture: null
           , exposure_compensation: null
           , exposure_mode: null
           , exposure_time: null
           , flash: null
           , focal_length: null
           , f_number: null
           , iso: null
           , light_value: null
           , metering_mode: null
           , shutter_speed: null
           , white_balance: null
           , device_name: null
           , device_vendor: null
           , device_software: 'ImageMagick 6.5.1-0 2009-08-27 Q16 OpenMP http://www.imagemagick.org'
           , latitude: null
           , longitude: null
           }
        }
      ]
   }
}

Comments