fps-timecode 0.0.3

data/lib/fps-timecode.rb

@@ -0,0 +1,200 @@
+# Timecode library
+# Implements Timecode class
+# Version 0.0.2
+#
+# Author: Loran Kary
+# Copyright 2013 Focal Point Software, all rights reserved
+
+module FPS      # Focal Point Software
+
+# A timecode library has two main purposes.
+# 1.) Given the timecode address of the first frame of a sequence of frames, 
+#     and given n, what is the timecode address of the nth frame of a sequence?
+# 2.) Given the timecode address of the first frame of a sequence, and
+#     given the timecode address for the nth frame of the sequence,  what is n?
+
+# Example 1.  A non-drop-frame 30 fps sequence starts at 00:01:00:00.  What is
+#           the timecode address of the 100th frame of the sequence?
+#  FPS::Timecode.count_to_string(:fps_30_ndf, 
+#       FPS::Timecode.string_to_count(:fps_30_ndf,"00:01:00:00") + 100)
+#   => "00:01:03:10"
+
+# Example 2.  A non-drop-frame 30 fps sequence starts at 00:01:00:00. What is n
+#       for the frame with the address 00:01:03:10?
+#  FPS::Timecode.string_to_count(:fps_30_ndf,"00:01:03:10") -
+#        FPS::Timecode.string_to_count(:fps_30_ndf,"00:01:00:00")
+#   => 100
+
+# An instance of the Timecode class represents one timecode address.
+# A timecode mode is always required to be given.  The mode determines the frame
+# rate and the dropness (drop-frame or non-drop-frame) of the timecode address.
+# The mode must be one of Timecode::Counts.keys.  E.g. :fps_24, :fps_25.
+# Create an instance of a Timecode using either a string in the format "xx:xx:xx:xx"
+# or a frame count.  The frame count represents n for the nth frame of a sequence
+# that begins with timecode address "00:00:00:00" (the zeroeth frame of the sequence).
+# When creating a timecode instance, default to using the string argument
+# and fall back to using the frame count argument if the string is invalid. 
+
+# Since there are many class methods, often there is no need to create 
+# an instance of class Timecode.
+
+class Timecode
+
+  attr_reader :tc_count, :tc_string, :tc_mode
+
+  Counts = { fps_24:     { fp24h: 2073600, fph: 86400,  fptm: 14400, fpm: 1440, fps: 24 },
+             fps_25:     { fp24h: 2160000, fph: 90000,  fptm: 15000, fpm: 1500, fps: 25 },
+             fps_30_df:  { fp24h: 2589408, fph: 107892, fptm: 17982, fpm: 1798, fps: 30 },             
+             fps_30_ndf: { fp24h: 2592000, fph: 108000, fptm: 18000, fpm: 1800, fps: 30 },
+             fps_48:     { fp24h: 4147200, fph: 172800, fptm: 28800, fpm: 2880, fps: 48 },
+             fps_50:     { fp24h: 4320000, fph: 180000, fptm: 30000, fpm: 3000, fps: 50 },
+             fps_60_df:  { fp24h: 5178816, fph: 215784, fptm: 35964, fpm: 3596, fps: 60 },
+             fps_60_ndf: { fp24h: 5184000, fph: 216000, fptm: 36000, fpm: 3600, fps: 60 },
+           }
+     
+  # count_to_string      
+  # Class method to compute a string from a frame count
+  def self.count_to_string(tc_mode, tc_count, duration = false) 
+    tc_count = Timecode.normalize(tc_mode, tc_count)
+
+    counts = Counts[tc_mode]
+    hours = tc_count / counts[:fph]
+    rem = tc_count % counts[:fph]
+    tens_mins = rem / counts[:fptm]
+    rem = rem % counts[:fptm]
+    units_mins = rem / counts[:fpm]
+    rem = rem % counts[:fpm]
+    
+    if(duration == false)  # not a duration, do drop-frame processing
+        # handle 30 fps drop frame
+        if(tc_mode == :fps_30_df && units_mins > 0 && rem <= 1)
+          units_mins -= 1
+          rem += counts[:fpm]
+        end
+        # handle 60 fps drop frame
+        if(tc_mode == :fps_60_df && units_mins > 0 && rem <= 3)
+          units_mins -= 1
+          rem += counts[:fpm]
+        end
+    end
+    
+    secs = rem / counts[:fps]
+    frms = rem % counts[:fps]
+    
+    "%02d:%d%d:%02d:%02d" % [hours, tens_mins, units_mins, secs, frms]
+  end
+  
+  # string_to_count
+  # Class method to compute a count from a string  
+  def self.string_to_count(tc_mode, tc_string)
+    unless Counts.include?(tc_mode)
+      raise ArgumentError,  "invalid timecode mode"
+    end
+    unless tc_string.is_a? String 
+      raise ArgumentError, "invalid timecode string"
+    end
+    unless tc_string =~ /\A(\d{2})[:;.](\d{2})[:;.](\d{2})[:;.](\d{2})\Z/
+      raise ArgumentError, "invalid timecode string"
+    end
+    if($1.to_i >= 24 || $2.to_i >= 60 || $3.to_i >= 60 || $4.to_i >= Counts[tc_mode][:fps])
+      raise ArgumentError, "invalid timecode string"
+    end
+
+    counts = Counts[tc_mode]
+    tc_string =~ /\A(\d{2})[:;.](\d)(\d)[:;.](\d{2})[:;.](\d{2})\Z/
+    $1.to_i * counts[:fph] +
+      $2.to_i * counts[:fptm] +
+      $3.to_i * counts[:fpm] +
+      $4.to_i * counts[:fps] + $5.to_i
+  end
+  
+  # Class method to normalize a frame count >= 0 and < 24h
+  # Correct 24 hour overflow or underflow
+  def self.normalize(tc_mode, tc_count)
+    # tc_mode must be given and must be one of the known tc modes
+    unless Counts.include?(tc_mode)
+      raise ArgumentError,  "invalid timecode mode"
+    end
+
+    unless tc_count.is_a? Fixnum 
+      raise ArgumentError, "invalid frame count #{tc_count}"
+    end
+    # normalize to 24 hours
+    _24h = Counts[tc_mode][:fp24h]
+    while tc_count < 0 do tc_count += _24h end
+    while tc_count >= _24h do tc_count -= _24h end
+    tc_count
+  end
+  
+  # Class method to compute a string as a duration from a frame count_to_string
+  def self.string_as_duration(tc_mode, tc_count)
+    Timecode.count_to_string(tc_mode, tc_count, true)
+  end
+
+
+
+# initialize
+# Construct a new instance of Timecode, given a mode and either a 
+# timecode string or a frame count.
+# Raises ArgumentError           
+  def initialize(tc_mode, tc_string, tc_count = nil)
+    # tc_string and tc_count cannot both be nil
+    if(tc_string === nil && tc_count === nil)
+      raise ArgumentError, "string and count both nil"
+    end
+    # tc_mode must be given and must be one of the known tc modes
+    unless Counts.include?(tc_mode)
+      raise ArgumentError,  "invalid timecode mode"
+    end
+    
+    @tc_mode = tc_mode
+   
+    # Try to use the string to construct the instance and fall back
+    # to the count if an exception is raised
+    begin
+      @tc_count = Timecode.string_to_count(@tc_mode, tc_string)
+      # always convert back to string because given string may not be drop-frame legal
+      @tc_string = Timecode.count_to_string(@tc_mode, @tc_count)
+    rescue
+      @tc_count = Timecode.normalize(@tc_mode, tc_count)
+      @tc_string = Timecode.count_to_string(@tc_mode, @tc_count)
+    end        
+  
+  end   #initialize
+  
+  # string_as_duration
+  # The difference of two timecodes might be used as a duration.
+  # For non-drop frame, the duration string does not differ from the
+  # string as a timecode address.  But for drop-frame, timecodes 
+  # that don't exist as an address can exist as a duration.
+  # One minute in drop frame is 1798 frames or 00:00:59:28.
+  # "00:01:00:00" as a drop-frame timecode address does not exist.
+  # But the difference between 00:01:59:28 and 00:00:59:28
+  # should be displayed as "00:01:00:00" -- one minute.
+  # 
+  def string_as_duration
+    Timecode.string_as_duration(@tc_mode, @tc_count)
+  end
+  
+  # succ
+  # return the next timecode address in the sequence
+  def succ
+    Timecode.new(@tc_mode, nil, @tc_count+1)
+  end
+  
+  # compare two timecodes for equality    
+  # equality operator does string compare
+  # two timecodes may be considered equal even though their modes and counts
+  # may be different.
+  def ==(other)
+    @tc_string == other.tc_string
+  end
+  
+  # compare two timecodes
+  # comparison (spaceship) operator does string compare
+  def <=>(other)
+    @tc_string <=> other.tc_string
+  end
+
+end #class
+end #module

data/test/test_fps-timecode.rb

@@ -0,0 +1,130 @@
+# Timecode test suite for Timecode class
+# Author: Loran Kary, Focal Point Software
+# to run from parent directory, "ruby -I lib test/test_fps-timecode.rb"
+
+
+require 'fps-timecode'
+
+require 'test/unit'
+
+class TestFpsTimecode < Test::Unit::TestCase
+
+  def test_create_legally_doesnt_fail
+    assert_nothing_raised do
+      FPS::Timecode.new(:fps_24, nil, 1000)
+      FPS::Timecode.new(:fps_30_ndf, "00:01:00:00", nil)
+      FPS::Timecode.new(:fps_25, "00:01:00:00")
+      FPS::Timecode.new(:fps_30_df, "00:02:00:00", 1798*2)
+      end
+  end
+  
+  def test_create_must_have_valid_tc_mode
+    assert_raises(ArgumentError) do
+      FPS::Timecode.new(:not_a_valid_tc_mode, nil, 1000)
+    end
+  end
+  
+  def test_create_string_and_count_cannot_both_be_nil
+    assert_raises(ArgumentError) do
+      FPS::Timecode.new(:fps_30_ndf, nil, nil)
+    end
+  end
+  
+  def test_create_use_string_by_default
+    assert_equal "00:01:00:00", FPS::Timecode.new(:fps_30_ndf, "00:01:00:00", 0).tc_string
+  end  
+  
+  def test_create_fall_back_to_count_when_string_is_invalid
+    assert_equal "00:01:00:00", FPS::Timecode.new(:fps_30_ndf, "invalid", 1800).tc_string
+  end
+  
+  def test_create_count_if_given_must_be_fixnum
+    assert_raises(ArgumentError) do
+      FPS::Timecode.new(:fps_30_ndf, nil, "1800")
+    end
+  end
+  
+  def test_create_negative_counts_will_be_normalized
+    assert_equal "23:59:00:00", FPS::Timecode.new(:fps_30_ndf, nil, -1800).tc_string
+  end
+
+  def test_create_counts_greater_than_24_hours_will_be_normalized
+    assert_equal "00:01:00:00", 
+      FPS::Timecode.new(:fps_30_ndf, nil, FPS::Timecode::Counts[:fps_30_ndf][:fp24h] + 1800).tc_string
+  end
+    
+  def test_create_string_must_be_valid_if_no_count_given
+    assert_raises(ArgumentError) do
+      FPS::Timecode.new(:fps_30_ndf, "invalid", nil)
+    end
+  end
+        
+  def test_create_string_all_fields_must_be_within_bounds # e.g. 24:60:60:30 for fps 30  
+    assert_nothing_raised do 
+      FPS::Timecode.new(:fps_30_ndf, "23:59:59:29", nil)
+    end
+    assert_raises(ArgumentError) do
+      FPS::Timecode.new(:fps_30_ndf, "23:59:59:30", nil)
+    end
+    assert_raises(ArgumentError) do
+      FPS::Timecode.new(:fps_30_ndf, "24:00:00:00", nil)
+    end
+  end
+  
+  def test_create_nonexistent_drop_frame_times_will_be_corrected
+    # "00:01:00:00" doesn't exist in drop-frame
+    assert_equal("00:00:59:28", 
+      FPS::Timecode.new(:fps_30_df, "00:01:00:00", nil).tc_string)
+    # "00:10:00:00" does exist in drop-frame
+    assert_equal("00:10:00:00", 
+      FPS::Timecode.new(:fps_30_df, "00:10:00:00", nil).tc_string)
+  end
+  
+  def test_comparison_works_on_strings_regardless_of_counts
+    # 00:10:00:00 drop-frame is equal to 00:10:00:00 non-drop
+    # despite different frame counts
+    assert_equal true,        
+      FPS::Timecode.new(:fps_30_ndf, nil, FPS::Timecode::Counts[:fps_30_ndf][:fptm]) ==
+      FPS::Timecode.new(:fps_30_df, nil, FPS::Timecode::Counts[:fps_30_df][:fptm])
+    assert_equal 0,        
+      FPS::Timecode.new(:fps_30_ndf, nil, FPS::Timecode::Counts[:fps_30_ndf][:fptm]) <=>
+      FPS::Timecode.new(:fps_30_df, nil, FPS::Timecode::Counts[:fps_30_df][:fptm])
+  end
+  
+  def test_dropframe_string_as_duration
+    a = FPS::Timecode.new(:fps_30_df, "00:01:59:28", nil)
+    b = FPS::Timecode.new(:fps_30_df, "00:00:59:28", nil)
+    difference = a.tc_count - b.tc_count
+    assert_equal 1798, difference
+    assert_equal "00:01:00:00", 
+        FPS::Timecode.new(:fps_30_df, nil, difference).string_as_duration       
+  end
+      
+  def test_succ
+    a = []
+    b = FPS::Timecode.new(:fps_30_df, "00:01:00:00", nil)
+    4.times do
+        a << b.tc_string
+        b = b.succ
+        end
+    assert_equal ["00:00:59:28", "00:00:59:29", "00:01:00:02", "00:01:00:03"], a
+    a.clear
+    b = FPS::Timecode.new(:fps_60_df, "00:01:00:00", nil)
+    6.times do
+        a << b.tc_string
+        b = b.succ
+        end
+    assert_equal ["00:00:59:56", "00:00:59:57", "00:00:59:58", "00:00:59:59",
+                    "00:01:00:04", "00:01:00:05"], a
+  end
+  
+  def test_class_methods
+    assert_equal "00:01:00:00", FPS::Timecode.count_to_string(:fps_30_ndf, 1800)
+    assert_equal 1800, FPS::Timecode.string_to_count(:fps_30_ndf, "00:01:00:00")
+    assert_equal 1800, FPS::Timecode.normalize(:fps_30_ndf, FPS::Timecode::Counts[:fps_30_ndf][:fp24h] + 1800)
+    assert_equal FPS::Timecode::Counts[:fps_30_ndf][:fp24h] - 1800, FPS::Timecode.normalize(:fps_30_ndf, -1800)
+    assert_equal "00:01:00:00", FPS::Timecode.string_as_duration(:fps_30_df, 1798)
+  end
+    
+
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: fps-timecode
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+platform: ruby
+authors:
+- Loran Kary
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-01-29 00:00:00.000000000 Z
+dependencies: []
+description: A library to support drop-frame and non-drop-frame timecodes
+email: lkary@focalpnt.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- doc/FPS.html
+- doc/FPS/Timecode.html
+- doc/TestFpsTimecode.html
+- doc/created.rid
+- doc/css/fonts.css
+- doc/css/rdoc.css
+- doc/fonts/Lato-Light.ttf
+- doc/fonts/Lato-LightItalic.ttf
+- doc/fonts/Lato-Regular.ttf
+- doc/fonts/Lato-RegularItalic.ttf
+- doc/fonts/SourceCodePro-Bold.ttf
+- doc/fonts/SourceCodePro-Regular.ttf
+- doc/fps-timecode_gemspec.html
+- doc/images/add.png
+- doc/images/arrow_up.png
+- doc/images/brick.png
+- doc/images/brick_link.png
+- doc/images/bug.png
+- doc/images/bullet_black.png
+- doc/images/bullet_toggle_minus.png
+- doc/images/bullet_toggle_plus.png
+- doc/images/date.png
+- doc/images/delete.png
+- doc/images/find.png
+- doc/images/loadingAnimation.gif
+- doc/images/macFFBgHack.png
+- doc/images/package.png
+- doc/images/page_green.png
+- doc/images/page_white_text.png
+- doc/images/page_white_width.png
+- doc/images/plugin.png
+- doc/images/ruby.png
+- doc/images/tag_blue.png
+- doc/images/tag_green.png
+- doc/images/transparent.png
+- doc/images/wrench.png
+- doc/images/wrench_orange.png
+- doc/images/zoom.png
+- doc/index.html
+- doc/js/darkfish.js
+- doc/js/jquery.js
+- doc/js/navigation.js
+- doc/js/navigation.js.gz
+- doc/js/search.js
+- doc/js/search_index.js
+- doc/js/search_index.js.gz
+- doc/js/searcher.js
+- doc/js/searcher.js.gz
+- doc/rdoc.css
+- doc/table_of_contents.html
+- lib/fps-timecode.rb
+- test/test_fps-timecode.rb
+homepage: http://focalpnt.com
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '1.9'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.4
+signing_key: 
+specification_version: 4
+summary: Implements timecode class
+test_files:
+- test/test_fps-timecode.rb