PHPackages cytopia/ffscreencast - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. cytopia/ffscreencast ActiveLibrary[Utility & Helpers](/categories/utility) cytopia/ffscreencast ==================== ffmpeg screencast with video overlay and multi monitor support. v0.6.4(9y ago)1.8k2.1k75[17 issues](https://github.com/cytopia/ffscreencast/issues)[3 PRs](https://github.com/cytopia/ffscreencast/pulls)MITShell Since Oct 1Pushed 1y ago33 watchersCompare [ Source](https://github.com/cytopia/ffscreencast)[ Packagist](https://packagist.org/packages/cytopia/ffscreencast)[ Docs](https://github.com/cytopia/ffscreencast)[ RSS](/packages/cytopia-ffscreencast/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependenciesVersions (13)Used By (0) ffscreencast ============ [](#ffscreencast) [Features](https://github.com/cytopia/ffscreencast#1-features) | [Installation](https://github.com/cytopia/ffscreencast#2-installation) | [Usage](https://github.com/cytopia/ffscreencast#3-usage) | [Screenshots](https://github.com/cytopia/ffscreencast#4-screenshots) | [FAQ](https://github.com/cytopia/ffscreencast#5-faq) | [Todo](https://github.com/cytopia/ffscreencast#6-todo) | [Contribution](https://github.com/cytopia/ffscreencast#7-contribution) | [License](https://github.com/cytopia/ffscreencast#8-license) | [Version](https://github.com/cytopia/ffscreencast#9-version) | [Awesome](https://github.com/cytopia/ffscreencast#10-awesome) [![Build Status](https://camo.githubusercontent.com/3c705c420a3e021dc20aa52ce2fcc9d52cc8ba107243cb98bde198118cf0a34b/68747470733a2f2f7472617669732d63692e6f72672f6379746f7069612f666673637265656e636173742e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/cytopia/ffscreencast)[![Latest Stable Version](https://camo.githubusercontent.com/df0054de99b93aea9d90b997e589d90433ae0b29f0bee218baafd239f25a12c1/68747470733a2f2f706f7365722e707567782e6f72672f6379746f7069612f666673637265656e636173742f762f737461626c65)](https://packagist.org/packages/cytopia/ffscreencast) [![Total Downloads](https://camo.githubusercontent.com/2ee82057e4d9c06f37f729f18b8013ffadf64498e8035f85e7d9f871aaf2d91b/68747470733a2f2f706f7365722e707567782e6f72672f6379746f7069612f666673637265656e636173742f646f776e6c6f616473)](https://packagist.org/packages/cytopia/ffscreencast) [![Latest Unstable Version](https://camo.githubusercontent.com/17ff960bff402f665fa296bb5686924f4ac432d55203b8c04ab37ccb1c798779/68747470733a2f2f706f7365722e707567782e6f72672f6379746f7069612f666673637265656e636173742f762f756e737461626c65)](https://packagist.org/packages/cytopia/ffscreencast) [![License](https://camo.githubusercontent.com/2957320dcf8466ce8680c11ecdc9369adce729f2f07195a4a55e40eef8607d08/68747470733a2f2f706f7365722e707567782e6f72672f6379746f7069612f666673637265656e636173742f6c6963656e7365)](http://opensource.org/licenses/MIT)[![Type](https://camo.githubusercontent.com/7b3316a9d8ffaaa563ae2bdacf059ad56d29bd152ead70c989bd6841e14d5dc9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f747970652d626173682d7265642e737667)](https://www.gnu.org/software/bash/) **About** `ffscreencast` is a shell wrapper for `ffmpeg` that allows fool-proof screen recording via the command line. It will auto-detect all available monitors, cameras and microphones and is able to interactively or manually choose the desired recording device(s). Additionally `ffscreencast` will let you overlay the camera stream on top of the desktop session. Besides that `ffscreencast` can act as an ffmpeg command generator. Every available option can also just show the corresponding ffmpeg command instead of executing it. Non-ffmpeg commands, such as how the camera resolution is pulled and others can also be shown instead of being executed. [![Screencast](https://raw.githubusercontent.com/cytopia/ffscreencast/master/doc/img/ffscreencast.png)](https://raw.githubusercontent.com/cytopia/ffscreencast/master/doc/img/ffscreencast.png) **Supported platforms** OSXLinuxFreeBSDWindows[![OSX](https://raw.githubusercontent.com/cytopia/icons/master/64x64/osx.png)](https://www.apple.com/osx)[![Linux](https://raw.githubusercontent.com/cytopia/icons/master/64x64/linux.png)](https://raw.githubusercontent.com/cytopia/icons/master/64x64/linux.png)[![FreeBSD](https://raw.githubusercontent.com/cytopia/icons/master/64x64/freebsd.png)](https://www.freebsd.org)[![Windows](https://raw.githubusercontent.com/cytopia/icons/master/64x64/windows.png)](https://www.microsoft.com/en-us/windows)via [AVFoundation](https://ffmpeg.org/ffmpeg-devices.html#avfoundation)via [x11grab](https://ffmpeg.org/ffmpeg-devices.html#x11grab)coming sooncoming soon**Requirements** ProgramRequiredDescription[bash](https://www.gnu.org/software/bash/)yesThe whole script is written in bash and might not be 100% Posix compliant[ffmpeg](https://www.ffmpeg.org/)yesThe ffmpeg binary must be present[v4l2-ctl](http://linuxtv.org/wiki/index.php/V4l-utils)LinuxRequired for linux to list camera devices[arecord](http://linux.die.net/man/1/arecord)LinuxRequired for linux to list sound devices[xdpyinfo](http://www.x.org/archive/X11R7.6/doc/man/man1/xdpyinfo.1.xhtml)LinuxRequired for linux to list screends1. Features ----------- [](#1-features) - Config file for default configuration - Screen recording - Camera overlay - Audio support - Allows to manually (parameter) or interactively choose monitor - Allows to manually (parameter) or interactively choose camera - Allows to manually (parameter) or interactively choose sound device - ffmpeg command generation 2. Installation --------------- [](#2-installation) ### 2.1 OSX [](#21-osx) ``` brew install cytopia/tap/ffscreencast ``` ### 2.2 Linux/BSD [](#22-linuxbsd) ``` git clone https://github.com/cytopia/ffscreencast cd ffscreencast sudo cp bin/ffscreencast /usr/local/bin ``` 3. Usage -------- [](#3-usage) ### 3.1 Overview [](#31-overview) To simply start desktop recording your screen call the program without any arguments `ffscreencast` and it will use the default screen without camera overlay and without sound. ``` $ ffscreencast Usage: ffscreencast [-s[num]] [--sargs=] [-a[num]] [--aargs=] [-c[num] [--cargs=] [--oargs=] [-e] [--dry] ffscreencast --slist [--dry] ffscreencast --alist [--dry] ffscreencast --clist [--dry] ffscreencast --help ffscreencast --version ffscreencast --test When invoked without any arguments, it will start screen recording on the default screen without sound and without camera overlay. Input options: -s[num] (Default) Enable screen capturing [with device number X]. If no device number is specified it will use the default, if only one device is present, otherwise it will ask you to choose one Use: -s or -s1 --sargs= Additional screen arguments. Specify additional ffmpeg arguments for the screen input device. Use: --sargs="-framerate 30" Default: '' -a[num] Enable audio capturing [with device number X] If no device number is specified it will use the default, if only one device is present, otherwise it will ask you to choose one Use: -a or -a1 --aargs= Additional audio arguments. Specify additional ffmpeg arguments for the audio input device. Use: --aargs="-ac 1" Default: '-ac 2' -c[num] Add camera overlay [with device number X] If no device number is specified it will use the default, if only one device is present, otherwise it will ask you to choose one Use: -c or -c1 --cargs= Additional camera arguments Specify additional ffmpeg arguments for the camera input device. Use: --cargs="-video_size 1280x720" Default: '' Output options: -e Output video format extension (Default: mkv) E.g.: -emkv, or -eavi, or -emp4 -oargs= Additional output arguments Specify additional ffmpeg arguments for the output encoding. Use: --oargs="-crf 0" Default: '-crf 0 -preset ultrafast' Behavior options: --dry Show the command (without executing) List options: --list List all devices --slist Only list screen capturing devices (monitors) --alist Only list audio capturing devices (microphones) --clist Only list camera capturing devices (cams) System information: --help Show this help screen --version Show version information --test Test requirements ``` The `num` (device numbers) can be omitted. If there is only one device of its type available, `ffscreencast` will automatically default to this device, otherwise it will ask interactively which device to use for recording. ### 3.2 Examples [](#32-examples) Do a screencast on the default screen (without explicitly choosing the monitor) ``` $ ffscreencast ``` List monitors and record on monitor 2 (`Capture screen 0`) ``` $ ffscreencast --slist Available screen recording devices (monitors): [2] Capture screen 0 Color LCD: Resolution: 2880 x 1800 Retina [3] Capture screen 1 S2431W: Resolution: 1920 x 1200 [4] Capture screen 2 Thunderbolt Display: Resolution: 2560 x 1440 $ ffscreencast -s2 ``` List cameras ``` $ ffscreencast --clist Available camera recording devices: [0] FaceTime HD Camera (Display) (160x120@29.97 160x120@25 160x120@23.999981 160x120@14.999993 176x144@29.97 176x144@25 176x144@23.999981 176x144@14.999993 320x240@29.97 320x240@25 320x240@23.999981 320x240@14.999993 352x288@29.97 352x288@25 352x288@23.999981 352x288@14.999993 640x480@29.97 640x480@25 640x480@23.999981 640x480@14.999993 960x540@29.97 960x540@25 960x540@23.999981 960x540@14.999993 1024x576@29.97 1024x576@25 1024x576@23.999981 1024x576@14.999993 1280x720@29.97 1280x720@25 1280x720@23.999981 1280x720@14.999993) [1] FaceTime HD Camera (1280x720@30 640x480@30 320x240@30) ``` Start a screencast with camera overlay (only one camera present) ``` $ ffscreencast -c ``` or select the camera device ``` $ ffscreencast -c0 ``` Show the ffmpeg command for camera recording ``` $ ffscreencast -c --dry ffmpeg -hide_banner -loglevel info -f avfoundation -i "1" -f avfoundation -i "0" -c:v libx264 -crf 0 -preset ultrafast -filter_complex 'overlay=main_w-overlay_w-10:main_h-overlay_h-10' "/Users/cytopia/Desktop/Screencast 2015-10-06 at 21.28.01.mkv" ``` 4. Screenshots -------------- [](#4-screenshots) Showing screen recording with and without camera overlay. [![Screencast](https://raw.githubusercontent.com/cytopia/ffscreencast/master/doc/img/ffscreencast.png)](https://raw.githubusercontent.com/cytopia/ffscreencast/master/doc/img/ffscreencast.png)[![Screencast](https://raw.githubusercontent.com/cytopia/ffscreencast/master/doc/img/ffscreencast2.png)](https://raw.githubusercontent.com/cytopia/ffscreencast/master/doc/img/ffscreencast2.png) 5. FAQ ------ [](#5-faq) This section will be updated whenever questions arise that are worth mentioning here ### 5.1 How to convert to other formats? [](#51-how-to-convert-to-other-formats) There is currently no built-in gif support, mainly because it will not produce such a good quality. It is recommended to first create your screencast with the best possible quality and least possible resources (you are obviously going to do something and will not want to consume all your cpu for the encoding) and afterwards convert it to a high quality gif or other formats. See [contrib](contrib/) for converters and feel free to add more. ### 5.2 How to enable cursor capturing on OSX? [](#52-how-to-enable-cursor-capturing-on-osx) By default `ffmpeg` on OSX (using `AVFoundation`) does not capture the mouse (on Linux it does). You can however pass this as a custom option to `ffscreencast` In order to capture the mouse pointer itself add the following `--sargs`: ``` ffscreencast --sargs="-capture_cursor 1" ``` If you also want to *see* when you actually click the mouse, do it like this: ``` ffscreencast --sargs="-capture_cursor 1 -capture_mouse_clicks 1" ``` ### 5.3 How to hide the cursor on Linux/BSD? [](#53-how-to-hide-the-cursor-on-linuxbsd) By default `ffmpeg` on Linux/BSD (using `x11grab`) does show the mouse pointer by default (OSX does not). You can however pass this as a custom option to `ffscreencast` in order to hide the mouse pointer: ``` ffscreencast --sargs="-draw_mouse 0" ``` ### 5.4 How to alter the *default* options (config file)? [](#54-how-to-alter-the-default-options-config-file) When you run `ffscreencast` for the first time, it will create a configuration file in `~/.config/ffscreencast/ffscreencastrc`. Everything specified in this file will be applied when you run `ffscreencast` without any arguments. So if you have your own nice defaults you always need to enter, you can simply add them to the config file. 6. Todo ------- [](#6-todo) ### 6.1 Bugs [](#61-bugs) - **General:** Sound is still behind one second when using camera overlay - **OSX:** USB Monitors (see [\#1](https://github.com/cytopia/ffscreencast/issues/1)) ### 6.2 Enhancements [](#62-enhancements) - **BSD:** Support for \[Free\]BSD (needs testing) - **Windows:** Support for Windows (via cygwin and dshow) - **Linux:** set sound options via cmd (alsa vs pulse) - **Linux:** Get default resolution/framerate for camera - **OSX:** Get default resolution/framerate for camera - **General:** Set camera resolution via cmd use `--cargs` - **General:** Set camera position via cmd - **General:** Be able to record one or multiple screens (monitors) 7. Contribution --------------- [](#7-contribution) Contributors are welcome. 8. License ---------- [](#8-license) [![license](https://camo.githubusercontent.com/2957320dcf8466ce8680c11ecdc9369adce729f2f07195a4a55e40eef8607d08/68747470733a2f2f706f7365722e707567782e6f72672f6379746f7069612f666673637265656e636173742f6c6963656e7365)](http://opensource.org/licenses/mit) 9. Version ---------- [](#9-version) For a complete list of verion see [CHANGELOG](CHANGELOG.md) 10. Awesome ----------- [](#10-awesome) Added by the following [![Awesome](https://camo.githubusercontent.com/2727609d8bfde9ba1a95be1449eb878bfafa4d76789ba05661857e2c8ac70fa1/68747470733a2f2f63646e2e7261776769742e636f6d2f73696e647265736f726875732f617765736f6d652f643733303566333864323966656437386661383536353265336136336531353464643865383832392f6d656469612f62616467652e737667)](https://github.com/sindresorhus/awesome) lists: - [awesome-cli](https://github.com/aharris88/awesome-cli) ### Health Score 41 — FairBetter than 89% of packages Maintenance27 Infrequent updates — may be unmaintained Popularity42 Moderate usage in the ecosystem Community22 Small or concentrated contributor base Maturity60 Established project with proven stability Bus Factor1 Top contributor holds 95.8% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~59 days Recently: every ~113 days Total 10 Last Release 3348d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/527dbe351b75d33be6d5428502783ceb57e86949892a0a0062f24199772aabae?d=identicon)[cytopia](/maintainers/cytopia) --- Top Contributors [![cytopia](https://avatars.githubusercontent.com/u/12533999?v=4)](https://github.com/cytopia "cytopia (46 commits)")[![lathiat](https://avatars.githubusercontent.com/u/290673?v=4)](https://github.com/lathiat "lathiat (1 commits)")[![Nek-](https://avatars.githubusercontent.com/u/972456?v=4)](https://github.com/Nek- "Nek- (1 commits)") --- Tags camera-overlayffmpegffmpeg-commandffmpeg-wrapperscreen-recorderscreencastffmpegscreencastscreen recording ### Embed Badge ![Health badge](/badges/cytopia-ffscreencast/health.svg) ``` [![Health](https://phpackages.com/badges/cytopia-ffscreencast/health.svg)](https://phpackages.com/packages/cytopia-ffscreencast) ``` ### Alternatives [php-ffmpeg/extras A set of audio/video formats compatible with PHP-FFMpeg 182287.6k1](/packages/php-ffmpeg-extras)[vonage/nexmo-bridge Provides a bridge for using the Vonage PHP SDK with the older Nexmo namespace 5310.3M3](/packages/vonage-nexmo-bridge)[mediawiki/chameleon-skin A highly flexible MediaWiki skin using Bootstrap 4 12481.8k2](/packages/mediawiki-chameleon-skin)[aeon-php/calendar-holidays Holidays calendar abstraction layer for Aeon Time management framework 14212.4k3](/packages/aeon-php-calendar-holidays) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)