gosavetool 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 69f3cfb13ab8816d737f566f527bda5e73a895d29512c41c5e99d98e344b211f
+  data.tar.gz: fc2ca7bce7f80fc3e2ad6851daf828c640df5f6129f4f56ca50f2cb652166f4a
+SHA512:
+  metadata.gz: f7c43d20f31741d1300b477c5821c169ab4afe3984b07cdfbbad958c03c0d6d275e8f3b00541e8ddffd093fad11f63fca47d827a347793cc9b0619fe83acd3b8
+  data.tar.gz: 9400fa7db0d4086150d39c0b9af9335ca55d8a2762e0a0a09cfddd78a2e44cdcb01793d93b1a5662ae24d7f4ebe9af8ae498b676ff4580262a49c884fb8e792b

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0 (2026-11-01)
+
+- First release: GoSaveTool::Subtitles (parse, convert, shift and repair SRT and WebVTT), GoSaveTool::Text (word count, social media limits, case changes, slugs, whitespace cleanup) and the `gosavetool` command.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GoSaveTool
+
+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/README.md

@@ -0,0 +1,61 @@
+# gosavetool
+
+Parse, convert, shift and repair **SRT and WebVTT** subtitles, and count **words, characters and reading time** with **social media character limits**, **Title Case**, **slugs** and other case changes. A Ruby library and a command-line tool, with no dependencies.
+
+Made by [GoSaveTool](https://www.gosavetool.com/), free online tools for creators.
+
+## Install
+
+```bash
+gem install gosavetool
+```
+
+Or in a Gemfile: `gem "gosavetool"`. Requires Ruby 3.0 or newer.
+
+## Command line
+
+```bash
+gosavetool convert movie.srt --to vtt      # writes movie.vtt
+gosavetool shift movie.srt -1.5            # 1.5 s earlier, in place
+gosavetool repair movie.srt                # sort, fix overlaps and bad times
+gosavetool info movie.vtt                  # WebVTT, 412 cues, ends at 01:42:10.500
+
+echo "Your caption" | gosavetool count
+gosavetool limits post.txt                 # characters left for X, Instagram, TikTok, YouTube, SEO...
+echo "the lord of the rings" | gosavetool case title
+```
+
+## Library
+
+```ruby
+require "gosavetool"
+
+S = GoSaveTool::Subtitles
+vtt = S.convert(File.read("movie.srt"), "vtt")
+cues = S.parse(text)                          # [#<struct Cue start=1000, end=3500, settings="", text="Hello">, ...]
+later = S.to_srt(S.shift(cues, 1500))
+fixed, n = S.repair(cues)                     # sorted, no overlaps, no empty cues
+
+T = GoSaveTool::Text
+T.stats(post)                                 # { words:, chars:, chars_no_spaces:, lines:, sentences:, read_seconds: }
+T.limits(post)["x-post"][:fits]               # also instagram-caption, tiktok-caption, youtube-title, seo-title, ...
+T.title("the lord of the rings")              # "The Lord of the Rings"
+T.slug("Ölçü Birimi & Çeviri!")               # "olcu-birimi-ceviri"
+T.camel("best posting time")                  # "bestPostingTime"
+```
+
+Characters are Unicode code points, so an emoji counts as one. The rules are the same as the [`@gosavetool/subtitles`](https://www.npmjs.com/package/@gosavetool/subtitles) and [`@gosavetool/text`](https://www.npmjs.com/package/@gosavetool/text) JavaScript packages.
+
+## Tests
+
+```bash
+rake test
+```
+
+## Online tools
+
+[VTT Subtitle Generator](https://www.gosavetool.com/vtt-subtitle-generator), [Auto Captions Generator](https://www.gosavetool.com/auto-captions-generator), [Character Counter](https://www.gosavetool.com/character-counter)
+
+## License
+
+MIT

data/exe/gosavetool

@@ -0,0 +1,117 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# gosavetool: subtitle and text tools on the command line. https://www.gosavetool.com/
+require "gosavetool"
+
+HELP = <<~TEXT
+  GoSaveTool #{GoSaveTool::VERSION}: subtitle and text tools
+
+  Subtitles:
+    gosavetool convert <file> --to srt|vtt   Write name.srt or name.vtt next to the file
+    gosavetool shift <file> <seconds>        Move every cue (1.5 = later, -2 = earlier), in place
+    gosavetool repair <file>                 Sort, fix overlaps and bad times, renumber, in place
+    gosavetool info <file>                   Format, number of cues and the end time
+
+  Text (reads the file, or standard input without one):
+    gosavetool count [file]                  Words, characters, sentences, lines, reading time
+    gosavetool limits [file]                 Social media and SEO character limits
+    gosavetool case <title|sentence|upper|lower|slug|camel|snake|kebab|clean> [file]
+
+  Options:
+    -o, --out <file>   Write to this file instead
+    --stdout           Print the result instead of writing a file
+
+  Online tools: https://www.gosavetool.com/
+TEXT
+
+CASES = %w[title sentence upper lower slug camel snake kebab clean].freeze
+
+def fail_with(msg)
+  warn "gosavetool: #{msg}\n\nRun gosavetool --help for usage."
+  exit 1
+end
+
+args = ARGV.dup
+take = lambda do |*names|
+  i = args.index { |a| names.include?(a) }
+  next nil unless i
+
+  args.delete_at(i)
+  args.delete_at(i)
+end
+to = take.call("--to")
+out = take.call("-o", "--out")
+stdout = !args.delete("--stdout").nil?
+
+if args.empty? || args.include?("-h") || args.include?("--help")
+  puts HELP
+  exit 0
+end
+if args.include?("-v") || args.include?("--version")
+  puts GoSaveTool::VERSION
+  exit 0
+end
+
+save = lambda do |content, target|
+  if stdout
+    print content
+  else
+    File.write(out || target, content)
+    puts "Wrote #{out || target}"
+  end
+end
+
+cmd = args.shift
+T = GoSaveTool::Text
+S = GoSaveTool::Subtitles
+
+case cmd
+when "count", "limits", "case"
+  op = cmd == "case" ? args.shift : nil
+  fail_with("case needs one of: #{CASES.join(', ')}") if cmd == "case" && !CASES.include?(op)
+  file = args.first
+  fail_with("file not found: #{file}") if file && file != "-" && !File.exist?(file)
+  s = file && file != "-" ? File.read(file, encoding: "UTF-8") : $stdin.read.force_encoding("UTF-8")
+  # A file or a pipe ends with a newline that is not part of the text being counted
+  counted = s.sub(/\r?\n\z/, "")
+  if cmd == "count"
+    st = T.stats(counted)
+    puts "Words: #{st[:words]}", "Characters: #{st[:chars]}", "Without spaces: #{st[:chars_no_spaces]}",
+         "Sentences: #{st[:sentences]}", "Lines: #{st[:lines]}", "Reading time: #{st[:read_seconds]} s"
+  elsif cmd == "limits"
+    T.limits(counted).each do |field, l|
+      puts format("%-22s%5d  %s", field, l[:limit], l[:fits] ? "#{l[:left]} left" : "#{-l[:left]} over")
+    end
+  elsif out
+    save.call(T.public_send(op, s), out)
+  else
+    print T.public_send(op, s)
+  end
+when "convert", "shift", "repair", "info"
+  file = args.first
+  fail_with("missing file") unless file
+  fail_with("file not found: #{file}") unless File.exist?(file)
+  src = File.read(file, encoding: "UTF-8")
+  cues = S.parse(src)
+  fail_with("no subtitle cues found in #{file}") if cues.empty?
+  vtt = S.vtt?(src)
+  write = ->(c) { vtt ? S.to_vtt(c) : S.to_srt(c) }
+  case cmd
+  when "convert"
+    fail_with("convert needs --to srt or --to vtt") unless %w[srt vtt].include?(to)
+    save.call(S.convert(src, to), file.sub(/\.[^.\/\\]*\z/, "") + ".#{to}")
+  when "shift"
+    seconds = Float(args[1].to_s.tr(",", "."), exception: false)
+    fail_with("shift needs seconds, like 1.5 or -2") unless seconds
+    save.call(write.call(S.shift(cues, (seconds * 1000).round)), file)
+  when "repair"
+    fixed, n = S.repair(cues)
+    save.call(write.call(fixed), file)
+    puts(n.positive? ? "#{n} problems fixed" : "No problems found") unless stdout
+  else
+    puts "#{vtt ? 'WebVTT' : 'SRT'}, #{cues.length} cues, ends at #{S.from_ms(cues.map(&:end).max, vtt ? '.' : ',')}"
+  end
+else
+  fail_with("unknown command #{cmd}")
+end

data/lib/gosavetool/subtitles.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module GoSaveTool
+  # SRT and WebVTT: read cues, write them in either format, shift and repair timings.
+  # The Ruby version of @gosavetool/subtitles: https://www.gosavetool.com/vtt-subtitle-generator
+  module Subtitles
+    # One subtitle cue; times in milliseconds.
+    Cue = Struct.new(:start, :end, :settings, :text, keyword_init: true)
+
+    STAMP = /(?:\d{1,2}:)?\d{1,2}:\d{1,2}[,.]\d{1,3}/
+    TIME = /(\d{1,2}:)?(\d{1,2}):(\d{1,2})[,.](\d{1,3})/
+    ARROW = /\A\s*(#{STAMP})\s*-->\s*(#{STAMP})(.*)\z/
+
+    module_function
+
+    # "00:01:02,500" or "01:02.5" => 62500; nil when it is not a timestamp
+    def to_ms(stamp)
+      m = TIME.match(stamp)
+      return nil unless m
+
+      h = m[1] ? m[1].chomp(":").to_i : 0
+      ((h * 60 + m[2].to_i) * 60 + m[3].to_i) * 1000 + m[4].ljust(3, "0").to_i
+    end
+
+    # 62500 => "00:01:02,500" (sep ",", SRT) or "00:01:02.500" (sep ".", WebVTT)
+    def from_ms(ms, sep = ",")
+      # Half up, as JavaScript's Math.round
+      t = [(ms + 0.5).floor, 0].max
+      format("%02d:%02d:%02d%s%03d", t / 3_600_000, t / 60_000 % 60, t / 1000 % 60, sep, t % 1000)
+    end
+
+    # Cues of an SRT or WebVTT text. Headers, NOTE and STYLE blocks are skipped.
+    def parse(src)
+      # "\r\r\n" too: a file saved twice with Windows line endings
+      text = src.delete_prefix("").gsub(/\r*\n|\r/, "\n")
+      text.split(/\n{2,}/).filter_map do |block|
+        lines = block.split("\n", -1)
+        at = lines.index { |l| ARROW.match?(l) }
+        next unless at
+
+        m = ARROW.match(lines[at])
+        Cue.new(start: to_ms(m[1]), end: to_ms(m[2]), settings: m[3].strip, text: lines[(at + 1)..].join("\n").strip)
+      end
+    end
+
+    # True when the text starts with the WEBVTT signature
+    def vtt?(src)
+      src.delete_prefix("").start_with?("WEBVTT")
+    end
+
+    def to_srt(cues)
+      cues.each_with_index.map { |c, i| "#{i + 1}\n#{from_ms(c.start, ',')} --> #{from_ms(c.end, ',')}\n#{c.text}" }.join("\n\n") + "\n"
+    end
+
+    def to_vtt(cues)
+      body = cues.map do |c|
+        settings = c.settings.to_s.empty? ? "" : " #{c.settings}"
+        "#{from_ms(c.start, '.')} --> #{from_ms(c.end, '.')}#{settings}\n#{c.text}"
+      end
+      "WEBVTT\n\n#{body.join("\n\n")}\n"
+    end
+
+    # Converts a subtitle text to "srt" or "vtt"
+    def convert(src, to)
+      case to.to_s
+      when "vtt" then to_vtt(parse(src))
+      when "srt" then to_srt(parse(src))
+      else raise ArgumentError, 'the target format must be "srt" or "vtt"'
+      end
+    end
+
+    # Moves every cue by ms (negative = earlier); cues pushed before zero are clipped or dropped
+    def shift(cues, ms)
+      cues.map { |c| Cue.new(start: [c.start + ms, 0].max, end: [c.end + ms, 0].max, settings: c.settings, text: c.text) }
+          .select { |c| c.end.positive? }
+    end
+
+    # Sorts cues, fixes end times before the start and overlaps, drops empty cues.
+    # Returns [cues, number_of_changes]. The input is not changed.
+    def repair(cues, min_duration: 2000)
+      fixed = cues.count { |c| c.text.empty? }
+      kept = cues.reject { |c| c.text.empty? }.map(&:dup)
+      # sort_by is not stable in Ruby, so the original position breaks ties
+      out = kept.each_with_index.sort_by { |c, i| [c.start, i] }.map(&:first)
+      fixed += 1 if out.map(&:start) != kept.map(&:start)
+      out.each_with_index do |c, i|
+        nxt = out[i + 1]
+        unless c.end > c.start
+          c.end = c.start + min_duration
+          fixed += 1
+        end
+        if nxt && c.end > nxt.start
+          c.end = [c.start + 1, nxt.start - 1].max
+          fixed += 1
+        end
+      end
+      [out, fixed]
+    end
+  end
+end

data/lib/gosavetool/text.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module GoSaveTool
+  # Word, character and reading-time counts, social media character limits, case changes, URL slugs and
+  # whitespace cleanup. The Ruby version of @gosavetool/text: https://www.gosavetool.com/character-counter
+  module Text
+    # Character limits of common fields; SEO values are the length search results show before cutting
+    LIMITS = {
+      "x-post" => 280,
+      "instagram-caption" => 2200,
+      "tiktok-caption" => 4000,
+      "youtube-title" => 100,
+      "youtube-description" => 5000,
+      "linkedin-post" => 3000,
+      "pinterest-description" => 500,
+      "seo-title" => 60,
+      "meta-description" => 160
+    }.freeze
+
+    SMALL = %w[a an and as at but by for in nor of on or so the to up yet via vs].freeze
+    SLUG_MAP = {
+      "ı" => "i", "İ" => "i", "ş" => "s", "Ş" => "s", "ğ" => "g", "Ğ" => "g", "ç" => "c", "Ç" => "c", "ö" => "o",
+      "Ö" => "o", "ü" => "u", "Ü" => "u", "ß" => "ss", "æ" => "ae", "ø" => "o", "đ" => "d", "ł" => "l"
+    }.freeze
+
+    WORD = /[\p{L}\p{N}][\p{L}\p{N}'’_-]*/
+    TITLE_WORD = /[\p{L}\p{N}][\p{L}\p{N}'’]*/
+    SENTENCE = /[^.!?…]+[.!?…]+/
+
+    module_function
+
+    # Words, characters, lines, sentences and reading time (238 words a minute) of a text.
+    # Characters are Unicode code points, so an emoji counts as one.
+    def stats(s)
+      words = s.scan(WORD).length
+      {
+        words: words,
+        chars: s.length,
+        chars_no_spaces: s.gsub(/[[:space:]]/, "").length,
+        lines: s.empty? ? 0 : s.split(/\r\n|\r|\n/, -1).length,
+        sentences: s.scan(SENTENCE).length,
+        read_seconds: (words / 238.0 * 60 + 0.5).floor
+      }
+    end
+
+    # How the text meets each limit: { "x-post" => { limit: 280, used: 120, left: 160, fits: true }, ... }
+    def limits(s, only = nil)
+      used = s.length
+      LIMITS.each_with_object({}) do |(field, limit), out|
+        next if only && !only.include?(field)
+
+        out[field] = { limit: limit, used: used, left: limit - used, fits: used <= limit }
+      end
+    end
+
+    # "bestPostingTime 2" => ["best", "Posting", "Time", "2"]
+    def words(s)
+      s.gsub(/([\p{Ll}\p{N}])(\p{Lu})/, '\1 \2').split(/[^\p{L}\p{N}]+/).reject(&:empty?)
+    end
+
+    def upper(s) = s.upcase
+    def lower(s) = s.downcase
+
+    def capitalize_first(w)
+      w.empty? ? w : w[0].upcase + w[1..]
+    end
+
+    # "the lord of the rings: return of the king" => "The Lord of the Rings: Return of the King"
+    def title(s)
+      low = s.downcase
+      first = true
+      low.gsub(TITLE_WORD) do |w|
+        at = Regexp.last_match.begin(0)
+        after_colon = low[0, at].match?(/[:.!?][[:space:]]*\z/)
+        keep = !first && !after_colon && SMALL.include?(w)
+        first = false
+        keep ? w : capitalize_first(w)
+      end
+    end
+
+    # "HELLO WORLD. how ARE you?" => "Hello world. How are you?"
+    def sentence(s)
+      s.downcase.gsub(/(\A[[:space:]]*|[.!?…][[:space:]]+)(\p{L})/) { Regexp.last_match(1) + Regexp.last_match(2).upcase }
+    end
+
+    # "Ölçü Birimi & Çeviri!" => "olcu-birimi-ceviri"
+    def slug(s)
+      mapped = s.gsub(/[ıİşŞğĞçÇöÖüÜßæøđł]/, SLUG_MAP)
+      mapped.unicode_normalize(:nfkd).gsub(/[̀-ͯ]/, "").downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+    end
+
+    def camel(s)
+      words(s).each_with_index.map { |w, i| i.zero? ? w.downcase : capitalize_first(w.downcase) }.join
+    end
+
+    def snake(s) = words(s).map(&:downcase).join("_")
+    def kebab(s) = words(s).map(&:downcase).join("-")
+
+    # Removes trailing spaces, runs of spaces and more than one blank line in a row.
+    def clean(s)
+      nl = s.include?("\r\n") ? "\r\n" : "\n"
+      lines = s.split(/\r\n|\n/, -1).map { |l| l.sub(/[ \t]+\z/, "").gsub(/([^[:space:]])[ \t]{2,}/, '\1 ') }
+      lines.join(nl).gsub(/(?:#{Regexp.escape(nl)}){3,}/, nl * 2)
+    end
+  end
+end

data/lib/gosavetool/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GoSaveTool
+  VERSION = "1.0.0"
+end

data/lib/gosavetool.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "gosavetool/version"
+require_relative "gosavetool/subtitles"
+require_relative "gosavetool/text"
+
+# Subtitle and text tools from GoSaveTool, free online tools for creators: https://www.gosavetool.com/
+#
+#   GoSaveTool::Subtitles.convert(srt, "vtt")
+#   GoSaveTool::Text.title("the lord of the rings")   # => "The Lord of the Rings"
+module GoSaveTool
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: gosavetool
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- GoSaveTool
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Parse, convert, shift and repair SRT and WebVTT subtitles; word, character
+  and reading-time counts, social media character limits, Title Case, slugs and other
+  case changes. No dependencies, with a command-line tool.
+executables:
+- gosavetool
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/gosavetool
+- lib/gosavetool.rb
+- lib/gosavetool/subtitles.rb
+- lib/gosavetool/text.rb
+- lib/gosavetool/version.rb
+homepage: https://www.gosavetool.com/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.gosavetool.com/
+  source_code_uri: https://github.com/mitolocya/gosavetool-ruby
+  bug_tracker_uri: https://www.gosavetool.com/contact
+  changelog_uri: https://github.com/mitolocya/gosavetool-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: SRT and WebVTT subtitle tools, word count, social media limits and case changes
+test_files: []