titlekit 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1b36a1f0921cdaa8ccdc52e9947507e17fa15000
-  data.tar.gz: c9925463a03d50b1486625d83e5df62ee4ab010a
+  metadata.gz: 650af440419b3a43cd9b6d57a2f83c7ccc61277e
+  data.tar.gz: c1a6eee753972bc12345d5f3fa7beeebfab6ed9d
 SHA512:
-  metadata.gz: d4eb3bf019168c863b72ed5c3eb05567ec5233fcfe71ca570f561fd08ad0da569f1bac69317f2c227c373144a05468e2efca751db90846e729fd47deb9741e03
-  data.tar.gz: 166c7fccd1d8085dba1cdf4c6eb49685d2ce20bdbb606fd58082dcd4e0e59c8dbd91f88474bd111ab58d431af0e062c0a11cfa128ce085c6def53ead5651b505
+  metadata.gz: b85b8b7783b76a0e9a295790049194dbe47ff7c765d5376c9d27142bac96fe1c4697cf130d0df4a56339538c55f78f12c73febfbff5737bde45ea8469852b7e0
+  data.tar.gz: 983e8444dbfced2363ad125ea9d8e720609ffae3804b3657d4799ad660e7871882b856de641c3bb8503821dbd829de810f169c3219b133208cb060d3a75867cb

data/README.md

@@ -43,6 +43,14 @@ unknown encoding)
   end
 ```
 
+### Template
+
+To get you started quickly with an edit script for subtitles, you can use a console command provided by Titlekit:
+
+     $ titlekit template [optional_title]
+
+This will generate either `template_job.rb` or `[optional_title].rb` if you have provided an optional title (Inside the directory you are in). The template script contains a basically complete Titlekit script, you just need to fill in your filenames, encodings, references, etc. as needed. There are also some comments included so you know where to start off!
+
 ### All features by example
 
 In all following examples I will omit `(1)` and `(4)` from the basic example, because they stay the same.  

data/bin/template_job.rb

@@ -0,0 +1,43 @@
+require 'titlekit'
+
+job = Titlekit::Job.new
+
+job.have do
+
+  # Specify the file you already have; Also works with .ssa and .ass
+  file('original.srt')
+
+  # Change this to your encoding, uncomment if you don't know
+  encoding('utf-8')
+
+  # Uncomment and edit to set a reference in the existing subtitles
+  # reference(:first, srt_timecode: '00:00:00,000')
+
+  # Uncomment and edit to set another reference in the existing subtitles
+  # reference(:second, srt_timecode: '00:00:00,000')
+
+end
+
+job.want do
+
+  # Specify the file to be created; Also works with .ssa and .ass
+  file('target.srt')
+
+  # Change this to your desired target encoding
+  encoding('utf-8')
+
+  # Uncomment and edit to set a new target timecode for the first reference
+  # reference(:first, srt_timecode: '00:00:00,000')
+
+  # Uncomment and edit to also set the second target timecode
+  # reference(:second, srt_timecode: '00:00:00,000')
+
+end
+
+if job.run
+  puts 'Job completed without errors!'
+else
+  puts 'There were errors:'
+  puts job.report.join("\n")
+end
+

data/bin/titlekit

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+
+if ARGV.length > 0 && ARGV[0] == 'template'
+
+  filename = ARGV.length > 1 ? ARGV[1] + '.rb' : 'template_job.rb'
+  
+  content = <<HERETEMPLATE
+require 'titlekit'
+
+job = Titlekit::Job.new
+
+job.have do
+
+  # Specify the file you already have; Also works with .ssa and .ass
+  file('original.srt')
+
+  # Change this to your encoding, uncomment if you don't know
+  encoding('utf-8')
+
+  # Uncomment and edit to set a reference in the existing subtitles
+  # reference(:first, srt_timecode: '00:00:00,000')
+
+  # Uncomment and edit to set another reference in the existing subtitles
+  # reference(:second, srt_timecode: '00:00:00,000')
+
+end
+
+job.want do
+
+  # Specify the file to be created; Also works with .ssa and .ass
+  file('target.srt')
+
+  # Change this to your desired target encoding
+  encoding('utf-8')
+
+  # Uncomment and edit to set a new target timecode for the first reference
+  # reference(:first, srt_timecode: '00:00:00,000')
+
+  # Uncomment and edit to also set the second target timecode
+  # reference(:second, srt_timecode: '00:00:00,000')
+
+end
+
+if job.run
+  puts 'Job completed without errors!'
+else
+  puts 'There were errors:'
+  puts job.report.join("\\n")
+end
+
+HERETEMPLATE
+
+  IO.write(filename, content)
+
+  puts "Created generic job script '#{filename}' in current directory;"
+  puts "Edit and then run with 'ruby #{filename}'"
+
+else
+  puts 'Your either provided an unknown option, or none at all;'
+  puts 'Currently only \'template [optional_title]\' is available;'
+  puts 'E.g. \'titlekit template myscript\''
+end

data/lib/titlekit/job.rb

@@ -4,14 +4,14 @@ module Titlekit
 
   class Job
 
-    # Returns everything we {Have}
+    # Returns everything you {Have}
     #
-    # @return [Array<Have>] All assigned {Have} specifications
+    # @return [Array<Have>] Everything you {Have}
     attr_reader :haves
 
-    # Returns everything we {Want}
+    # Returns everything you {Want}
     #
-    # @return [Array<Want>] All assigned {Want} specifications  
+    # @return [Array<Want>] Everything you {Want}
     attr_reader :wants
 
     # Returns the job report, which documents the direct cause of failures
@@ -23,7 +23,7 @@ module Titlekit
 
     # Starts a new job.
     #
-    # A job requires at least one thing you {Have} and one thing you {Want}
+    # A job requires at least one file you {Have} and one file you {Want}
     # in order to be runable. Use {Job#have} and {Job#want} to add
     # and obtain specification interfaces for the job.
     #
@@ -42,7 +42,7 @@ module Titlekit
       end  
     end
 
-    # Fulfills the job.
+    # Runs the job.
     #
     # @return [Boolean] true if the job succeeds, false if it fails.
     #   {Job#report} provides information in case of failure.
@@ -214,6 +214,8 @@ module Titlekit
           SSA.import(data)
         when '.srt'
           SRT.import(data)
+        when '.yt'
+          YT.import(data)        
         else
           raise 'Not supported'
         end
@@ -258,7 +260,9 @@ module Titlekit
       end
     end
 
-    # Clean out subtitles that fell out of the usable time range
+    # Cleans out subtitles that fell out of the usable time range
+    #
+    # @params have [Have] What we {Have}   
     def cull(have)
       have.subtitles.reject! { |subtitle| subtitle[:end] < 0 }
       have.subtitles.each do |subtitle|
@@ -266,8 +270,10 @@ module Titlekit
       end
     end
 
-    # Assign track identification fields for distinguishing
+    # Assigns track identification fields for distinguishing
     # between continuous/simultaneous subtitles
+    #
+    # @params have [Have] What we {Have} 
     def group(have)
       if have.track
         # Assign a custom track identifier if one was supplied
@@ -348,6 +354,9 @@ module Titlekit
         when '.srt'
           SRT.master(want.subtitles)
           SRT.export(want.subtitles)
+        when '.yt'
+          YT.master(want.subtitles)
+          YT.export(want.subtitles)         
         else
           raise 'Not supported'
         end
@@ -391,6 +400,12 @@ module Titlekit
       end
     end
 
+    # Rescales timecodes based on two differing framerates and then applies a
+    # simple timeshift to the subtitles we {Have}.
+    #
+    # @param have [Have] the subtitles we {Have}
+    # @param want [Want] the subtitles we {Want}
+    # @param reference [Symbol, String] the key of the reference
     def retime_by_framerate_plus_reference(have, want, reference)
       ratio = want.fps.to_f / have.fps.to_f
       have.references[reference][:timecode] *= ratio
@@ -435,6 +450,10 @@ module Titlekit
       end
     end
 
+    # Rescales timecodes based on two differing framerates.
+    #
+    # @param have [Have] the subtitles we {Have}
+    # @param want [Want] the subtitles we {Want}
     def retime_by_framerate(have, want)
       ratio = want.fps.to_f / have.fps.to_f
       have.subtitles.each do |subtitle|

data/lib/titlekit/parsers/ass.rb

@@ -3,24 +3,28 @@ require 'treetop'
 module Titlekit
   module ASS
 
+    # Internal intermediate class used for parsing with treetop
     class Subtitles < Treetop::Runtime::SyntaxNode
       def build
         event_section.events.build
       end
     end
 
+    # Internal intermediate class used for parsing with treetop
     class ScriptInfo < Treetop::Runtime::SyntaxNode
       def build
         # elements.map { |subtitle| subtitle.build }
       end
     end
 
+    # Internal intermediate class used for parsing with treetop
     class V4PStyles < Treetop::Runtime::SyntaxNode
       def build
         # elements.map { |subtitle| subtitle.build }
       end
     end
 
+    # Internal intermediate class used for parsing with treetop
     class Events < Treetop::Runtime::SyntaxNode
       def build
         elements.map do |line|
@@ -38,9 +42,10 @@ module Titlekit
       end
     end
 
-    # Parses the supplied string and returns the results.
-    #
+    # Parses the supplied string and builds the resulting subtitles array.
     #
+    # @param string [String] proper UTF-8 ASS file content
+    # @return [Array<Hash>] the imported subtitles
     def self.import(string)
       Treetop.load(File.join(__dir__, 'ass'))
       parser = ASSParser.new
@@ -119,6 +124,10 @@ module Titlekit
       end
     end
 
+    # Exports the supplied subtitles to ASS format
+    #
+    # @param subtitles [Array<Hash>] The subtitle to export
+    # @return [String] Proper UTF-8 ASS as a string
     def self.export(subtitles)
       result = ''
 
@@ -159,6 +168,10 @@ module Titlekit
 
     protected
 
+    # Builds an ASS-formatted timecode from a float representing seconds
+    #
+    # @param seconds [Float] an amount of seconds
+    # @return [String] An ASS-formatted timecode ('h:mm:ss.ms')
     def self.build_timecode(seconds)
       sprintf("%01d:%02d:%02d.%s",
               seconds / 3600,
@@ -167,6 +180,10 @@ module Titlekit
               sprintf("%.2f", seconds)[-2, 3])
     end
 
+    # Parses an ASS-formatted timecode into a float representing seconds
+    #
+    # @param timecode [String] An ASS-formatted timecode ('h:mm:ss.ms')
+    # @param [Float] an amount of seconds
     def self.parse_timecode(timecode)
       mres = timecode.match(/(?<h>\d):(?<m>\d{2}):(?<s>\d{2})[:|\.](?<ms>\d+)/)
       return "#{mres["h"].to_i * 3600 + mres["m"].to_i * 60 + mres["s"].to_i}.#{mres["ms"]}".to_f

data/lib/titlekit/parsers/srt.rb

@@ -3,12 +3,14 @@ require 'treetop'
 module Titlekit
   module SRT
 
+    # Internal intermediate class used for parsing with treetop
     class Subtitles < Treetop::Runtime::SyntaxNode
       def build
         elements.map { |subtitle| subtitle.build }
       end
     end
 
+    # Internal intermediate class used for parsing with treetop
     class Subtitle < Treetop::Runtime::SyntaxNode
       def build
         {
@@ -20,6 +22,7 @@ module Titlekit
       end
     end
 
+    # Internal intermediate class used for parsing with treetop
     class Timecode < Treetop::Runtime::SyntaxNode
       def build
         value = 0
@@ -31,9 +34,10 @@ module Titlekit
       end
     end
 
-    # Parses the supplied string and returns the results.
-    #
+    # Parses the supplied string and builds the resulting subtitles array.
     #
+    # @param string [String] proper UTF-8 SRT file content
+    # @return [Array<Hash>] the imported subtitles
     def self.import(string)
       Treetop.load(File.join(__dir__, 'srt'))
       parser = SRTParser.new
@@ -104,6 +108,10 @@ module Titlekit
       end
     end
 
+    # Exports the supplied subtitles to SRT format
+    #
+    # @param subtitles [Array<Hash>] The subtitle to export
+    # @return [String] Proper UTF-8 SRT as a string
     def self.export(subtitles)
       result = ''
 
@@ -123,6 +131,10 @@ module Titlekit
 
     protected
 
+    # Builds an SRT-formatted timecode from a float representing seconds
+    #
+    # @param seconds [Float] an amount of seconds
+    # @return [String] An SRT-formatted timecode ('hh:mm:ss,ms')
     def self.build_timecode(seconds)
       sprintf("%02d:%02d:%02d,%s",
               seconds / 3600,
@@ -131,6 +143,10 @@ module Titlekit
               sprintf("%.3f", seconds)[-3, 3])
     end
 
+    # Parses an SRT-formatted timecode into a float representing seconds
+    #
+    # @param timecode [String] An SRT-formatted timecode ('hh:mm:ss,ms')
+    # @param [Float] an amount of seconds
     def self.parse_timecode(timecode)
       mres = timecode.match(/(?<h>\d+):(?<m>\d+):(?<s>\d+),(?<ms>\d+)/)
       "#{mres["h"].to_i * 3600 + mres["m"].to_i * 60 + mres["s"].to_i}.#{mres["ms"]}".to_f

data/lib/titlekit/parsers/ssa.rb

@@ -3,24 +3,28 @@ require 'treetop'
 module Titlekit
   module SSA
 
+    # Internal intermediate class used for parsing with treetop
     class Subtitles < Treetop::Runtime::SyntaxNode
       def build
         event_section.events.build
       end
     end
 
+    # Internal intermediate class used for parsing with treetop
     class ScriptInfo < Treetop::Runtime::SyntaxNode
       def build
         # elements.map { |subtitle| subtitle.build }
       end
     end
 
+    # Internal intermediate class used for parsing with treetop
     class V4PStyles < Treetop::Runtime::SyntaxNode
       def build
         # elements.map { |subtitle| subtitle.build }
       end
     end
 
+    # Internal intermediate class used for parsing with treetop
     class Events < Treetop::Runtime::SyntaxNode
       def build
         elements.map do |line|
@@ -38,31 +42,10 @@ module Titlekit
       end
     end    
 
-    # class Subtitle < Treetop::Runtime::SyntaxNode
-    #   def build
-    #     {
-    #       id: id.text_value.to_i,
-    #       start: from.build,
-    #       end: to.build,
-    #       lines: lines.text_value.rstrip
-    #     }
-    #   end
-    # end
-
-    # class Timecode < Treetop::Runtime::SyntaxNode
-    #   def build
-    #     value = 0
-    #     value += hours.text_value.to_i * 3600
-    #     value += minutes.text_value.to_i * 60
-    #     value += seconds.text_value.to_i
-    #     value += "0.#{fractions.text_value}".to_f
-    #     value
-    #   end
-    # end
-
-    # Parses the supplied string and returns the results.
-    #
+    # Parses the supplied string and builds the resulting subtitles array.
     #
+    # @param string [String] proper UTF-8 SSA file content
+    # @return [Array<Hash>] the imported subtitles
     def self.import(string)
       Treetop.load(File.join(__dir__, 'ssa'))
       parser = SSAParser.new
@@ -141,6 +124,10 @@ module Titlekit
       end
     end
 
+    # Exports the supplied subtitles to SSA format
+    #
+    # @param subtitles [Array<Hash>] The subtitle to export
+    # @return [String] Proper UTF-8 SSA as a string
     def self.export(subtitles)
       result = ''
 
@@ -185,6 +172,10 @@ module Titlekit
 
     protected
 
+    # Builds an SSA-formatted timecode from a float representing seconds
+    #
+    # @param seconds [Float] an amount of seconds
+    # @return [String] An SSA-formatted timecode ('h:mm:ss.ms')
     def self.build_timecode(seconds)
       sprintf("%01d:%02d:%02d.%s",
               seconds / 3600,
@@ -193,6 +184,10 @@ module Titlekit
               sprintf("%.2f", seconds)[-2, 3])
     end 
 
+    # Parses an SSA-formatted timecode into a float representing seconds
+    #
+    # @param timecode [String] An SSA-formatted timecode ('h:mm:ss.ms')
+    # @param [Float] an amount of seconds
     def self.parse_timecode(timecode)
       mres = timecode.match(/(?<h>\d):(?<m>\d{2}):(?<s>\d{2})[:|\.](?<ms>\d+)/)
       return "#{mres["h"].to_i * 3600 + mres["m"].to_i * 60 + mres["s"].to_i}.#{mres["ms"]}".to_f

data/lib/titlekit/specification.rb

@@ -1,7 +1,7 @@
 module Titlekit
   class Specification
 
-    # Only for internal usage by the job control center
+    # Only for internal usage by the job
     attr_accessor :subtitles
 
     def initialize
@@ -15,6 +15,8 @@ module Titlekit
       return self
     end
 
+    # Specifies the encoding you have or want.
+    #
     # @param [String] A string specifying the encoding, e.g. 'utf-8' or 'ISO-8859-1'
     # @return If you omit the argument, it returns the already specified encoding
     def encoding(*args)
@@ -26,6 +28,8 @@ module Titlekit
       end
     end
 
+    # Specifies the file (path) you have or want.
+    #
     # @param [String] A string specifying the path to the file
     # @return If you omit the argument, it returns the already specified path 
     def file(*args)
@@ -37,6 +41,8 @@ module Titlekit
       end
     end
 
+    # Specifies the track the subtitles should be assigned to.
+    #
     # @param [String] A string specifying the track identifier
     # @return If you omit the argument, it returns the already specified track 
     def track(*args)
@@ -48,6 +54,8 @@ module Titlekit
       end
     end      
 
+    # Specifies the framerate you have or want.
+    #
     # @param [Float] A float specifying the frames per second, e.g. 23.976
     # @return If you omit the argument, it returns the already specified fps
     def fps(*args)

data/lib/titlekit/utilities.rb

@@ -1,3 +1,6 @@
 module Titlekit
+  # The default palette is used to distinguish simultaneous subtitles
+  # by their color (if distinguishing them by different position is either
+  # not possible due to the format or not sensible in the specific case)
   DEFAULT_PALETTE = %w{EDF393 F5E665 FFC472 FFA891 89BABE}
 end

data/lib/titlekit/version.rb

@@ -1,3 +1,4 @@
 module Titlekit
-  VERSION = '1.0.0'
+  # Versioning follows the semantic versioning scheme: http://semver.org/
+  VERSION = '1.1.0'
 end

data/lib/titlekit/want.rb

@@ -3,12 +3,12 @@ module Titlekit
 
     def initialize
       super
-      @glue_treshold = 0.08
+      @glue_treshold = 0.3
     end
 
-    # For dual subtitles the starts and ends of simultaneously occuring
+    # For dual+ subtitles the starts and ends of simultaneously occuring
     # subtitles can be micro-adjusted together if their distance is smaller
-    # than the glue_treshold. Normally defaults to 0.08 (super-conservative).
+    # than the glue_treshold. Normally defaults to 0.3
     #
     # @param [Float] Specifies the new glue_treshold
     # @return If you omit the argument, it returns the set glue_treshold