cohere-transcribe 0.1.0

data/lib/cohere/transcribe/output/rendering.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../python_text"
+require_relative "../types"
+
+module Cohere
+  module Transcribe
+    module Output
+      module Rendering
+        module_function
+
+        SENTENCE_ENDINGS = [".", "!", "?", "؟", "،", "؛", "…"].freeze
+
+        def build_cues(words, max_chars:, max_duration:, max_gap:, min_cue_duration: 0.30, media_duration: nil)
+          cue_words = []
+          current = []
+          words.each do |word|
+            if current.any?
+              candidate = (current.map { |item| field(item, :text) } + [field(word, :text)]).join(" ")
+              gap = field(word, :start) - field(current.last, :end)
+              duration = field(word, :end) - field(current.first, :start)
+              if candidate.length > max_chars || duration > max_duration || gap > max_gap
+                cue_words << current
+                current = []
+              end
+            end
+            current << word
+            if SENTENCE_ENDINGS.any? { |ending| field(word, :text).end_with?(ending) }
+              cue_words << current
+              current = []
+            end
+          end
+          cue_words << current if current.any?
+
+          cues = cue_words.map do |items|
+            SubtitleCue.new(
+              start: [0.0, field(items.first, :start)].max,
+              end: [field(items.first, :start), field(items.last, :end)].max,
+              text: PythonText.strip(items.map { |item| field(item, :text) }.join(" "))
+            )
+          end
+          cues.each_with_index.map do |cue, index|
+            start_time = media_duration ? [cue.start, media_duration].min : cue.start
+            end_time = media_duration ? [cue.end, media_duration].min.clamp(start_time, media_duration) : cue.end
+            next_start = index + 1 < cues.length ? cues[index + 1].start : Float::INFINITY
+            upper_bound = [next_start, media_duration || Float::INFINITY].min
+            desired_end = [end_time, start_time + min_cue_duration].max
+            cue.with(start: start_time, end: [[desired_end, upper_bound].min, start_time].max)
+          end.freeze
+        end
+
+        def timestamp(seconds, include_hours: false, marker: ".")
+          milliseconds = ([0.0, seconds].max * 1000).round(half: :even)
+          hours, milliseconds = milliseconds.divmod(3_600_000)
+          minutes, milliseconds = milliseconds.divmod(60_000)
+          whole_seconds, milliseconds = milliseconds.divmod(1000)
+          if include_hours || hours.positive?
+            format("%<hours>02d:%<minutes>02d:%<seconds>02d%<marker>s%<milliseconds>03d",
+                   hours: hours, minutes: minutes, seconds: whole_seconds, marker: marker, milliseconds: milliseconds)
+          else
+            format("%<minutes>02d:%<seconds>02d%<marker>s%<milliseconds>03d",
+                   minutes: minutes, seconds: whole_seconds, marker: marker, milliseconds: milliseconds)
+          end
+        end
+
+        def plain_text(lines)
+          normalized = lines.filter_map do |line|
+            text = PythonText.strip(line.to_s)
+            text unless text.empty?
+          end
+          "#{normalized.join("\n")}\n"
+        end
+
+        def srt(cues)
+          cues.each_with_index.map do |cue, index|
+            "#{index + 1}\n#{timestamp(field(cue, :start), include_hours: true, marker: ",")} --> " \
+              "#{timestamp(field(cue, :end), include_hours: true, marker: ",")}\n#{field(cue, :text)}\n\n"
+          end.join
+        end
+
+        def vtt(cues)
+          body = cues.map do |cue|
+            "#{timestamp(field(cue, :start))} --> #{timestamp(field(cue, :end))}\n#{field(cue, :text)}\n\n"
+          end.join
+          "WEBVTT\n\n#{body}"
+        end
+
+        def json(payload)
+          "#{JSON.pretty_generate(payload)}\n"
+        end
+
+        def field(value, name)
+          return value.public_send(name) if value.respond_to?(name)
+          return value[name] if value.respond_to?(:key?) && value.key?(name)
+          return value[name.to_s] if value.respond_to?(:key?) && value.key?(name.to_s)
+
+          raise KeyError, "missing #{name}"
+        end
+        private_class_method :field
+      end
+    end
+  end
+end

data/lib/cohere/transcribe/output/timing.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../python_text"
+require_relative "../types"
+
+module Cohere
+  module Transcribe
+    module Output
+      module Timing
+        module_function
+
+        def uniform_words(text, start_time, end_time, segment_index, timing_source = "uniform_segment")
+          tokens = PythonText.split(text.to_s)
+          return [] if tokens.empty?
+
+          token_duration = [0.0, end_time - start_time].max.fdiv(tokens.length)
+          tokens.each_with_index.map do |token, index|
+            TranscriptionWord.new(
+              start: start_time + (index * token_duration),
+              end: start_time + ((index + 1) * token_duration),
+              text: token,
+              segment_index: segment_index,
+              segment_word_index: index,
+              timing_source: timing_source
+            )
+          end.freeze
+        end
+
+        def uniform_words_across_spans(text, spans, segment_index, timing_source = "uniform_speech_spans")
+          tokens = PythonText.split(text.to_s)
+          valid_spans = spans.select { |start_time, end_time| end_time > start_time }
+          return [] if tokens.empty? || valid_spans.empty?
+
+          counts = proportional_counts(tokens.length, valid_spans)
+          token_offset = 0
+          words = valid_spans.zip(counts).flat_map do |(start_time, end_time), count|
+            next [] unless count.positive?
+
+            duration = (end_time - start_time).fdiv(count)
+            Array.new(count) do |local_index|
+              token_index = token_offset + local_index
+              TranscriptionWord.new(
+                start: start_time + (local_index * duration),
+                end: start_time + ((local_index + 1) * duration),
+                text: tokens.fetch(token_index),
+                segment_index: segment_index,
+                segment_word_index: token_index,
+                timing_source: timing_source
+              )
+            end.tap { token_offset += count }
+          end
+          raise "Speech-span token allocation did not preserve every token" unless token_offset == tokens.length
+
+          words.freeze
+        end
+
+        def proportional_counts(token_count, spans)
+          raise ArgumentError, "token_count must be non-negative" if token_count.negative?
+
+          durations = spans.map { |start_time, end_time| [0.0, end_time - start_time].max }
+          total = durations.sum
+          return Array.new(spans.length, 0).freeze if token_count.zero? || total <= 0
+
+          exact = durations.map { |duration| token_count * duration.fdiv(total) }
+          counts = exact.map(&:floor)
+          remaining = token_count - counts.sum
+          order = spans.each_index.sort_by do |index|
+            [-(exact[index] - counts[index]), -durations[index], index]
+          end
+          order.first(remaining).each { |index| counts[index] += 1 }
+          counts.freeze
+        end
+
+        def spans_within(speech_spans, start_time, end_time)
+          speech_spans.filter_map do |speech_start, speech_end|
+            next unless speech_end > start_time && speech_start < end_time
+
+            clipped_start = [start_time, speech_start].max
+            clipped_end = [end_time, speech_end].min
+            [clipped_start, clipped_end] if clipped_end > clipped_start
+          end.freeze
+        end
+      end
+    end
+  end
+end

data/lib/cohere/transcribe/python_text.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Cohere
+  module Transcribe
+    # Python's str.strip()/str.split() recognize a slightly wider whitespace
+    # set than Ruby's String#strip/String#split. Keep public validation and text
+    # normalization stable across the two language implementations.
+    module PythonText
+      WHITESPACE_CLASS = "[[:space:]\u001C-\u001F]"
+      LEADING_WHITESPACE = /\A#{WHITESPACE_CLASS}+/u
+      TRAILING_WHITESPACE = /#{WHITESPACE_CLASS}+\z/u
+      WHITESPACE_RUN = /#{WHITESPACE_CLASS}+/u
+      # Python 3.12 uses Unicode 15.0. Ruby 4 recognizes a small Unicode 16
+      # set whose newly assigned case/compatibility mappings would otherwise
+      # make the same input normalize differently from the reference package.
+      UNICODE_15_NORMALIZATION_BOUNDARIES = [
+        0x1C89,
+        0xA7CB, 0xA7CC, 0xA7CE, 0xA7D2, 0xA7D4, 0xA7DA, 0xA7DC, 0xA7F1,
+        *(0x10D50..0x10D65),
+        *(0x16EA0..0x16EB8),
+        *(0x1CCD6..0x1CCF9)
+      ].to_h { |codepoint| [codepoint, true] }.freeze
+      private_constant :WHITESPACE_CLASS, :LEADING_WHITESPACE, :TRAILING_WHITESPACE, :WHITESPACE_RUN,
+                       :UNICODE_15_NORMALIZATION_BOUNDARIES
+
+      module_function
+
+      def strip(value)
+        value.sub(LEADING_WHITESPACE, "").sub(TRAILING_WHITESPACE, "")
+      end
+
+      def blank?(value)
+        strip(value).empty?
+      end
+
+      def split(value)
+        stripped = strip(value)
+        stripped.empty? ? [] : stripped.split(WHITESPACE_RUN)
+      end
+
+      def collapse(value)
+        strip(value.gsub(WHITESPACE_RUN, " "))
+      end
+
+      def nfkc_lower(value)
+        return value.unicode_normalize(:nfkc).downcase unless value.each_codepoint.any? do |codepoint|
+          UNICODE_15_NORMALIZATION_BOUNDARIES.key?(codepoint)
+        end
+
+        normalized = +""
+        ordinary = +""
+        value.each_char do |character|
+          if UNICODE_15_NORMALIZATION_BOUNDARIES.key?(character.ord)
+            normalized << ordinary.unicode_normalize(:nfkc).downcase
+            ordinary.clear
+            normalized << character
+          else
+            ordinary << character
+          end
+        end
+        normalized << ordinary.unicode_normalize(:nfkc).downcase
+      end
+
+      def whitespace_class
+        WHITESPACE_CLASS
+      end
+    end
+    private_constant :PythonText
+  end
+end