transloadit 1.2.0 → 2.0.0

data/examples/basic/audio-concat-transcoder.rb

@@ -0,0 +1,40 @@
+class AudioConcatTranscoder < MediaTranscoder
+  require 'transloadit'
+  require_relative 'media-transcoder'
+
+  # in this example a file is encoded as an mp3, id3 tags are added, and it is stored in s3
+  def transcode!(files)
+    concat = transloadit_client.step('concat', '/audio/concat', {
+      preset: 'mp3',
+      use: {
+        steps: files.map.each_with_index do |f, i|
+          { name: ':original', as: "audio_#{i}", fields: "file_#{i}" }
+        end
+      },
+      result: true
+    })
+    store = transloadit_client.step('store', '/s3/store', {
+      key: ENV.fetch('S3_ACCESS_KEY'),
+      secret: ENV.fetch('S3_SECRET_KEY'),
+      bucket: ENV.fetch('S3_BUCKET'),
+      bucket_region: ENV.fetch('S3_REGION'),
+      use: ['concat']
+    })
+    assembly = transloadit_client.assembly(steps: [concat, store])
+    assembly.submit! *open_files(files)
+  end
+
+  def open_files(files)
+    files.map do |f|
+      open(f)
+    end
+  end
+
+  def mp3_metadata
+    meta = { publisher: 'Transloadit', title: '${file.name}' }
+    meta[:album] = 'Transloadit Compilation'
+    meta[:artist] = 'Transloadit'
+    meta[:track] = '1/1'
+    meta
+  end
+end

data/examples/basic/audio-transcoder.rb

@@ -0,0 +1,37 @@
+class AudioTranscoder < MediaTranscoder
+  require 'transloadit'
+  require_relative 'media-transcoder'
+
+  # in this example a file is encoded as an mp3, id3 tags are added, and it is stored in s3
+  def transcode!(file)
+    encode_mp3 = transloadit_client.step('mp3_encode', '/audio/encode', {
+      use: ':original',
+      preset: 'mp3',
+      ffmpeg_stack: 'v2.2.3',
+      result: true
+    })
+    write_metadata = transloadit_client.step('mp3', '/meta/write', {
+      use: 'mp3_encode',
+      ffmpeg_stack: 'v2.2.3',
+      result: true,
+      data_to_write: mp3_metadata
+    })
+    store = transloadit_client.step('store', '/s3/store', {
+      key: ENV.fetch('S3_ACCESS_KEY'),
+      secret: ENV.fetch('S3_SECRET_KEY'),
+      bucket: ENV.fetch('S3_BUCKET'),
+      bucket_region: ENV.fetch('S3_REGION'),
+      use: ['mp3']
+    })
+    assembly = transloadit_client.assembly(steps: [encode_mp3, write_metadata, store])
+    assembly.submit! open(file)
+  end
+
+  def mp3_metadata
+    meta = { publisher: 'Transloadit', title: '${file.name}' }
+    meta[:album] = 'Transloadit Compilation'
+    meta[:artist] = 'Transloadit'
+    meta[:track] = '1/1'
+    meta
+  end
+end

data/examples/basic/image-transcoder.rb

@@ -0,0 +1,27 @@
+class ImageTranscoder < MediaTranscoder
+  require 'transloadit'
+  require_relative 'media-transcoder'
+
+  # in this example a file is submitted, optimized, and then stored in s3
+  def transcode!(file)
+    optimize = transloadit_client.step('image', '/image/optimize', {
+      progressive: true,
+      use: ':original',
+      result: true
+    })
+    store = transloadit_client.step('store', '/s3/store', {
+      key: ENV.fetch('S3_ACCESS_KEY'),
+      secret: ENV.fetch('S3_SECRET_KEY'),
+      bucket: ENV.fetch('S3_BUCKET'),
+      bucket_region: ENV.fetch('S3_REGION'),
+      use: 'image'
+    })
+    assembly = transloadit_client.assembly(steps: [optimize, store])
+    assembly.submit! open(file)
+  end
+
+  def get_status!(assembly_id)
+    req = Transloadit::Request.new('/assemblies/' + assembly_id.to_s, ENV.fetch('TRANSLOADIT_SECRET'))
+    req.get.extend!(Transloadit::Response::Assembly)
+  end
+end

data/examples/basic/main.rb

@@ -0,0 +1,69 @@
+require 'open-uri'
+require_relative 'media-transcoder'
+require_relative 'image-transcoder'
+require_relative 'audio-transcoder'
+require_relative 'audio-concat-transcoder'
+
+p 'starting image transcoding job...'
+p 'fetching image from the cat api...'
+
+open('http://thecatapi.com/api/images/get') do |f|
+  p 'starting transcoding job...'
+  image_transcoder = ImageTranscoder.new
+  response = image_transcoder.transcode!(f)
+
+  # if you are using rails one thing you can do would be to start an ActiveJob process that recursively
+  # checks on the status of the assembly until it is finished
+  while !response.finished?
+    sleep 1
+    p 'checking job status...'
+    response = image_transcoder.get_status!(response[:assembly_id])
+  end
+  p response[:message]
+  p response[:results]['image'][0]['url']
+end
+
+p 'starting audio transcoding job...'
+p 'fetching soundbite from nasa...'
+p "\n"
+
+open('http://www.nasa.gov/640379main_Computers_are_in_Control.m4r') do |f|
+  p 'starting transcoding job...'
+  audio_transcoder = AudioTranscoder.new
+  response = audio_transcoder.transcode!(f)
+
+  # if you are using rails one thing you can do would be to start an ActiveJob process that recursively
+  # checks on the status of the assembly until it is finished
+  while !response.finished?
+    sleep 1
+    p 'checking job status...'
+    response = audio_transcoder.get_status!(response[:assembly_id])
+  end
+  p response[:message]
+  p response[:results]['mp3'][0]['url']
+  p "\n"
+end
+
+p 'starting audio concat transcoding job...'
+p 'fetching 3 soundbites from nasa...'
+
+files = [
+  'http://www.nasa.gov/mp3/640148main_APU%20Shutdown.mp3',
+  'http://www.nasa.gov/mp3/640164main_Go%20for%20Deploy.mp3',
+  'http://www.nasa.gov/mp3/640165main_Lookin%20At%20It.mp3'
+]
+
+p 'starting transcoding job...'
+audio_concat_transcoder = AudioConcatTranscoder.new
+response = audio_concat_transcoder.transcode!(files)
+
+# if you are using rails one thing you can do would be to start an ActiveJob process that recursively
+# checks on the status of the assembly until it is finished
+while !response.finished?
+  sleep 1
+  p 'checking job status...'
+  response = audio_concat_transcoder.get_status!(response[:assembly_id])
+end
+p response[:message]
+p response[:results]['concat'][0]['url']
+p "\n"

data/examples/basic/media-transcoder.rb

@@ -0,0 +1,13 @@
+class MediaTranscoder
+  def transloadit_client
+    @transloadit ||= Transloadit.new({
+      key: ENV.fetch('TRANSLOADIT_KEY'),
+      secret: ENV.fetch('TRANSLOADIT_SECRET')
+    })
+  end
+
+  def get_status!(assembly_id)
+    req = Transloadit::Request.new('/assemblies/' + assembly_id.to_s, ENV.fetch('TRANSLOADIT_SECRET'))
+    req.get.extend!(Transloadit::Response::Assembly)
+  end
+end

data/lib/transloadit.rb

@@ -1,14 +1,18 @@
 require 'multi_json'
+require 'date'
 
 #
 # Implements the Transloadit REST API in Ruby. Check the {file:README.md README}
 # for usage instructions.
 #
 class Transloadit
+  autoload :ApiModel, 'transloadit/api_model'
   autoload :Assembly, 'transloadit/assembly'
+  autoload :Exception, 'transloadit/exception'
   autoload :Request,  'transloadit/request'
   autoload :Response, 'transloadit/response'
   autoload :Step,     'transloadit/step'
+  autoload :Template, 'transloadit/template'
   autoload :VERSION,  'transloadit/version'
 
   # @return [String] your Transloadit auth key
@@ -75,6 +79,33 @@ class Transloadit
     Transloadit::Assembly.new(self, options)
   end
 
+  #
+  # Creates a Transloadit::Template instance ready to interact with its corresponding REST API.
+  #
+  # See the Transloadit {documentation}[https://transloadit.com/docs/api-docs/#template-api]
+  # for futher information on Templates and available endpoints.
+  #
+  def template(options = {})
+    Transloadit::Template.new(self, options)
+  end
+
+  #
+  # Gets user billing reports for specified month and year.
+  # Defaults to current month or year if corresponding param is not specified.
+  #
+  # @param [Integer] month the month for which billing reports should be retrieved.
+  #   defaults to current month if not specified.
+  # @param [Integer] year the year for which billing reports should be retrieved.
+  #   defaults to current year if not specified.
+  #
+  def bill(month = Date.today.month, year = Date.today.year)
+    # convert month to 2 digit format
+    month = format '%02d', month
+    path = "bill/#{year}-#{month}"
+
+    Transloadit::Request.new(path, self.secret).get({ :auth => self.to_hash })
+  end
+
   #
   # @return [String] a human-readable version of the Transloadit.
   #

data/lib/transloadit/api_model.rb

@@ -0,0 +1,73 @@
+require 'transloadit'
+
+#
+# Represents an API class that more Transloadit specific API classes
+# would inherit from.
+#
+class Transloadit::ApiModel
+  # @return [Transloadit] the associated Transloadit instance
+  attr_reader :transloadit
+
+  # @return [Hash] the options describing the Assembly
+  attr_accessor :options
+
+  #
+  # Creates a new API instance authenticated using the given +transloadit+
+  # instance.
+  #
+  # @param [Transloadit] transloadit the associated Transloadit instance
+  # @param [Hash]        options     the configuration for the API;
+  #
+  def initialize(transloadit, options = {})
+    self.transloadit = transloadit
+    self.options     = options
+  end
+
+  #
+  # @return [String] a human-readable version of the API
+  #
+  def inspect
+    self.to_hash.inspect
+  end
+
+  #
+  # @return [Hash] a Transloadit-compatible Hash of the API's contents
+  #
+  def to_hash
+    self.options.merge(
+      :auth  => self.transloadit.to_hash,
+    ).delete_if {|_,v| v.nil?}
+  end
+
+  #
+  # @return [String] JSON-encoded String containing the API's contents
+  #
+  def to_json
+    MultiJson.dump(self.to_hash)
+  end
+
+  protected
+
+  attr_writer :transloadit
+
+  private
+
+  #
+  # Performs http request in favour of it's caller
+  #
+  # @param [String]     path      url path to which request is made
+  # @param [Hash]       params    POST/GET data to submit with the request
+  # @param [String]     method    http request method. This could be 'post' or 'get'
+  # @param [Hash]       extra_params   additional POST/GET data to submit with the request
+  #
+  # @return [Transloadit::Response] the response
+  #
+  def _do_request(path, params = nil, method = 'get', extra_params = nil)
+    if !params.nil?
+      params = self.to_hash.update(params)
+      params = { :params => params } if ['post', 'put', 'delete'].include? method
+      params.merge!(extra_params) if !extra_params.nil?
+    end
+    Transloadit::Request.new(path, self.transloadit.secret).public_send(method, params)
+  end
+end

data/lib/transloadit/assembly.rb

@@ -1,34 +1,13 @@
 require 'transloadit'
 
 #
-# Represents a Assembly ready to be sent to the REST API for processing. An
-# Assembly can contain one or more Steps for processing or point to a
-# server-side template. It's submitted along with a list of files to process,
-# at which point Transloadit will process and store the files according to the
-# rules in the Assembly.
+# Represents an Assembly API ready to make calls to the REST API endpoints.
 #
-# See the Transloadit {documentation}[http://transloadit.com/docs/building-assembly-instructions]
-# for futher information on Assemblies and their parameters.
+# See the Transloadit {documentation}[https://transloadit.com/docs/api-docs/#assembly-api]
+# for futher information on Assemblies and available endpoints.
 #
-class Transloadit::Assembly
-  # @return [Transloadit] the associated Transloadit instance
-  attr_reader   :transloadit
-
-  # @return [Hash] the options describing the Assembly
-  attr_accessor :options
-
-  #
-  # Creates a new Assembly authenticated using the given +transloadit+
-  # instance.
-  #
-  # @param [Transloadit] transloadit the associated Transloadit instance
-  # @param [Hash]        options     the configuration for the Assembly;
-  #   see {Transloadit#assembly}
-  #
-  def initialize(transloadit, options = {})
-    self.transloadit = transloadit
-    self.options     = options
-  end
+class Transloadit::Assembly < Transloadit::ApiModel
+  DEFAULT_TRIES = 3
 
   #
   # @return [Hash] the processing steps, formatted for sending to Transloadit
@@ -38,41 +17,106 @@ class Transloadit::Assembly
   end
 
   #
-  # Submits the assembly for processing. Accepts as many IO objects as you
-  # wish to process in the assembly. The last argument is an optional Hash
+  # Creates a Transloadit::Assembly and sends to the REST API. An
+  # Assembly can contain one or more Steps for processing or point to a
+  # server-side template. It's submitted along with a list of files to process,
+  # at which point Transloadit will process and store the files according to the
+  # rules in the Assembly.
+  # See the Transloadit {documentation}[http://transloadit.com/docs/building-assembly-instructions]
+  # for futher information on Assemblies and their parameters.
+  #
+  # Accepts as many IO objects as you wish to process in the assembly.
+  # The last argument is an optional Hash
   # of parameters to send along with the request.
   #
-  # @overload submit!(*ios)
+  # @overload create!(*ios)
   #   @param [Array<IO>] *ios   the files for the assembly to process
   #
-  # @overload submit!(*ios, params = {})
+  # @overload create!(*ios, params = {})
   #   @param [Array<IO>] *ios   the files for the assembly to process
-  #   @param [Hash]      params additional POST data to submit with the request
+  #   @param [Hash]      params additional POST data to submit with the request;
+  #     for a full list of parameters, see the official documentation
+  #     on {templates}[http://transloadit.com/docs/templates].
+  #   @option params [Step, Array<Step>] :steps the steps to perform in this
+  #     assembly
+  #   @option params [String] :notify_url A URL to be POSTed when the assembly
+  #     has finished processing
+  #   @option params [String] :template_id the ID of a
+  #     {template}[https://transloadit.com/templates] to use instead of
+  #     specifying params here directly
+  #
+  def create!(*ios, **params)
+    params[:steps] = _wrap_steps_in_hash(params[:steps]) if !params[:steps].nil?
+
+    extra_params = {}
+    extra_params.merge!(self.options[:fields]) if self.options[:fields]
+
+    trials = self.options[:tries] || DEFAULT_TRIES
+    (1..trials).each do |trial|
+      # update the payload with file entries
+      ios.each_with_index {|f, i| extra_params.update :"file_#{i}" => f }
+
+      response = _do_request(
+        '/assemblies',params,'post', extra_params
+      ).extend!(Transloadit::Response::Assembly)
+
+      return response unless response.rate_limit?
+
+      _handle_rate_limit!(response, ios, trial < trials)
+    end
+  end
+
+  #
+  # alias for create!
+  # keeping this method for backward compatibility
   #
   def submit!(*ios)
-    params  = _extract_options!(ios)
-    payload = { :params => self.to_hash.update(params) }
-    payload.merge!(self.options[:fields]) if self.options[:fields]
+    warn "#{caller(1)[0]}: warning: Transloadit::Assembly#submit!"\
+      " is deprecated. use Transloadit::Assembly#create! instead"
+    self.create!(*ios)
+  end
 
-    # update the payload with file entries
-    ios.each_with_index {|f, i| payload.update :"file_#{i}" => f }
+  #
+  # Returns a list of all assemblies
+  # @param [Hash]        additional GET data to submit with the request
+  #
+  def list(params = {})
+    _do_request('/assemblies', params)
+  end
 
-    # find a bored instance
-    Transloadit::Request.bored!
+  #
+  # Returns a single assembly object specified by the assembly id
+  # @param [String]     id    id of the desired assembly
+  #
+  def get(id)
+    _do_request("/assemblies/#{id}").extend!(Transloadit::Response::Assembly)
+  end
 
-    # create the request
-    request = Transloadit::Request.new '/assemblies',
-      self.transloadit.secret
+  #
+  # Replays an assembly specified by the  id
+  # @param [String]   id       id of the desired assembly
+  # @param [Hash]     params   additional POST data to submit with the request
+  #
+  def replay(id, params = {})
+    params.merge!({ :wait => false })
+    _do_request("/assemblies/#{id}/replay", params, 'post').extend!(Transloadit::Response::Assembly)
+  end
 
-    # post the request, extend it with the Assembly extensions
-    request.post(payload).extend!(Transloadit::Response::Assembly)
+  #
+  # Returns all assembly notifications
+  # @param [Hash]        params    additional GET data to submit with the request
+  #
+  def get_notifications(params = {})
+    _do_request "/assembly_notifications", params
   end
 
   #
-  # @return [String] a human-readable version of the Assembly
+  # Replays an assembly notification by the  id
+  # @param [String]      id         id of the desired assembly
+  # @param [Hash]        params     additional POST data to submit with the request
   #
-  def inspect
-    self.to_hash.inspect
+  def replay_notification(id, params = {})
+    _do_request("/assembly_notifications/#{id}/replay", params, 'post')
   end
 
   #
@@ -85,17 +129,6 @@ class Transloadit::Assembly
     ).delete_if {|k,v| v.nil?}
   end
 
-  #
-  # @return [String] JSON-encoded String containing the Assembly's contents
-  #
-  def to_json
-    MultiJson.dump(self.to_hash)
-  end
-
-  protected
-
-  attr_writer :transloadit
-
   private
 
   #
@@ -116,13 +149,20 @@ class Transloadit::Assembly
   end
 
   #
-  # Extracts the last argument from a set of arguments if it's a hash.
-  # Otherwise, returns an empty hash.
+  # Stays idle for certain time and then reopens assembly files for reprocessing.
+  # Should be called when assembly rate limit is reached.
   #
-  # @param  *args  the arguments to search for an options hash
-  # @return [Hash] the options passed, otherwise an empty hash
+  # @param  [Response] response  assembly response that comes with a rate limit
+  # @param [Array<IO>] ios the files sent for the assembly to process.
   #
-  def _extract_options!(args)
-    args.last.is_a?(Hash) ? args.pop : {}
+  def _handle_rate_limit!(response, ios, is_retrying)
+    if is_retrying
+      warn "Rate limit reached. Waiting for #{response.wait_time} seconds before retrying."
+      sleep response.wait_time
+      # RestClient closes file streams at the end of a request.
+      ios.collect! {|file| open file.path }
+    else
+      raise Transloadit::Exception::RateLimitReached.new(response)
+    end
   end
 end