titlekit 1.0.0

data/lib/titlekit/job.rb

@@ -0,0 +1,446 @@
+module Titlekit
+  class AbortJob < StandardError
+  end
+
+  class Job
+
+    # Returns everything we {Have}
+    #
+    # @return [Array<Have>] All assigned {Have} specifications
+    attr_reader :haves
+
+    # Returns everything we {Want}
+    #
+    # @return [Array<Want>] All assigned {Want} specifications  
+    attr_reader :wants
+
+    # Returns the job report, which documents the direct cause of failures
+    # and any other unusual events that occur on the job. (regardless if it
+    # failed or succeeded)
+    #
+    # @return [Array<String>] All reported messages 
+    attr_reader :report
+
+    # Starts a new job.
+    #
+    # A job requires at least one thing you {Have} and one thing you {Want}
+    # in order to be runable. Use {Job#have} and {Job#want} to add
+    # and obtain specification interfaces for the job.
+    #
+    def initialize
+      @haves = []
+      @wants = []
+      @report = []
+
+      require 'rchardet19'
+
+      begin
+        if Gem::Specification.find_by_name('charlock_holmes')
+          require 'charlock_holmes'
+        end
+      rescue Gem::LoadError
+      end  
+    end
+
+    # Fulfills the job.
+    #
+    # @return [Boolean] true if the job succeeds, false if it fails.
+    #   {Job#report} provides information in case of failure.
+    def run
+      @wants.each do |want|
+        @haves.each do |have|
+          import(have)
+          retime(have, want)
+          cull(have)
+          group(have)
+
+          want.subtitles += have.subtitles.clone
+        end
+        
+        polish(want)
+        export(want)
+      end
+
+      return true
+    rescue AbortJob
+      return false
+    end
+
+    # Adds a new {Have} specification to your job.
+    #
+    # @example Using a block without a variable (careful: the scope changes!)
+    #   job.have do
+    #     encoding('utf-8')
+    #     file('path/to/my/input.srt')
+    #     fps(25)
+    #   end
+    #   
+    # @example Using a block and providing a variable
+    #   job.have do |have|
+    #     have.encoding('utf-8')
+    #     have.file('path/to/my/input.srt')
+    #     have.fps(25)
+    #   end
+    #   
+    # @example Catching the reference and assigning things at any later point
+    #   have = job.have
+    #   have.encoding('utf-8')
+    #   have.file('path/to/my/input.srt')
+    #   have.fps(25)
+    #
+    # @example Cloning a previous specification and extending on it
+    #   have2 = job.have(template: have1)
+    #   have2.encoding('ISO-8859-1')
+    #   have2.file('path/to/my/input2.srt')
+    #
+    # @param template [Have] optionally you can specify another {Have} as a 
+    #   template, from which all properties but the file path are cloned
+    # @return [Have] a reference to the newly assigned {Have}
+    def have(*args, template: nil, &block)
+      specification = Have.new
+
+      if template
+        specification.fps = template.fps.clone
+        specification.references = template.references.clone
+      end
+
+      if block
+        if block.arity < 1
+          specification.instance_eval(&block)
+        else
+          block[specification]
+        end
+      end
+
+      @haves << specification
+
+      return specification
+    end
+
+    # Adds a new {Want} specification to your job.
+    #
+    # @example Using a block without a variable (careful: the scope changes!)
+    #   job.want do
+    #     encoding('utf-8')
+    #     file('path/to/my/output.srt')
+    #     fps(23.976)
+    #   end
+    #   
+    # @example Using a block and providing a variable
+    #   job.want do |want|
+    #     want.encoding('utf-8')
+    #     want.file('path/to/my/output.srt')
+    #     want.fps((23.976)
+    #   end
+    #   
+    # @example Catching the reference and assigning things at any later point
+    #   want = job.want
+    #   want.encoding('utf-8')
+    #   want.file('path/to/my/output.srt')
+    #   want.fps((23.976)
+    #
+    # @example Cloning a previous specification and extending on it
+    #   want2 = job.want(template: want1)
+    #   want2.encoding('ISO-8859-1')
+    #   want2.file('path/to/my/output.ass')
+    #
+    # @param template [Want] optionally you can specify another {Want} as a 
+    #   template, from which all properties but the file path are cloned
+    # @return [Want] a reference to the newly assigned {Want}
+    def want(*args, template: nil, &block)
+      specification = Want.new
+
+      if template
+        specification.fps = template.fps.clone
+        specification.references = template.references.clone
+      end
+
+      if block
+        if block.arity < 1
+          specification.instance_eval(&block)
+        else
+          block[specification]
+        end
+      end
+
+      @wants << specification
+
+      return specification
+    end
+
+    private
+
+    # Imports what we {Have}
+    #
+    # @param [Have] What we {Have}
+    def import(have)
+      begin
+        data = File.read(have.file)
+      rescue
+        @report << "Failure while reading #{have.file}"
+        raise AbortJob
+      end
+
+      begin
+        if [:detect, :charlock_holmes].include?(have.encoding) && defined?(CharlockHolmes)
+          detection = CharlockHolmes::EncodingDetector.detect(data)
+          @report << "Assuming #{detection[:encoding]} for #{have.file} (detected by charlock_holmes with #{detection[:confidence]}% confidence)"
+          data.force_encoding(detection[:encoding])
+        elsif [:detect, :rchardet19].include?(have.encoding) && defined?(CharDet)
+          detection = CharDet.detect(data)
+          @report << "Assuming #{detection.encoding} for #{have.file} (detected by rchardet19 with #{(detection.confidence*100).to_i}% confidence)"
+          data.force_encoding(detection.encoding)
+        else
+          @report << "Assuming #{have.encoding} for #{have.file} (user-supplied)"
+          data.force_encoding(have.encoding)
+        end
+      rescue
+        @report << "Failure while setting encoding for #{have.file}"
+        raise AbortJob
+      end
+
+      begin
+        data.encode!('UTF-8')
+      rescue
+        @report << "Failure while transcoding #{have.file} from #{data.encoding} to intermediate UTF-8 encoding"
+        raise AbortJob
+      end
+
+      begin
+        have.subtitles = case File.extname(have.file)
+        when '.ass'
+          ASS.import(data)
+        when '.ssa'
+          SSA.import(data)
+        when '.srt'
+          SRT.import(data)
+        else
+          raise 'Not supported'
+        end
+      rescue
+        @report << "Failure while importing #{File.extname(have.file)[1..3].upcase} from #{have.file}"
+        raise AbortJob
+      end
+    end
+
+    # Transfers the subtitles from the state we {Have}, to the state we {Want}.
+    #
+    # @params have [Have] What we {Have}
+    # @params want [Want] What we {Want}
+    def retime(have, want)
+      matching_references = want.references.keys & have.references.keys
+
+      # Resolve subtitle references by getting actual timecodes
+      matching_references.each do |reference|
+        if (index = have.references[reference][:subtitle])
+          have.references[reference][:timecode] = have.subtitles[index][:start]
+        end
+      end
+
+      case matching_references.length
+      when 3..(infinity = 1.0/0)
+        # "synchronization jitter" correction by interpolating ? Consider !
+      when  2
+        retime_by_double_reference(have,
+                                     want,
+                                     matching_references[0],
+                                     matching_references[1])
+      when 1
+        if have.fps && want.fps
+          retime_by_framerate_plus_reference(have, want, matching_references[0])
+        else
+          retime_by_single_reference(have, want, matching_references[0])
+        end
+      when 0
+        if have.fps && want.fps
+          retime_by_framerate(have, want)
+        end
+      end
+    end
+
+    # Clean out subtitles that fell out of the usable time range
+    def cull(have)
+      have.subtitles.reject! { |subtitle| subtitle[:end] < 0 }
+      have.subtitles.each do |subtitle|
+        subtitle[:start] = 0 if subtitle[:start] < 0
+      end
+    end
+
+    # Assign track identification fields for distinguishing
+    # between continuous/simultaneous subtitles
+    def group(have)
+      if have.track
+        # Assign a custom track identifier if one was supplied
+        have.subtitles.each { |subtitle| subtitle[:track] = have.track }
+      elsif @haves.index(have) == 0 || @haves[@haves.index(have) - 1].subtitles.empty?
+        # Otherwise let the path be the track identifier for the first subtitle
+        have.subtitles.each { |subtitle| subtitle[:track] = have.file }
+      else
+        # For the 2nd+ subtitles determine the track association by detecting
+        # collisions against the previously imported subtitles
+
+        collisions = 0
+
+        have.subtitles.each do |subtitle|
+          @haves[@haves.index(have) - 1].subtitles.each do |previous_subtitle|
+            collisions += 1 if (subtitle[:start] > previous_subtitle[:start] &&
+                                subtitle[:start] < previous_subtitle[:end]) ||
+                               (subtitle[:end] > previous_subtitle[:start] &&
+                                subtitle[:end] < previous_subtitle[:end]) ||
+                               (previous_subtitle[:start] > subtitle[:start] &&
+                                previous_subtitle[:start] < subtitle[:end]) ||
+                               (previous_subtitle[:end] > subtitle[:start] &&
+                                previous_subtitle[:end] < subtitle[:end]) ||
+                               (subtitle[:start] == previous_subtitle[:start] ||
+                                subtitle[:end] == previous_subtitle[:end])
+          end
+        end
+
+        if collisions.to_f / have.subtitles.length.to_f > 0.01
+          # Add a new track if there are > 1% collisions between these
+          # subtitles and the ones that were last imported
+          have.subtitles.each { |subtitle| subtitle[:track] = have.file }
+        else
+          # Otherwise continue using the previous track identifier
+          # (= Assume that these and the previous subtitles are one track)
+          previous_track = @haves[@haves.index(have) - 1].subtitles.first[:track]
+          have.subtitles.each { |subtitle| subtitle[:track] = previous_track }
+        end
+      end
+    end
+
+    # Polishes what we {Want}
+    #
+    # @params want [Want] What we {Want} polished
+    def polish(want)
+      # Glue subtitle starts
+      want.subtitles.sort_by! { |subtitle| subtitle[:start] }
+      want.subtitles.each_cons(2) do |pair|
+        distance = pair[1][:start] - pair[0][:start]
+        if distance < want.glue_treshold
+          pair[0][:start] += distance / 2
+          pair[1][:start] -= distance / 2
+        end
+      end
+
+      # Glue subtitles ends
+      want.subtitles.sort_by! { |subtitle| subtitle[:end] }
+      want.subtitles.each_cons(2) do |pair|
+        if pair[1][:end]-pair[0][:end] < want.glue_treshold
+          pair[0][:end] += (pair[1][:end]-pair[0][:end]) / 2
+          pair[1][:end] -= (pair[1][:end]-pair[0][:end]) / 2
+        end
+      end
+    end
+
+    # Exports what we {Want}
+    #
+    # @param want [Want] What we {Want}
+    def export(want)
+      begin
+        data = case File.extname(want.file)
+        when '.ass'
+          ASS.master(want.subtitles)
+          ASS.export(want.subtitles)
+        when '.ssa'
+          SSA.master(want.subtitles)
+          SSA.export(want.subtitles)
+        when '.srt'
+          SRT.master(want.subtitles)
+          SRT.export(want.subtitles)
+        else
+          raise 'Not supported'
+        end
+      rescue
+        @report << "Failure while exporting #{File.extname(want.file)[1..3].upcase} for #{want.file}"
+        raise AbortJob
+      ensure
+        want.subtitles = nil
+      end
+
+      if want.encoding
+        begin
+          data.encode!(want.encoding)
+        rescue
+          @report << "Failure while transcoding from #{data.encoding} to #{want.encoding} for #{want.file}"
+          raise AbortJob
+        end
+      end
+
+      begin
+        IO.write(want.file, data)
+      rescue
+        @report << "Failure while writing to #{want.file}"
+        raise AbortJob
+      end
+    end
+
+    # Applies a simple timeshift to the subtitle we {Have}.
+    # Each subtitle gets shifted forward/backward by the same amount of seconds.
+    #
+    # @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_single_reference(have, want, reference)
+      amount = want.references[reference][:timecode] -
+               have.references[reference][:timecode]
+
+      have.subtitles.each do |subtitle|
+        subtitle[:start] += amount
+        subtitle[:end] += amount
+      end
+    end
+
+    def retime_by_framerate_plus_reference(have, want, reference)
+      ratio = want.fps.to_f / have.fps.to_f
+      have.references[reference][:timecode] *= ratio
+      have.subtitles.each do |subtitle|
+        subtitle[:start] *= ratio
+        subtitle[:end] *= ratio
+      end
+
+      amount = want.references[reference][:timecode] -
+               have.references[reference][:timecode]
+
+      have.subtitles.each do |subtitle|
+        subtitle[:start] += amount
+        subtitle[:end] += amount
+      end      
+    end
+
+    # Applies a progressive timeshift on the subtitles we {Have}
+    # Two points in time are known for both of which a different shift in time
+    # should be applied. Thus a steadily increasing or decreasing forwards or
+    # backwards shift will be applied to each subtitle, depending on its
+    # place in the time continuum
+    #
+    # @param have [Have] the subtitles we {Have}
+    # @param [Array<Float>] origins the two points in time (given in seconds)
+    #   which shall be shifted differently
+    # @param [Array<Float>] targets the two amounts of time by which to shift
+    #   either of the two points that shall be shifted
+    def retime_by_double_reference(have, want, reference_a, reference_b)
+      origins = [ have.references[reference_a][:timecode],
+                  have.references[reference_b][:timecode] ]
+
+      targets = [ want.references[reference_a][:timecode],
+                  want.references[reference_b][:timecode] ]
+
+      rescale_factor = (targets[1] - targets[0]) / (origins[1] - origins[0])
+      rebase_shift = targets[0] - origins[0] * rescale_factor
+
+      have.subtitles.each do |subtitle|
+        subtitle[:start] = subtitle[:start] * rescale_factor + rebase_shift
+        subtitle[:end] = subtitle[:end] * rescale_factor + rebase_shift
+      end
+    end
+
+    def retime_by_framerate(have, want)
+      ratio = want.fps.to_f / have.fps.to_f
+      have.subtitles.each do |subtitle|
+        subtitle[:start] *= ratio
+        subtitle[:end] *= ratio
+      end
+    end
+  end
+end

data/lib/titlekit/parsers/ass.rb

@@ -0,0 +1,175 @@
+require 'treetop'
+
+module Titlekit
+  module ASS
+
+    class Subtitles < Treetop::Runtime::SyntaxNode
+      def build
+        event_section.events.build
+      end
+    end
+
+    class ScriptInfo < Treetop::Runtime::SyntaxNode
+      def build
+        # elements.map { |subtitle| subtitle.build }
+      end
+    end
+
+    class V4PStyles < Treetop::Runtime::SyntaxNode
+      def build
+        # elements.map { |subtitle| subtitle.build }
+      end
+    end
+
+    class Events < Treetop::Runtime::SyntaxNode
+      def build
+        elements.map do |line|
+          subtitle = {}
+
+          fields = line.text_value.split(',')
+          
+          subtitle[:id] = elements.index(line) + 1
+          subtitle[:start] = SSA.parse_timecode(fields[1])
+          subtitle[:end] = SSA.parse_timecode(fields[2])
+          subtitle[:lines] = fields[9..-1].join.gsub('\N', "\n")
+
+          subtitle
+        end
+      end
+    end
+
+    # Parses the supplied string and returns the results.
+    #
+    #
+    def self.import(string)
+      Treetop.load(File.join(__dir__, 'ass'))
+      parser = ASSParser.new
+      syntax_tree = parser.parse(string)
+
+      if syntax_tree
+        return syntax_tree.build
+      else
+        failure = "failure_index #{parser.failure_index}\n"
+        failure += "failure_line #{parser.failure_line}\n"
+        failure += "failure_column #{parser.failure_column}\n"
+        failure += "failure_reason #{parser.failure_reason}\n"
+
+        raise failure
+      end 
+    end
+
+    # Master the subtitles for best possible usage of the format's features.
+    #
+    # @param subtitles [Array<Hash>] the subtitles to master
+    def self.master(subtitles)
+      tracks = subtitles.map { |subtitle| subtitle[:track] }.uniq
+
+      if tracks.length == 1
+  
+        # maybe styling? aside that: nada más!
+
+      elsif tracks.length == 2 || tracks.length == 3
+
+        subtitles.each do |subtitle|
+          case tracks.index(subtitle[:track])
+          when 0
+            subtitle[:style] = 'Default'
+          when 1
+            subtitle[:style] = 'Top'
+          when 2
+            subtitle[:style] = 'Middle'
+          end
+        end
+
+      elsif tracks.length >= 4
+
+        mastered_subtitles = []
+
+        # Determine timeframes with a discrete state
+        cuts = subtitles.map { |s| [s[:start], s[:end]] }.flatten.uniq.sort
+        frames = []
+        cuts.each_cons(2) do |pair|
+          frames << { start: pair[0], end: pair[1] }
+        end
+
+        frames.each do |frame|
+          intersecting = subtitles.select do |subtitle|
+            (subtitle[:end] == frame[:end] || subtitle[:start] == frame[:start] ||
+            (subtitle[:start] < frame[:start] && subtitle[:end] > frame[:end]))
+          end
+
+          if intersecting.any?
+            intersecting.sort_by! { |subtitle| tracks.index(subtitle[:track]) }
+            intersecting.each do |subtitle|
+              new_subtitle = {}
+              new_subtitle[:id] = mastered_subtitles.length+1
+              new_subtitle[:start] = frame[:start]
+              new_subtitle[:end] = frame[:end]
+
+              color = DEFAULT_PALETTE[tracks.index(subtitle[:track]) % DEFAULT_PALETTE.length]
+              new_subtitle[:style] = color
+              new_subtitle[:lines]  = subtitle[:lines]
+
+              mastered_subtitles << new_subtitle
+            end
+          end
+        end
+
+        subtitles.replace(mastered_subtitles)
+      end
+    end
+
+    def self.export(subtitles)
+      result = ''
+
+      result << "[Script Info]\nScriptType: v4.00+\n\n"
+      result << "[V4+ Styles]\nFormat: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding\n"
+      result << "Style: Default,Arial,16,&H00FFFFFF,&H00FFFFFF,&H40000000,&H40000000,0,0,0,0,100,100,0,0.00,1,3,0,2,20,20,20,1\n"
+      result << "Style: Top,Arial,16,&H00FFFFFF,&H00FFFFFF,&H40000000,&H40000000,0,0,0,0,100,100,0,0.00,1,3,0,8,20,20,20,1\n"
+      result << "Style: Middle,Arial,16,&H00FFFFFF,&H00FFFFFF,&H40000000,&H40000000,0,0,0,0,100,100,0,0.00,1,3,0,5,20,20,20,1\n"
+
+      DEFAULT_PALETTE.each do |color|
+        processed_color = '&H00' + (color[4..5] + color[2..3] + color[0..1])
+        result << "Style: #{color},Arial,16,#{processed_color},#{processed_color},&H40000000,&H40000000,0,0,0,0,100,100,0,0.00,1,3,0,2,20,20,20,1\n"
+      end
+
+      result << "\n" # Close styles section
+      
+      result << "[Events]\nFormat: Layer, Start, End, Style, Actor, MarginL, MarginR, MarginV, Effect, Text\n"
+      
+      subtitles.each do |subtitle|
+        fields = [
+          'Dialogue: 0',  # Format: Marked
+          SSA.build_timecode(subtitle[:start]),  # Start
+          SSA.build_timecode(subtitle[:end]),  # End
+          subtitle[:style] || 'Default',  # Style
+          '',  # Name
+          '0000',  # MarginL
+          '0000',  # MarginR
+          '0000',  # MarginV
+          '',# Effect
+          subtitle[:lines].gsub("\n", '\N')  # Text
+        ]
+
+        result << fields.join(',') + "\n"
+      end
+
+      return result
+    end
+
+    protected
+
+    def self.build_timecode(seconds)
+      sprintf("%01d:%02d:%02d.%s",
+              seconds / 3600,
+              (seconds%3600) / 60,
+              seconds % 60,
+              sprintf("%.2f", seconds)[-2, 3])
+    end
+
+    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
+    end     
+  end
+end

data/lib/titlekit/parsers/ass.treetop

@@ -0,0 +1,72 @@
+grammar ASS
+  rule subtitles
+    info?
+    styles?
+    event_section
+    fonts?
+    graphics?
+    end_of_data
+
+    <Titlekit::ASS::Subtitles>
+  end
+
+  rule info
+    '[Script Info]' end_of_line lines* end_of_section <Titlekit::ASS::ScriptInfo>
+  end
+
+  rule styles
+    '[V4+ Styles]' end_of_line lines* end_of_section <Titlekit::ASS::V4PStyles>
+  end
+
+  rule event_section
+    '[Events]' end_of_line line events end_of_section
+  end
+
+  rule events
+    line* <Titlekit::ASS::Events>
+  end
+
+  rule event
+    'Dialogue'
+  end
+
+  rule fonts
+    '[Fonts]' end_of_line lines* end_of_section
+  end
+
+  rule graphics
+    '[Graphics]' end_of_line lines* end_of_section
+  end
+
+  rule lines
+    line+
+  end
+
+  rule line
+    string (end_of_line / end_of_file)
+  end
+
+  rule end_of_section
+    end_of_line+ / end_of_file
+  end
+  
+  rule end_of_line
+    "\r\n" / "\n" / "\r"
+  end
+
+  rule end_of_data
+    end_of_line+ / end_of_file
+  end
+
+  rule end_of_file
+    !.
+  end
+  
+  rule number
+    [0-9]+
+  end
+
+  rule string
+    (!end_of_line .)+
+  end
+end