vid-skim 0.0.1

data/README

@@ -0,0 +1,51 @@
+=
+
+     --- ---             
+    +-------------+
+    | +----+ ---- | ---  
+    | | :) | ---- | ---  
+    | +----+ ---- | ---  
+    +-------------+      
+                         
+  
+
+  ~ Video Skimmer
+
+
+  # Transcripts and commentary for long boring videos on YouTube! #
+
+    * Present your videos with transcripts and running commentary.
+    * Let your users skip to the good parts.
+  
+    Designed for:
+
+    * News organizations
+    * Producers comfortable with the command line
+    * Raw video from court transcripts, Political Speeches, Uncut Interviews. In
+      short: lengthy video.
+
+  ~ Documentation
+
+    #Wiki: https://github.com/propublica/vid-skim/wikis
+    #RDoc: http://rdoc.info/projects/propublica/vid-skim
+
+  ~ Getting Started
+
+    Install the gem
+  
+      >> sudo install vid-skim
+  
+    Install the directory structure.
+  
+      >> vidskim install video-skimmer
+  
+    Under ./video-skimmer/ you'll see an html and and videos directory. 
+    Put your vidskim json or expanded files in ./video-skimmer/videos/ (see the
+    wiki for formatting info).
+  
+    Once your json is complete run:
+    
+      >> vidskim build video-skimmer
+  
+    And you'll see some html files that look something like this:
+       http://projects.propublica.org/skimmer/ron_boline

data/bin/vidskim

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require File.dirname(__FILE__ ) + "/../lib/vid_skim"
+
+VidSkim::Command.new

data/lib/vid_skim.rb

@@ -0,0 +1,57 @@
+$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__))
+
+require 'rubygems'
+gem 'nokogiri'
+gem 'json'
+
+autoload :JSON,         'json'
+autoload :ERB,          'erb'
+autoload :FileUtils,    'fileutils'
+autoload :Set,          'set'
+autoload :OptionParser, 'optparse'
+
+
+module VidSkim
+  autoload :Command, 'vid_skim/command'
+  autoload :Transcript, "vid_skim/transcript"
+  autoload :Inflector, "vid_skim/inflector"
+  autoload :Compiler, "vid_skim/compiler"
+  autoload :Parser, "vid_skim/parser"
+  autoload :Files, "vid_skim/files"
+  
+  ROOT = File.expand_path(File.dirname(__FILE__) + '/..')
+  
+  
+  class << self
+    attr_reader :working_path, :build_path, :output_path, :parser_path
+    
+    
+    # Set the paths for each of the directories VidSkim works with.
+    def configure(working_path)
+      @working_path = working_path
+      @build_path = working_path + '/videos/'
+      @output_path = working_path + '/html/'
+      @parser_path = working_path + '/parsers/'
+    end
+    
+    # Borrowed from Jeremy Ashkenas's wonderful cloud-crowd gem.
+    # Build a list of parsers from both VidSkim's defaults and
+    # those installed in the working directory.
+    def parsers
+      return @parsers if @parsers
+      @parsers = {}
+      installed = Dir["#{@parser_path}*.rb"]
+      default   = Dir["#{ROOT}/parsers/*.rb"]
+      
+      (installed + default).each do |path|
+        name = File.basename(path, File.extname(path))
+        require path
+        @parsers[name] = Module.const_get(Inflector.camelize(name))
+      end
+      @parsers
+    rescue NameError => e
+      adjusted_message = "One of your parsers failed to load. Please ensure that the name of your parser class can be deduced from the name of the file. ex: 'json_parser.rb' => 'JsonParser'\n#{e.message}" 
+      raise NameError.new(adjusted_message, e.name)
+    end
+  end
+end

data/lib/vid_skim/command.rb

@@ -0,0 +1,119 @@
+module VidSkim
+
+  # Command-line `vidskim` client. Handles commands for initial installation
+  # and building out the exported HTML files.
+  class Command
+    
+    # Command-line banner for the usage message.
+    BANNER = <<-EOS
+Usage: vidskim COMMAND path/to/directory OPTIONS
+
+Commands:
+  install     Install the VidSkim configuration to the specified directory
+  build       Build all videos in a VidSkim directory into HTML pages
+  parse       Parse a file using a parser into the VidSkim directory
+  compile     Compiles and builds each json file from an expanded format
+  
+  parse path/to/directory -f <input_file> -p <parser_name>  
+      Parse an <input_file> using the parser in <parser_name>
+      
+      Example: vid-skim parse ./vids -f edit.edl -p edl_parser will parse an    
+               EDL file using the edl_parser
+               
+  Options:
+    EOS
+    
+    # Creating a VidSkim::Command parses all command-line arguments and
+    # options.
+    def initialize
+      @options = {}   
+      parse_options      
+      @command = ARGV.shift
+      @directory = ARGV.shift || '.'
+      configure
+      case @command
+        when 'install' then run_install
+        when 'build'   then run_build
+        when 'parse'   then run_parse
+        when 'compile' then run_compile
+        else                usage
+      end
+    end
+    
+   
+    # Parse the options from the command line
+    def parse_options
+      @option_parser = OptionParser.new do |opts|
+        opts.on('-p', '--parser NAME', 'Name of parser') do |parser_name|
+          @options[:parser_name] = parser_name
+        end
+        
+        opts.on('-f', '--file FILE', 'Input file to parse') do |parser_file|
+          @options[:parser_file] = parser_file
+        end
+        
+        opts.on('--force', 'Force overwriting of files') do
+          Files.force = true
+        end
+        
+        opts.on_tail('-v', '--version', 'Show version') do
+          puts "VidSkim version #{VERSION}"
+          exit
+        end
+      end
+      @option_parser.banner = BANNER
+      @option_parser.parse!(ARGV)
+    end
+    
+    # Install the example VidSkim folder to a location of your choosing.
+    def run_install
+      FileUtils.mkdir_p(VidSkim.working_path) unless File.exists?(VidSkim.working_path)
+      Files.install_dir "#{VidSkim::ROOT}/template/html",   "#{VidSkim.output_path}"
+      Files.install_dir "#{VidSkim::ROOT}/template/videos", "#{VidSkim.build_path}"
+      Files.install_dir "#{VidSkim::ROOT}/template/parsers", "#{VidSkim.parser_path}"
+    end
+    
+    # Build the html files from the json in the videos directory.
+    def run_build
+      Files.walk_build_path(".json").each do |f|
+        template = ERB.new(File.open(VidSkim::ROOT +
+                                '/views/template.html.erb', 'r').read)
+        @transcript = Transcript.find(f)
+        str = template.result(binding)
+        Files.create_file(VidSkim.output_path + "#{@transcript.slug}.html", str)
+      end
+    end
+    
+    # Run a parser to build the files in the videos directory.  Allow an   
+    # escape hatch if the directory exists
+    def run_parse
+      raise Error.new("To run a parser you must use both the -p and -f flags.") if
+              !@options[:parser_name] && !@options[:parser_file]
+      parser = VidSkim.parsers[@options[:parser_name]].new
+      parser.load(@options[:parser_file])
+      parser.parse
+    end
+    
+    # Run the compiler to compile and build the files in each directory 
+    # created by a parser or by hand.
+    def run_compile
+      compiler = VidSkim::Compiler.new
+      compiler.compile
+    end
+    
+    # Print out `vidskim` usage.
+    def usage
+      puts "\n#{@option_parser}\n"
+    end
+    
+    
+    private
+    
+    # Make sure that everyone knows where to put any files they generate
+    def configure
+      VidSkim.configure(@directory)
+    end
+    
+      
+  end
+end

data/lib/vid_skim/compiler.rb

@@ -0,0 +1,106 @@
+module VidSkim
+  # The compiler handles both the compiling to json of an expanded directory, 
+  # and the creation of expanded directories.
+  class Compiler
+    
+    # Set up the erb templates for .entry, .div and .trans files.
+    def initialize
+      @transcript_t = ERB.new <<-EOS
+<%= skim.title || "TITLE OF VIDEO" %>
+<%= skim.youtube_id || "YOUTUBE_ID" %>
+<%= skim.duration || "DURATION IN SECONDS" %>
+<%= skim.default || "DEFAULT TAB" %>
+      EOS
+      @division_t = ERB.new <<-EOS
+<%= division.name || "DIVISION ID" %>
+<%= division.color || "COLOR IN #XXXXXX FORMAT" %>
+<%= division.hover || "HOVER COLOR IN #XXXXXX FORMAT" %>
+      EOS
+      @entry_t = ERB.new <<-EOS
+<%= division.name %>
+<%= entry.title || "TITLE HERE" %>
+<%= entry.range.collect.to_json || "['00:00:00', '00:00:00']" %>
+<%= entry.transcript || "<p>HTML HERE (CAN BE MULTIPLE LINES)</p>" %>
+      EOS
+    end
+    
+    # Create an expanded directory from a VidSkim::Transcript
+    def explode(skim)
+      
+      file_tree = {}
+      working_dir = Inflector.parameterize(skim.title)
+      file_tree[working_dir] = 
+                        [["/#{working_dir}.trans", @transcript_t.result(binding)]]
+      skim.divisions.each do |title, division|
+        file_tree[working_dir] << [
+            "/#{division.name}.div",
+            @division_t.result(binding)
+          ]
+        
+        division.entries.each_with_index do |entry, i|
+          file_tree[working_dir] << [
+            "/#{division.name}-#{i}.entry",
+            @entry_t.result(binding)
+          ]
+        
+        end
+      end
+      Files.create_tree(file_tree)
+      
+    end
+    
+    # Create a VidSkim::Transcript and compile it to json from an expanded
+    # directory
+    def compile
+      Dir[VidSkim.build_path + "**"].each do |dir|
+        next unless File.directory?(dir)
+        @skim = VidSkim::Transcript.new({})
+        Dir["#{dir}/*.{trans,div,entry}"].each do |path|
+          path =~ /.*\.(trans|div|entry)/
+          send("compile_#{$1}", File.open(path).read.split("\n"))
+        end
+        Files.create_file(VidSkim.build_path + Inflector.parameterize(@skim.title) + ".json", @skim.to_json)
+      end
+      
+    
+    rescue NameError => boom
+        message = "One of your build files failed, are you sure everything's in the right order and the right format?\n\nThis might help:\n#{boom.message}"
+      raise NameError.new(message, boom.name)
+    end
+    
+    private
+     
+    # Compile a trans file
+    def compile_trans(arr)
+      assign(@skim, [:title=, :youtube_id=, :duration=, :default=], arr)
+      @skim.duration = @skim.duration.to_i || 0
+    end
+    
+    # Compile a division file
+    def compile_div(arr)
+      @skim.divisions[arr[0]] = Transcript::Division.new("")
+      name = arr.shift
+      @skim.divisions[name].name = name
+      assign(@skim.divisions[name], [:color=, :hover=], arr)     
+    end
+    
+    # Compile an entry file
+    def compile_entry(arr)
+      entry = Transcript::Entry.new()
+      division_name = arr.shift
+      assign(entry, [:title=], arr)
+      entry.range = JSON.parse(arr.shift)
+      entry.transcript = arr.join      
+      @skim.divisions[division_name].entries << entry
+    end
+    
+    # Assign each attribute to the right place in +@skim+
+    def assign(obj, dest, values)
+      dest.each do |attribute|
+        obj.send(attribute, values.shift)
+      end
+    end
+     
+  end
+  
+end

data/lib/vid_skim/files.rb

@@ -0,0 +1,61 @@
+module VidSkim
+
+  class Files
+    
+    class << self
+      attr_accessor :force
+    end
+  
+    # To be refactored soon. Takes an hash of arrays
+    # => puts tree
+    # >> {"path" => ["filename", contents], ... }
+    # which allows us to to write out the file and underlying directories.
+    # Allows for escape oppurtunities if we're about to overwrite something.
+    def self.create_tree(tree)
+      tree.each_pair do |dir, files|
+        dir = "/videos/" + dir
+        path = File.join(VidSkim.working_path, dir)
+        FileUtils.mkdir_p path unless File.exists? path
+        files.each do |filename, contents|
+          if filename.respond_to? :each_pair 
+            create_tree filename, path
+          else
+            self.create_file(path + filename, contents)
+          end
+        end
+      end
+    end
+    
+    # Walk the build path and return files with a given extension.
+    def self.walk_build_path(ext)
+      Dir[VidSkim.build_path + "**/*#{ext}"]
+    end
+  
+    # Check if a file exists and asks the user if they want to overwrite it         
+    # returns false if they say no.
+    def self.check_file(dest)
+      if File.exists?(dest) && !@force && ENV["VID_SKIM_ENV"] != 'test'
+        print "#{dest} already exists. Overwrite it? (yes/no) "
+        return false unless ['y', 'yes', 'ok'].include? gets.chomp.downcase
+      end
+      true
+    end
+
+    # Install a file and log the installation. Allow opportunities to back out
+    # of overwriting existing files.
+    def self.install_dir(source, dest)
+      return unless check_file(dest)
+      FileUtils.cp_r(source, dest)
+      puts "installed #{dest}" unless ENV["VID_SKIM_ENV"] == 'test'
+    end
+
+    # Create a file and underlying directories if needed and log the creation.
+    def self.create_file(dest, str)
+      return unless check_file(dest)
+      File.new(dest, "w").write(str)
+      puts "created #{dest}" unless ENV["VID_SKIM_ENV"] == 'test'
+    end
+    
+  end
+  
+end

data/lib/vid_skim/inflector.rb

@@ -0,0 +1,16 @@
+module VidSkim
+  # Various string utilities.
+  class Inflector
+    # From rails
+    # Return the camelized form of the word. Useful for loading parsers.
+    def self.camelize(word)
+      word.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
+    end
+    
+    # Remove non printing characters and replace them with the seperator +sep+
+    def self.parameterize(string, sep = '-')
+      string.gsub(/[^a-z0-9\-_\+]+/i, sep).downcase
+    end
+  end
+  
+end

data/lib/vid_skim/parser.rb

@@ -0,0 +1,21 @@
+module VidSkim
+  # Each parser you define in your parser directory needs to set the
+  # +@transcript+ attribute with a VidSkim::Transcript instance. You can see a
+  # fully fleshed out example in parsers/edl_parser.rb.
+  #
+  # A key point to remember: every unset attribute of the @transcript will be 
+  # replaced with a sane default when the Compiler expands @transcript.
+  class Parser
+    attr_accessor :transcript
+    # The load method takes a name of a file and must return a 
+    # VidSkim::Transcript object
+    def load(file)
+      raise NotImplementedError, "Parsers must define a load method that takes the name of the file to read from."
+    end
+
+    def parse
+      Compiler.new.explode(@transcript)
+    end
+
+  end
+end

data/lib/vid_skim/transcript.rb

@@ -0,0 +1,195 @@
+module VidSkim
+  
+  # Transcript is a json parser/updater which parses a Video Skimmer formatted
+  # json file. 
+  class Transcript
+    attr_accessor :divisions, :title, :youtube_id, :duration, :default
+
+    def initialize(hash)
+      @divisions = {}
+      @youtube_id = hash["youtube_id"]
+      @title = hash["title"]
+      @default = hash["default"]
+      @duration = hash["duration"].to_i
+      send("divisions=", hash["divisions"]) if hash["divisions"]
+    end
+    
+    # Set each division from a hash of divisions
+    def divisions=(hash)
+       hash.each_pair do |key, value|
+                          @divisions["#{key}"] = Transcript::Division.new(key)
+                          value.each_pair do |method, value|
+                            @divisions["#{key}"].send("#{method}=", value) 
+                          end
+                       end 
+       
+    end
+    
+    # Return the json representation
+    def to_json
+      to_hash.to_json
+    end
+    
+    # Return the hash representation
+    def to_hash
+      c = {}
+      c["youtube_id"] = @youtube_id
+      c["title"] = @title
+      c["default"] = @default
+      c["duration"] = @duration
+      c["divisions"] = {}
+      @divisions.each_pair{|d,v| c["divisions"].merge!(v.collect)}
+      c
+    end 
+  
+
+    # Return a parameterized version of the title for creating the actual
+    # html file
+    def slug
+      Inflector.parameterize(@title, "_")
+    end
+
+  
+    class << self
+      # Search for a Transcript based on a path
+      def find(f)
+        hash = JSON.parse(File.open("#{f}").read)
+        Transcript.new(hash)
+      end
+    end
+    
+  
+    # The building blocks of transcripts: each Transcript::Division is a
+    # different view to the video
+    class Division
+
+      attr_accessor :name, :color, :hover
+      def initialize(name)
+        @name = name || ""
+        @entries = []
+      end
+    
+      # Set each individual Entry from a straight hash of +entries+, which 
+      # are synced to the video
+      def entries=(entries)
+        @entries=[]
+        entries.each do |e|
+                      entry = Transcript::Entry.new()
+                      e.each_pair {|key, value| entry.send("#{key}=", value)}
+                      @entries << entry
+                     end
+      end
+    
+      # Return an array of entries ensuring that their sorted by the low end 
+      # of each Range
+      def entries
+        @entries.sort!{|a, b| a.range.low <=> b.range.low }
+      end
+      
+      # Collect each Entry and returns a hash
+      def collect
+        c = {
+          @name => {
+            "color"=> @color,
+            "hover"=> @hover,
+            "entries"=> []
+          }
+        }
+        entries.each{ |e| c[@name]['entries'] << e.collect }
+        c
+      end
+      
+      
+      
+    
+      # Build a dynamic finder (<tt>unique_entries_by_attribute</tt> where 
+      # attribute is an Entry attribute) so that filters returns unique 
+      # entries you can do things like:
+      #   >> entries = [{'title'=>'Hamm', 'range'=>["00:00:00", "00:00:00"]},
+      #               {'title'=> 'Clove', 'range'=>["00:00:00", "00:00:00"]},
+      #               {'title'=>'Hamm', 'range'=>["00:00:00", "00:00:00"]}]
+      #   >> d = Transcript::Division.new('Endgame')
+      #   >> d.entries = entries
+      #   >> uniq = d.unique_entries_by_title
+      #   >> uniq.each {|u| p u.title }
+      #   "Hamm"
+      #   "Clove"
+      def method_missing(method_id, *args)
+        if method_id.to_s =~ /unique_entries_by_([_a-zA-Z]\w*)$/
+          unique_entries_by_($1.to_sym) #just having a bit of fun
+        else
+          super
+        end
+      end
+      
+      private
+        # Use a set to build the unique entries returned by method missing
+        def unique_entries_by_(key) 
+          seen = Set.new()
+          entries.select { |e|
+            k = e.send(key)
+            seen.add?(k)
+          }.sort{|a, b| a.range.low <=> b.range.low }
+        end
+    
+    end
+    # An Transcript::Entry is an individual section of video 
+    class Entry
+      attr_accessor :title, :range, :transcript
+    
+      def initialize()
+      end
+    
+      # Set a Transcript::Entry::Range object based on a +range+ of the format
+      # ['hh:mm:ss', 'hh:mm:ss'].
+      def range=(range)
+        @range = Range.new(range)
+      end
+    
+      # Return the original hash representation of this object
+      def collect
+        {
+          "title"=> @title,
+          "range"=> @range.collect,
+          "transcript"=> @transcript,
+        }
+      end
+    
+      # A Transcript::Entry::Range parses a timecode.
+      class Range
+
+        # +range+ should be of the format ['hh:mm:ss', 'hh:mm:ss']
+        def initialize(range)
+          @range_low = range.first
+          @range_high = range.last
+        end
+        # Return the low end of the Transcript::Entry::Range
+        def low
+          @range_low
+        end
+      
+        # Return the high end of the Transcript::Entry::Range
+        def high
+          @range_high
+        end
+      
+        # Convert a Transcript::Entry::Range into seconds, the
+        # argument can either be :low or :high
+        def to_seconds(sym)
+          seconds = 0
+          self.send(sym).split(':').reverse.each_with_index do |i, x|
+            seconds += (x == 0 ? 1 : 60 ** x) * i.to_i
+          end
+          seconds
+        end
+
+        # Return the original array representation of this object
+        def collect
+          [@range_low, @range_high]
+        end
+      end
+    
+    end
+  
+  end
+end