Gem Version https://rubygems.org/gems/ffmpeg-screenrecorder Yard Docs Build Status Maintainability

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


Supports Windows and Linux as of version 1.0.0-beta5. macOS support will be added before the final release of v1.0.0.


1. Setup FFmpeg

OS Download
Microsoft Windows ffmpeg.org#build-windows or libx264 enabled build
Linux ffmpeg.org#build-linux
macOS ffmpeg.org#build-mac

Add location of the ffmpeg/bin folder to PATH environment variable if using Microsoft Windows (instructions). Alternatively, you can define the location using FFMPEG.ffmpeg_binary='/path/to/binary' in your project.

2. Install gem

Next, add this line to your application's Gemfile:

gem 'ffmpeg-screenrecorder'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ffmpeg-screenrecorder --pre

3. Require gem

Require this gem in your project and start using the gem:

require 'ffmpeg-screenrecorder'

Record Desktop

opts      = { input:     'desktop',
              output:    'recording.mp4' }
@recorder = FFMPEG::ScreenRecorder.new(opts)

# ... Run tests or whatever you want to record


# Recorded file metadata
#=> #<FFMPEG::Movie:0x00000000067e0a08
    @video_stream="h264 (High 4:4:4 Predictive) (avc1 / 0x31637661), yuv444p, 2560x1440, 1048 kb/s, 15 fps, 15 tbr, 15360 tbn, 30 tbc (default)",
    @video_codec="h264 (High 4:4:4 Predictive) (avc1 / 0x31637661)", @colorspace="yuv444p",

Record Application Window

require 'watir'

browser = Watir::Browser.new :firefox

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

opts      = { input:     FFMPEG::WindowTitles.fetch('firefox').first,
              output:    'recording.mp4' }
@recorder = FFMPEG::ScreenRecorder.new(opts)

# Run tests or whatever you want to record



  • Only works on Microsoft Windows (gdigrab).
  • #fetch only returns titles from currently active (visible) windows.
  • #fetch may return ArgumentError (invalid byte sequence in UTF-8) for a window title with non UTF-8 characters. See #38 for workaround.
  • Always stop the recording before closing the application. Otherwise, ffmpeg will force exit as soon as the window disappears and may produce an invalid video file.
  • If you're launching multiple applications or testing an application at different window sizes, recording the desktop is a better option.


  • :input - 'desktop' or application window name
  • :output - Output file location/name
  • :framerate - Capture FPS
  • :log - Defaults to ffmpeg.log
  • :log_level for this gem. Default: ERROR

All other FFmpeg options can be passed through the advanced key. This feature is yet to be fully tested, so please feel free to report any bugs or request a feature.

opts = { input:     'desktop',
         output:    'recorder-test.mp4',
         framerate: 30.0,
         log:       'recorder.log',
         log_level: Logger::DEBUG, # For gem
         advanced: { loglevel: 'level+debug', # For FFmpeg
                     video_size:  '640x480',
                     show_region: '1' }

# Command to FFmpeg:
# ffmpeg -y -f gdigrab -r 15 -loglevel level+debug -video_size 640x480
#   -show_region 1 -i desktop recorder-test.mp4 2> recorder.log


You can find example video recordings here. Cucumber + Watir based example is here.


After checking out the repo, run bin/setup to install dependencies. Then, run bundle exec rake spec to run the tests. 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.



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.