goncalossilva-kaltura_fu 0.2.0

data/lib/kaltura_fu/entry.rb

@@ -0,0 +1,107 @@
+module KalturaFu
+  
+  ##
+  # The entry module provides a slightly more intuitive interface to the
+  # Kaltura media service.  It determines what retrieval and setting actions 
+  # you can perform based upon the version of the Kaltura-Ruby library using 
+  # reflection.  This allows Kaltura_Fu to be a bit more future proof than the 
+  # Kaltura API client itself!   The tradeoff is that getting/adding/setting 
+  # attributes are defined dynamically.  The current behavior is that the first
+  # call to a dynamic method will then define all of Kaltura's media entries 
+  # methods.  This allows the module to be slightly lighter weight in the event
+  # that it is included in a class but never used, and faster than using method_missing
+  # lookups for 100% of the dynamic methods.  The first call will be slower though,
+  # as it generates numerous other methods.
+  # 
+  # == Usage
+  # The entry module is intended to be used to link Rails Models to Kaltura MediaEntry's.  
+  # However, you should not perform these actions during a web application request.  Doing
+  # so will slow down your request unecessarily.  There is nearly nothing gained from adding a
+  # round trip to your Kaltura server to make an update synchronus.  Instead, this module
+  # should mostly be used in processing a background request from an observer.  
+  #
+  # == Uploading to Kaltura
+  # The entry module provides convienance to uploading directly to your installation of 
+  # Kaltura.  For your web application, there are two Kaltura flash widgets that perform
+  # a much better job of uploading files though.  This functionality has been used in 
+  # production environments that use lecture capture.  A video file is placed in a folder, 
+  # a script picks the file up, and then uploads it into Kaltura.
+  #
+  # The Kaltura API supports uploading media from files, URL's, and also has a batch action.  
+  # The implementation of Kaltura Fu currently ignores the URL and batch methods, instead 
+  # focusing on file uploading.
+  #
+  # @example A basic file upload example:
+  #   media_file = File.new("/path/to/video.mp4")
+  #   upload(media_file,:source => :file)
+  #
+  # @example A file upload with metadata fields populated:
+  #   media_file = File.new("/path/to/video.mp4")
+  #   upload(media_file, :source => :file,
+  #     :name => "My Rad video",
+  #     :description => "I'm capable of such rad things.",
+  #     :tags => "rad,rowdy,video,h.264",
+  #     :categories => "raditude"
+  #   )
+  # == Getting, Setting, and Adding Metadata
+  # The entry module provides an easy mean to retrieve the current state and modify a Kaltura entry.
+  # For metadata fields that act as a list of objects, it also provides an easy way to append values
+  # onto the list.  It uses get_ and set_ instead of the more common Ruby practice of using just the 
+  # attribute and attribute= so that you can include this module in your model without conflict.  Also,
+  # when you are performing actions on the category fields, the module is making sure these are available
+  # in the KMC by calling Kaltura's Category service.
+  # 
+  # @example Retrieving metadata:
+  #   get_name("1_q34aa52a")
+  #   get_categories("1_q34aa52a")
+  #
+  # @example Setting metadata:
+  #   set_name("1_q34aa52a", "waffles")
+  #   set_categories("1_q34aa52a", "HD,h.264,live recording")
+  #
+  # @example Appending tags to an existing set:
+  #   add_tags("1_q34aa52a","eductation, lecture capture")
+  # 
+  # == Checking the Status of an Entry
+  # One unfortunate aspect of the Kaltura API is that an entry will report it's status as "ready"
+  # while flavors are still encoding.  When you embed the entry on a webpage, it will render an
+  # error "Media is currently converting".  The only solution is to instead check the status of 
+  # each flavor instead to ensure total readiness.
+  #
+  # @example Checking an entries status:
+  #   check_status("1_q34aa52a")
+  #
+  # == Retrieving Status About the Source Video
+  # Occasionally, you need to interact with the original video in some form or another with Kaltura.
+  # One production situation I have encountered in the past is maintaining a copy of the source video
+  # on a large data store seperate from Kaltura.  It is extremely difficult to work with the download
+  # URL that Kaltura provides for that.
+  #
+  # @example Getting the Flavor ID of the original video associated with an entry:
+  #   original_flavor("1_q34aa52a")
+  #
+  # @example Getting the file extension of the original video associated with an entry:
+  #   original_file_extension("1_q34aa52a")
+  # 
+  # @example Getting a usable download URL for the entries original file:
+  #   original_download_url("1_q34aa52a")
+  #
+  # @author Patrick Robertson
+  ##
+  module Entry
+        
+    ##
+    # @private
+    ##
+    def self.included(base)
+      base.extend ClassMethods
+      base.class_eval do 
+        include Metadata
+        include InstanceMethods
+        include Flavor
+      end
+      super
+    end
+    
+  end #Entry
+end #KalturFu

data/lib/kaltura_fu/entry/class_methods.rb

@@ -0,0 +1,61 @@
+module KalturaFu
+  module Entry
+    
+    ##
+    # Class level methods for the Entry module.  
+    ##
+    module ClassMethods
+      #extend KalturaFu::Entry::Metadata
+      ##
+      # Allows you to upload some variety of media into Kaltura.  
+      # This isn't going to be as great to use as one of their flash widgets, and 
+      # should likely be used "off" the web process to not slow the application down.
+      #
+      # @param upload_object The object to upload.  Currently, it only works with a File.
+      # @param [Hash] options An options hash of Kaltura Media Entry attributes to add & the
+      #   upload_object source.
+      # @option options [Symbol] :source(nil) Currently only accepts :file
+      #
+      # @return [String] Returns the Kaltura Media Entry's ID that was created.
+      # @raise [Kaltura::APIError] It will force a Kaltura::APIError if something went terribly wrong.
+      #
+      # @todo Add the other upload types.
+      ##
+      def upload(upload_object,options={})
+        KalturaFu.check_for_client_session
+        
+        #options_for_media_entry = options.delete(:source)
+        media_entry = construct_entry_from_options(options)
+        upload_from_file(upload_object,media_entry) if options[:source] == :file
+      end
+      
+      ##
+      # @todo Build find.
+      ##
+      def find
+        #pending
+      end
+      
+      ##
+      # @private
+      ##
+      def upload_from_file(upload_object,media_entry)
+        upload_token = KalturaFu.client.media_service.upload(upload_object)
+        KalturaFu.client.media_service.add_from_uploaded_file(media_entry,upload_token).id
+      end
+      
+      ##
+      # @private
+      ##
+      def construct_entry_from_options(options={})
+        media_entry = Kaltura::MediaEntry.new
+        options.each do |key,value|
+          media_entry.send("#{key}=",value) if valid_entry_attribute?(key)
+        end
+          media_entry.media_type = Kaltura::Constants::Media::Type::VIDEO if options[:media_type].nil?
+          return media_entry
+      end
+      
+    end #ClassMethods
+  end #Entry
+end #KalturaFu

data/lib/kaltura_fu/entry/flavor.rb

@@ -0,0 +1,117 @@
+module KalturaFu
+  module Entry
+    ##
+    # The flavor module mixes in instance methods for a class that includes the Entry module.  This 
+    # module primarily provides means to operate on the original upload to Kaltura.  It also contains
+    # a very important method for checking the overall status of a specific entry.  
+    #
+    # @author Patrick Robertson
+    ##
+    module Flavor
+      ##
+      # Checks each flavor under a Kaltura entry for readiness.  It is possible under v3 of the Kaltura API
+      # to receive a 'ready' status for the entry while flavors are still encoding.  Attempting to view the entry
+      # with a player will result in a 'Media is converting' error screen.  This prevents that occurance.
+      # 
+      # @param [String] video_id Kaltura entry_id of the video.
+      #
+      # @return [Number] Kaltura::Constants::FlavorAssetStatus.  2 is ready.
+      ##
+      def check_status(entry_id)
+        KalturaFu.check_for_client_session
+
+        entry_status = get_status(entry_id)
+        if entry_status == Kaltura::Constants::Entry::Status::READY
+         flavor_array = KalturaFu.client.flavor_asset_service.get_by_entry_id(entry_id)
+         error_count = 0
+         not_ready_count = 0
+         ready_count = 0
+         flavor_array.each do |flavor|
+           case flavor.status
+             when Kaltura::Constants::FlavorAssetStatus::READY ||  Kaltura::Constants::FlavorAssetStatus::DELETED || Kaltura::Constants::FlavorAssetStatus::NOT_APPLICABLE
+               ready_count +=1
+             when Kaltura::Constants::FlavorAssetStatus::ERROR
+               error_count +=1
+             when Kaltura::Constants::FlavorAssetStatus::QUEUED || Kaltura::Constants::FlavorAssetStatus::CONVERTING
+               not_ready_count +=1
+           end
+         end
+         #puts "errors: #{error_count} ready:#{ready_count} not_ready:#{not_ready_count} total:#{video_array.size} \n"
+         if error_count > 0
+           Kaltura::Constants::FlavorAssetStatus::ERROR
+         elsif not_ready_count > 0
+           Kaltura::Constants::FlavorAssetStatus::CONVERTING
+         else
+           Kaltura::Constants::FlavorAssetStatus::READY
+         end
+        else
+         entry_status
+        end
+      end
+    
+      ##
+      # Returns the flavor ID of the original file uploaded to Kaltura.
+      #
+      # @param [String] video_id Kaltura entry_id of the video.
+      #
+      # @return [String] flavor_id
+      ##
+      def original_flavor(entry_id)
+       KalturaFu.check_for_client_session
+
+       flavor_array = KalturaFu.client.flavor_asset_service.get_by_entry_id(entry_id)
+       ret_flavor = nil
+
+       flavor_array.each do |flavor|
+         if flavor.is_original
+           ret_flavor = flavor.id.to_s
+           break
+         end
+       end
+       ret_flavor
+      end
+
+      ##
+      # Returns the file extension of the original file uploaded to Kaltura for a given entry
+      #
+      # @param [String] video_id Kaltura entry_id of the video.
+      #
+      # @return [String] file extension
+      ##
+      def original_file_extension(entry_id)
+        KalturaFu.check_for_client_session
+
+        flavor_array = KalturaFu.client.flavor_asset_service.get_by_entry_id(entry_id)
+        source_extension = nil
+        flavor_array.each do |flavor|
+          if flavor.is_original
+            source_extension = flavor.file_ext
+            break
+          end
+        end
+        source_extension
+      end
+
+      ##
+      # Returns a download URL suitable to be used for iTunes one-click syndication.  serveFlavor is not documented in KalturaAPI v3
+      # nor is the ?novar=0 paramter.  
+      # 
+      # @param [String] video_id Kaltura entry_id of the video
+      #
+      # @return [String] URL that works with RSS/iTunes syndication.  Normal flavor serving is flakey with syndication.
+      ##
+      def original_download_url(video_id)
+        KalturaFu.check_for_client_session
+        
+        service_url = KalturaFu.config[:service_url] || "http://www.kaltura.com"
+        partner_id = KalturaFu.config[:partner_id]
+        subpartner_id = (partner_id.to_i * 100).to_s
+        flavor = original_flavor(video_id)
+        extension = original_file_extension(video_id)
+        
+        "#{service_url}/p/#{partner_id}/sp/#{subpartner_id}/serveFlavor/flavorId/#{flavor}/name/#{flavor}.#{extension}?novar=0"
+      end
+             
+    end #Flavor
+  end #Entry
+end #KalturaFu

data/lib/kaltura_fu/entry/instance_methods.rb

@@ -0,0 +1,28 @@
+module KalturaFu
+  module Entry
+    ##
+    # Instance level methods for the Entry module.
+    ##
+    module InstanceMethods
+      ##
+      # Deletes a Kaltura entry.  Unlike the base API delete method, this returns true/false based on success.
+      # 
+      # @param [String] entry_id Kaltura entry ID to delete.
+      #
+      # @return [Boolean] returns true if the delete was successful or false otherwise.
+      # 
+      ##
+      def delete_entry(entry_id)
+        KalturaFu.check_for_client_session
+
+        begin
+          KalturaFu.client.media_service.delete(entry_id)
+          true
+        rescue Kaltura::APIError => e
+          false
+        end      
+      end     
+      
+    end
+  end
+end

data/lib/kaltura_fu/entry/metadata.rb

@@ -0,0 +1,156 @@
+require 'active_support'
+
+module KalturaFu
+  module Entry
+    
+    ##
+    # The Metadata module provides methods that get/set and add metadata to the 
+    # Kaltura installation.  
+    #
+    # @author Patrick Robertson
+    ##
+    module Metadata
+
+      ##
+      # @private
+      ##
+      def self.included(base)
+        base.extend ClassAndInstanceMethods
+        base.extend ClassMethods
+        base.class_eval do
+          include ClassAndInstanceMethods
+        end
+        super
+      end
+      
+      ##
+      # @private
+      ##      
+      def method_missing(name, *args)
+        method_name = name.to_s  
+        unless self.class.generated_methods?
+          self.class.define_attribute_methods
+          if self.class.generated_methods.include?(method_name)
+            return self.send(name,*args)
+          else
+            super
+          end
+        else
+          super
+        end
+      end
+      
+      ##
+      # @private
+      ##
+      def respond_to?(method)
+        case method.to_s
+          when /^(get|set)_(.*)/
+            valid_entry_attribute?($2.to_sym) || super
+          when /^(add)_(.*)/
+            (valid_entry_attribute?($2.pluralize.to_sym) && valid_add_attribute?($2) ) || super
+        else
+          super
+        end         
+      end
+      
+      ##
+      # Gets a Kaltura::MediaEntry given a Kaltura entry.
+      #
+      # @param [String] video_id Kaltura entry_id of the video.
+      #
+      # @return [Kaltura::MediaEntry] The MediaEntry object for the Kaltura entry.
+      # @raose [Kaltura::APIError] Raises a kaltura error if it can't find the entry.
+      ##
+      def get_entry(entry_id)  
+        KalturaFu.check_for_client_session
+
+        KalturaFu.client.media_service.get(entry_id)      
+      end
+      
+      ##
+      # Sets a specific Kaltura::MediaEntry attribute given a Kaltura entry.
+      # This method is called by method_missing, allowing this module set attributes based
+      # off of the current API wrapper, rather than having to update along side the API wrapper.
+      #
+      # @param [String] attr_name The attribute to set.
+      # @param [String] entry_id The Kaltura entry ID.
+      # @param [String] value The value you wish to set the attribute to.
+      # 
+      # @return [String] Returns the value as stored in the Kaltura database.  Tag strings come back
+      #   slightly funny.
+      #
+      # @raise [Kaltura::APIError] Passes Kaltura API errors directly through.
+      ##
+      def set_attribute(attr_name,entry_id,value)
+        KalturaFu.check_for_client_session
+        
+        add_categories_to_kaltura(value) if (attr_name =~ /^(.*)_categories/ || attr_name =~ /^categories/)
+        
+        media_entry = Kaltura::MediaEntry.new
+        media_entry.send("#{attr_name}=",value)
+        KalturaFu.client.media_service.update(entry_id,media_entry).send(attr_name.to_sym)
+        
+      end
+      
+      ##
+      # @private
+      ##
+      def add_categories_to_kaltura(categories)
+        KalturaFu.check_for_client_session
+        
+        categories.split(",").each do |category|
+          unless category_exists?(category)
+            cat = Kaltura::Category.new
+            cat.name = category
+            KalturaFu.client.category_service.add(cat)            
+          end
+        end
+      end
+      
+      ## 
+      # @private
+      ##  
+      def category_exists?(category_name)
+        KalturaFu.check_for_client_session
+
+        category_filter = Kaltura::Filter::CategoryFilter.new
+        category_filter.full_name_equal = category_name
+        category_check = KalturaFu.client.category_service.list(category_filter).objects
+        if category_check.nil?
+          false
+        else
+          category_check
+        end
+      end
+      
+      
+      ##
+      # Appends a specific Kaltura::MediaEntry attribute to the end of the original attribute given a Kaltura entry.
+      # This method is called by method_missing, allowing this module add attributes based
+      # off of the current API wrapper, rather than having to update along side the API wrapper.
+      #
+      # @param [String] attr_name The attribute to set.
+      # @param [String] entry_id The Kaltura entry ID.
+      # @param [String] value The value you wish to append the attribute with.
+      # 
+      # @return [String] Returns the value as stored in the Kaltura database.  Tag strings come back
+      #   slightly funny.
+      #
+      # @raise [Kaltura::APIError] Passes Kaltura API errors directly through.
+      ##      
+      def add_attribute(attr_name,entry_id,value)
+        KalturaFu.check_for_client_session
+
+
+        add_categories_to_kaltura(value) if (attr_name =~ /^(.*)_categor(ies|y)/ || attr_name =~ /^categor(ies|y)/)        
+        
+        old_attributes = KalturaFu.client.media_service.get(entry_id).send(attr_name.to_sym)
+        media_entry = Kaltura::MediaEntry.new
+        media_entry.send("#{attr_name}=","#{old_attributes},#{value}")
+        KalturaFu.client.media_service.update(entry_id,media_entry).send(attr_name.to_sym)
+      end
+      
+    end
+  end
+end