julik-timecode 0.1.4

data/History.txt

@@ -0,0 +1,26 @@
+* Tests remade using test/spec
+
+=== 0.1.4 / 2000-01-01
+
+* Expanded test coverage
+* Some formatting/doc improvements
+
+=== 0.1.3 / 2008-12-25
+
+* Implement the format FFmpeg uses (fractional seconds instead of frames)
+
+=== 0.1.2 / 2008-12-25
+
+* Fix to_uint
+* Always use float frame rates and rely on a small delta for comparison
+
+=== 0.1.1 / 2008-12-15
+
+* Allow passing framerate to from_uint
+
+=== 0.1.0 / 2008-12-15
+
+* 1 major enhancement
+
+  * Birthday!
+

data/Manifest.txt

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

data/README.txt

@@ -0,0 +1,48 @@
+= timecode
+
+* http://wiretap.rubyforge.org/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,15 @@
+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.extra_deps << 'test-spec'
+  p.rubyforge_name = 'wiretap'
+  p.remote_rdoc_dir = 'timecode'
+end
+
+task "specs" do
+  `specrb test/* --rdox > SPECS.txt`
+end

data/SPECS.txt

@@ -0,0 +1,74 @@
+
+== Timecode on instantiation should
+* be instantable from int
+* always coerce FPS to float
+* create a zero TC with no arguments
+
+== An existing Timecode should
+* report that the framerates are in delta
+* validate equality based on delta
+* report total as it's to_i
+* support hours
+* support minutes
+* support seconds
+* support frames
+* report frame_interval as a float
+
+== A Timecode of zero should
+* properly respond to zero?
+
+== An existing TImecode on inspection should
+* properly present himself via inspect
+* properly print itself
+
+== An existing Timecode used within ranges should
+* properly provide successive value that is one frame up
+* work as a range member
+
+== A Timecode on conversion should
+* copy itself with a different framerate
+
+== A Timecode on calculations should
+* support addition
+* should raise on addition if framerates do not match
+* when added with an integer instead calculate on total
+* support subtraction
+* on subtraction of an integer instead calculate on total
+* raise when subtracting a Timecode with a different framerate
+* support multiplication
+* raise when the resultig Timecode is negative
+* yield a Timecode when divided by an Integer
+* yield a number when divided by another Timecode
+
+== A Timecode used with fractional number of seconds
+* should properly return fractional seconds
+* properly translate to frames when instantiated from fractional seconds
+
+== Timecode.at() should
+* disallow more than 99 hrs
+* disallow more than 59 minutes
+* disallow more than 59 seconds
+* disallow more frames than what the framerate permits
+* propery accept usable values
+
+== Timecode.parse() should
+* handle complete SMPTE timecode
+* refuse to handle timecode that is out of range for the framerate
+* parse a row of numbers as parts of a timecode starting from the right
+* parse a number with f suffix as frames
+* parse a number with s suffix as seconds
+* parse a number with m suffix as minutes
+* parse a number with h suffix as hours
+* parse different suffixes as a sum of elements
+* parse timecode with fractional second instead of frames
+* raise on improper format
+
+== Timecode.soft_parse should
+* parse the timecode
+* not raise on improper format and return zero TC instead
+
+== Timecode with unsigned integer conversions should
+* parse from a 4x4bits packed 32bit unsigned int
+* properly convert itself back to 4x4 bits 32bit unsigned int
+
+48 specifications (80 requirements), 0 failures

data/lib/timecode.rb

@@ -0,0 +1,342 @@
+# Timecode is a convenience object for calculating SMPTE timecode natively. 
+# 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.4'
+
+  include Comparable
+  
+  DEFAULT_FPS = 25.0
+  
+  #:stopdoc:
+  NTSC_FPS = (30.0 * 1000 / 1001).freeze
+  ALLOWED_FPS_DELTA = (0.001).freeze
+  
+  COMPLETE_TC_RE = /^(\d{2}):(\d{2}):(\d{2}):(\d{2})$/
+  DF_TC_RE = /^(\d{1,2}):(\d{1,2}):(\d{1,2});(\d{2})$/
+  FRACTIONAL_TC_RE = /^(\d{2}):(\d{2}):(\d{2}).(\d{1,8})$/
+  
+  WITH_FRACTIONS_OF_SECOND = "%02d:%02d:%02d.%02d"
+  WITH_FRAMES = "%02d:%02d:%02d:%02d"
+  #:startdoc:
+  
+  # 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
+
+  # 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
+  
+  # Initialize a new Timecode object with a certain amount of frames and a framerate
+  # will be interpreted as the total number of frames
+  def initialize(total = 0, fps = DEFAULT_FPS)
+    raise WrongFramerate, "FPS cannot be zero" if fps.zero?
+    
+    # If total is a string, use parse
+    raise RangeError, "Timecode cannot be negative" if total.to_i < 0
+    # Always cast framerate to float, and num of rames to integer
+    @total, @fps = total.to_i, fps.to_f
+    @value = validate!
+    freeze
+  end
+  
+  def inspect # :nodoc:
+    "#<Timecode:%s (%dF@%.2f)>" % [to_s, total, fps]
+  end
+  
+  TIME_FIELDS = 7 # :nodoc:
+  
+  class << self
+    
+    # Use initialize for integers and parsing for strings
+    def new(from, fps = DEFAULT_FPS)
+      from.is_a?(String) ? parse(from, fps) : super(from, fps)
+    end
+    
+    # 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.
+    # The following formats are supported:
+    # * 10h 20m 10s 1f (or any combination thereof) - will be disassembled to hours, frames, seconds and so on automatically
+    # * 123 - will be parsed as 00:00:01:23
+    # * 00:00:00:00 - will be parsed as zero TC
+    def parse(input, with_fps = DEFAULT_FPS)
+      # Drop frame goodbye
+      raise Error, "We do not support drop frame" if (input =~ /\;/)
+      
+      hrs, mins, secs, frames = 0,0,0,0
+      atoms = []
+      
+      # 00:00:00:00
+      if (input =~ COMPLETE_TC_RE)
+        atoms = input.scan(COMPLETE_TC_RE).to_a.flatten
+      # 00:00:00.0
+      elsif input =~ FRACTIONAL_TC_RE
+        parse_with_fractional_seconds(input, with_fps)
+      # 10h 20m 10s 1f
+      elsif 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
+      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
+    
+    # Parse a timecode with fractional seconds instead of frames. This is how ffmpeg reports
+    # a timecode
+    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, ":%02d" % frame_idx)
+
+      parse(tc_with_frameno, fps)
+    end
+  
+    # create a timecode from the number of seconds. 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. This method
+    # unpacks such an integer into a timecode.
+    def from_uint(uint, fps = DEFAULT_FPS)
+      tc_elements = (0..7).to_a.reverse.map do | multiplier | 
+        ((uint >> (multiplier * 4)) & 0x0F)
+      end.join.scan(/(\d{2})/).flatten.map{|e| e.to_i}
+
+      tc_elements << fps
+      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 32 bit 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.reverse.each_with_index do | p, i |
+      uint |= p << 4 * i 
+    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).
+  def convert(new_fps)
+    self.class.new(@total, new_fps)
+  end
+  
+  # get formatted SMPTE timecode
+  def to_s
+    WITH_FRAMES % 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) && framerate_in_delta(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) &&  framerate_in_delta(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, @fps)
+  end
+  
+  # Get the number of times a passed timecode fits into this time span (if performed with Timecode) or 
+  # a Timecode that multiplied by arg will give this one
+  def /(arg)
+    arg.is_a?(Timecode) ?  (@total / arg.total) : Timecode.new(@total /arg, @fps)
+  end
+  
+  # Timecodes can be compared to each other
+  def <=>(other_tc)
+    if other_tc.is_a?(Timecode) && framerate_in_delta(fps, other_tc.fps)
+      self.total <=> other_tc.total
+    else
+      self.total <=> other_tc
+    end
+  end
+  
+  # FFmpeg expects a fraction of a second as the last element instead of number of frames. Use this
+  # method to get the timecode that adheres to that expectation. The return of this method can be fed
+  # to ffmpeg directly.
+  #  Timecode.parse("00:00:10:24", 25).with_frames_as_fraction #=> "00:00:10.96"
+  def with_frames_as_fraction
+    vp = value_parts.dup
+    vp[-1] = (100.0 / @fps) * vp[-1]
+    WITH_FRACTIONS_OF_SECOND % vp
+  end
+  alias_method :with_fractional_seconds, :with_frames_as_fraction
+  
+  # Validate that framerates are within a small delta deviation considerable for floats
+  def framerate_in_delta(one, two)
+    (one.to_f - two.to_f).abs <= ALLOWED_FPS_DELTA
+  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 RangeError, "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,318 @@
+require 'test/unit'
+require 'rubygems'
+require 'test/spec'
+
+require File.dirname(__FILE__) + '/../lib/timecode'
+
+
+context "Timecode on instantiation should" do
+  
+  specify "be instantable from int" do
+    tc = Timecode.new(10)
+    tc.should.be.kind_of Timecode
+    tc.total.should.equal 10
+  end
+  
+  specify "always coerce FPS to float" do
+    Timecode.new(10, 24).fps.should.be.kind_of(Float)
+    Timecode.new(10, 25.0).fps.should.be.kind_of(Float)
+  end
+  
+  specify "create a zero TC with no arguments" do
+    Timecode.new(nil).should.be.zero?
+  end
+end
+
+context "An existing Timecode should" do
+  
+  before do
+    @five_seconds = Timecode.new(5*25, 25)
+    @one_and_a_half_film = (90 * 60) * 24
+    @film_tc = Timecode.new(@one_and_a_half_film, 24)
+  end
+  
+  
+  specify "report that the framerates are in delta" do
+    tc = Timecode.new(1)
+    tc.framerate_in_delta(25.0000000000000001, 25.0000000000000003).should.equal(true)
+  end
+ 
+  specify "validate equality based on delta" do
+    t1, t2 = Timecode.new(10, 25.0000000000000000000000000001), Timecode.new(10, 25.0000000000000000000000000002)
+    t1.should.equal(t2)
+  end
+  
+  specify "report total as it's to_i" do
+    Timecode.new(10).to_i.should.equal(10)
+  end
+  
+  specify "support hours" do
+    @five_seconds.should.respond_to :hours
+    @five_seconds.hours.should.equal 0
+    @film_tc.hours.should.equal 1
+  end
+
+  specify "support minutes" do
+    @five_seconds.should.respond_to :minutes
+    @five_seconds.minutes.should.equal 0
+    @film_tc.minutes.should.equal 30
+  end
+
+  specify "support seconds" do
+    @five_seconds.should.respond_to :seconds
+    @five_seconds.seconds.should.equal 5
+    @film_tc.seconds.should.equal 0
+  end
+  
+  specify "support frames" do
+    @film_tc.frames.should.equal 0
+  end
+  
+  specify "report frame_interval as a float" do
+    tc = Timecode.new(10)
+    tc.should.respond_to :frame_interval
+    
+    tc.frame_interval.should.be.close 0.04, 0.0001
+    tc = Timecode.new(10, 30)
+    tc.frame_interval.should.be.close 0.03333, 0.0001
+  end
+  
+end
+
+context "A Timecode of zero should" do
+  specify "properly respond to zero?" do
+    Timecode.new(0).should.respond_to :zero?
+    Timecode.new(0).should.be.zero
+    Timecode.new(1).should.not.be.zero
+  end
+end
+
+context "An existing TImecode on inspection should" do
+  specify "properly present himself via inspect" do
+    Timecode.new(10, 25).inspect.should.equal "#<Timecode:00:00:00:10 (10F@25.00)>"
+  end
+  
+  specify "properly print itself" do
+    Timecode.new(5, 25).to_s.should.equal "00:00:00:05"
+  end
+end
+
+context "An existing Timecode used within ranges should" do
+  specify "properly provide successive value that is one frame up" do
+    Timecode.new(10).succ.total.should.equal 11
+    Timecode.new(22).succ.should.equal Timecode.new(23) 
+  end
+  
+  specify "work as a range member" do
+    r = Timecode.new(10)...Timecode.new(20)
+    r.to_a.length.should.equal 10
+    r.to_a[4].should.equal Timecode.new(14)
+  end
+  
+end
+
+context "A Timecode on conversion should" do
+  specify "copy itself with a different framerate" do
+    tc = Timecode.new(40,25)
+    at24 = tc.convert(24)
+    at24.total.should.equal 40
+  end
+end
+
+context "A Timecode on calculations should" do
+  
+  specify "support addition" do
+    a, b = Timecode.new(24, 25.000000000000001), Timecode.new(22, 25.000000000000002)
+    (a + b).should.equal Timecode.new(24 + 22, 25.000000000000001)
+  end
+  
+  specify "should raise on addition if framerates do not match" do
+    lambda{ Timecode.new(10, 25) + Timecode.new(10, 30) }.should.raise(Timecode::WrongFramerate)
+  end
+  
+  specify "when added with an integer instead calculate on total" do
+    (Timecode.new(5) + 5).should.equal(Timecode.new(10))
+  end
+  
+  specify "support subtraction" do
+    a, b = Timecode.new(10), Timecode.new(4)
+    (a - b).should.equal Timecode.new(6)
+  end
+
+  specify "on subtraction of an integer instead calculate on total" do
+    (Timecode.new(15) - 5).should.equal Timecode.new(10)
+  end
+  
+  specify "raise when subtracting a Timecode with a different framerate" do
+    lambda { Timecode.new(10, 25) - Timecode.new(10, 30) }.should.raise(Timecode::WrongFramerate)
+  end
+  
+  specify "support multiplication" do
+    (Timecode.new(10) * 10).should.equal(Timecode.new(100))
+  end
+  
+  specify "raise when the resultig Timecode is negative" do
+    lambda { Timecode.new(10) * -200 }.should.raise(Timecode::RangeError)
+  end
+  
+  specify "yield a Timecode when divided by an Integer" do
+    v = Timecode.new(200) / 20
+    v.should.be.kind_of(Timecode)
+    v.should.equal Timecode.new(10)
+  end
+  
+  specify "yield a number when divided by another Timecode" do
+    v = Timecode.new(200) / Timecode.new(20)
+    v.should.be.kind_of(Numeric)
+    v.should.equal 10
+  end
+end
+
+context "A Timecode used with fractional number of seconds" do
+  
+  specify "should properly return fractional seconds" do
+    tc = Timecode.new(100 -1, fps = 25)
+    tc.frames.should.equal 24
+    
+    tc.with_frames_as_fraction.should.equal "00:00:03.96"
+    tc.with_fractional_seconds.should.equal "00:00:03.96"
+  end
+
+  specify "properly translate to frames when instantiated from fractional seconds" do
+    fraction = 7.1
+    tc = Timecode.from_seconds(fraction, 10)
+    tc.to_s.should.equal "00:00:07:01"
+
+    fraction = 7.5
+    tc = Timecode.from_seconds(fraction, 10)
+    tc.to_s.should.equal "00:00:07:05"
+
+    fraction = 7.16
+    tc = Timecode.from_seconds(fraction, 12.5)
+    tc.to_s.should.equal "00:00:07:02"
+  end
+
+end
+
+context "Timecode.at() should" do 
+  
+  specify "disallow more than 99 hrs" do
+    lambda{ Timecode.at(99,0,0,0) }.should.not.raise
+    lambda{ Timecode.at(100,0,0,0) }.should.raise(Timecode::RangeError)
+  end
+  
+  specify "disallow more than 59 minutes" do
+    lambda{ Timecode.at(1,60,0,0) }.should.raise(Timecode::RangeError)
+  end
+
+  specify "disallow more than 59 seconds" do
+    lambda{ Timecode.at(1,0,60,0) }.should.raise(Timecode::RangeError)
+  end
+  
+  specify "disallow more frames than what the framerate permits" do
+    lambda{ Timecode.at(1,0,60,25, 25) }.should.raise(Timecode::RangeError)
+    lambda{ Timecode.at(1,0,60,32, 30) }.should.raise(Timecode::RangeError)
+  end
+  
+  specify "propery accept usable values" do
+    Timecode.at(20, 20, 10, 5).to_s.should.equal "20:20:10:05"
+  end
+end
+
+
+context "Timecode.parse() should" do
+  
+  specify "handle complete SMPTE timecode" do
+    simple_tc = "00:10:34:10"
+    Timecode.parse(simple_tc).to_s.should.equal(simple_tc)
+  end
+
+  specify "handle complete SMPTE timecode via new" do
+    simple_tc = "00:10:34:10"
+    Timecode.new(simple_tc).to_s.should.equal(simple_tc)
+  end
+  
+  specify "refuse to handle timecode that is out of range for the framerate" do
+    bad_tc = "00:76:89:30"
+    lambda { Timecode.parse(bad_tc, 25) }.should.raise(Timecode::RangeError)
+  end
+  
+  specify "parse a row of numbers as parts of a timecode starting from the right" do
+    Timecode.parse("10").should.equal Timecode.new(10)
+    Timecode.parse("210").should.equal Timecode.new(60)
+    Timecode.parse("10101010").to_s.should.equal "10:10:10:10"
+  end
+  
+  specify "parse a number with f suffix as frames" do
+    Timecode.parse("60f").should.equal Timecode.new(60)
+  end
+  
+  specify "parse a number with s suffix as seconds" do
+    Timecode.parse("2s", 25).should.equal Timecode.new(50, 25)    
+    Timecode.parse("2s", 30).should.equal Timecode.new(60, 30)
+  end
+
+  specify "parse a number with m suffix as minutes" do
+    Timecode.parse("3m").should.equal Timecode.new(25 * 60 * 3)
+  end
+  
+  specify "parse a number with h suffix as hours" do
+    Timecode.parse("3h").should.equal Timecode.new(25 * 60 * 60 * 3)
+  end
+  
+  specify "parse different suffixes as a sum of elements" do
+    Timecode.parse("1h 4f").to_s.should.equal '01:00:00:04'
+    Timecode.parse("4f 1h").to_s.should.equal '01:00:00:04'
+    Timecode.parse("29f 1h").to_s.should.equal '01:00:01:04'
+  end
+  
+  specify "parse timecode with fractional second instead of frames" do
+    fraction = "00:00:07.1"
+    tc = Timecode.parse_with_fractional_seconds(fraction, 10)
+    tc.to_s.should.equal "00:00:07:01"
+
+    fraction = "00:00:07.5"
+    tc = Timecode.parse_with_fractional_seconds(fraction, 10)
+    tc.to_s.should.equal "00:00:07:05"
+    
+    fraction = "00:00:07.04"
+    tc = Timecode.parse_with_fractional_seconds(fraction, 12.5)
+    tc.to_s.should.equal "00:00:07:00"
+    
+    fraction = "00:00:07.16"
+    tc = Timecode.parse_with_fractional_seconds(fraction, 12.5)
+    tc.to_s.should.equal "00:00:07:02"
+  end
+  
+  specify "raise on improper format" do
+    lambda { Timecode.parse("Meaningless nonsense", 25) }.should.raise Timecode::CannotParse
+    lambda { Timecode.parse("", 25) }.should.raise Timecode::CannotParse
+  end
+  
+end
+
+context "Timecode.soft_parse should" do
+  specify "parse the timecode" do
+    Timecode.soft_parse('200').to_s.should.equal "00:00:02:00"
+  end
+  
+  specify "not raise on improper format and return zero TC instead" do
+    lambda do
+      tc = Timecode.soft_parse("Meaningless nonsense", 25)
+      tc.should.be.zero?
+    end.should.not.raise
+  end
+end
+
+context "Timecode with unsigned integer conversions should" do
+  
+  specify "parse from a 4x4bits packed 32bit unsigned int" do
+    uint, tc = 87310853, Timecode.at(5,34,42,5)
+    Timecode.from_uint(uint).should.equal tc
+  end
+  
+  specify "properly convert itself back to 4x4 bits 32bit unsigned int" do
+    uint, tc = 87310853, Timecode.at(5,34,42,5)
+    tc.to_uint.should.equal uint
+  end
+end

data/timecode.gemspec

@@ -0,0 +1,36 @@
+Gem::Specification.new do |s|
+  s.name = %q{timecode}
+  s.version = "0.1.4"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Julik"]
+  s.date = %q{2009-01-14}
+  s.description = %q{Value class for SMPTE timecode information}
+  s.email = ["me@julik.nl"]
+  s.extra_rdoc_files = ["History.txt", "Manifest.txt", "README.txt", "SPECS.txt"]
+  s.files = ["History.txt", "Manifest.txt", "README.txt", "SPECS.txt", "Rakefile", "lib/timecode.rb", "test/test_timecode.rb", "timecode.gemspec"]
+  s.has_rdoc = true
+  s.homepage = %q{http://wiretap.rubyforge.org/timecode}
+  s.rdoc_options = ["--main", "README.txt"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{wiretap}
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{Value class for SMPTE timecode information}
+  s.test_files = ["test/test_timecode.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<test-spec>, [">= 0"])
+      s.add_development_dependency(%q<hoe>, [">= 1.8.2"])
+    else
+      s.add_dependency(%q<test-spec>, [">= 0"])
+      s.add_dependency(%q<hoe>, [">= 1.8.2"])
+    end
+  else
+    s.add_dependency(%q<test-spec>, [">= 0"])
+    s.add_dependency(%q<hoe>, [">= 1.8.2"])
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: julik-timecode
+version: !ruby/object:Gem::Version 
+  version: 0.1.4
+platform: ruby
+authors: 
+- Julik
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-01-14 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: test-spec
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  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
+- SPECS.txt
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- SPECS.txt
+- Rakefile
+- lib/timecode.rb
+- test/test_timecode.rb
+- timecode.gemspec
+has_rdoc: true
+homepage: http://wiretap.rubyforge.org/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.2.0
+signing_key: 
+specification_version: 2
+summary: Value class for SMPTE timecode information
+test_files: 
+- test/test_timecode.rb