timecode 0.1.0

data/History.txt

@@ -0,0 +1,6 @@
+=== 1.0.0 / 2008-12-15
+
+* 1 major enhancement
+
+  * Birthday!
+

data/Manifest.txt

@@ -0,0 +1,6 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/timecode.rb
+test/test_timecode.rb

data/README.txt

@@ -0,0 +1,48 @@
+= timecode
+
+* http://projects.juli.nl/timecode
+
+== DESCRIPTION:
+
+Value class for SMPTE timecode information
+
+== SYNOPSIS:
+
+  tc = Timecode.parse("00:00:10:12", fps = 25)
+  tc.total #=> 262
+  
+  plus_ten = tc + Timecode.parse("10h", fps = 25)
+  plus_ten #=> "10:00:10:12"
+  
+== PROBLEMS:
+
+Currently there is no support for drop-frame timecode
+
+== INSTALL:
+
+* sudo gem install timecode
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Julik Tarkhanov
+
+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/Rakefile

@@ -0,0 +1,9 @@
+require 'rubygems'
+require 'hoe'
+require './lib/timecode.rb'
+
+Hoe.new('timecode', Timecode::VERSION) do |p|
+  p.developer('Julik', 'me@julik.nl')
+  p.extra_deps.reject! {|e| e[0] == 'hoe' }
+  p.rubyforge_name = 'wiretap'
+end

data/lib/timecode.rb

@@ -0,0 +1,327 @@
+# Timecode is a convenience object for calculating SMPTE timecode natively. It is used in
+# various StoryTool models and templates, offers string output and is immutable.
+#
+# The promise is that you only have to store two values to know the timecode - the amount
+# of frames and the framerate. An additional perk might be to save the dropframeness,
+# but we avoid that at this point.
+#
+# You can calculate in timecode objects ass well as with conventional integers and floats.
+# Timecode is immutable and can be used as a value object. Timecode objects are sortable.
+#
+# Here's how to use it with ActiveRecord (your column names will be source_tc_frames_total and tape_fps)
+#
+#   composed_of :source_tc, :class_name => 'Timecode',
+#     :mapping => [%w(source_tc_frames total), %w(tape_fps fps)]
+
+class Timecode
+  VERSION = '0.1.0'
+
+  include Comparable
+  DEFAULT_FPS = 25
+  COMPLETE_TC_RE = /^(\d{1,2}):(\d{1,2}):(\d{1,2}):(\d{1,2})$/
+  
+  # All Timecode lib errors inherit from this
+  class Error < RuntimeError; end
+  
+  # Will be raised for functions that are not supported
+  class TimecodeLibError < Error; end
+
+  # Gets raised if timecode is out of range (like 100 hours long)
+  class RangeError < Error; end
+
+  # Self-explanatory
+  class NonPositiveFps < RangeError; end
+
+  # Gets raised when float frame count is passed
+  class FrameIsWhole < RangeError; end
+
+  # Gets raised when you divide by zero
+  class TcIsZero < ZeroDivisionError; end
+
+  # Gets raised when a timecode cannot be parsed
+  class CannotParse < Error; end
+
+  # Gets raised when you try to compute two timecodes with different framerates together
+  class WrongFramerate < ArgumentError; end
+
+  # Well well...
+  class MethodRequiresTimecode < ArgumentError; end
+  
+  # Initialize a new Timecode. If a string is passed, it will be parsed, an integer
+  # will be interpreted as the total number of frames
+  def self.new(total_or_string = 0, fps = DEFAULT_FPS)
+    if total_or_string.nil?
+      new(0, fps)
+    elsif total_or_string.is_a?(String)
+      parse(total_or_string, fps)
+    else
+      super(total_or_string, fps)
+    end
+  end
+  
+  def initialize(total = 0, fps = DEFAULT_FPS) # :nodoc:
+    if total.is_a?(Float)
+      raise FrameIsWhole, "the number of frames cannot be partial (Integer value needed)"
+    end
+    
+    raise RangeError, "Timecode cannot be negative" if total.to_f < 0
+    raise WrongFramerate, "FPS cannot be zero" if fps.zero?
+    @total, @fps = total, fps 
+    @value = validate!
+    freeze
+  end
+  
+  def inspect # :nodoc:
+    super.gsub(/@fps/, self.to_s + ' @fps').gsub(/ @value=\[(.+)\],/, '')
+  end
+  
+  TIME_FIELDS = 7 # :nodoc:
+  
+  class << self
+    
+    # Parse timecode and return zero if none matched
+    def soft_parse(input, with_fps = DEFAULT_FPS)
+      parse(input) rescue new(0, with_fps)
+    end
+      
+    # Parse timecode entered by the user. Will raise if the string cannot be parsed.
+    def parse(input, with_fps = DEFAULT_FPS)
+      # Drop frame goodbye
+      raise TimecodeLibError, "We do not support drop frame" if (input =~ /\;/)
+      
+      hrs, mins, secs, frames = 0,0,0,0
+      atoms = []
+      
+      # 10h 20m 10s 1f
+      if input =~ /\s/
+        return input.split.map{|part|  parse(part, with_fps) }.inject { |sum, p| sum + p.total }
+      # 10s
+      elsif input =~ /^(\d+)s$/
+        return new(input.to_i * with_fps, with_fps)
+      # 10h
+      elsif input =~ /^(\d+)h$/i
+        return new(input.to_i * 60 * 60 * with_fps, with_fps)
+      # 20m
+      elsif input =~ /^(\d+)m$/i
+        return new(input.to_i * 60 * with_fps, with_fps)
+      # 60f - 60 frames, or 2 seconds and 10 frames
+      elsif input =~ /^(\d+)f$/i
+        return new(input.to_i, with_fps)
+      # A bunch of integers
+      elsif (input =~ /^(\d+)$/)
+        ints = input.split(//)
+        atoms.unshift [ints.pop, ints.pop].reverse.join.to_i
+        atoms.unshift [ints.pop, ints.pop].reverse.join.to_i
+        atoms.unshift [ints.pop, ints.pop].reverse.join.to_i
+        atoms.unshift [ints.pop, ints.pop].reverse.join.to_i
+      elsif (input =~ COMPLETE_TC_RE)
+        atoms = input.scan(COMPLETE_TC_RE).to_a.flatten
+      else
+        raise CannotParse, "Cannot parse #{input} into timecode, no match"
+      end
+      
+      if atoms.any?
+        hrs, mins, secs, frames = atoms.map{|e| e.to_i}
+      else
+        raise CannotParse, "Cannot parse #{input} into timecode, atoms were empty"
+      end
+      
+      at(hrs, mins, secs, frames, with_fps)
+    end
+    
+    # Initialize a Timecode object at this specfic timecode
+    def at(hrs, mins, secs, frames, with_fps = DEFAULT_FPS)
+      case true
+        when hrs > 99
+          raise RangeError, "There can be no more than 99 hours, got #{hrs}"
+        when mins > 59
+          raise RangeError, "There can be no more than 59 minutes, got #{mins}"
+        when secs > 59
+          raise RangeError, "There can be no more than 59 seconds, got #{secs}"
+        when frames > (with_fps -1)
+          raise RangeError, "There can be no more than #{with_fps -1} frames @#{with_fps}, got #{frames}"
+      end
+    
+      total = (hrs*(60*60*with_fps) +  mins*(60*with_fps) + secs*with_fps + frames).round
+      new(total, with_fps)
+    end
+    
+    def parse_with_fractional_seconds(tc_with_fractions_of_second, fps = DEFAULT_FPS)
+      fraction_expr = /\.(\d+)$/
+      fraction_part = ('.' + tc_with_fractions_of_second.scan(fraction_expr)[0][0]).to_f
+
+      seconds_per_frame = 1.0 / fps.to_f
+      frame_idx = (fraction_part / seconds_per_frame).floor
+
+      tc_with_frameno = tc_with_fractions_of_second.gsub(fraction_expr, ":#{frame_idx}")
+
+      parse(tc_with_frameno, fps)
+    end
+  
+    # create a timecode from seconds. Seconds can be float (this is how current time is supplied by
+    # QuickTime and other systems which have non-frame-based timescales)
+    def from_seconds(seconds_float, the_fps = DEFAULT_FPS)
+      total_frames = (seconds_float.to_f * the_fps.to_f).ceil
+      new(total_frames, the_fps)
+    end
+  
+    
+    # Some systems (like SGIs) and DPX format store timecode as unsigned integer, bit-packed
+    def from_uint(uint)
+      shift = 4 * TIME_FIELDS
+      tc_elements = (0..TIME_FIELDS).map do 
+        part = ((uint >> shift) & 0x0F)
+        shift -= 4
+        part
+      end.join.scan(/(\d{2})/).flatten.map{|e| e.to_i}
+      at(*tc_elements)
+    end
+  end
+  
+  # is the timecode at 00:00:00:00
+  def zero?
+    @total.zero?
+  end
+  
+  # get total frame count
+  def total
+    to_f
+  end
+  
+  #get FPS
+  def fps
+    @fps
+  end
+    
+  # get the number of frames
+  def frames
+    value_parts[3]
+  end
+  
+  # get the number of seconds
+  def seconds
+    value_parts[2]
+  end
+  
+  # get the number of minutes
+  def minutes
+    value_parts[1]
+  end
+  
+  # get the number of hours
+  def hours
+    value_parts[0]
+  end
+  
+  # get frame interval in fractions of a second
+  def frame_interval
+    1.0/@fps
+  end
+  
+  # get the timecode as bit-packed unsigned int (suitable for DPX and SGI)
+  def to_uint
+    elements = (("%02d" * 4) % [hours,minutes,seconds,frames]).split(//).map{|e| e.to_i }
+    uint = 0
+    elements.each do | el | 
+      uint = ((uint >> el))
+    end
+    uint
+  end
+  
+  # Convert to different framerate based on the total frames. Therefore,
+  # 1 second of PAL video will convert to 25 frames of NTSC (this 
+  # is suitable for PAL to film TC conversions and back).
+  # It does not account for pulldown or anything in that sense, because
+  # then you need to think about cadences and such
+  def convert(new_fps)
+    raise NonPositiveFps, "FPS cannot be less than 0" if new_fps < 1
+    self.class.new((total/fps)*new_fps, new_fps)
+  end
+  
+  # get formatted SMPTE timecode
+  def to_s
+    "%02d:%02d:%02d:%02d" % value_parts
+  end
+  
+  # get total frames as float
+  def to_f
+    @total
+  end
+
+  # get total frames as integer
+  def to_i
+    @total
+  end
+  
+  # add number of frames (or another timecode) to this one
+  def +(arg)
+    if (arg.is_a?(Timecode) && arg.fps == @fps)
+      Timecode.new(@total+arg.total, @fps)
+    elsif (arg.is_a?(Timecode))
+      raise WrongFramerate, "You are calculating timecodes with different framerates"
+    else
+      Timecode.new(@total + arg, @fps)
+    end
+  end
+  
+  # Subtract a number of frames
+  def -(arg)
+    if (arg.is_a?(Timecode) &&  arg.fps == @fps)
+      Timecode.new(@total-arg.total, @fps)
+    elsif (arg.is_a?(Timecode))
+      raise WrongFramerate, "You are calculating timecodes with different framerates"
+    else
+      Timecode.new(@total-arg, @fps)
+    end
+  end
+  
+  # Multiply the timecode by a number
+  def *(arg)
+    raise RangeError, "Timecode multiplier cannot be negative" if (arg < 0)
+    Timecode.new(@total*arg.to_i, @fps)
+  end
+  
+  # Get the next frame
+  def succ
+    self.class.new(@total + 1)
+  end
+  
+  # Slice the timespan in pieces
+  def /(arg)
+    Timecode.new(@total/arg, @fps)
+  end
+  
+  # Timecodes can be compared to each other
+  def <=>(other_tc)
+    if other_tc.is_a?(Timecode)
+      self.total <=> other_tc.class.new(other_tc.total, self.fps).total
+    else
+      self.total <=> other_tc
+    end
+  end
+
+  private
+  
+  # Formats the actual timecode output from the number of frames
+  def validate!
+    frames = @total
+    secs = (@total.to_f/@fps).floor
+    frames-=(secs*@fps)
+    mins = (secs/60).floor
+    secs -= (mins*60)
+    hrs = (mins/60).floor
+    mins-= (hrs*60)
+  
+    raise RangeError, "Timecode cannot be longer that 99 hrs" if hrs > 99 
+    raise RangeError, "More than 59 minutes" if mins > 59 
+    raise RangeError, "More than 59 seconds" if secs > 59
+    raise TimecodeLibError, "More than #{@fps.to_s} frames (#{frames}) in the last second" if frames >= @fps
+  
+    [hrs, mins, secs, frames]
+  end
+  
+  def value_parts
+    @value ||= validate!
+  end
+  
+end

data/test/test_timecode.rb

@@ -0,0 +1,160 @@
+require 'test/unit'
+require 'rubygems'
+require 'timecode'
+
+# for Fixnum#hours
+require 'active_support'
+
+class TimecodeTest < Test::Unit::TestCase
+  
+  def test_basics
+    five_seconds_of_pal = 5.seconds * 25
+    tc = Timecode.new(five_seconds_of_pal, 25)
+    assert_equal 0, tc.hours
+    assert_equal 0, tc.minutes
+    assert_equal 5, tc.seconds
+    assert_equal 0, tc.frames
+    assert_equal five_seconds_of_pal, tc.total
+    assert_equal "00:00:05:00", tc.to_s
+    
+    one_and_a_half_hour_of_hollywood = 90.minutes * 24
+
+    film_tc = Timecode.new(one_and_a_half_hour_of_hollywood, 24)
+    assert_equal 1, film_tc.hours
+    assert_equal 30, film_tc.minutes
+    assert_equal 0, film_tc.seconds
+    assert_equal 0, film_tc.frames
+    assert_equal one_and_a_half_hour_of_hollywood, film_tc.total
+    assert_equal "01:30:00:00", film_tc.to_s
+
+    assert_equal "01:30:00:04", (film_tc + 4).to_s
+    assert_equal "01:30:01:04", (film_tc + 28).to_s
+
+    assert_raise(Timecode::WrongFramerate) do
+      tc + film_tc
+    end
+    
+    two_seconds_and_five_frames_of_pal = ((2.seconds * 25) + 5)
+    pal_tc = Timecode.new(two_seconds_and_five_frames_of_pal, 25)
+    assert_nothing_raised do
+      added_tc = pal_tc + tc
+      assert_equal "00:00:07:05", added_tc.to_s
+    end
+
+  end
+    
+  def test_parse
+    simple_tc = "00:10:34:10"
+    
+    assert_nothing_raised do
+      @tc = Timecode.parse(simple_tc)
+      assert_equal simple_tc, @tc.to_s
+    end
+  
+    bad_tc = "00:76:89:30"
+    unknown_gobbledygook = "this is insane"
+    
+    assert_raise(Timecode::CannotParse) do
+      tc = Timecode.parse(unknown_gobbledygook, 25)
+    end
+    
+    assert_raise(Timecode::RangeError) do
+      Timecode.parse(bad_tc, 25)
+    end
+  end
+  
+  def test_succ
+    assert_equal Timecode.new(23), Timecode.new(22).succ
+  end
+  
+  def test_zero
+    assert Timecode.new(0).zero?
+    assert !Timecode.new(1).zero?
+    assert !Timecode.new(1000).zero?
+  end
+  
+  def test_parse_from_numbers
+    assert_equal Timecode.new(10), Timecode.parse("10")
+    assert_equal Timecode.new(60), Timecode.parse("210")
+    assert_equal "10:10:10:10", Timecode.parse("10101010").to_s
+  end
+  
+  def test_parse_with_f
+    assert_equal Timecode.new(60), Timecode.parse("60f")
+  end
+  
+  def test_parse_s
+    assert_equal Timecode.new(50), Timecode.parse("2s")
+    assert_equal Timecode.new(60), Timecode.parse("2s", 30)
+  end
+
+  def test_parse_m
+    assert_equal Timecode.new(25 * 60 * 3), Timecode.parse("3m")
+  end
+
+  def test_parse_h
+    assert_equal Timecode.new(25 * 60 * 60 * 3), Timecode.parse("3h")
+  end
+  
+  def test_parse_from_elements
+    assert_equal '01:00:00:04', Timecode.parse("1h 4f").to_s
+    assert_equal '01:00:00:04', Timecode.parse("4f 1h").to_s
+    assert_equal '01:00:01:04', Timecode.parse("29f 1h").to_s
+  end
+  
+  def test_float_framerate
+    tc = Timecode.new(25, 12.5)
+    assert_equal "00:00:02:00", tc.to_s
+  end
+  
+  def test_timecode_with_nil_gives_zero
+    assert_equal Timecode.new(0), Timecode.new(nil)
+  end
+  
+  def test_parse_fractional_tc
+    fraction = "00:00:07.1"
+    tc = Timecode.parse_with_fractional_seconds(fraction, 10)
+    assert_equal "00:00:07:01", tc.to_s
+
+    fraction = "00:00:07.5"
+    tc = Timecode.parse_with_fractional_seconds(fraction, 10)
+    assert_equal "00:00:07:05", tc.to_s
+    
+    fraction = "00:00:07.04"
+    tc = Timecode.parse_with_fractional_seconds(fraction, 12.5)
+    assert_equal "00:00:07:00", tc.to_s
+    
+    fraction = "00:00:07.16"
+    tc = Timecode.parse_with_fractional_seconds(fraction, 12.5)
+    assert_equal "00:00:07:02", tc.to_s
+  end
+  
+# def test_parse_with_calculation
+#   tc = Timecode.parse_with_calculation("00:00:00:15 +2f")
+#   assert_equal Timecode.new(17), tc
+# end
+  
+  def test_from_uint
+    uint, tc = 87310853, Timecode.at(5,34,42,5)
+    assert_equal tc, Timecode.from_uint(uint)
+  end
+  
+  def test_to_uint
+    uint, tc = 87310853, Timecode.at(5,34,42,5)
+    assert_equal uint, tc.to_uint
+  end
+  
+  def test_from_seconds
+    fraction = 7.1
+    tc = Timecode.from_seconds(fraction, 10)
+    assert_equal "00:00:07:01", tc.to_s
+
+    fraction = 7.5
+    tc = Timecode.from_seconds(fraction, 10)
+    assert_equal "00:00:07:05", tc.to_s
+
+    fraction = 7.16
+    tc = Timecode.from_seconds(fraction, 12.5)
+    assert_equal "00:00:07:02", tc.to_s
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: timecode
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Julik
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-12-19 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.8.2
+    version: 
+description: Value class for SMPTE timecode information
+email: 
+- me@julik.nl
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- lib/timecode.rb
+- test/test_timecode.rb
+has_rdoc: true
+homepage: http://projects.juli.nl/timecode
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: wiretap
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: Value class for SMPTE timecode information
+test_files: 
+- test/test_timecode.rb