edl 0.0.1 → 0.0.2

data/lib/edl.rb

@@ -1,31 +1,34 @@
 require "rubygems"
 require "timecode"
+require 'stringio'
+
+require File.dirname(__FILE__) + '/edl/event'
+require File.dirname(__FILE__) + '/edl/transition'
+require File.dirname(__FILE__) + '/edl/timewarp'
 
 # A simplistic EDL parser. Current limitations: no support for DF timecode, no support for audio,
 # no support for split edits, no support for key effects, no support for audio
 module EDL
-  VERSION = "0.0.1"
-  
+  VERSION = "0.0.2"
   DEFAULT_FPS = 25
   
   # Represents an EDL, is returned from the parser. Traditional operation is functional style, i.e.
   #  edl.renumbered.without_transitions.without_generators
-  class List
-    attr_accessor :events, :fps
+  class List < Array
     
-    def initialize(events = [])
-      @events = events.dup
+    def events #:nodoc:
+      STDERR.puts "EDL::List#events is deprecated and will be removed, use EDL::List as an array instead"
+      self
     end
     
-    # Return the same EDL with all dissolves stripped and replaced by the clips under them
+    # Return the same EDL with all dissolves stripped and replaced by the clips underneath
     def without_transitions
       # Find dissolves
       cpy = []
-      
-      @events.each_with_index do | e, i |
+      each_with_index do | e, i |
         # A dissolve always FOLLOWS the incoming clip
-        if @events[i+1] && @events[i+1].has_transition?
-          dissolve = @events[i+1]
+        if e.ends_with_transition?
+          dissolve = self[i+1]
           len = dissolve.transition.duration.to_i
           
           # The dissolve contains the OUTGOING clip, we are the INCOMING. Extend the
@@ -34,7 +37,7 @@ module EDL
           incoming.src_end_tc += len
           incoming.rec_end_tc += len
           
-          outgoing = dissolve.copy_properties_to(Clip.new)
+          outgoing = dissolve.copy_properties_to(Event.new)
           
           # Add the A suffix to the ex-dissolve
           outgoing.num += 'A'
@@ -43,7 +46,7 @@ module EDL
           cpy << incoming
           cpy << outgoing
         elsif e.has_transition?
-          # Skip, already handled!
+          # Skip, already handled on the previous clip
         else
           cpy << e.dup
         end
@@ -53,15 +56,14 @@ module EDL
       self.class.new(cpy)
     end
     
+    # Return the same EDL, with events renumbered starting from 001
     def renumbered
-      renumed = @events.dup
+      renumed = self.dup
       pad = renumed.length.to_s.length
       pad = 3 if pad < 3
       
       (0...renumed.length).map{|e| renumed[e].num = "%0#{pad}d" % (e+1) }
-      x = self.class.new(renumed)
-      puts x.inspect
-      x
+      self.class.new(renumed)
     end
         
     # Return the same EDL with all timewarps expanded to native length. Clip length
@@ -69,8 +71,7 @@ module EDL
     # (so this is best used in concert with the original EDL where record TC is pristine)
     def without_timewarps
       self.class.new(
-        @events.map do | e |
-          
+        map do | e |
           if e.has_timewarp?
             repl = e.copy_properties_to(e.class.new)
             from, to = e.timewarp.actual_src_start_tc, e.timewarp.actual_src_end_tc
@@ -86,7 +87,7 @@ module EDL
     # Return the same EDL without AX, BL and other GEN events (like slug, text and solids).
     # Usually used in concert with "without_transitions"
     def without_generators
-      self.class.new(@events.reject{|e| e.generator? })
+      self.class.new(self.reject{|e| e.generator? })
     end
     
     # Return the list of clips used by this EDL at full capture length
@@ -97,9 +98,9 @@ module EDL
     # Return the same EDL with the first event starting at 00:00:00:00 and all subsequent events
     # shifted accordingly
     def from_zero
-      shift_by = @events[0].rec_start_tc
+      shift_by = self[0].rec_start_tc
       self.class.new(
-        @events.map do | original |
+        map do | original |
           e = original.dup
           e.rec_start_tc =  (e.rec_start_tc - shift_by)
           e.rec_end_tc =  (e.rec_end_tc - shift_by)
@@ -111,7 +112,7 @@ module EDL
     # Return the same EDL with neighbouring clips joined at cuts where applicable (if a clip
     # is divided in two pieces it will be spliced). Most useful in combination with without_timewarps
     def spliced
-      spliced_edl = @events.inject([]) do | spliced, cur  |
+      spliced_edl = inject([]) do | spliced, cur  |
         latest = spliced[-1]
         # Append to latest if splicable
         if latest && (latest.reel == cur.reel) && (cur.src_start_tc == (latest.src_end_tc + 1))
@@ -126,112 +127,7 @@ module EDL
     end
   end
   
-  # Represents an edit event
-  class Event
-    attr_accessor :num, 
-      :reel, 
-      :track,
-      :src_start_tc, 
-      :src_end_tc, 
-      :rec_start_tc, 
-      :rec_end_tc,
-      :comments,
-      :original_line
-    
-    def to_s
-      %w( num reel track src_start_tc src_end_tc rec_start_tc rec_end_tc).map{|a| self.send(a).to_s}.join("  ")
-    end
-    
-    def inspect
-      to_s
-    end
-    
-    def copy_properties_to(evt)
-      %w( num reel track src_start_tc src_end_tc rec_start_tc rec_end_tc).each do | k |
-        evt.send("#{k}=", send(k)) if evt.respond_to?(k)
-      end
-      evt
-    end
-  end
-  
-  class Clip < Event
-    attr_accessor :clip_name, :timewarp
-    attr_accessor :transition
-    
-    # Returns true if the clip starts with a transiton (not a jump cut)
-    def has_transition?
-      !transition.nil?
-    end
-    
-    def has_timewarp?
-      !timewarp.nil?
-    end
-    
-    def black?
-      reel == 'BL'
-    end
-    alias_method :slug?, :black?
-    
-    def length
-      (rec_end_tc - rec_start_tc).to_i
-    end
-    
-    def generator?
-      black? || (%(AX GEN).include?(reel))
-    end
-  end
-  
-  # Represents a transition. We currently only support dissolves and SMPTE wipes
-  # Will be avilable as EDL::Clip#transition
-  class Transition
-    attr_accessor :duration, :effect
-  end
-  
-  # Represents a dissolve
-  class Dissolve < Transition; end
-  
-  # Represents an SMPTE wipe
-  class Wipe < Transition
-    attr_accessor :smpte_wipe_index
-  end
-  
-  # Represents a timewarp
-  class Timewarp
-    attr_accessor :actual_framerate
-    attr_accessor :clip
-    
-    def speed_in_percent
-      (actual_framerate.to_f / DEFAULT_FPS.to_f ) * 100
-    end
-    
-    # Get the actual end of source that is needed for the timewarp to be computed properly,
-    # round up to not generate stills at ends of clips
-    def actual_src_end_tc
-      unless reverse?
-        clip.src_start_tc + actual_length_of_source
-      else
-        clip.src_start_tc
-      end
-    end
-    
-    def actual_src_start_tc
-      unless reverse?
-        clip.src_start_tc
-      else
-        clip.src_start_tc - actual_length_of_source
-      end
-    end
-    
-    # Returns the true number of frames that is needed to complete the timewarp edit
-    def actual_length_of_source
-      length_in_edit = (clip.src_end_tc - clip.src_start_tc).to_i
-      ((length_in_edit / 25.0) * actual_framerate).ceil.abs
-    end
-    
-    def reverse?
-      actual_framerate < 0
-    end
-  end
+  #:stopdoc:
   
   # A generic matcher
   class Matcher
@@ -246,7 +142,7 @@ module EDL
     end
     
     def matches?(line)
-      line =~ @regexp
+      !!(line =~ @regexp)
     end
     
     def apply(stack, line)
@@ -254,6 +150,18 @@ module EDL
     end
   end
   
+  # EDL clip comment matcher, a generic one
+  class CommentMatcher < Matcher
+    def initialize
+      super(/\* (.+)/)
+    end
+    
+    def apply(stack, line)
+      stack[-1].comments << line.scan(@regexp).flatten.pop.strip
+    end
+  end
+
+  # Clip name matcher
   class NameMatcher < Matcher
     def initialize
       super(/\* FROM CLIP NAME:(\s+)(.+)/)
@@ -261,6 +169,7 @@ module EDL
     
     def apply(stack, line)
       stack[-1].clip_name = line.scan(@regexp).flatten.pop.strip
+      CommentMatcher.new.apply(stack, line)
     end
   end
   
@@ -271,6 +180,7 @@ module EDL
     
     def apply(stack, line)
       stack[-1].transition.effect = line.scan(@regexp).flatten.pop.strip
+      CommentMatcher.new.apply(stack, line)
     end
   end
   
@@ -297,7 +207,7 @@ module EDL
       end
       
       evt_with_tw = stack.reverse.find{|e| e.src_start_tc == tw_start_source_tc && e.reel == from_reel }
-
+      
       unless evt_with_tw
         raise ApplyError, "Cannot find event marked by timewarp", line
       else
@@ -326,7 +236,7 @@ module EDL
     def apply(stack, line)
       
       matches = line.scan(@regexp).shift
-      props = {:original_line => line}
+      props = {}
       
       # FIrst one is the event number
       props[:num] = matches.shift
@@ -355,28 +265,33 @@ module EDL
       # Then the timecodes
       [:src_start_tc, :src_end_tc, :rec_start_tc, :rec_end_tc].each do | k |
         begin
-          PROPS[K] = edl::pARSER.TIMECODE_FROM_LINE_ELEMENTS(MATCHES, @FPS)
+          props[k] = EDL::Parser.timecode_from_line_elements(matches, @fps)
         rescue Timecode::Error => e 
           raise ApplyError, "Cannot parse timecode - #{e}", line
         end
       end
       
-      evt = Clip.new
+      evt = Event.new
       transition_idx = props.delete(:transition)
       evt.transition = case transition_idx
         when 'D'
           d = Dissolve.new
-          d.duration = props.delete(:duration)
+          d.duration = props.delete(:duration).to_i
           d
-        when /W/
+        when /W(\d+)/
           w = Wipe.new
-          w.duration = props.delete(:duration)
+          w.duration = props.delete(:duration).to_i
           w.smpte_wipe_index = transition_idx.gsub(/W/, '')
           w
         else
           nil
       end
       
+      # Give a hint on the incoming clip as well
+      if evt.transition && stack[-1]
+        stack[-1].outgoing_transition_duration = evt.transition.duration
+      end
+      
       props.each_pair { | k, v | evt.send("#{k}=", v) }
       
       stack << evt
@@ -384,6 +299,9 @@ module EDL
     end
   end
   
+  #:startdoc:
+  
+  # Is used to parse an EDL
   class Parser
     
     attr_reader :fps
@@ -394,12 +312,15 @@ module EDL
       @fps = with_fps
     end
     
-    def get_matchers
-      [ EventMatcher.new(@fps), EffectMatcher.new, NameMatcher.new, TimewarpMatcher.new(@fps) ]
+    def get_matchers #:nodoc:
+      [ EventMatcher.new(@fps), EffectMatcher.new, NameMatcher.new, TimewarpMatcher.new(@fps), CommentMatcher.new ]
     end
     
+    # Parse a passed File or IO object line by line, or the whole string
     def parse(io)
-      stack, matchers = [], get_matchers
+      return parse(StringIO.new(io.to_s)) unless io.respond_to?(:eof?)
+      
+      stack, matchers = List.new, get_matchers
       until io.eof?
         current_line = io.gets.strip
         matchers.each do | matcher |
@@ -412,15 +333,14 @@ module EDL
           end
         end
       end
-      
-      return List.new(stack)
+      stack
     end
     
-    def self.timecode_from_line_elements(elements, fps)
-      args = (0..3).map{|_| elements.shift.to_i} + [fps]
+    # Init a Timecode object from the passed elements with the passed framerate
+    def self.timecode_from_line_elements(elements, fps) #:nodoc:
+      args = (0..3).map{|_| elements.shift.to_i} + [fps.to_f]
       Timecode.at(*args)
     end
   end
-  
-  
+
 end

data/lib/edl/cutter.rb

@@ -1,6 +1,6 @@
 module EDL
   # Can chop an offline edit into events according to the EDL
-  class Cutter
+  class Cutter #:nodoc:
     def initialize(source_path)
       @source_path = source_path
     end
@@ -18,7 +18,7 @@ module EDL
     end
   end
   
-  class FFMpegCutter < Cutter
+  class FFMpegCutter < Cutter #:nodoc:
     def cut_segment(evt, start_at, end_at)
       source_dir, source_file = File.dirname(@source_path), File.basename(@source_path)
       dest_segment = File.join(source_dir, ('%s_%s' % [evt.num, source_file]))

data/lib/edl/event.rb

@@ -0,0 +1,132 @@
+module EDL
+  # Represents an edit event
+  class Event
+    # Event number as in the EDL
+    attr_accessor :num
+
+    # Reel name as in the EDL
+    attr_accessor :reel
+  
+    # Event tracks as in the EDL
+    attr_accessor :track
+
+    # Source start timecode of the start frame as in the EDL,
+    # no timewarps or dissolves included
+    attr_accessor :src_start_tc
+
+    # Source end timecode of the last frame as in the EDL,
+    # no timewarps or dissolves included
+    attr_accessor :src_end_tc
+
+    # Record start timecode of the event in the master as in the EDL
+    attr_accessor :rec_start_tc 
+
+    # Record end timecode of the event in the master as in the EDL,
+    # outgoing transition is not included
+    attr_accessor :rec_end_tc
+
+    # Array of comment lines verbatim (all comments are included)
+    attr_accessor :comments
+
+    # Clip name contained in FROM CLIP NAME: comment
+    attr_accessor :clip_name
+
+    # Timewarp metadata (an EDL::Timewarp), or nil if no retime is made
+    attr_accessor :timewarp
+
+    # Incoming transition metadata (EDL::Transition), or nil if no transition is used
+    attr_accessor :transition
+  
+    # How long is the incoming transition on the next event
+    attr_accessor :outgoing_transition_duration
+    
+    def initialize(opts = {})
+      opts.each_pair{|k,v| send("#{k}=", v) }
+      yield(self) if block_given?
+    end
+    
+    # Output a textual description (will not work as an EDL line!)
+    def to_s
+      %w( num reel track src_start_tc src_end_tc rec_start_tc rec_end_tc).map{|a| self.send(a).to_s}.join("  ")
+    end
+  
+    def inspect
+      to_s
+    end
+  
+    def comments #:nodoc:
+      @comments ||= []
+      @comments
+    end
+    
+    def outgoing_transition_duration #:nodoc:
+      @outgoing_transition_duration || 0
+    end
+  
+    # Is the clip reversed in the edit?
+    def reverse?
+      (timewarp && timewarp.reverse?)
+    end
+    alias_method :reversed?, :reverse?
+  
+    def copy_properties_to(evt)
+      %w( num reel track src_start_tc src_end_tc rec_start_tc rec_end_tc).each do | k |
+        evt.send("#{k}=", send(k)) if evt.respond_to?(k)
+      end
+      evt
+    end
+  
+    # Returns true if the clip starts with a transiton (not a jump cut)
+    def has_transition?
+      !transition.nil?
+    end
+  
+    # Returns true if the clip ends with a transition (if the next clip starts with a transition)
+    def ends_with_transition?
+      outgoing_transition_duration > 0
+    end
+  
+    # Returns true if the clip has a timewarp (speed ramp, motion memory, you name it)
+    def has_timewarp?
+      !timewarp.nil?
+    end
+  
+    # Is this a black slug?
+    def black?
+      reel == 'BL'
+    end
+    alias_method :slug?, :black?
+  
+    # Get the record length of the event (how long it occupies in the EDL without an eventual outgoing transition)
+    def rec_length
+      (rec_end_tc.to_i - rec_start_tc.to_i).to_i
+    end
+
+    # Get the record length of the event (how long it occupies in the EDL without an eventual outgoing transition)
+    def rec_length_with_transition
+      rec_length + outgoing_transition_duration.to_i
+    end
+  
+    # How long does the capture need to be to complete this event including timewarps and transitions
+    def src_length
+      @timewarp ? @timewarp.actual_length_of_source : rec_length_with_transition
+    end
+  
+    alias_method :capture_length, :src_length
+
+    # Capture from (and including!) this timecode to complete this event including timewarps and transitions
+    def capture_from_tc
+      timewarp ? timewarp.source_used_from : src_start_tc
+    end
+  
+    # Capture up to (but not including!) this timecode to complete this event including timewarps and transitions
+    def capture_to_tc
+      timewarp ? timewarp.source_used_upto : (src_start_tc + rec_length_with_transition)
+    end
+  
+    # Returns true if this event is a generator
+    def generator?
+      black? || (%(AX GEN).include?(reel))
+    end
+  end
+end