Skip to content
Ruby gem to video record your computer screen - desktop or specific window. Works on Windows, Linux, and macOS.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Ask for Ruby version in Issues. Jun 14, 2019
bin Update rubocop configs. Jun 18, 2019
spec Do not use NotImplementedError. Use StandardError instead. May 16, 2019
.gitignore Run rubocop with specs. (#61) Apr 12, 2019
.rspec Create gem using Bundler. Oct 11, 2018
.rubocop.yml Update rubocop configs. Jun 18, 2019
.travis.yml Rename CHANGES to CHANGELOG. Jun 18, 2019
Gemfile Update rubocop configs. Jun 18, 2019
LICENSE.txt Create gem using Bundler. Oct 11, 2018 Update info on Window recording mode. Jun 17, 2019
Rakefile Update rubocop configs. Jun 18, 2019
appveyor.yml Support JRuby. Closes #58. Jun 15, 2019
screen-recorder.gemspec Fix spacing in gem description. Jun 18, 2019


Gem Version Yard Docs Build Status AppVeyor status Maintainability Test Coverage

A Ruby gem to video record your computer screen - desktop or specific window - using FFmpeg. Primarily geared towards recording automated UI test executions for debugging and documentation.



Works on Windows, Linux, and macOS. Requires Ruby 2.0+ or JRuby 9.2+.


1. Setup FFmpeg

Linux and macOS instructions are here.

For Microsoft Windows, download the libx264 enabled binary from here. Once downloaded, add location of the ffmpeg/bin folder to the PATH environment variable (instructions).

Alternatively, you can point to the binary file using ScreenRecorder.ffmpeg_binary = '/path/to/ffmpeg' in your project.

2. Install gem

Next, add these lines to your application's Gemfile:

gem 'ffi' # Windows only
gem 'screen-recorder'

The ffi gem is used by the childprocess gem on Windows, but it does not explicitly require it. More information on this here.

And then execute:

$ bundle

Or install it yourself as:

$ gem install ffi # Windows only
$ gem install screen-recorder
3. Require gem
require 'screen-recorder'


Record Desktop

@recorder = 'recording.mkv')

# Run tests or whatever you want to record


Linux and macOS users can optionally provide a display or input device number. Read more about it in the wiki here.

Record Application Window (Microsoft Windows only)

require 'watir'

browser   = :firefox
@recorder = 'Mozilla Firefox', output: 'recording.mkv')

# Run tests or whatever you want to record


This mode has limited capabilities. Read more about it in the wiki here.

Fetch Title

A helper method is available to fetch the title of the active window for the given process name.

ScreenRecorder::Titles.fetch('firefox') # Name of exe
#=> ["Mozilla Firefox"]

#=> ["New Tab - Google Chrome"]


Once the recorder is stopped, you can view the video metadata or transcode it if desired.
=> #<FFMPEG::Movie:0x0000000004327900 
        @metadata={:streams=>[{:index=>0, :codec_name=>"h264", :codec_long_name=>"H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10", 
        ... >"recording.mp4") { |progress| puts progress } # 0.2 ... 0.5 ... 1.0

See streamio-ffmpeg gem for more details.

Discard Recording

If your test passes or you do not want the recording for any reason, simply call @recorder.discard or @recorder.delete to delete the video file.

Advanced Options

You can provide additional parameters to FFmpeg using the advanced parameter. You can specify input/output specific parameters using input: {} and output: {} within the advanced Hash.

advanced = {
  input:    {
    framerate:  30,
    pix_fmt:    'yuv420p',
    video_size: '1280x720'
  output:   {
    r:       15, # Framerate
    pix_fmt: 'yuv420p'
  log:      'recorder.log',
  loglevel: 'level+debug', # For FFmpeg
} 'recording.mkv', advanced: advanced)

This will be parsed as:

ffmpeg -y -f gdigrab -framerate 30 -pix_fmt yuv420p -video_size 1280x720 -i desktop -r 15 pix_fmt yuv420p -loglevel level+debug recording.mkv

Logging & Debugging

You can configure the logging level of the gem to troubleshoot problems:

ScreenRecorder.logger.level = :DEBUG

Also refer to the ffmpeg.log file for details.

Use with Cucumber

A Cucumber + Watir based example is available here.


Please see the wiki for solutions to commonly reported issues.


After checking out the repo, run bin/setup to install dependencies. Then, run bundle exec rake to run the tests and rubocop. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.


Bug reports and pull requests are welcome.


The gem is available as open source under the terms of the MIT License.


Thanks to Denys Bazarnyi for testing macOS compatibility in v1.1.0.


This gem is based on the streamio-ffmpeg gem.

SauceLabs Logo

Thanks to SauceLabs for providing me with a free account. If you manage an open source project, you can apply for a free account here.

You can’t perform that action at this time.