screen-recorder 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/LICENSE.txt CHANGED
@@ -1,21 +1,21 @@
1
- The MIT License (MIT)
2
-
3
- Copyright (c) 2018 Lakshya Kapoor
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in
13
- all copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
- THE SOFTWARE.
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2018 Lakshya Kapoor
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
data/README.md CHANGED
@@ -1,219 +1,213 @@
1
- # ScreenRecorder
2
-
3
- [![Gem Version](https://badge.fury.io/rb/screen-recorder.svg)](https://badge.fury.io/rb/screen-recorder)
4
- [![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/github/kapoorlakshya/screen-recorder/master)
5
- [![Build Status](https://travis-ci.org/kapoorlakshya/screen-recorder.svg?branch=master)](https://travis-ci.org/kapoorlakshya/screen-recorder)
6
- [![Maintainability](https://api.codeclimate.com/v1/badges/b6049dfee7375aed9bc8/maintainability)](https://codeclimate.com/github/kapoorlakshya/screen-recorder/maintainability)
7
-
8
- A Ruby gem to video record your computer screen - desktop or specific
9
- window - using [FFmpeg](https://www.ffmpeg.org/). Primarily
10
- geared towards recording automated UI test executions for debugging
11
- and documentation.
12
-
13
- Demo - [https://kapoorlakshya.github.io/introducing-screen-recorder-ruby-gem](https://kapoorlakshya.github.io/introducing-screen-recorder-ruby-gem).
14
-
15
- ## Compatibility
16
-
17
- Works on Windows, Linux, and macOS. Requires Ruby 2.0.0 or higher.
18
-
19
- ## Installation
20
-
21
- ##### 1. Setup FFmpeg
22
-
23
- Linux and macOS instructions are [here](https://www.ffmpeg.org/download.html).
24
-
25
- For Microsoft Windows, download the *libx264* enabled binary from [here](https://ffmpeg.zeranoe.com/builds/).
26
- Once downloaded, add location of the `ffmpeg/bin` folder to `PATH` environment variable
27
- ([instructions](https://windowsloop.com/install-ffmpeg-windows-10/)).
28
-
29
- Alternatively, you can provide the location using
30
- `ScreenRecorder.ffmpeg_binary = '/path/to/binary'` in your project.
31
-
32
- ##### 2. Install gem
33
-
34
- Next, add this line to your application's Gemfile:
35
-
36
- ```ruby
37
- gem 'screen-recorder'
38
- ```
39
-
40
- And then execute:
41
-
42
- ```bash
43
- $ bundle
44
- ```
45
-
46
- Or install it yourself as:
47
-
48
- ```bash
49
- $ gem install screen-recorder
50
- ```
51
-
52
- ##### 3. Require gem
53
-
54
- ```ruby
55
- require 'screen-recorder'
56
- ```
57
-
58
- ## Usage
59
-
60
- #### Record Desktop
61
-
62
- ```ruby
63
- @recorder = ScreenRecorder::Desktop.new(output: 'recording.mkv')
64
- @recorder.start
65
-
66
- # Run tests or whatever you want to record
67
-
68
- @recorder.stop
69
- ```
70
-
71
- Linux and macOS users can optionally provide a display or input device number as
72
- `input: ':99'`. Default is `:0` on Linux and `1` on macOS.
73
-
74
- Run command `echo $DISPLAY` on Linux and `ffmpeg -f avfoundation -list_devices true -i ""` on macOS to get a list of available
75
- inputs.
76
-
77
- #### Record Application Window (Microsoft Windows only)
78
-
79
- ```ruby
80
- require 'watir'
81
-
82
- browser = Watir::Browser.new :firefox
83
- @recorder = ScreenRecorder::Window.new(title: 'Mozilla Firefox', output: 'recording.mkv')
84
- @recorder.start
85
-
86
- # Run tests or whatever you want to record
87
-
88
- @recorder.stop
89
- browser.quit
90
- ```
91
-
92
- ##### Fetch Title
93
-
94
- A helper method is available to fetch the title of the active window
95
- for the given process name.
96
-
97
- ```ruby
98
- ScreenRecorder::Titles.fetch('firefox') # Name of exe
99
- #=> ["Mozilla Firefox"]
100
- ```
101
-
102
- ##### Limitations
103
-
104
- - Only available for Microsoft Windows (*gdigrab*). Linux (*x11grab*) and macOS
105
- (*avfoundation*) capture devices do not provide this feature. However, there
106
- is a workaround documented in the [wiki](https://github.com/kapoorlakshya/screen-recorder/wiki/Window-recording-in-Linux-and-Mac).
107
- - Always stop the recording before closing the application. Otherwise,
108
- ffmpeg will force exit as soon as the window disappears and may produce
109
- an invalid video file.
110
- - If you're launching multiple applications or testing an application
111
- at different window sizes, recording the `desktop` is a better option.
112
- - `#fetch` only returns the title from a currently active (visible) window
113
- for the given process.
114
- - `#fetch` may return `ArgumentError (invalid byte sequence in UTF-8)`
115
- for a window title with non `UTF-8` characters. See [wiki](https://github.com/kapoorlakshya/screen-recorder/wiki/Invalid-byte-sequence-in-UTF-8)
116
- for workaround.
117
-
118
- #### Output
119
-
120
- Once the recorder is stopped, you can view the video metadata or transcode
121
- it if desired. See [`streamio-ffmpeg`](https://github.com/streamio/streamio-ffmpeg) for more details.
122
-
123
- ```ruby
124
- @recorder.video
125
- => #<FFMPEG::Movie:0x0000000004327900
126
- @path="recording.mkv",
127
- @metadata={:streams=>[{:index=>0, :codec_name=>"h264", :codec_long_name=>"H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
128
- :profile=>"High",
129
- :codec_type=>"video",
130
- ...
131
- @bitrate=264198,
132
- @video_codec="h264",
133
- @colorspace="yuv420p",
134
- @width=1920,
135
- @height=1080,
136
- @video_bitrate=0,
137
- ... >
138
- ```
139
-
140
- If your test passes or you do not want the recording for any reason,
141
- simply call `@recorder.discard` or `@recorder.delete` to delete
142
- the video file.
143
-
144
- #### Advanced Options
145
-
146
- You can provide additional parameters to FFmpeg using the `advanced`
147
- parameter. The keys in the Hash are prefixed with `-` and paired with the
148
- values in the final command.
149
-
150
- ```ruby
151
- advanced = { framerate: 30,
152
- log: 'recorder.log',
153
- loglevel: 'level+debug', # For FFmpeg
154
- video_size: '640x480',
155
- show_region: '1' }
156
- ScreenRecorder::Desktop.new(output: 'recording.mkv',
157
- advanced: advanced)
158
- ```
159
-
160
- This will be parsed as:
161
-
162
- ```bash
163
- ffmpeg -y -f gdigrab -framerate 30 -loglevel level+debug -video_size 640x480 -show_region 1 -i desktop recording.mkv 2> recorder.log
164
- ```
165
-
166
- This feature is yet to be fully tested, so please feel free
167
- to report any bugs or request a feature.
168
-
169
- #### Logging
170
-
171
- You can configure the logging level of the gem to troubleshoot problems:
172
-
173
- ```ruby
174
- ScreenRecorder.logger.level = :DEBUG
175
- ```
176
-
177
- Also refer to the `ffmpeg.log` file for details.
178
-
179
- #### Use with Cucumber
180
-
181
- A Cucumber + Watir based example is available
182
- [here](https://github.com/kapoorlakshya/cucumber-watir-test-recorder-example).
183
-
184
- ## Wiki
185
-
186
- Please see the [wiki](https://github.com/kapoorlakshya/screen-recorder/wiki) for solutions to commonly reported issues.
187
-
188
- ## Development
189
-
190
- After checking out the repo, run `bin/setup` to install dependencies.
191
- Then, run `bundle exec rake spec` to run the tests. You can also run
192
- `bin/console` for an interactive prompt that will allow you to experiment.
193
-
194
- To install this gem onto your local machine, run `bundle exec rake install`.
195
-
196
- ### Contributing
197
-
198
- Bug reports and pull requests are welcome.
199
-
200
- - Please update the specs for your code changes and run them locally with `bundle exec rake spec`.
201
- - Follow the Ruby style guide and format your code - <https://github.com/rubocop-hq/ruby-style-guide>
202
-
203
- ### License
204
-
205
- The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
206
-
207
- ## Credits
208
-
209
- [![Streamio](http://d253c4ja9jigvu.cloudfront.net/assets/small-logo.png)](http://streamio.com)
210
-
211
- This gem is based on the [streamio-ffmpeg](https://github.com/streamio/streamio-ffmpeg) gem.
212
- <br />
213
- <br />
214
-
215
- ![SauceLabs Logo](https://saucelabs.com/content/images/logo.png)
216
-
217
- Thanks to [SauceLabs](https://saucelabs.com) for providing me with a
218
- free account. If you manage an open source project, you can apply for
1
+ # ScreenRecorder
2
+
3
+ [![Gem Version](https://badge.fury.io/rb/screen-recorder.svg)](https://badge.fury.io/rb/screen-recorder)
4
+ [![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/github/kapoorlakshya/screen-recorder/master)
5
+ [![Build Status](https://travis-ci.org/kapoorlakshya/screen-recorder.svg?branch=master)](https://travis-ci.org/kapoorlakshya/screen-recorder)
6
+ [![AppVeyor status](https://ci.appveyor.com/api/projects/status/u1qashueuw82r235/branch/master?svg=true)](https://ci.appveyor.com/project/kapoorlakshya/screen-recorder/branch/master)
7
+ [![Maintainability](https://api.codeclimate.com/v1/badges/b6049dfee7375aed9bc8/maintainability)](https://codeclimate.com/github/kapoorlakshya/screen-recorder/maintainability)
8
+ [![Test Coverage](https://api.codeclimate.com/v1/badges/b6049dfee7375aed9bc8/test_coverage)](https://codeclimate.com/github/kapoorlakshya/screen-recorder/test_coverage)
9
+
10
+ A Ruby gem to video record your computer screen - desktop or specific
11
+ window - using [FFmpeg](https://www.ffmpeg.org/). Primarily
12
+ geared towards recording automated UI test executions for debugging
13
+ and documentation.
14
+
15
+ Demo - [https://kapoorlakshya.github.io/introducing-screen-recorder-ruby-gem](https://kapoorlakshya.github.io/introducing-screen-recorder-ruby-gem).
16
+
17
+ ## Compatibility
18
+
19
+ Works on Windows, Linux, and macOS. Requires Ruby 2.0 or higher.
20
+
21
+ ## Installation
22
+
23
+ ##### 1. Setup FFmpeg
24
+
25
+ Linux and macOS instructions are [here](https://www.ffmpeg.org/download.html).
26
+
27
+ For Microsoft Windows, download the *libx264* enabled binary from [here](https://ffmpeg.zeranoe.com/builds/).
28
+ Once downloaded, add location of the `ffmpeg/bin` folder to `PATH` environment variable
29
+ ([instructions](https://windowsloop.com/install-ffmpeg-windows-10/)).
30
+
31
+ Alternatively, you can point to the binary file using
32
+ `ScreenRecorder.ffmpeg_binary = '/path/to/ffmpeg'` in your project.
33
+
34
+ ##### 2. Install gem
35
+
36
+ Next, add this line to your application's Gemfile:
37
+
38
+ ```ruby
39
+ gem 'screen-recorder'
40
+ ```
41
+
42
+ And then execute:
43
+
44
+ ```bash
45
+ $ bundle
46
+ ```
47
+
48
+ Or install it yourself as:
49
+
50
+ ```bash
51
+ $ gem install screen-recorder
52
+ ```
53
+
54
+ ##### 3. Require gem
55
+
56
+ ```ruby
57
+ require 'screen-recorder'
58
+ ```
59
+
60
+ ## Usage
61
+
62
+ #### Record Desktop
63
+
64
+ ```ruby
65
+ @recorder = ScreenRecorder::Desktop.new(output: 'recording.mkv')
66
+ @recorder.start
67
+
68
+ # Run tests or whatever you want to record
69
+
70
+ @recorder.stop
71
+ ```
72
+
73
+ Linux and macOS users can optionally provide a display or input device number.
74
+ Read more about it in the wiki [here](https://github.com/kapoorlakshya/screen-recorder/wiki/Input-Values).
75
+
76
+ #### Record Application Window (Microsoft Windows only)
77
+
78
+ ```ruby
79
+ require 'watir'
80
+
81
+ browser = Watir::Browser.new :firefox
82
+ @recorder = ScreenRecorder::Window.new(title: 'Mozilla Firefox', output: 'recording.mkv')
83
+ @recorder.start
84
+
85
+ # Run tests or whatever you want to record
86
+
87
+ @recorder.stop
88
+ browser.quit
89
+ ```
90
+
91
+ ##### Fetch Title
92
+
93
+ A helper method is available to fetch the title of the active window
94
+ for the given process name.
95
+
96
+ ```ruby
97
+ ScreenRecorder::Titles.fetch('firefox') # Name of exe
98
+ #=> ["Mozilla Firefox"]
99
+
100
+ ScreenRecorder::Titles.fetch('chrome')
101
+ #=> ["New Tab - Google Chrome"]
102
+ ```
103
+
104
+ This mode has limited capabilities. Read more about it in the wiki
105
+ [here](https://github.com/kapoorlakshya/screen-recorder/wiki/Window-Capture-Limitations).
106
+
107
+ #### Output
108
+
109
+ Once the recorder is stopped, you can view the video metadata or transcode
110
+ it if desired.
111
+
112
+ ```ruby
113
+ @recorder.video
114
+ => #<FFMPEG::Movie:0x0000000004327900
115
+ @path="recording.mkv",
116
+ @metadata={:streams=>[{:index=>0, :codec_name=>"h264", :codec_long_name=>"H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
117
+ :profile=>"High",
118
+ :codec_type=>"video"}
119
+ @video_codec="h264",
120
+ @colorspace="yuv420p",
121
+ ... >
122
+
123
+ @recorder.video.transcode("movie.mp4") { |progress| puts progress } # 0.2 ... 0.5 ... 1.0
124
+ ```
125
+
126
+ See [`streamio-ffmpeg`](https://github.com/streamio/streamio-ffmpeg) gem for more details.
127
+
128
+ #### Discard Recoding
129
+
130
+ If your test passes or you do not want the recording for any reason,
131
+ simply call `@recorder.discard` or `@recorder.delete` to delete
132
+ the video file.
133
+
134
+ #### Advanced Options
135
+
136
+ You can provide additional parameters to FFmpeg using the `advanced`
137
+ parameter. You can specify input/output specific parameters using the `input: {}`
138
+ and `output: {}` within the `advanced` Hash.
139
+
140
+ ```ruby
141
+ advanced = {
142
+ input: {
143
+ framerate: 30,
144
+ pix_fmt: 'yuv420p',
145
+ video_size: '1280x720'
146
+ },
147
+ output: {
148
+ r: 15, # Framerate
149
+ pix_fmt: 'yuv420p'
150
+ },
151
+ log: 'recorder.log',
152
+ loglevel: 'level+debug', # For FFmpeg
153
+ }
154
+ ScreenRecorder::Desktop.new(output: 'recording.mkv', advanced: advanced)
155
+ ```
156
+
157
+ This will be parsed as:
158
+
159
+ ```bash
160
+ ffmpeg -y -f gdigrab -framerate 30 -pix_fmt yuv420p -video_size 1280x720 -i desktop -r 15 pix_fmt yuv420p -loglevel level+debug recording.mkv
161
+ ```
162
+
163
+ #### Logging & Debugging
164
+
165
+ You can configure the logging level of the gem to troubleshoot problems:
166
+
167
+ ```ruby
168
+ ScreenRecorder.logger.level = :DEBUG
169
+ ```
170
+
171
+ Also refer to the `ffmpeg.log` file for details.
172
+
173
+ #### Use with Cucumber
174
+
175
+ A Cucumber + Watir based example is available
176
+ [here](https://github.com/kapoorlakshya/cucumber-watir-test-recorder-example).
177
+
178
+ ## Wiki
179
+
180
+ Please see the [wiki](https://github.com/kapoorlakshya/screen-recorder/wiki) for solutions to commonly reported issues.
181
+
182
+ ## Development
183
+
184
+ After checking out the repo, run `bin/setup` to install dependencies.
185
+ Then, run `bundle exec rake` to run the tests and rubocop. You can also run
186
+ `bin/console` for an interactive prompt that will allow you to experiment.
187
+
188
+ To install this gem onto your local machine, run `bundle exec rake install`.
189
+
190
+ ### Contributing
191
+
192
+ Bug reports and pull requests are welcome.
193
+
194
+ - Please update the specs for your code changes and run them locally with `bundle exec rake spec`.
195
+ - Follow the Ruby style guide and format your code - <https://github.com/rubocop-hq/ruby-style-guide>
196
+
197
+ ### License
198
+
199
+ The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
200
+
201
+ ## Credits
202
+
203
+ [![Streamio](http://d253c4ja9jigvu.cloudfront.net/assets/small-logo.png)](http://streamio.com)
204
+
205
+ This gem is based on the [streamio-ffmpeg](https://github.com/streamio/streamio-ffmpeg) gem.
206
+ <br />
207
+ <br />
208
+
209
+ ![SauceLabs Logo](https://saucelabs.com/content/images/logo.png)
210
+
211
+ Thanks to [SauceLabs](https://saucelabs.com) for providing me with a
212
+ free account. If you manage an open source project, you can apply for
219
213
  a free account [here](https://saucelabs.com/open-source).