{"id":20159530,"url":"https://github.com/transloadit/ruby-sdk","last_synced_at":"2025-04-04T11:11:47.603Z","repository":{"id":1325900,"uuid":"1271346","full_name":"transloadit/ruby-sdk","owner":"transloadit","description":"Transloadit's official Ruby SDK, maintained by the community","archived":false,"fork":false,"pushed_at":"2024-12-05T12:18:48.000Z","size":1600,"stargazers_count":28,"open_issues_count":0,"forks_count":21,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-28T10:06:26.059Z","etag":null,"topics":["encoding","ruby","transloadit","uploading"],"latest_commit_sha":null,"homepage":"https://transloadit.com/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/transloadit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-01-19T16:04:28.000Z","updated_at":"2024-12-05T12:18:52.000Z","dependencies_parsed_at":"2024-03-01T12:25:52.366Z","dependency_job_id":"a3013ba9-4339-4a5f-aa70-b63e779a9737","html_url":"https://github.com/transloadit/ruby-sdk","commit_stats":{"total_commits":281,"total_committers":17,"mean_commits":"16.529411764705884","dds":0.6512455516014235,"last_synced_commit":"a7d3d5d1c87b95e31a16f006cdd05020ff27e492"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transloadit%2Fruby-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transloadit%2Fruby-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transloadit%2Fruby-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transloadit%2Fruby-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/transloadit","download_url":"https://codeload.github.com/transloadit/ruby-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247166168,"owners_count":20894654,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["encoding","ruby","transloadit","uploading"],"created_at":"2024-11-14T00:08:45.460Z","updated_at":"2025-04-04T11:11:47.587Z","avatar_url":"https://github.com/transloadit.png","language":"Ruby","readme":"[![Build Status](https://github.com/transloadit/ruby-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/transloadit/ruby-sdk/actions/workflows/ci.yml)\n[![Coverage](https://codecov.io/gh/transloadit/ruby-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/transloadit/ruby-sdk)\n\n# Transloadit Ruby SDK\n\nA **Ruby** Integration for [Transloadit](https://transloadit.com)'s file uploading and encoding service\n\n## Intro\n\n[Transloadit](https://transloadit.com) 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](https://transloadit.com) is the Swiss Army Knife for your files.\n\nThis is a **Ruby** SDK to make it easy to talk to the [Transloadit](https://transloadit.com) REST API.\n\n_If you run Ruby on Rails and are looking to integrate with the browser for file uploads, checkout the [rails-sdk](https://github.com/transloadit/rails-sdk)._\n\n## Install\n\n```bash\ngem install transloadit\n```\n\n## Usage\n\nTo get started, you need to require the 'transloadit' gem:\n\n```bash\n$ irb -rubygems\n\u003e\u003e require 'transloadit'\n=\u003e true\n```\n\nThen create a Transloadit instance, which will maintain your\n[authentication credentials](https://transloadit.com/accounts/credentials)\nand allow us to make requests to [the API](https://transloadit.com/docs/api/).\n\n```ruby\ntransloadit = Transloadit.new(\n  :key    =\u003e 'MY_TRANSLOADIT_KEY',\n  :secret =\u003e 'MY_TRANSLOADIT_SECRET'\n)\n```\n\n### 1. Resize and store an image\n\nThis example demonstrates how you can create an \u003cdfn\u003eAssembly\u003c/dfn\u003e to resize an image\nand store the result on [Amazon S3](https://aws.amazon.com/s3/).\n\n```ruby\nrequire 'transloadit'\n\ntransloadit = Transloadit.new(\n  :key    =\u003e 'MY_TRANSLOADIT_KEY',\n  :secret =\u003e 'MY_TRANSLOADIT_SECRET'\n)\n\n# First, we create two steps: one to resize the image to 320x240, and another to\n# store the image in our S3 bucket.\nresize = transloadit.step 'resize', '/image/resize',\n  :width  =\u003e 320,\n  :height =\u003e 240\n\nstore  = transloadit.step 'store', '/s3/store',\n  :key    =\u003e 'MY_AWS_KEY',\n  :secret =\u003e 'MY_AWS_SECRET',\n  :bucket =\u003e 'MY_S3_BUCKET'\n\n# Now that we have the steps, we create an assembly (which is just a request to\n# process a file or set of files) and let Transloadit do the rest.\nassembly = transloadit.assembly(\n  :steps =\u003e [ resize, store ]\n)\n\nresponse = assembly.create! open('/PATH/TO/FILE.jpg')\n\n# reloads the response once per second until all processing is finished\nresponse.reload_until_finished!\n\nif response.error?\n  # handle error\nelse\n  # handle other cases\n  puts response\nend\n```\n\n\u003cdiv class=\"alert alert-note\"\u003e\n  \u003cstrong\u003eNote:\u003c/strong\u003e The \u003cdfn\u003eAssembly\u003c/dfn\u003e method \u003ccode\u003esubmit!\u003c/code\u003e has been deprecated and replaced with \u003ccode\u003ecreate!\u003c/code\u003e.\n  The \u003ccode\u003esubmit!\u003c/code\u003e method remains as an alias of \u003ccode\u003ecreate!\u003c/code\u003e for backward Compatibility.\n\u003c/div\u003e\n\nWhen the `create!` method returns, the file has been uploaded but may not yet\nbe done processing. We can use the returned object to check if processing has\ncompleted, or examine other attributes of the request.\n\n```ruby\n# returns the unique API ID of the assembly\nresponse[:assembly_id] # =\u003e '9bd733a...'\n\n# returns the API URL endpoint for the assembly\nresponse[:assembly_ssl_url] # =\u003e 'https://api2.vivian.transloadit.com/assemblies/9bd733a...'\n\n# checks how many bytes were expected / received by transloadit\nresponse[:bytes_expected] # =\u003e 92933\nresponse[:bytes_received] # =\u003e 92933\n\n# checks if all processing has been finished\nresponse.finished? # =\u003e false\n\n# cancels further processing on the assembly\nresponse.cancel! # =\u003e true\n\n# checks if processing was successfully completed\nresponse.completed? # =\u003e true\n\n# checks if the processing returned with an error\nresponse.error? # =\u003e false\n```\n\nIt's important to note that none of these queries are \"live\" (with the\nexception of the `cancel!` method). They all check the response given by the\nAPI at the time the \u003cdfn\u003eAssembly\u003c/dfn\u003e was created. You have to explicitly ask the\n\u003cdfn\u003eAssembly\u003c/dfn\u003e to reload its results from the API.\n\n```ruby\n# reloads the response's contents from the REST API\nresponse.reload!\n\n# reloads once per second until all processing is finished, up to number of\n# times specified in :tries option, otherwise will raise ReloadLimitReached\nresponse.reload_until_finished! tries: 300 # default is 600\n```\n\nIn general, you use hash accessor syntax to query any direct attribute from\nthe [response](https://transloadit.com/docs/api/#assembly-status-response).\nMethods suffixed by a question mark provide a more readable way of querying\nstate (e.g., `assembly.completed?` vs. checking the result of\n`assembly[:ok]`). Methods suffixed by a bang make a live query against the\nTransloadit HTTP API.\n\n### 2. Uploading multiple files\n\nMultiple files can be given to the `create!` method in order to upload more\nthan one file in the same request. You can also pass a single \u003cdfn\u003eStep\u003c/dfn\u003e for the\n`steps` parameter, without having to wrap it in an Array.\n\n```ruby\nrequire 'transloadit'\n\ntransloadit = Transloadit.new(\n  :key    =\u003e 'MY_TRANSLOADIT_KEY',\n  :secret =\u003e 'MY_TRANSLOADIT_SECRET'\n)\n\nassembly = transloadit.assembly(steps: store)\n\nresponse = assembly.create!(\n  open('puppies.jpg'),\n  open('kittens.jpg'),\n  open('ferrets.jpg')\n)\n```\n\nYou can also pass an array of files to the `create!` method.\nJust unpack the array using the splat `*` operator.\n\n```ruby\nfiles = [open('puppies.jpg'), open('kittens.jpg'), open('ferrets.jpg')]\nresponse = assembly.create! *files\n```\n\n### 3. Parallel Assembly\n\nTransloadit allows you to perform several processing steps in parallel. You\nsimply need to `use` other \u003cdfn\u003eSteps\u003c/dfn\u003e. Following\n[their example](https://transloadit.com/docs/#special-parameters):\n\n```ruby\nrequire 'transloadit'\n\ntransloadit = Transloadit.new(\n  :key    =\u003e 'MY_TRANSLOADIT_KEY',\n  :secret =\u003e 'MY_TRANSLOADIT_SECRET'\n)\n\nencode = transloadit.step 'encode', '/video/encode', { ... }\nthumbs = transloadit.step 'thumbs', '/video/thumbs', { ... }\nexport = transloadit.step 'store',  '/s3/store',     { ... }\n\nexport.use [ encode, thumbs ]\n\ntransloadit.assembly(\n  :steps =\u003e [ encode, thumbs, export ]\n).create! open('/PATH/TO/FILE.mpg')\n```\n\nYou can also tell a step to use the original uploaded file by passing the\nSymbol `:original` instead of another step.\n\nCheck the YARD documentation for more information on using\n[use](https://rubydoc.info/gems/transloadit/frames/Transloadit/Step#use-instance_method).\n\n### 4. Creating an Assembly with Templates\n\nTransloadit allows you to use custom [templates](https://github.com/transloadit/ruby-sdk/blob/main/README.md#8-templates)\nfor recurring encoding tasks. In order to use these do the following:\n\n```ruby\nrequire 'transloadit'\n\ntransloadit = Transloadit.new(\n  :key    =\u003e 'MY_TRANSLOADIT_KEY',\n  :secret =\u003e 'MY_TRANSLOADIT_SECRET'\n)\n\ntransloadit.assembly(\n  :template_id =\u003e 'MY_TEMPLATE_ID'\n).create! open('/PATH/TO/FILE.mpg')\n```\n\nYou can use your steps together with this template and even use variables.\nThe [Transloadit documentation](https://transloadit.com/docs/#passing-variables-into-a-template)\nhas some nice examples for that.\n\n### 5. Using fields\n\nTransloadit allows you to submit form field values that you'll get back in the\nnotification. This is quite handy if you want to add additional custom metadata\nto the upload itself. You can use fields like the following:\n\n```ruby\nrequire 'transloadit'\n\ntransloadit = Transloadit.new(\n  :key    =\u003e 'MY_TRANSLOADIT_KEY',\n  :secret =\u003e 'MY_TRANSLOADIT_SECRET'\n)\n\ntransloadit.assembly(\n  :fields =\u003e {\n    :tag =\u003e 'some_tag_name',\n    :field_name =\u003e 'field_value'\n  }\n).create! open('/PATH/TO/FILE.mpg')\n```\n\n### 6. Notify URL\n\nIf you want to be notified when the processing is finished you can provide\na Notify URL for the \u003cdfn\u003eAssembly\u003c/dfn\u003e.\n\n```ruby\nrequire 'transloadit'\n\ntransloadit = Transloadit.new(\n  :key    =\u003e 'MY_TRANSLOADIT_KEY',\n  :secret =\u003e 'MY_TRANSLOADIT_SECRET'\n)\n\ntransloadit.assembly(\n  :notify_url =\u003e 'https://example.com/processing_finished'\n).create! open('/PATH/TO/FILE.mpg')\n```\n\nRead up more on the \u003cdfn\u003eNotifications\u003c/dfn\u003e [on Transloadit's documentation page](https://transloadit.com/docs/#notifications)\n\n### 7. Other Assembly methods\n\nTransloadit also provides methods to retrieve/replay \u003cdfn\u003eAssemblies\u003c/dfn\u003e and their \u003cdfn\u003eNotifications\u003c/dfn\u003e.\n\n```ruby\nrequire 'transloadit'\n\ntransloadit = Transloadit.new(\n  :key    =\u003e 'MY_TRANSLOADIT_KEY',\n  :secret =\u003e 'MY_TRANSLOADIT_SECRET'\n)\n\nassembly = transloadit.assembly\n\n# returns a list of all assemblies\nassembly.list\n\n# returns a specific assembly\nassembly.get 'MY_ASSEMBLY_ID'\n\n# replays a specific assembly\nresponse = assembly.replay 'MY_ASSEMBLY_ID'\n# should return true if assembly is replaying and false otherwise.\nresponse.replaying?\n\n# returns all assembly notifications\nassembly.get_notifications\n\n# replays an assembly notification\nassembly.replay_notification 'MY_ASSEMBLY_ID'\n```\n\n### 8. Templates\n\nTransloadit provides a [templates api](https://transloadit.com/docs/#templates)\nfor recurring encoding tasks. Here's how you would create a \u003cdfn\u003eTemplate\u003c/dfn\u003e:\n\n```ruby\nrequire 'transloadit'\n\ntransloadit = Transloadit.new(\n  :key    =\u003e 'MY_TRANSLOADIT_KEY',\n  :secret =\u003e 'MY_TRANSLOADIT_SECRET'\n)\n\ntemplate = transloadit.template\n\n# creates a new template\ntemplate.create(\n  :name =\u003e 'TEMPLATE_NAME',\n  :template =\u003e {\n    \"steps\": {\n      \"encode\": {\n        \"use\": \":original\",\n        \"robot\": \"/video/encode\",\n        \"result\": true\n      }\n    }\n  }\n)\n```\n\nThere are also some other methods to retrieve, update and delete a \u003cdfn\u003eTemplate\u003c/dfn\u003e.\n\n```ruby\nrequire 'transloadit'\n\ntransloadit = Transloadit.new(\n  :key    =\u003e 'MY_TRANSLOADIT_KEY',\n  :secret =\u003e 'MY_TRANSLOADIT_SECRET'\n)\n\ntemplate = transloadit.template\n\n# returns a list of all templates.\ntemplate.list\n\n# returns a specific template.\ntemplate.get 'MY_TEMPLATE_ID'\n\n# updates the template whose id is specified.\ntemplate.update(\n  'MY_TEMPLATE_ID',\n  :name =\u003e 'CHANGED_TEMPLATE_NAME',\n  :template =\u003e {\n    :steps =\u003e {\n      :encode =\u003e {\n        :use =\u003e ':original',\n        :robot =\u003e '/video/merge'\n      }\n    }\n  }\n)\n\n# deletes a specific template\ntemplate.delete 'MY_TEMPLATE_ID'\n```\n\n### 9. Getting Bill reports\n\nIf you want to retrieve your Transloadit account billing report for a particular month and year\nyou can use the `bill` method passing the required month and year like the following:\n\n```ruby\nrequire 'transloadit'\n\ntransloadit = Transloadit.new(\n  :key    =\u003e 'MY_TRANSLOADIT_KEY',\n  :secret =\u003e 'MY_TRANSLOADIT_SECRET'\n)\n\n# returns bill report for February, 2016.\ntransloadit.bill(2, 2016)\n```\n\nNot specifying the `month` or `year` would default to the current month or year.\n\n### 10. Signing Smart CDN URLs\n\nYou can generate signed [Smart CDN](https://transloadit.com/services/content-delivery/) URLs using your Transloadit instance:\n\n```ruby\nrequire 'transloadit'\n\ntransloadit = Transloadit.new(\n  :key    =\u003e 'MY_TRANSLOADIT_KEY',\n  :secret =\u003e 'MY_TRANSLOADIT_SECRET'\n)\n\n# Generate a signed URL using instance credentials\nurl = transloadit.signed_smart_cdn_url(\n  workspace: \"MY_WORKSPACE\",\n  template: \"MY_TEMPLATE\",\n  input: \"avatars/jane.jpg\"\n)\n\n# Add URL parameters\nurl = transloadit.signed_smart_cdn_url(\n  workspace: \"MY_WORKSPACE\",\n  template: \"MY_TEMPLATE\",\n  input: \"avatars/jane.jpg\",\n  url_params: {\n    width: 100,\n    height: 200\n  }\n)\n\n# Set expiration time\nurl = transloadit.signed_smart_cdn_url(\n  workspace: \"MY_WORKSPACE\",\n  template: \"MY_TEMPLATE\",\n  input: \"avatars/jane.jpg\",\n  expire_at_ms: 1732550672867  # Specific timestamp\n)\n```\n\nThe generated URL will be signed using your Transloadit credentials and can be used to access files through the Smart CDN in a secure manner.\n\n### 11. Rate limits\n\nTransloadit enforces rate limits to guarantee that no customers are adversely affected by the usage\nof any given customer. See [Rate Limiting](https://transloadit.com/docs/api/#rate-limiting).\n\nWhile creating an \u003cdfn\u003eAssembly\u003c/dfn\u003e, 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.\n\nTo change the number of attempts that will be made when creating an \u003cdfn\u003eAssembly\u003c/dfn\u003e, you may pass the `tries` option to your \u003cdfn\u003eAssembly\u003c/dfn\u003e like so.\n\n```ruby\nrequire 'transloadit'\n\ntransloadit = Transloadit.new(\n  :key    =\u003e 'MY_TRANSLOADIT_KEY',\n  :secret =\u003e 'MY_TRANSLOADIT_SECRET'\n)\n\n# would make one extra attempt after a failed attempt.\ntransloadit.assembly(:tries =\u003e 2).create! open('/PATH/TO/FILE.mpg')\n\n# Would make no attempt at all. Your request would not be sent.\ntransloadit.assembly(:tries =\u003e 0).create! open('/PATH/TO/FILE.mpg')\n```\n\n## Example\n\nA small sample tutorials of using the Transloadit Ruby SDK to optimize an image, encode MP3 audio, add ID3 tags,\nand more can be found [here](https://github.com/transloadit/ruby-sdk/tree/main/examples).\n\n## Documentation\n\nUp-to-date YARD documentation is automatically generated. You can view the\ndocs for the \u003ca href=\"https://rubydoc.info/gems/transloadit/frames\" rel=\"canonical\"\u003ereleased gem\u003c/a\u003e or\nfor the latest [git main](https://rubydoc.info/github/transloadit/ruby-sdk/main/frames).\n\n## Compatibility\n\nPlease see [ci.yml](https://github.com/transloadit/ruby-sdk/tree/main/.github/workflows/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\n[bug report](https://github.com/transloadit/ruby-sdk/issues). Compatibility patches for other Rubies are welcome.\n\n### Ruby 2.x\n\nIf you still need support for Ruby 2.x, 2.0.1 is the last version that supports it.\n\n## Contributing\n\nContributions are welcome!\n\n### Running tests\n\n```bash\nbundle install\nbundle exec rake test\n```\n\nTo also test parity against the Node.js reference implementation, run:\n\n```bash\nTEST_NODE_PARITY=1 bundle exec rake test\n```\n\nTo disable coverage reporting, run:\n\n```bash\nCOVERAGE=0 bundle exec rake test\n```\n\n### Releasing on RubyGems\n\nLet's say you wanted to release version `3.1.0`, here are the steps:\n\n1. Update the version number in the version file `version.rb` and `CHANGELOG.md`\n2. Commit: `git add CHANGELOG.md lib/transloadit/version.rb \u0026\u0026 git commit -m \"Release 3.1.0\"`\n3. Create a git tag: `git tag -a v3.1.0 -m \"Release 3.1.0\"`\n4. Push the git tag: `git push origin v3.1.0`\n5. Release on RubyGems: `gem build transloadit.gemspec \u0026\u0026 gem push transloadit-3.1.0.gem`\n6. Draft a release [here](https://github.com/transloadit/ruby-sdk/releases). Click the `v3.1.0` tag and click `Generate release notes`. Inspect and Publish.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransloadit%2Fruby-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftransloadit%2Fruby-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransloadit%2Fruby-sdk/lists"}