speedrun 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c0622185252d91812dedda26e692722bca73497fb9ef979cab8d4af602391867
+  data.tar.gz: 8c8d1ffb726b10f5aa0bf6c948713af211f710617fe348a9174f0cf57bd2a689
+SHA512:
+  metadata.gz: b46d265c87d2679cef58df69c092bf72b297b27ca1663dfb5b72dd8f41a4208d9ab982cb0e26d8bab53aded0f6cdaf6a84b4fdb6753bef419faf1cc7ceb0a35c
+  data.tar.gz: cd11c55079861ada32b8eca148fe3c022b628b6d36b682d6a38126330f10c687bde7fdd66f787c82ddf8592118d47f429e30681837113cf46f90e1d368330796

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-11-03
+
+### Added
+- Initial release of speedrun gem
+- Core video trimming functionality to detect and remove freeze/low-motion regions
+- FFmpeg integration for video processing
+- CLI interface with Thor framework
+- Time, duration, and filesize formatters
+- Freeze detection using motion vectors
+- Video segment extraction and concatenation
+- Dry-run mode for testing without processing
+- Configurable noise threshold for motion detection
+- Progress feedback during video processing
+- Comprehensive test suite with mocked FFmpeg calls

data/Guardfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+guard :minitest, autorun: false do
+  # Watch lib files and run all tests
+  watch(%r{^lib/(.+)\.rb$}) { 'test' }
+
+  # Watch test files and run corresponding test
+  watch(%r{^test/test_(.+)\.rb$})
+  watch(%r{^test/speedrun/test_(.+)\.rb$})
+
+  # Watch test_helper and run all tests
+  watch(%r{^test/test_helper\.rb$}) { 'test' }
+  watch(%r{^test/support/.+\.rb$}) { 'test' }
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Benjamin Jackson
+
+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,140 @@
+# speedrun
+
+Automatically detect and remove freeze/low-motion regions from videos using ffmpeg.
+
+## Description
+
+`speedrun` analyzes videos for frozen or low-motion segments (using ffmpeg's `freezedetect` filter) and removes them, stitching together only the active parts. Perfect for cleaning up screen recordings, presentation videos, or any footage with long static periods.
+
+## Installation
+
+Install the gem:
+
+```bash
+gem install speedrun
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'speedrun'
+```
+
+### Requirements
+
+- Ruby >= 3.2.0
+- ffmpeg (with freezedetect filter support)
+- ffprobe
+
+Install ffmpeg via your package manager:
+
+```bash
+# macOS
+brew install ffmpeg
+
+# Ubuntu/Debian
+apt-get install ffmpeg
+
+# Arch Linux
+pacman -S ffmpeg
+```
+
+## Usage
+
+Basic usage:
+
+```bash
+speedrun trim input.mp4
+```
+
+This creates `input-trimmed.mp4` with frozen segments removed.
+
+### Options
+
+```bash
+speedrun trim INPUT [OUTPUT] [options]
+
+Options:
+  -n, --noise THRESHOLD        # Noise tolerance in dB (default: -70)
+  -d, --duration SECONDS       # Minimum freeze duration in seconds (default: 1.0)
+  --dry-run                    # Preview without processing
+  -q, --quiet                  # Minimal output
+
+Examples:
+  speedrun trim video.mp4                                    # Creates video-trimmed.mp4
+  speedrun trim video.mp4 output.mp4                         # Custom output name
+  speedrun trim video.mp4 --noise -60                        # More sensitive detection
+  speedrun trim video.mp4 --duration 2.0                     # Only remove freezes >= 2s
+  speedrun trim video.mp4 --dry-run                          # Preview analysis only
+```
+
+#### Understanding the Noise Threshold
+
+The `--noise` parameter controls how sensitive freeze detection is to small changes in the video:
+
+- **Less negative values** (like `-60 dB`) = **More sensitive**
+  Detects freezes even when there's subtle motion or slight changes
+  Use when you want to catch nearly-static sections
+
+- **More negative values** (like `-80 dB`) = **Less sensitive**
+  Only detects freezes when frames are nearly identical
+  Use when you want to preserve sections with minimal motion
+
+The default of `-70 dB` works well for most screen recordings. If you're getting false positives (motion incorrectly flagged as frozen), try `-80 dB`. If freezes are being missed, try `-60 dB`.
+
+### Other Commands
+
+```bash
+speedrun version                   # Show version
+speedrun help                      # Show help
+```
+
+## How It Works
+
+1. **Detect:** Uses ffmpeg's `freezedetect` filter to find frozen/low-motion segments
+2. **Analyze:** Calculates which portions to keep vs. remove
+3. **Extract:** Extracts active segments using ffmpeg
+4. **Stitch:** Concatenates segments into final output
+
+## Development
+
+After checking out the repo:
+
+```bash
+bin/setup                      # Install dependencies
+bundle exec rake test          # Run test suite
+bundle exec guard              # Auto-run tests on file changes
+```
+
+### Testing
+
+The codebase follows strict TDD with 100% test coverage. All ffmpeg calls are mocked for fast, isolated testing.
+
+```bash
+bundle exec rake test          # Run full test suite
+```
+
+### Test Structure
+
+- **Unit tests:** All components tested in isolation with mocks
+- **Integration tests:** Full workflow with mocked FFmpeg
+- **Fixtures:** Sample ffmpeg/ffprobe outputs for realistic testing
+
+## Architecture
+
+```
+lib/speedrun/
+├── version.rb        # Version constant
+├── formatter.rb      # Time/duration/filesize formatters
+├── ffmpeg.rb         # FFmpeg command wrappers & parsers
+├── trimmer.rb        # Core video processing logic
+└── cli.rb            # Thor-based CLI interface
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/benjaminjackson/speedrun.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/exe/speedrun

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "speedrun"
+
+Speedrun::CLI.start(ARGV)

data/lib/speedrun/cli.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module Speedrun
+  class CLI < Thor
+    desc "version", "Display version"
+    def version
+      puts "speedrun version #{Speedrun::VERSION}"
+    end
+
+    desc "trim INPUT [OUTPUT]", "Trim freeze/low-motion regions from video"
+    option :noise, type: :numeric, aliases: '-n', default: -70, desc: "Noise tolerance in dB (less negative = more cuts)"
+    option :duration, type: :numeric, aliases: '-d', default: 1.0, desc: "Minimum freeze duration to remove in seconds"
+    option :'dry-run', type: :boolean, default: false, desc: "Preview without processing"
+    option :quiet, type: :boolean, aliases: '-q', default: false, desc: "Minimal output"
+    def trim(input_file, output_file = nil)
+      unless File.exist?(input_file)
+        puts "Error: File not found: #{input_file}"
+        exit 1
+      end
+
+      trimmer = Trimmer.new(
+        input_file,
+        output_file,
+        noise_threshold: options[:noise],
+        min_duration: options[:duration]
+      )
+
+      trimmer.dry_run = options[:'dry-run']
+      trimmer.run
+    rescue => e
+      puts "Error: #{e.message}"
+      exit 1
+    end
+
+    default_task :trim
+  end
+end

data/lib/speedrun/ffmpeg.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require 'tempfile'
+
+module Speedrun
+  module FFmpeg
+    FREEZE_START_PATTERN = /freeze_start:\s*([\d.]+)/
+    FREEZE_END_PATTERN = /freeze_end:\s*([\d.]+)/
+
+    def self.parse_duration(output)
+      output.strip.to_f
+    end
+
+    def self.parse_freezes(output)
+      regions = []
+      freeze_start = nil
+
+      output.each_line do |line|
+        if line =~ FREEZE_START_PATTERN
+          freeze_start = ::Regexp.last_match(1).to_f
+        elsif line =~ FREEZE_END_PATTERN && freeze_start
+          freeze_end = ::Regexp.last_match(1).to_f
+          regions << [freeze_start, freeze_end]
+          freeze_start = nil
+        end
+      end
+
+      regions
+    end
+
+    def self.get_duration(file_path)
+      raise ArgumentError, "File not found: #{file_path}" unless File.exist?(file_path)
+
+      cmd = [
+        'ffprobe',
+        '-v', 'error',
+        '-show_entries', 'format=duration',
+        '-of', 'default=noprint_wrappers=1:nokey=1',
+        file_path
+      ].shelljoin
+
+      output = `#{cmd}`
+      parse_duration(output)
+    end
+
+    def self.detect_freezes(file_path, noise_threshold: -70, min_duration: 1.0)
+      raise ArgumentError, "File not found: #{file_path}" unless File.exist?(file_path)
+
+      cmd = [
+        'ffmpeg',
+        '-i', file_path,
+        '-vf', "freezedetect=n=#{noise_threshold}dB:d=#{min_duration}",
+        '-f', 'null',
+        '-'
+      ].shelljoin
+
+      output = `#{cmd} 2>&1`
+      parse_freezes(output)
+    end
+
+    def self.extract_and_concat(input_file, output_file, keep_regions)
+      raise ArgumentError, "File not found: #{input_file}" unless File.exist?(input_file)
+      raise ArgumentError, "No regions to keep" if keep_regions.empty?
+
+      abs_input = File.absolute_path(input_file)
+
+      Tempfile.create(['concat', '.txt']) do |concat_file|
+        keep_regions.each do |start_time, end_time|
+          concat_file.puts "file '#{abs_input}'"
+          concat_file.puts "inpoint #{start_time}"
+          concat_file.puts "outpoint #{end_time}"
+        end
+        concat_file.flush
+
+        cmd = [
+          'ffmpeg',
+          '-f', 'concat',
+          '-safe', '0',
+          '-i', concat_file.path,
+          '-c', 'copy',
+          '-y',
+          output_file
+        ].shelljoin
+
+        output = `#{cmd} 2>&1`
+        success = $?.success?
+
+        raise "FFmpeg failed: #{output}" unless success
+
+        success
+      end
+    end
+  end
+end

data/lib/speedrun/formatter.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Speedrun
+  module Formatter
+    SECONDS_PER_MINUTE = 60
+    SECONDS_PER_HOUR = 3600
+    BYTES_PER_KB = 1024
+    BYTES_PER_MB = 1024 * 1024
+    BYTES_PER_GB = 1024 * 1024 * 1024
+
+    def self.format_time(seconds)
+      hours = (seconds / SECONDS_PER_HOUR).to_i
+      minutes = ((seconds % SECONDS_PER_HOUR) / SECONDS_PER_MINUTE).to_i
+      secs = seconds % SECONDS_PER_MINUTE
+
+      format('%02d:%02d:%06.3f', hours, minutes, secs)
+    end
+
+    def self.format_duration(seconds)
+      if seconds < SECONDS_PER_MINUTE
+        format('%.2fs', seconds)
+      elsif seconds < SECONDS_PER_HOUR
+        minutes = (seconds / SECONDS_PER_MINUTE).to_i
+        secs = seconds % SECONDS_PER_MINUTE
+        format('%dm %.1fs', minutes, secs)
+      else
+        hours = (seconds / SECONDS_PER_HOUR).to_i
+        minutes = ((seconds % SECONDS_PER_HOUR) / SECONDS_PER_MINUTE).to_i
+        secs = seconds % SECONDS_PER_MINUTE
+        format('%dh %dm %ds', hours, minutes, secs.to_i)
+      end
+    end
+
+    def self.format_filesize(bytes)
+      if bytes < BYTES_PER_KB
+        format('%d B', bytes)
+      elsif bytes < BYTES_PER_MB
+        format('%.1f KB', bytes / BYTES_PER_KB.to_f)
+      elsif bytes < BYTES_PER_GB
+        format('%.1f MB', bytes / BYTES_PER_MB.to_f)
+      else
+        format('%.1f GB', bytes / BYTES_PER_GB.to_f)
+      end
+    end
+  end
+end

data/lib/speedrun/trimmer.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Speedrun
+  class Trimmer
+    attr_reader :input_file, :output_file
+    attr_accessor :dry_run
+
+    def initialize(input_file, output_file = nil, noise_threshold: -70, min_duration: 1.0)
+      raise ArgumentError, "File not found: #{input_file}" unless File.exist?(input_file)
+
+      @input_file = input_file
+      @output_file = output_file || generate_output_filename(input_file)
+      @noise_threshold = noise_threshold
+      @min_duration = min_duration
+      @dry_run = false
+    end
+
+    def dry_run?
+      @dry_run
+    end
+
+    def run
+      puts "Input:  #{@input_file}"
+      puts "Output: #{@output_file}"
+      puts
+
+      # Step 1: Detect freeze regions
+      freeze_regions = FFmpeg.detect_freezes(
+        @input_file,
+        noise_threshold: @noise_threshold,
+        min_duration: @min_duration
+      )
+
+      if freeze_regions.empty?
+        puts "No freeze regions detected. Copying original video..."
+        FileUtils.cp(@input_file, @output_file) unless dry_run?
+        return
+      end
+
+      # Step 2: Calculate keep regions
+      video_duration = FFmpeg.get_duration(@input_file)
+      keep_regions = calculate_keep_regions(freeze_regions, video_duration)
+
+      if keep_regions.empty?
+        raise "All video content would be removed!"
+      end
+
+      # Step 3: Print summary
+      print_summary(freeze_regions, keep_regions, video_duration)
+
+      # Step 4: Process or dry-run
+      if dry_run?
+        puts
+        puts "DRY RUN - No files were modified"
+      else
+        puts
+        puts "Processing video..."
+        FFmpeg.extract_and_concat(@input_file, @output_file, keep_regions)
+
+        output_size = File.size(@output_file)
+        puts "Complete! Output saved to #{@output_file}"
+        puts "  File size: #{Formatter.format_filesize(output_size)}"
+      end
+    end
+
+    private
+
+    def generate_output_filename(input_file)
+      ext = File.extname(input_file)
+      base = File.basename(input_file, ext)
+      dir = File.dirname(input_file)
+
+      output = "#{base}-trimmed#{ext}"
+      dir == "." ? output : File.join(dir, output)
+    end
+
+    def calculate_keep_regions(freeze_regions, video_duration)
+      return [[0.0, video_duration]] if freeze_regions.empty?
+
+      keep_regions = []
+      current_time = 0.0
+
+      freeze_regions.each do |start_time, end_time|
+        if start_time > current_time
+          keep_regions << [current_time, start_time]
+        end
+        current_time = end_time
+      end
+
+      keep_regions << [current_time, video_duration] if current_time < video_duration
+
+      keep_regions
+    end
+
+    def print_summary(freeze_regions, keep_regions, video_duration)
+      total_removed = freeze_regions.sum { |s, e| e - s }
+      total_kept = keep_regions.sum { |s, e| e - s }
+
+      puts "Analysis complete:"
+      puts "  Found #{freeze_regions.length} freeze region#{freeze_regions.length == 1 ? '' : 's'}"
+      puts "  Keeping #{keep_regions.length} segment#{keep_regions.length == 1 ? '' : 's'} with motion"
+      puts
+      puts "Summary:"
+      puts "  Original duration: #{Formatter.format_duration(video_duration)}"
+      puts "  Keeping:  #{Formatter.format_duration(total_kept)} (#{'%.1f' % (total_kept / video_duration * 100)}%)"
+      puts "  Removing: #{Formatter.format_duration(total_removed)} (#{'%.1f' % (total_removed / video_duration * 100)}%)"
+    end
+  end
+end

data/lib/speedrun/version.rb

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

data/lib/speedrun.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "speedrun/version"
+require_relative "speedrun/formatter"
+require_relative "speedrun/ffmpeg"
+require_relative "speedrun/trimmer"
+require_relative "speedrun/cli"
+
+module Speedrun
+  class Error < StandardError; end
+end

data/sig/speedrun.rbs

@@ -0,0 +1,4 @@
+module Speedrun
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: speedrun
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Benjamin Jackson
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: ruby-progressbar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: pastel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.18'
+- !ruby/object:Gem::Dependency
+  name: guard-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: minitest-stub_any_instance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: CLI tool that uses ffmpeg to automatically detect frozen or low-motion
+  segments in videos and remove them, stitching together the active parts.
+email:
+- ben@hearmeout.co
+executables:
+- speedrun
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Guardfile
+- LICENSE
+- README.md
+- Rakefile
+- exe/speedrun
+- lib/speedrun.rb
+- lib/speedrun/cli.rb
+- lib/speedrun/ffmpeg.rb
+- lib/speedrun/formatter.rb
+- lib/speedrun/trimmer.rb
+- lib/speedrun/version.rb
+- sig/speedrun.rbs
+homepage: https://github.com/benjaminjackson/speedrun
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/benjaminjackson/speedrun
+  changelog_uri: https://github.com/benjaminjackson/speedrun/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Detect and remove freeze/low-motion regions from videos
+test_files: []