screen-recorder 1.3.0 → 1.6.0

data/README.md

@@ -1,19 +1,16 @@
 # ScreenRecorder
 
 [![Gem Version](https://badge.fury.io/rb/screen-recorder.svg)](https://badge.fury.io/rb/screen-recorder)
-[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/github/kapoorlakshya/screen-recorder/master)
-[![Build Status](https://travis-ci.org/kapoorlakshya/screen-recorder.svg?branch=master)](https://travis-ci.org/kapoorlakshya/screen-recorder)
-[![AppVeyor status](https://ci.appveyor.com/api/projects/status/u1qashueuw82r235/branch/master?svg=true)](https://ci.appveyor.com/project/kapoorlakshya/screen-recorder/branch/master)
-[![Maintainability](https://api.codeclimate.com/v1/badges/b6049dfee7375aed9bc8/maintainability)](https://codeclimate.com/github/kapoorlakshya/screen-recorder/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/b6049dfee7375aed9bc8/test_coverage)](https://codeclimate.com/github/kapoorlakshya/screen-recorder/test_coverage)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/gems/screen-recorder/)
+[![Tests](https://github.com/kapoorlakshya/screen-recorder/actions/workflows/tests.yml/badge.svg)](https://github.com/kapoorlakshya/screen-recorder/actions/workflows/tests.yml)
 
-A Ruby gem to video record your computer screen - desktop or specific
+A Ruby gem to video record or take screenshots of your computer screen - desktop or specific
 window - using [FFmpeg](https://www.ffmpeg.org/). Primarily
 geared towards recording automated UI (Selenium) test executions for 
 debugging and documentation.
 
 #### Demo
-[https://kapoorlakshya.github.io/introducing-screen-recorder-ruby-gem](https://kapoorlakshya.github.io/introducing-screen-recorder-ruby-gem).
+[https://kapoorlakshya.github.io/introducing-screen-recorder-ruby-gem](https://kapoorlakshya.github.io/introducing-screen-recorder-ruby-gem)
 
 ## Compatibility
 
@@ -23,11 +20,13 @@ Works on Windows, Linux, and macOS. Requires Ruby 2.0+ or JRuby 9.2+.
 
 ##### 1. Setup FFmpeg
 
-Linux and macOS instructions are [here](https://www.ffmpeg.org/download.html). 
+Linux and macOS instructions are [here](https://trac.ffmpeg.org/wiki/CompilationGuide).
 
-For Microsoft Windows, download the *libx264* enabled binary from [here](https://ffmpeg.zeranoe.com/builds/).
-Once downloaded, add location of the `ffmpeg/bin` folder to the `PATH` 
-environment variable ([instructions](https://windowsloop.com/install-ffmpeg-windows-10/)).
+> macOS: Follow [these steps](https://github.com/kapoorlakshya/screen-recorder/issues/88#issuecomment-629139032) to avoid
+> issues related to Privacy settings.
+
+For Microsoft Windows, download the binary from [here](https://www.videohelp.com/software/ffmpeg). Once downloaded, 
+add location of the `ffmpeg/bin` folder to the `PATH`  environment variable ([instructions](https://windowsloop.com/install-ffmpeg-windows-10/)).
 
 Alternatively, you can point to the binary file using 
 `ScreenRecorder.ffmpeg_binary = '/path/to/ffmpeg'` in your project.
@@ -38,13 +37,13 @@ Next, add these lines to your application's Gemfile:
 
 ```ruby
 gem 'ffi' # Windows only
-gem 'screen-recorder'
+gem 'screen-recorder', '~> 1.0'
 ```
 
 The [`ffi`](https://github.com/ffi/ffi) gem is used by the 
 [`childprocess`](https://github.com/enkessler/childprocess) gem on 
 Windows, but it does not explicitly require it. More information 
-on this [here](https://github.com/enkessler/childprocess/issues/150).
+on this [here](https://github.com/enkessler/childprocess/issues/160).
 
 
 And then execute:
@@ -80,7 +79,7 @@ require 'screen-recorder'
 ```
 
 Linux and macOS users can optionally provide a display or input device number.
-Read more about it in the wiki [here](https://github.com/kapoorlakshya/screen-recorder/wiki/Input-Values).
+Read more about it in the wiki [here](https://github.com/kapoorlakshya/screen-recorder/wiki/Display-or-Input-Device-Selection).
 
 #### Record Application Window (Microsoft Windows only)
 
@@ -96,7 +95,7 @@ browser   = Watir::Browser.new :firefox
 @recorder.stop
 browser.quit 
 ```
-This mode has limited capabilities. Read more about it in the wiki 
+This mode has a few limitations which are listed in the wiki 
 [here](https://github.com/kapoorlakshya/screen-recorder/wiki/Window-Capture-Limitations).
 
 ##### Fetch Title
@@ -105,14 +104,76 @@ A helper method is available to fetch the title of the active window
 for the given process name.
 
 ```ruby
-ScreenRecorder::Window.fetch_title('firefox') # Name of exe
+ScreenRecorder::('firefox') # Name of exe
 #=> ["Mozilla Firefox"]
 
-ScreenRecorder::Window.fetch_title('chrome')
+ScreenRecorder::('chrome')
 #=> ["New Tab - Google Chrome"]
 ```
 
-#### Output
+#### Capture Audio
+
+Provide the following `advanced` configurations to capture audio:
+
+```ruby
+# Linux
+advanced = { f: 'alsa', ac: 2, i: 'hw:0'} # Using ALSA
+# Or using PulseAudio 
+advanced = { 'f': 'pulse', 'ac': 2, 'i': 'default' } # Records default sound output device 
+
+# macOS
+advanced = { input: { i: '1:1' } } # -i video:audio input device ID
+
+# Windows
+advanced = { f: 'dshow', i: 'audio="Microphone (Realtek High Definition Audio)"' }
+```
+
+You can retrieve a list of audio devices by running these commands:
+
+```
+# Linux
+$ arecord -L # See https://trac.ffmpeg.org/wiki/Capture/ALSA
+
+# macOS
+$ ffmpeg -f avfoundation -list_devices true -i ""
+
+# Windows
+> ffmpeg -list_devices true -f dshow -i dummy
+```
+
+#### Screenshots
+
+Screenshots can be captured at any point after initializing the recorder:
+
+```ruby
+# Desktop
+@recorder = ScreenRecorder::Desktop.new(output: 'recording.mkv')
+@recorder.screenshot('before-recording.png')
+@recorder.start
+@recorder.screenshot('during-recording.png')
+@recorder.stop
+@recorder.screenshot('after-recording.png')
+
+# Window (Microsoft Windows only)
+browser   = Watir::Browser.new :chrome, options: { args: ['--disable-gpu'] } # Hardware acceleration must be disabled
+browser.goto('watir.com')
+window_title = ScreenRecorder::('chrome').first
+@recorder = ScreenRecorder::Window.new(title: window_title, output: 'recording.mkv')
+@recorder.screenshot('before-recording.png')
+@recorder.start
+@recorder.screenshot('during-recording.png')
+@recorder.stop
+@recorder.screenshot('after-recording.png')
+browser.quit 
+```
+
+You can even specify a custom capture resolution:
+
+```rb
+@recorder.screenshot('screenshot.png', '1024x768')
+```
+
+#### Video Output
 
 Once the recorder is stopped, you can view the video metadata or transcode
 it if desired.

data/bin/setup

@@ -1,8 +1,8 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
-
-bundle install
-
-# Do any other automated setup that you need to do here
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/screen-recorder.rb

@@ -12,14 +12,41 @@ module ScreenRecorder
   #   ScreenRecorder.ffmpeg_binary = 'C:\ffmpeg.exe'
   #
   def self.ffmpeg_binary=(bin)
+    ScreenRecorder.logger.debug 'Setting ffmpeg path...'
     FFMPEG.ffmpeg_binary = bin
+    ScreenRecorder.logger.debug "ffmpeg path set: #{bin}"
+    ScreenRecorder.ffmpeg_binary
   end
 
   #
-  # Returns path to ffmpeg binary
+  # Returns path to ffmpeg binary or raises DependencyNotFound
   #
   def self.ffmpeg_binary
     FFMPEG.ffmpeg_binary
+  rescue Errno::ENOENT # Raised when binary is not set in project or found in ENV
+    raise Errors::DependencyNotFound
+  end
+
+  #
+  # Uses user given ffprobe binary
+  #
+  # @example
+  #   ScreenRecorder.ffprobe_binary= = 'C:\ffprobe.exe'
+  #
+  def self.ffprobe_binary=(bin)
+    ScreenRecorder.logger.debug 'Setting ffprobe path...'
+    FFMPEG.ffprobe_binary = bin
+    ScreenRecorder.logger.debug "ffprobe path set: #{bin}"
+    ScreenRecorder.ffmpeg_binary
+  end
+
+  #
+  # Returns path to ffprobe binary or raises DependencyNotFound
+  #
+  def self.ffprobe_binary
+    FFMPEG.ffprobe_binary
+  rescue Errno::ENOENT # Raised when binary is not set in project or found in ENV
+    raise Errors::DependencyNotFound
   end
 
   #
@@ -35,9 +62,9 @@ module ScreenRecorder
   def self.logger
     return @logger if @logger
 
-    logger           = Logger.new(STDOUT)
-    logger.level     = Logger::ERROR
-    logger.progname  = 'ScreenRecorder'
+    logger = Logger.new($stdout)
+    logger.level = Logger::ERROR
+    logger.progname = 'ScreenRecorder'
     logger.formatter = proc do |severity, time, progname, msg|
       "#{time.strftime('%F %T')} #{progname} - #{severity} - #{msg}\n"
     end
@@ -51,5 +78,6 @@ require 'screen-recorder/errors'
 require 'screen-recorder/options'
 require 'screen-recorder/titles'
 require 'screen-recorder/common'
+require 'screen-recorder/screenshot'
 require 'screen-recorder/desktop'
 require 'screen-recorder/window'

data/lib/screen-recorder/common.rb

@@ -9,6 +9,8 @@ module ScreenRecorder
     attr_reader :options, :video
 
     def initialize(input:, output:, advanced: {})
+      raise Errors::DependencyNotFound unless ffmpeg_exists?
+
       @options = Options.new(input: input, output: output, advanced: advanced)
       @video   = nil
       @process = nil
@@ -19,8 +21,8 @@ module ScreenRecorder
     #
     def start
       ScreenRecorder.logger.debug 'Starting recorder...'
-      @video     = nil # New file
-      @process   = start_ffmpeg
+      @video   = nil # New file
+      @process = start_ffmpeg
       ScreenRecorder.logger.info 'Recording...'
       @process
     end
@@ -30,10 +32,12 @@ module ScreenRecorder
     #
     def stop
       ScreenRecorder.logger.debug 'Stopping ffmpeg...'
-      stop_ffmpeg
+      exit_code = stop_ffmpeg
+      return if exit_code == 1 # recording failed
+
       ScreenRecorder.logger.debug 'Stopped ffmpeg.'
       ScreenRecorder.logger.info 'Recording complete.'
-      @video = FFMPEG::Movie.new(options.output)
+      @video = prepare_video unless exit_code == 1
     end
 
     #
@@ -42,7 +46,7 @@ module ScreenRecorder
     # needed.
     #
     def discard
-      FileUtils.rm options.output
+      File.delete options.output
     end
 
     alias delete discard
@@ -54,17 +58,9 @@ module ScreenRecorder
     # the given options.
     #
     def start_ffmpeg
-      raise Errors::DependencyNotFound, 'ffmpeg binary not found.' unless ffmpeg_exists?
-
-      ScreenRecorder.logger.debug "Command: #{command}"
-      process           = build_command
-      @log_file         = File.new(options.log, 'w+')
-      process.io.stdout = process.io.stderr = @log_file
-      @log_file.sync    = true
-      process.duplex    = true
-      process.start
-      sleep(1.5) # Takes ~1.5s on average to initialize
-      # Stopped because of an error
+      process = execute_command(ffmpeg_command, options.log)
+      sleep(1.5) # Takes ~1.5s to initialize ffmpeg
+      # Check if it exited unexpectedly
       raise FFMPEG::Error, "Failed to start ffmpeg. Reason: #{lines_from_log(:last, 2)}" if process.exited?
 
       process
@@ -78,37 +74,51 @@ module ScreenRecorder
       @process.io.stdin.puts 'q' # Gracefully exit ffmpeg
       @process.io.stdin.close
       @log_file.close
-      @process.poll_for_exit(PROCESS_TIMEOUT)
-      @process.exit_code
-    rescue ChildProcess::TimeoutError
-      ScreenRecorder.logger.error 'FFmpeg failed to stop. Force killing it...'
-      @process.stop # Tries increasingly harsher methods to kill the process.
-      ScreenRecorder.logger.error "Check '#{@options.log}' for more information."
+      wait_for_process_exit(@process)
+    end
+
+    #
+    # Runs ffprobe on the output video file and returns
+    # a FFMPEG::Movie object.
+    #
+    def prepare_video
+      max_attempts  = 3
+      attempts_made = 0
+      delay         = 1.0
+
+      begin # Fixes #79
+        ScreenRecorder.logger.info 'Running ffprobe to prepare video (output) file.'
+        FFMPEG::Movie.new(options.output)
+      rescue Errno::EAGAIN, Errno::EACCES
+        attempts_made += 1
+        ScreenRecorder.logger.error "Failed to run ffprobe. Retrying... (#{attempts_made}/#{max_attempts})"
+        sleep(delay)
+        retry if attempts_made < max_attempts
+        raise
+      end
+    end
+
+    def ffmpeg_bin
+      "#{ScreenRecorder.ffmpeg_binary} -y"
     end
 
     #
     # Generates the command line arguments based on the given
     # options.
     #
-    def command
-      cmd = "#{ScreenRecorder.ffmpeg_binary} -y "
-      cmd << @options.parsed
+    def ffmpeg_command
+      "#{ffmpeg_bin} #{@options.parsed}"
     end
 
     #
     # Returns true if ffmpeg binary is found.
     #
     def ffmpeg_exists?
-      return !`which ffmpeg`.empty? if OS.linux? # "" if not found
-
-      return !`where ffmpeg`.empty? if OS.windows?
+      return true if FFMPEG.ffmpeg_binary
 
-      # If the user does not use ScreenRecorder.ffmpeg_binary=() to set the binary path,
-      # ScreenRecorder.ffmpeg_binary returns 'ffmpeg' assuming it must be in ENV. However,
-      # if the above two checks fail, it is not in the ENV either.
-      return false if ScreenRecorder.ffmpeg_binary == 'ffmpeg'
-
-      true
+      false
+    rescue Errno::ENOENT # Raised when binary is not set in project or found in ENV
+      false
     end
 
     #
@@ -125,15 +135,48 @@ module ScreenRecorder
     end
 
     #
-    # Returns OS specific arguments for Childprocess.build
+    # Executes the given command and outputs to the
+    # optional logfile
+    #
+    def execute_command(cmd, logfile = nil)
+      ScreenRecorder.logger.debug "Executing command: #{cmd}"
+      process        = new_process(cmd)
+      process.duplex = true
+      if logfile
+        @log_file         = File.new(logfile, 'w+')
+        process.io.stdout = process.io.stderr = @log_file
+        @log_file.sync    = true
+      end
+      process.start
+      process
+    end
+
     #
-    def build_command
-      ChildProcess.posix_spawn = true # Support JRuby.
+    # Calls Childprocess.new with OS specific arguments
+    # to start the given process.
+    #
+    def new_process(process)
+      ChildProcess.posix_spawn = true if RUBY_PLATFORM == 'java' # Support JRuby.
       if OS.windows?
-        ChildProcess.build('cmd.exe', '/c', command)
+        ChildProcess.new('cmd.exe', '/c', process)
       else
-        ChildProcess.build('sh', '-c', command)
+        ChildProcess.new('sh', '-c', process)
       end
     end
+
+    #
+    # Waits for given process to exit.
+    # Forcefully kills the process if it does not exit within 5 seconds.
+    # Returns exit code.
+    #
+    def wait_for_process_exit(process)
+      process.poll_for_exit(PROCESS_TIMEOUT)
+      process.exit_code # 0
+    rescue ChildProcess::TimeoutError
+      ScreenRecorder.logger.error 'ffmpeg failed to stop. Force killing it...'
+      process.stop # Tries increasingly harsher methods to kill the process.
+      ScreenRecorder.logger.error 'Forcefully killed ffmpeg. Recording failed!'
+      1
+    end
   end
 end

data/lib/screen-recorder/desktop.rb

@@ -2,14 +2,16 @@
 module ScreenRecorder
   # @since 1.0.0-beta11
   class Desktop < Common
-    DEFAULT_INPUT_WIN   = 'desktop'.freeze
+    include Screenshot
+
+    DEFAULT_INPUT_WIN = 'desktop'.freeze
     DEFAULT_INPUT_LINUX = ':0'.freeze
-    DEFAULT_INPUT_MAC   = '1'.freeze
+    DEFAULT_INPUT_MAC = '1'.freeze
 
     #
     # Desktop recording mode.
     #
-    def initialize(input: input_by_os, output:, advanced: {})
+    def initialize(output:, input: input_by_os, advanced: {})
       super(input: determine_input(input), output: output, advanced: advanced)
     end
 

data/lib/screen-recorder/errors.rb

@@ -1,10 +1,18 @@
-module ScreenRecorder
-  # @since 1.0.0-beta5
-  module Errors
-    # @since 1.0.0-beta3
-    class ApplicationNotFound < StandardError; end
-
-    # @since 1.0.0-beta5
-    class DependencyNotFound < StandardError; end
-  end
+module ScreenRecorder
+  # @since 1.0.0-beta5
+  module Errors
+    # @since 1.0.0-beta3
+    class ApplicationNotFound < StandardError
+      def message
+        'expected application was not found by ffmpeg.'
+      end
+    end
+
+    # @since 1.0.0-beta5
+    class DependencyNotFound < StandardError
+      def message
+        'ffmpeg/ffprobe binary path not set or not found in ENV.'
+      end
+    end
+  end
 end