convert2ascii 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 37a56a08059d638a7c1e406248484e8fb3ca0fd1d494c8676ac5cc1119e15eeb
+  data.tar.gz: 3cbf2abb2d13a8a1d1091128852584d35d073ac8b1d7a056dc856916d913582d
+SHA512:
+  metadata.gz: e1dcecc188abc4c1a5916199f91fba45fa1ee70d6fe25427a27b502e5c41fa57fe3c3dedf4cd0a7f3402ac36f132e44f87874ada185d0dc374d78eb29fd9e389
+  data.tar.gz: aedcc98597e9ef05af5c26435384cb72741b2e97cca92df0e1e2b44e9314f0f2a465f5a070503db29a5bc16bb0cc97933ab4ab7a9b9d21f44179f9df923bc6f9

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Mark24
+
+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,114 @@
+# Convert2ASCII
+
+Convert Image/Video to ASCII art.
+
+
+## Test pass
+
+* MacOS 15.2 ✅
+* Ubuntu 24.04 ✅
+* Windows 11  ❌
+
+
+## Example
+
+![example](./example/wukong.jpg)
+
+![neo](./example/neo.gif)
+
+![example2](./example/doulai.jpg)
+
+## Prerequisites
+
+* Ruby3+
+* ImageMagick ([Download here](https://imagemagick.org/script/download.php))
+* ffmpeg ([Download here](https://www.ffmpeg.org/))
+
+
+## Executable command
+
+### image2ascii
+
+Make image to ascii art in your terminal.
+
+```bash
+image2ascii -h
+Usage: image2ascii [options]
+        --version                    verison
+    -i, --image=URI                  image uri (required)
+    -w, --width=WIDTH                image width (integer)
+    -s, --style=STYLE                ascii style: ['color'| 'text']
+    -b, --block                      ascii color style use BLOCK or not [ true | false ]
+```
+
+### video2ascii
+
+Make image to ascii art in your terminal.
+
+```bash
+Usage: video2ascii [options]
+
+* default will generate and play without save.
+* -p will just play ascii frames dir, and ignore -i, -o others options. --loop will play loop
+* -i,-o will just generate and output frames and ignore others options
+        --version                    verison
+    -i, --input=URI                  video uri (required)
+    -w, --width=WIDTH                video width (integer)
+    -s, --style=STYLE                ascii style: ['color'| 'text']
+    -b, --block                      ascii color style use BLOCK or not [ true | false ]
+    -o, --ouput=OUTPUT               save ascii frame to output dirname
+    -p, --play_dir=PLAY_DIRNAME      input ascii frames dirname to play
+        --loop
+```
+
+
+## As a Gem
+
+### Convert2Ascii::Image2Ascii
+
+
+```ruby
+require 'convert2ascii/image2ascii'
+
+# generate image
+uri = "path/to/image"
+ascii = Convert2Ascii::Image2Ascii.new(uri:, width: 50)
+
+# generate image
+ascii.generate
+# display in your terminal
+ascii.tty_print
+
+
+# also chain call
+ascii.generate.tty_print
+
+```
+
+
+### Convert2Ascii::Video2Ascii
+
+```ruby
+require 'convert2ascii/video2ascii'
+
+# generate video
+uri = "path/to/video.mp4"
+ascii = Convert2Ascii::Video2Ascii.new(uri:, width: 50)
+# generate video
+ascii.generate
+# save frames
+ascii.save(output_path)
+
+# play in terminal
+ascii.play
+
+
+# chain call
+ascii.generate.play
+
+```
+
+## Inspired by
+
+* [michaelkofron/image2ascii](https://github.com/michaelkofron/image2ascii)
+* [andrewcohen/video_to_ascii](https://github.com/andrewcohen/video_to_ascii)

data/Rakefile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+require "bundler/gem_tasks"
+
+desc "Run Test"
+task :test do
+  tests = Dir.glob("./test/test_*.rb")
+  tests.each do |t|
+    system("ruby #{t}")
+  end
+end
+
+desc "Build Rdoc"
+task :build_rdoc do
+  system("rdoc build")
+end
+
+
+
+task default: %i[]

data/TODO.md

@@ -0,0 +1,8 @@
+# TODO
+
+* [x] video loop play
+* [x] audio play use ffplay
+* [x] add audio loop play
+* [ ] add play control: pause, next, prev, exit
+* [ ] memory play is too limit
+* [ ] windows support

data/exe/image2ascii

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+require 'optparse'
+require_relative "../lib/convert2ascii/image2ascii"
+
+
+options = {}
+OptionParser.new do |parser|
+  parser.banner = "Usage: image2ascii [options]"
+
+  parser.on("--version", "verison") do |v|
+    puts "convert2ascii/image2ascii: v#{::Convert2Ascii::VERSION}"
+    puts "author: Mark24"
+    puts "mail: mark.zhangyoung@gmail.com"
+    puts "project: https://github.com/mark24Code/convert2ascii"
+    return
+  end
+
+  parser.on("-iURI", "--image=URI", "image uri (required)") do |uri|
+    options[:uri] = uri
+
+    # check options
+    unless options[:uri]
+      puts "Error: --image option is required."
+      exit 1
+    end
+  end
+
+  parser.on("-wWIDTH", "--width=WIDTH", Integer ,"image width (integer)") do |width|
+    options[:width] = width
+  end
+
+  parser.on("-sSTYLE", "--style=STYLE", "ascii style: ['color'| 'text']") do |style|
+    options[:style] = style
+
+    styles = ["color", "text"]
+    # check options
+    unless styles.include? options[:style]
+      puts "Error: --style option must be [\"color\" | \"text\"]."
+      exit 1
+    end
+  end
+
+  parser.on("-b", "--block", "ascii color style use BLOCK or not [ true | false ] ") do |color_block|
+    options[:color_block] = color_block || false
+  end
+end.parse!
+
+Convert2Ascii::Image2Ascii.new(**options).generate.tty_print

data/exe/video2ascii

@@ -0,0 +1,127 @@
+#!/usr/bin/env ruby
+require 'optparse'
+require_relative "../lib/convert2ascii/video2ascii"
+require_relative "../lib/convert2ascii/terminal-player"
+
+
+def get_name_order(name_path)
+  if name_path
+    return File.basename(name_path, ".*").to_i
+  end
+end
+
+def play_frames(dist_dir, play_loop: false)
+
+  config = JSON.parse(File.read(File.join(dist_dir, "meta.json")))
+  step_duration = config["step_duration"]
+  audio_name = config["audio"]
+  audio = audio_name ? File.join(dist_dir, audio_name) : nil
+
+  frames_path = Dir.glob("#{dist_dir}/*.txt")
+  frames_path = frames_path.sort do |a, b|
+    get_name_order(a) <=> get_name_order(b)
+  end
+
+  # TODO
+  # 载入内存中可能会遇到过大的问题
+  frames = frames_path.map { |f| File.open(f).read }
+
+  payload = {
+    frames: frames,
+    audio: audio,
+    play_loop: play_loop,
+    step_duration: step_duration
+  }
+  Convert2Ascii::TerminalPlayer.new(**payload).play
+end
+
+
+options = {}
+OptionParser.new do |parser|
+  parser.banner = <<DOC
+Usage: video2ascii [options]
+
+* default will generate and play without save.
+* -p will just play ascii frames dir, and ignore -i, -o others options. --loop will play loop
+* -i,-o will just generate and output frames and ignore others options
+DOC
+  parser.on("--version", "verison") do |v|
+    puts "convert2ascii/video2ascii: v#{::Convert2Ascii::VERSION}"
+    puts "author: Mark24"
+    puts "mail: mark.zhangyoung@gmail.com"
+    puts "project: https://github.com/mark24Code/convert2ascii"
+    return
+  end
+
+  parser.on("-iURI", "--input=URI", "video uri (required)") do |uri|
+    options[:uri] = uri
+
+    # check options
+    unless options[:uri]
+      puts "Error: --video option is required."
+      exit 1
+    end
+  end
+
+  parser.on("-wWIDTH", "--width=WIDTH", Integer ,"video width (integer)") do |width|
+    options[:width] = width
+  end
+
+  parser.on("-sSTYLE", "--style=STYLE", "ascii style: ['color'| 'text']") do |style|
+    options[:style] = style
+
+    styles = ["color", "text"]
+    # check options
+    unless styles.include? options[:style]
+      puts "Error: --style option must be [\"color\" | \"text\"]."
+      exit 1
+    end
+  end
+
+  parser.on("-b", "--block", "ascii color style use BLOCK or not [ true | false ] ") do |color_block|
+    options[:color_block] = color_block || false
+  end
+
+  parser.on("-o", "--ouput=OUTPUT", "save ascii frame to output dirname") do |output|
+    options[:output] = output
+  end
+
+  parser.on("-p", "--play_dir=PLAY_DIRNAME", "input ascii frames dirname to play") do |play_dir|
+    options[:play_dir] = play_dir
+  end
+
+  parser.on("--loop", "play loop") do |play_loop|
+    options[:play_loop] = play_loop
+  end
+end.parse!
+
+if options[:play_dir]
+  # play frames
+  # TODO
+  # 导出文件必须包含更多信息 step_duration
+  play_loop = false
+
+  if options[:play_loop]
+    play_loop = options[:play_loop]
+  end
+  play_frames(options[:play_dir], play_loop: play_loop)
+  exit 0
+end
+
+payload = {
+  uri: options[:uri],
+  width: options[:width],
+  style: options[:style],
+  color_block: options[:color_block],
+}
+
+if options[:uri] and options[:output]
+  output = options[:output]
+
+  Convert2Ascii::Video2Ascii.new(**payload).generate.save(output)
+
+  exit 0
+end
+
+
+Convert2Ascii::Video2Ascii.new(**payload).generate.play

data/lib/convert2ascii/check_package.rb

@@ -0,0 +1,167 @@
+require 'rainbow'
+
+module Convert2Ascii
+  module OS
+
+    module OS_ENUM
+      MacOS = :macos
+      Linux = :linux
+      Windows = :ms
+      Unknow = :unknow
+    end
+
+    def detect_os
+      if RUBY_PLATFORM =~ /linux/
+        return OS_ENUM::Linux
+      elsif RUBY_PLATFORM =~ /darwin/
+        return OS_ENUM::MacOS
+      elsif RUBY_PLATFORM =~ /mswin|mingw|cygwin/
+        return OS_ENUM::Windows
+      else
+        return OS_ENUM::Unknow
+      end
+    end
+  end
+
+  class CheckPackageError < StandardError
+  end
+
+  class CheckPackage
+    include OS
+
+    def initialize
+      @os_name = nil
+    end
+
+    def macos_check
+    end
+
+    def ms_check
+    end
+
+    def linux_check
+    end
+
+    def unknow_check
+      raise CheckPackageError, Rainbow("[Error] #{@os_name} not support!").red
+    end
+
+
+    def macos_installed?(package_name)
+      output = `brew list #{package_name} 2>/dev/null`
+      return output != ""
+    end
+
+    def detect_linux_distribution
+
+      if !File.exist?('/etc/os-release')
+        raise CheckPackageError, Rainbow("[Error] can not detect_os! #{@os_name} ").red
+      end
+
+      os_release = File.read('/etc/os-release')
+
+      if os_release.include?('debian')
+        # debian/ubuntu
+        return'debian'
+      end
+
+      if os_release.include?('centos')
+        # centos
+        return'centos'
+      end
+
+      if os_release.include?('redhat')
+        # redhat
+        return'redhat'
+      end
+
+      if os_release.include?('arch')
+        # arch linux
+        return'arch'
+      end
+
+      raise CheckPackageError, Rainbow("[Error] #{@os_name} linux platform not support!").red
+    end
+
+
+    def debian_installed?(package_name)
+      output = `dpkg -l | grep #{package_name}`
+      !output.strip.empty?
+    end
+
+    def centos_installed?(package_name)
+      output = `rpm -qa | grep #{package_name}`
+      !output.strip.empty?
+    end
+
+    def redhat_installed?(package_name)
+      output = `yum list installed | grep #{package_name}`
+      !output.strip.empty?
+    end
+
+    def arch_installed?(package_name)
+      output = `pacman -Q | grep #{package_name}`
+      !output.strip.empty?
+    end
+
+    def check
+      @os_name = detect_os
+      __send__ "#{@os_name}_check"
+    end
+  end
+
+  class CheckFFmpeg < CheckPackage
+    def initialize
+      super
+      @name = "ffmpeg"
+      @need_error = Rainbow("[Error] `#{@name}` is need!").red
+      @tips = Rainbow("[Tips ] For more details and install: https://www.ffmpeg.org/").green
+    end
+
+    def macos_check
+      if !macos_installed?(@name)
+        raise CheckPackageError, "\n#{@need_error}\n#{@tips}\n"
+      end
+    end
+
+    def linux_check
+      linux_platform_name = detect_linux_distribution
+      __send__ "#{linux_platform_name}_installed?", @name
+    end
+
+  end
+
+  class CheckImageMagick < CheckPackage
+    def initialize
+      super
+      @name = "imagemagick"
+      @need_error = Rainbow("[Error] `imagemagick` is need!").red
+      @tips = Rainbow("[Tips ] For more details and install guide: https://github.com/rmagick/rmagick").green
+
+    end
+
+    def macos_check
+      if !macos_installed?(@name)
+        raise CheckPackageError, "\n#{@need_error}\n#{@tips}\n"
+      end
+    end
+
+    def linux_check
+      # just Debian/Ubuntu
+      linux_pkg = {
+        "debian" => "libmagickwand-dev",
+        "redhat" => "ImageMagick-devel",
+        "arch" => "imagemagick",
+      }
+
+      linux_platform_name = detect_linux_distribution
+      pkg_name = linux_pkg.fetch(linux_platform_name, nil)
+
+      if !pkg_name
+        raise CheckPackageError, "\n#{@need_error}\n#{@tips}\n"
+      end
+
+      __send__ "#{linux_platform_name}_installed?", pkg_name
+    end
+  end
+end

data/lib/convert2ascii/image2ascii.rb

@@ -0,0 +1,132 @@
+require "io/console"
+require "rmagick"
+require "rainbow"
+require "open-uri"
+require_relative "./check_package"
+require_relative './version'
+
+module Convert2Ascii
+  class Image2AsciiError < StandardError
+  end
+
+  class Image2Ascii
+    module STYLE_ENUM
+      Color = "color"
+      Text = "text"
+    end
+
+    module COLOR_ENUM
+      Full = "full"
+      Greyscale = "greyscale"
+    end
+
+
+    attr_reader :width, :ascii_string
+    attr_accessor :chars
+
+    def initialize(**args)
+      @uri = args[:uri]
+      @width = args[:width] || IO.console.winsize[1]
+      @style = args[:style] || STYLE_ENUM::Color # "color": color ansi , "text": plain text
+      @color = args[:color] || COLOR_ENUM::Full # full
+      @color_block = args[:color_block] || false
+
+      check_quantum_convert_factor
+      # divides quantum depth color space into usable rgb values
+      @quantum_convert_factor = Magick::MAGICKCORE_QUANTUM_DEPTH == 16 ? 257 : 1
+
+      @chars = ".'`^\",:;Il!i><~+_-?][}{1)(|\\/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$"
+      @ascii_string = ""
+    end
+
+    def check_quantum_convert_factor
+      # quantum conversion factor for dealing with quantum depth color values
+      if Magick::MAGICKCORE_QUANTUM_DEPTH > 16
+        raise Image2AsciiError, "[Error] ImageMagick quantum depth is set to #{Magick::MAGICKCORE_QUANTUM_DEPTH}. It needs to be 16 or less"
+      end
+    end
+
+    def generate(**args)
+      @width = args[:width] || @width
+      @style = args[:style] || @style # "color": color ansi , "text": plain text
+      @color = args[:color] || @color # full
+      @color_block = args[:color_block] || @color_block
+
+      generate_string
+
+      self
+    end
+
+    def tty_print
+      print @ascii_string
+    end
+
+    private
+
+    def check_packages
+      CheckImageMagick.new.check
+    end
+
+    def generate_string
+      resource = URI.open(@uri)
+      img = Magick::ImageList.new
+      img.from_blob(resource.read)
+
+      img = correct_aspect_ratio(img, @width)
+
+      img.each_pixel do |pixel, col, row|
+        r, g, b, brightness = get_pixel_values(pixel)
+        char = select_character(brightness)
+
+        if @style == STYLE_ENUM::Text
+          @ascii_string << char
+        end
+
+        if @style == STYLE_ENUM::Color
+          chosen_color = get_chosen_color(@color, r, g, b)
+
+          if @color_block == true
+            @ascii_string << Rainbow(" ").background(*chosen_color)
+          else
+            @ascii_string << Rainbow(char).color(*chosen_color)
+          end
+        end
+
+        # add line wrap once desired width is reached
+        if (col % (@width - 1) == 0) and (col != 0)
+          @ascii_string << "\n"
+        end
+      end
+    end
+
+    def correct_aspect_ratio(img, width)
+      img = img.scale(width / img.columns.to_f)
+      img = img.scale(img.columns, img.rows / 2)
+    end
+
+    def get_pixel_values(pixel)
+      r = pixel.red / @quantum_convert_factor
+      g = pixel.green / @quantum_convert_factor
+      b = pixel.blue / @quantum_convert_factor
+      # Brightness ref: https://en.wikipedia.org/wiki/Relative_luminance
+      brightness = (0.2126 * r + 0.7152 * g + 0.0722 * b)
+
+      return [r, g, b, brightness]
+    end
+
+    def select_character(brightness)
+      char_index = brightness / (255.0 / @chars.length)
+      @chars[char_index.floor]
+    end
+
+    def get_chosen_color(color, r, g, b)
+      if color == COLOR_ENUM::Full
+        [r, g, b]
+      elsif color == COLOR_ENUM::Greyscale
+        [r, r, r]
+      else
+        color
+      end
+    end
+  end
+end

data/lib/convert2ascii/multi-tasker.rb

@@ -0,0 +1,36 @@
+require "async"
+require "async/barrier"
+require "async/semaphore"
+require "etc"
+
+module Convert2Ascii
+  class MultiTasker
+    def initialize(proc_tasks)
+      @proc_tasks = proc_tasks
+      @count = set_threads_count
+    end
+
+    def set_threads_count
+      cpu_threads = (Etc.nprocessors || 1)
+      cpu_threads = cpu_threads > 4 ? cpu_threads - 1 : cpu_threads
+      cpu_threads
+    end
+
+    def run
+      barrier = Async::Barrier.new
+
+      Sync do
+        # Only 10 tasks are created at a time:
+        semaphore = Async::Semaphore.new(@count, parent: barrier)
+
+        @proc_tasks.map do |proc_task|
+          semaphore.async do
+            proc_task.call
+          end
+        end.map(&:wait)
+      ensure
+        barrier.stop
+      end
+    end
+  end
+end

data/lib/convert2ascii/terminal-player.rb

@@ -0,0 +1,184 @@
+require "rainbow"
+require_relative "./terminal"
+
+module Convert2Ascii
+  class TerminalPlayer
+
+    SAFE_SLOW_DELTA = 0.9 # seconds
+    SAFE_FAST_DELTA = 0.2 # seconds
+
+    attr_accessor :play_loop, :step_duration, :debug
+    def initialize(**args)
+      @debug = false
+      @audio = args[:audio]
+      @frames = args[:frames]
+      @play_loop = args[:play_loop]
+      @step_duration = args[:step_duration]
+
+      @total_duration = @frames.length * @step_duration
+      @first_frame = true
+      @backspace_adjust = "\033[A" * (@frames.length + 1)
+
+      regist_hook
+    end
+
+    def play
+      begin
+        init_screen
+        render
+      rescue => error
+        raise error
+      ensure
+        clean_up
+      end
+    end
+
+    private
+
+    def regist_hook
+      trap("INT") {
+        clean_up
+        exit 0
+      }
+
+      # TODO  ??? 改变会消失
+      # # 窗口变化事件
+      # trap("SIGWINCH") {
+      #   resize
+      # }
+    end
+
+    def resize
+      clear_screen
+    end
+
+    def clear_screen
+      Terminal.clear_buffer
+    end
+
+    def init_screen
+      clear_screen
+      setup
+    end
+
+    def setup
+      Terminal.open_buffer
+      Terminal.hide_cursor
+      Terminal.clear_screen
+    end
+
+    def clean_up
+      if !@debug
+        Terminal.close_buffer
+        Terminal.clear_screen
+        Terminal.show_cursor
+      end
+    end
+
+    def debug_log(var_name)
+      puts Rainbow('-- debug ----').yellow
+      puts "class:"
+      p var_name.class
+      puts "value:"
+      p var_name
+    end
+
+    def full_screen(content)
+
+      if !content
+        return content
+      end
+      # 补齐高度，没内容也要追加 \n 刷新，因为会拖拽 窗体尺寸会变化
+      rows, _ = Terminal.winsize
+      # content: pure text with "\n"
+      content = content.split("\n")
+
+      rows_fill = []
+      delta = rows - content.length
+
+      if delta > 0
+        delta.times do
+          rows_fill << "\n"
+        end
+      elsif delta < 0
+        content = content[0..(rows - 1)]
+      end
+
+      content.join("\n")
+    end
+
+    def self_adaption_frame_play
+      # 当偏移在-90ms（音频滞后于视频）到+20ms（音频超前视频）之间时，人感觉不到视听质量的变化，这个区域可以认为是同步区域
+      # https://github.com/0voice/audio_video_streaming/blob/main/article/029-%E9%9F%B3%E8%A7%86%E9%A2%91%E5%90%8C%E6%AD%A5%E7%AE%97%E6%B3%95.md
+
+      start_time = Time.now
+      if @audio
+        Thread.new do
+          start_time = Time.now # 以音频为准
+          play_cmd = "ffplay -nodisp "
+          if @play_loop
+            play_cmd << " -loop 0"
+          end
+          system("#{play_cmd} -i #{@audio} &> /dev/null")
+          if @debug
+            puts Rainbow("[info] audio time: #{Time.now - start_time} s").green
+          end
+        end
+      end
+      frame_index = 0
+      loop do
+        if frame_index <= @frames.length
+          content = @frames[frame_index]
+          if !@first_frame
+            $stdout.print @backspace_adjust
+          end
+          clear_screen
+          $stdout.print(full_screen(content))
+          @first_frame = false
+          sleep(@step_duration)
+        end
+
+        actual_time = Time.now - start_time
+        video_play_time = frame_index * @step_duration
+
+        offset_time = actual_time - video_play_time
+        if offset_time > SAFE_SLOW_DELTA
+          offset = (offset_time / @step_duration).floor
+          if @debug
+            puts Rainbow("[+] #{offset}").green
+          end
+        elsif offset_time < -1 * SAFE_FAST_DELTA
+          offset = 0
+        else
+          offset = 1
+        end
+
+        frame_index = (frame_index + offset) % @frames.length
+
+        real_time = Time.now - start_time
+        frame_time = (frame_index + 1) * @step_duration
+
+        if !@play_loop
+          if real_time > @total_duration
+            break
+          end
+        end
+
+        if @debug
+          puts ""
+          puts Rainbow("RealTime: #{real_time} s").green
+          puts Rainbow("FrameTime: #{frame_time} s").green
+          puts Rainbow("CurrentFrame: #{frame_index} / #{@frames.length} ").green
+          puts Rainbow("Real - Frame: #{real_time - frame_time} s").green
+          puts Rainbow("[+] #{offset}").green
+          puts Rainbow("@step_duration #{@step_duration}").green
+          puts Rainbow("@play_loop #{@play_loop}").green
+        end
+      end
+    end
+
+    def render
+      self_adaption_frame_play
+    end
+  end
+end

data/lib/convert2ascii/terminal.rb

@@ -0,0 +1,40 @@
+require "io/console"
+
+# ANSI_escape_code
+# Ref: https://xn--rpa.cc/irl/term.html
+# https://en.wikipedia.org/wiki/ANSI_escape_code#CSIsection
+module Convert2Ascii
+  class Terminal
+    class << self
+      def winsize
+        IO.console.winsize # [rows, columns]
+      end
+
+      def clear_buffer
+        print "\x1b[3J"
+      end
+
+      def clear_screen
+        print "\x1b[2J"
+      end
+
+      def hide_cursor
+        print "\x1b[?25l"
+      end
+
+      def show_cursor
+        print "\x1b[?25h"
+      end
+
+      def open_buffer
+        # 打开特殊缓存
+        print "\x1b[?1049h"
+      end
+
+      def close_buffer
+        # 关闭特殊缓存
+        print "\x1b[?1049l"
+      end
+    end
+  end
+end

data/lib/convert2ascii/version.rb

@@ -0,0 +1,3 @@
+module Convert2Ascii
+  VERSION = "0.1.0"
+end

data/lib/convert2ascii/video2ascii.rb

@@ -0,0 +1,199 @@
+require "open-uri"
+require "json"
+require "tmpdir"
+require "etc"
+require "io/console"
+require "rainbow"
+require_relative "./image2ascii"
+require_relative "./terminal-player"
+require_relative "./multi-tasker"
+require_relative "./check_package"
+require_relative './version'
+
+module Convert2Ascii
+  class Video2AsciiError < StandardError
+  end
+
+  class Video2Ascii
+    DEFAULT_STEP_DURATION = 0.04
+
+
+    attr_accessor :uri, :width, :threads_count, :output, :step_duration
+    def initialize(**args)
+      @uri = args[:uri]
+      @step_duration = args[:step_duration] || DEFAULT_STEP_DURATION
+      @threads_count = set_threads_count
+
+      @tmpdir = nil
+      @output = Dir.pwd
+
+      # image2ascii attrs
+      @width = args[:width] || IO.console.winsize[1]
+      @style = args[:style] || Image2Ascii::STYLE_ENUM::Color # "color": color ansi , "text": plain text
+      @color = args[:color] || Image2Ascii::COLOR_ENUM::Full # full
+      @color_block = args[:color_block] || false
+
+      check_packages
+      regist_hooks
+    end
+
+    def generate(**args)
+      @width = args[:width] || @width
+      @style = args[:style] || @style # "color": color ansi , "text": plain text
+      @color = args[:color] || @color # full
+      @color_block = args[:color_block] || @color_block
+
+      @tmpdir = Dir.mktmpdir
+      @audio = get_audio_from_video(@tmpdir)
+      screenshots_from_video(@tmpdir)
+      convert_all_images(@tmpdir)
+      @frames_path = order_frames_path
+
+      self
+    end
+
+
+    def save(output_dir)
+      system("rm -rf #{@tmpdir}/*.jpg")
+      system("rm -rf #{output_dir} && mkdir #{output_dir}")
+      system("cp -r #{@tmpdir}/* #{output_dir}")
+
+      # save config
+      File.open("#{output_dir}/meta.json", "w") do |f|
+        config = {
+          step_duration: @step_duration,
+          audio: @audio ?  File.basename(@audio) : nil,
+          frames_count: @frames_path.length
+        }
+        json_data = JSON.generate(config, pretty: true)
+        f.puts json_data
+      end
+
+      puts ""
+      puts Rainbow("[info] save success!").green
+    end
+
+    def order_frames_path
+      frames_path = Dir.glob("#{@tmpdir}/*.txt")
+      frames_path = frames_path.sort do |a, b|
+        get_name_order(a) <=> get_name_order(b)
+      end
+
+      @frames_path =  frames_path
+    end
+
+    def play(**args)
+      play_loop = args[:play_loop] || false
+      step_duration = args[:step_duration] || @step_duration
+      frames = @frames_path.map { |f| File.open(f).read }
+
+      player_args = {
+        frames: ,
+        audio: @audio,
+        play_loop:,
+        step_duration:,
+      }
+      TerminalPlayer.new(**player_args).play
+
+      return true
+    end
+
+    private
+
+    def check_packages
+      CheckImageMagick.new.check
+      CheckFFmpeg.new.check
+    end
+
+    def regist_hooks
+      at_exit {
+        if @tmpdir
+          FileUtils.remove_entry @tmpdir
+        end
+      }
+    end
+
+    def set_threads_count
+      cpu_threads = (Etc.nprocessors || 1)
+      cpu_threads = cpu_threads > 4 ? cpu_threads - 1 : cpu_threads
+      cpu_threads
+    end
+
+    def get_audio_from_video(save_dir)
+      puts Rainbow("[info] parsing audio...").green
+      audio_save = "#{save_dir}/audio.mp3"
+      cmd = "ffmpeg -i '#{@uri}' -vn  -nostats -loglevel 0   #{audio_save}"
+      result = system(cmd)
+      if !result
+        audio_save = nil
+      end
+      puts Rainbow("[info] parsing audio done.").green
+
+      return audio_save
+    end
+
+    def screenshots_from_video(save_dir)
+      # ffmpeg use multi threads
+      # Benchmark
+      # Apple M1 Max:
+      # * thread:1   2.64s
+      # * thread:9   0.96s
+      puts Rainbow("[info] video slicing...").green
+      image_path = save_dir
+      cmd = "ffmpeg -i '#{@uri}' -threads #{@threads_count} -vf fps=1/#{@step_duration}  -nostats -loglevel 0   #{image_path}/%d.jpg"
+      result = system(cmd)
+
+      if !result
+        raise Video2AsciiError, Rainbow("\n[Error] exec `#{cmd}` fail!").red
+      end
+      puts Rainbow("[info] video slicing done.").green
+
+      return image_path
+    end
+
+    def convert_to_ascii(image)
+      config = {
+        width: @width,
+        style: @style,
+        color: @color,
+        color_block: @color_block
+      }
+      Image2Ascii.new(uri: image).generate(**config).ascii_string
+    end
+
+    def get_name_order(name_path)
+      if name_path
+        return File.basename(name_path, ".*").to_i
+      end
+    end
+
+    def convert_all_images(save_dir)
+      images = Dir.glob("#{save_dir}/*.jpg")
+
+      processed_count = 0
+      tasks = []
+      time_start = Time.now
+      images.each_with_index do |image, i|
+        tasks << lambda {
+          begin
+            ascii_string = convert_to_ascii(image)
+            basename = File.basename(image, ".jpg")
+            File.open("#{@tmpdir}/#{basename}.txt", "w") do |f|
+              f.puts ascii_string
+            end
+
+            processed_count += 1
+            print(Rainbow("\rprocessing...  #{sprintf("%.2f", (1.0 * processed_count / images.length) * 100)} % (time: #{sprintf("%.2f", Time.now - time_start)} s)").green)
+          rescue => error
+            puts "-------"
+            puts Rainbow("\n[Error] convert_to_ascii -> image: #{image} | i: #{i}").red
+            puts error
+          end
+        }
+      end
+
+      MultiTasker.new(tasks).run
+    end
+
+  end
+end

data/lib/convert2ascii.rb

@@ -0,0 +1,3 @@
+require_relative './convert2ascii/version.rb'
+require_relative './convert2ascii/image2ascii.rb'
+require_relative './convert2ascii/video2ascii.rb'

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: convert2ascii
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mark24
+bindir: exe
+cert_chain: []
+date: 2025-01-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rmagick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.1
+- !ruby/object:Gem::Dependency
+  name: rainbow
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.1
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.21'
+description: This gem can help you convert image or video became ASCII art in your
+  terminal.
+email:
+- mark.zhangyoung@gmail.com
+executables:
+- image2ascii
+- video2ascii
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- TODO.md
+- exe/image2ascii
+- exe/video2ascii
+- lib/convert2ascii.rb
+- lib/convert2ascii/check_package.rb
+- lib/convert2ascii/image2ascii.rb
+- lib/convert2ascii/multi-tasker.rb
+- lib/convert2ascii/terminal-player.rb
+- lib/convert2ascii/terminal.rb
+- lib/convert2ascii/version.rb
+- lib/convert2ascii/video2ascii.rb
+homepage: https://github.com/Mark24Code/convert2ascii
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Mark24Code/convert2ascii
+  source_code_uri: https://github.com/Mark24Code/convert2ascii
+  changelog_uri: https://github.com/Mark24Code/convert2ascii
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Convert image or video to ASCII art
+test_files: []