zencodable 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2011 YOURNAME
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,116 @@
+# Zencodable
+
+Gives you `has_video_encodings` method for your models, that sets up jobs to encode multiple video container/codecs using [Zencoder](http://zencoder.com). It tells Zencoder to place the output files in some bucket in your S3 account. From there, they are yours to enjoy forever.
+
+```ruby
+class Video < ActiveRecord::Base
+
+  has_video_encodings :video_files, :formats            => [:ogg, :mp4, :webm, :flv],
+                                    :output_dimensions  => '852x480',
+                                    :s3_config          => "#{Rails.root}/config/amazon_s3.yml",
+                                    :path               => "videos/zc/:basename/",
+                                    :thumbnails         => { :number => 2, :aspect_mode => 'crop', 'size' => '290x160' },
+                                    :options            => { :device_profile => 'mobile/advanced' }
+
+end
+```
+
+## Requirements
+
+_developed on ruby 1.9.2-p290 and Rails 3.1.3_
+
+1. A [Zencoder][1] account of course, testing or full.
+
+2. A working Amazon S3 account with a shiny new bucket ready to receive video files.
+
+3. this gem (zencodable) in your gemfile, and typhoeus.
+
+    gem 'zencodable'
+    gem 'typhoeus'
+
+# Setup
+
+## Zencoder API keys
+
+the zencoder/zencoder-rb gem expects access to your Zencoder API keys in some fashion. Also, we need to use dbalatero/typhoeus for HTTP stuffs, that's the only way Zencoder will work with S3. So, I like something in `config/initializers` like
+
+    # zencoder setup
+    if Rails.env == 'production'
+      Zencoder.api_key = 'therealdealkey00000000000000000'
+    else
+      Zencoder.api_key = 'keyfortestingonly00000000000000'
+    end
+
+    Zencoder::HTTP.http_backend = Zencoder::HTTP::Typhoeus
+
+## Bucket policy
+
+The bucket needs to have a custom policy to allow Zencoder to place the output videos on it. [Here is a guide on Zencoder's site, follow it](https://app.zencoder.com/docs/guides/getting-started/working-with-s3)
+
+(There is currently a branch where an attempt to create a rake task to auto-install this policy was made. Unfortunately it seems the marcel/aws-s3 gem doesn't know how to update a bucket policy after all, it just manages the ACLs. It seems fog can't do that either. Oh well, you'll have to paste in the policy.)
+
+## Run the generator
+
+    rails g zencodable:migrations <Model> <association_name>
+
+e.g.,
+
+    rails g zencodable:migrations KittehVideo kitteh_video_files
+
+This will actually create two `has_many` associations for your model - the `kitteh_video_files` for the output files themselves (one for each format), and the `kitteh_video_file_thumbnails` for the framegrab thumbnails that Zencoder can create (if configured).
+
+you can add a `--skip-thumbnails` option if you don't want to use the auto-generated thumbnails.
+
+now do a `rake db:migrate`
+
+## How to use
+
+### Configure model and encoding options
+
+add something like the above `has_video_encodings` class method to your model (the generator does not try to do this for you).
+
+The options should include a `:s3_config` key that gives a location of a YAML file containing your S3 credentials, which should contain a 'bucket' key (you already have one, right?) Actually, all we need from that is the bucket name, so you can instead use a `:bucket` key to give the name of the bucket where the output files should be placed.
+
+The `:path` option can be any path within that bucket. It can contain a `:basename` token, which will be replaced with a sanitized, URL-encoded version of the original filename as uploaded. 
+
+`:formats` is a list of output formats you'd like. [Supported formats and codecs](https://app.zencoder.com/docs/api/encoding/format-and-codecs/format)
+
+The other options are all those that can be handled by Zencoder. More info can be found on [:thumbnails](https://app.zencoder.com/docs/api/encoding/thumbnails), [:output_dimensions](https://app.zencoder.com/docs/api/encoding/resolution/size) and other output settings [:options](https://app.zencoder.com/docs/api/encoding)
+
+### Give it a source URL
+
+All that's needed to trigger the Zencoder job is to change the `origin_url` value of your model, and then save. That will be picked up, sent to Zencoder, and your job will be started with your desired settings. 
+
+As the job runs, you can check `Model.job_status` as you see fit, if the job is neither failed nor finished, it will request an update from Zencoder for that Job.
+
+Individual files will complete at different times, so you can also check the `state` of each associated output file.
+
+    vid = Video.new :title => 'Hilarious Kitteh Antics!'
+    vid.origin_url = 'http://sourcebucket.s3.amazonaws.com/largevideos/funny_kittehs[HD].mov'
+    vid.save
+    vid.job_status # "new"
+    ... 
+    vid.job_status # "waiting"
+    ... 
+    vid.job_status # "processing"
+    vid.video_encoded_files.collect { |v| [v.format, v.state] }
+    ... 
+    vid.job_status # "finished"
+    vid.video_encoded_files.size # 4
+    vid.video_encoded_file_thumbnails.size # 2
+    
+
+## TODO
+
+* change name of `origin_url` column and make sure its added in the migrations
+* rake task to generate a working bucket policy (even if it has to be pasted in)
+* background jobs to update the ZC job progress, with events/notifications
+* is s3_url basename sanitization going to be good for non-ASCII filenames? no.
+
+## License
+
+Uses MIT-LICENSE. You are free to use this as you like, but don't expect anything.
+
+Forking and pull requests would be much appreciated.
+
+  [1]:http://zencoder.com/

data/Rakefile

@@ -0,0 +1,37 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Zencodable'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/lib/generators/zencodable/migration_generator.rb

@@ -0,0 +1,36 @@
+require 'rails/generators'
+require 'rails/generators/named_base'
+
+module Zencodable
+  module Generators
+    class Migration < ::Rails::Generators::NamedBase
+      include Rails::Generators::Migration
+
+      desc "creates migrations to create tables for the models that hold the encoded video files and thumbnails"
+
+      argument :association_name, :type => :string, :default => 'video_files'
+      class_option :skip_thumbnails, :type => :boolean, :default => false
+
+      source_root File.expand_path("../templates", __FILE__)
+
+      def self.next_migration_number(dirname)
+        if ActiveRecord::Base.timestamped_migrations
+          migration_number = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+          migration_number += 1
+          migration_number.to_s
+        else
+          "%.3d" % (current_migration_number(dirname) + 1)
+        end
+      end
+
+      def create_migration_files
+        migration_template 'create_association_table.rb', "db/migrate/create_#{association_name}"
+        unless options.skip_thumbnails?
+          migration_template 'create_association_thumbnails_table.rb', "db/migrate/create_#{association_name}_thumbnails"
+        end
+      end
+
+    end
+  end
+end
+

data/lib/generators/zencodable/templates/create_association_table.rb

@@ -0,0 +1,17 @@
+class CreateZencodableOutputFilesAssociationTable < ActiveRecord::Migration
+  def change
+    create_table "<%= association_name %>" do |t|
+      t.string   "url"
+      t.string   "format"
+      t.integer  "zencoder_file_id"
+      t.integer  "<%= name.foreign_key %>"
+      t.datetime "created_at"
+      t.integer  "width"
+      t.integer  "height"
+      t.integer  "file_size"
+      t.string   "error_message"
+      t.string   "state"
+      t.timestamps
+    end
+  end
+end

data/lib/generators/zencodable/templates/create_association_thumbnails_table.rb

@@ -0,0 +1,12 @@
+class CreateZencodableOutputFilesAssociationTable < ActiveRecord::Migration
+  def change
+    create_table "<%= association_name.singularize %>_thumbnails" do |t|
+      t.string   "thumbnail_file_name"
+      t.string   "thumbnail_content_type"
+      t.integer  "thumbnail_file_size"
+      t.datetime "thumbnail_updated_at"
+      t.integer  "<%= name.foreign_key %>"
+      t.timestamps
+    end
+  end
+end

data/lib/zencodable/version.rb

@@ -0,0 +1,3 @@
+module Zencodable
+  VERSION = "0.0.1"
+end

data/lib/zencodable.rb

@@ -0,0 +1,239 @@
+require 'zencoder'
+
+module Zencodable
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :encoder_definitions
+    class_attribute :encoder_output_files_association
+    class_attribute :encoder_thumbnails_association
+  end
+
+  module ClassMethods
+
+    def has_video_encodings target_association, options = {}
+      self.encoder_definitions = options
+      self.encoder_output_files_association = target_association
+
+      has_many self.encoder_output_files_association, :dependent => :destroy
+
+      unless options[:thumbnails].blank?
+        self.encoder_thumbnails_association = "#{target_association.to_s.singularize}_thumbnails".to_sym
+        has_many self.encoder_thumbnails_association, :dependent => :destroy
+      end
+
+      before_save :create_job
+
+      # TODO cleanup
+      #before_destroy :prepare_for_destroy
+      #after_destroy :destroy_attached_files
+    end
+
+  end
+
+  module InstanceMethods
+
+    def job_status
+      unless ['finished','failed'].include? zencoder_job_status
+        logger.debug "Unfinished job found. Updating details."
+        update_job
+      end
+      self.zencoder_job_status
+    end
+
+    def create_job
+      if self.origin_url_changed?
+        logger.debug "Origin URL changed. Creating new ZenCoder job."
+        if @job = Encoder::Job.create(origin_url, self.class.encoder_definitions)
+          logger.debug "ZenCoder job created, ID = #{@job.id}"
+          self.zencoder_job_id = @job.id
+          self.zencoder_job_status = 'new'
+          self.zencoder_job_created = Time.now
+          self.zencoder_job_finished = nil
+        end
+      end
+    end
+
+    def update_job
+      self.zencoder_job_status = encoder_job.status
+      self.zencoder_job_finished = encoder_job.finished_at
+      self.video_files = encoder_job.files.collect{ |file| video_files_class.new(file) } rescue []
+      self.video_thumbnails = encoder_job.thumbnails.collect{ |file| video_thumbnails_class.new(file) } rescue []
+      save
+    end
+
+    def source_file_for(fmt)
+      self.video_files.where(:format => fmt).first
+    end
+
+    def video_files
+      self.send(video_files_method)
+    end
+
+    def video_thumbnails
+      self.send(video_files_thumbnails_method)
+    end
+
+    def video_files= *args
+      self.send "#{video_files_method}=", *args
+    end
+
+    def video_thumbnails= *args
+      self.send("#{video_files_thumbnails_method}=", *args) if self.respond_to?(video_files_thumbnails_method)
+    end
+
+
+    private
+    def encoder_job
+      @job ||= Encoder::Job.new(self.zencoder_job_id)
+    end
+
+    def video_files_method
+      self.class.encoder_output_files_association
+    end
+
+    def video_files_thumbnails_method
+      self.class.encoder_thumbnails_association
+    end
+
+    # need to know the Class of the associations so we can instantiate some when job is complete.
+    def video_files_class
+      self.class.reflect_on_all_associations(:has_many).detect{ |reflection| reflection.name == self.class.encoder_output_files_association }.klass
+    end
+
+    def video_thumbnails_class
+      self.class.reflect_on_all_associations(:has_many).detect{ |reflection| reflection.name == self.class.encoder_thumbnails_association }.klass
+    end
+
+  end
+
+
+
+  module Encoder
+    include Zencoder
+
+    class Job < Zencoder::Job
+
+      attr_accessor :id
+
+      class << self
+
+        def create(origin, encoder_definitions)
+          response = super(:input => origin,
+                           :outputs => build_encoder_output_options(origin, encoder_definitions))
+          if response.code == 201
+            job_id = response.body['id']
+            self.new(job_id)
+          end
+        end
+
+        def build_encoder_output_options(origin, definitions)
+
+          formats = definitions[:formats] || [:ogg]
+          size = definitions[:output_dimensions] || '400x300'
+          base_url = s3_url(origin, definitions[:s3_config], definitions[:path])
+
+          defaults = { :public => true,
+                       :device_profile => "mobile/advanced",
+                       :size => size
+                     }
+          defaults = defaults.merge(definitions[:options]) if definitions[:options]
+
+          if definitions[:thumbnails]
+            defaults[:thumbnails] = {:aspect_mode => 'crop',
+                                     :base_url => base_url,
+                                     :size => size
+                                    }.merge(definitions[:thumbnails])
+          end
+
+          formats.collect{ |f| defaults.merge( :format => f.to_s, :label => f.to_s, :base_url => base_url ) }
+        end
+
+        def s3_url origin_url, s3_config_file, path
+          basename = origin_url.match( %r|([^/][^/\?]+)[^/]*\.[^.]+\z| )[1] # matches filename without extension
+          basename = basename.downcase.squish.gsub(/\s+/, '-').gsub(/[^\w\d_.-]/, '') # cheap/ugly to_url
+          path = path.gsub(%r|:basename\b|, basename)
+          "s3://#{s3_bucket_name(s3_config_file)}.s3.amazonaws.com/#{path}/"
+        end
+
+        def s3_bucket_name s3_config_file
+          s3_config_file ||= "#{Rails.root}/config/s3.yml"
+          @s3_config ||= YAML.load_file(s3_config_file)[Rails.env].symbolize_keys
+          @s3_config[:bucket_name]
+        end
+
+      end
+
+      def initialize(job_id)
+        @id = job_id
+        @job_detail = {}
+      end
+
+
+      def details
+        if @job_detail.empty? and @id
+          response = self.class.details @id
+          if response.code == 200
+            @job_detail = response.body['job']
+          end
+        end
+        @job_detail
+      end
+
+      def status
+        self.details['state']
+      end
+
+      def finished_at
+        self.details['finished_at']
+      end
+
+      def files
+        if outfiles = self.details['output_media_files']
+          outfiles.collect { |f| { :url =>              f['url'],
+                                   :format =>           f['label'],
+                                   :zencoder_file_id => f['id'],
+                                   :created_at =>       f['finished_at'],
+                                   :duration_sec =>     f['duration_in_ms'],
+                                   :width =>            f['width'],
+                                   :height =>           f['height'],
+                                   :file_size =>        f['file_size_bytes'],
+                                   :error_message =>    f['error_message'],
+                                   :state =>            f['state'] }
+                           }
+        end
+      end
+
+      # ZC gives thumbnails for each output file format, but gives them the same
+      # name and overwrites them at the same S3 location. So if we have f
+      # formats, and ask for x thumbnails, we get x*f files described in the
+      # details['thumbnails'] API, but there are actually only x on the S3
+      # server.  So, the inject() here is done to pare that down to unique URLs,
+      # and give us the cols/vals that paperclip in VideoThumbnail is going to want
+      def thumbnails
+        if thumbs = self.details['thumbnails']
+
+          thumbs.inject([]) do |res,th|
+            unless res.map{ |r| r[:thumbnail_file_name] }.include?(th['url'])
+              res << { :thumbnail_file_name =>   th['url'],
+                       :thumbnail_content_type =>th['format'],
+                       :thumbnail_file_size =>   th['file_size_bytes'],
+                       :thumbnail_updated_at =>  th['created_at']
+                     }
+            end
+            res
+          end
+
+        end
+      end
+
+    end
+
+  end
+end
+
+
+class ActiveRecord::Base
+  include Zencodable
+end
+