- DESCRIPTION
- USAGE
- OPTIONS
-s, --size=NxN
-p, --position=N,N
-d, --display
-b, --border
-S, --select-region
-r, --fps=N
-f, --format=TYPE
-i, --audio-input=NAME
-a, --audio-encoder=NAME
-v, --video-encoder=NAME
-A, --vaapi-device=NODE
-e, --fade=TYPE
-m, --volume-factor=N
-w, --watermark=TEXT
-z, --wmark-size=NxN
-k, --wmark-position=N,N
-
--wmark-position=PRE
-c, --wmark-font=NAME
-W, --webcam
-I, --webcam-input=DEV
-Z, --webcam-size=NxN
-P, --webcam-position=N,N
-
--webcam-position=PRE
-R, --webcam-fps=N
-L, --live-streaming=URL
-1, --one-step
-x, --fixed=N
-n, --no-notifications
-g, --png-optimizer=NAME
-o, --output-dir=DIR
-t, --tmp-dir=DIR
-K, --keep
-u, --auto-filename
-l, --list
-h, --help
-V, --version
- EXAMPLES
- INSTALLATION
- REQUIREMENTS
- REMARKS
- LIMITATIONS
- LINKS
- AUTHOR
- COPYRIGHT
- LICENSE
screencast is a command line interface to record a X11 desktop using FFmpeg, having support for offline recording and live streaming. It's designed to make desktop recording a simple task, eliminating the somewhat complex FFmpeg command line arguments and the need of multiple commands. It uses predefined encoder settings that should be suitable for most needs. The default settings provides a quick and affordable way to record the desktop and is YouTube ready, letting the user to be focused on just specifying the desired video size (resolution) and position. If the user doesn't want to stick with the default settings, it is possible to choose among a set of supported encoders and container formats.
screencast not only provides an easy way to record your desktop, but it also has options to automatically add some effects to the recordings, like video fade-in / fade-out, text watermarking, webcam overlay and volume increase.
$ screencast [options] <output>
$ screencast [options] -u
$ screencast [options] -L <URL>
The specified output filename must have an extension which in turn must be a supported container format.
- Options usage notes:
- The default setting will be used for any option that is not specified. You do not need to specify an option if you want to use its default value.
- Long options can be used with spaces or an equal sign (
=
). For example,--fade in
is the same as--fade=in
. - Short options cannot be combined in UNIX style. For example,
$ screencast -unx60
cannot be used and should be entered as$ screencast -u -n -x 60
.
The video size. This is actually the video resolution (width x height). Combined with -p
option it will define a rectangular desktop area that will be recorded. This rectangular area must be inside of the current screen size/resolution (cannot be out of screen bounds).
Both the width and height specified in video size must a multiple of 8. This is a requirement for x265
, kvazaar
, theora
, vp8
and vp9
video encoders. For x264
, h264_nvenc
and hevc_nvenc
video encoders this is actually not required, but it will avoid speedloss with them.
default: 640x480
The screen position defining from where the recording will take place. These are X and Y offsets from the screen top left corner. Combined with -s
option it will define a rectangular desktop area that will be recorded. This rectangular area must be inside of the current screen size/resolution (cannot be out of screen bounds).
default: 0,0
(screen top left corner)
The X server display where to record from. It can be also specified a screen where to record from by adding a dot followed by the screen number (.N
). For example, a value of :0.0
means display 0 and screen 0. If a screen number is not specified, it will defaul to 0
in FFmpeg. Make sure to specify display and screen numbers that are available on the system.
default: :0.0
Tickness of the screen region border delimiter. Valid values are 0
to 128
. A value of 0
disables showing the border delimiter.
default: 2
Select with mouse the screen region to record. Use a single mouse click to select an entire window. Click and drag with mouse to select a region. When dragging, use the arrow keys to fine tune. Right click or any other keystroke to cancel. The -s
and -p
options cannot be used with this option.
The selected width and height must be a multiple of 8 (please see the -s
option for details). It's hard to select a screen region that matches this need with the currently used tool. To overcome this, if the width and height of the selected region does not meet this requirement they will be automatically changed to the immediately higher number that comply with this criteria. Note that if these newly changed values are out of screen bounds screencast will not be able to record and will exit with error.
Video framerate (frames per second - fps).
default: 25
Container format of the output video. This option can be used only with the -u
option (if you want to specify a container format when using automatic output filename choosing). This option cannot be used when entering an output filename. When not using the -u
option, the container format needs to be specified directly in the output filename.
default: mp4
supported types: mp4
, mov
, mkv
, webm
, ogg
, ogv
, flv
, nut
, wmv
, asf
, avi
ALSA audio input device name. Make sure to have a working ALSA configuration, for example, by a having properly configured ~/.asoundrc
file. To determine possible ALSA input device names please see the FFmpeg ALSA capture guide.
- Some special values that can be used:
none
: audio will be disabled (video without audio, only video stream will be present)default
: the default ALSA devicepulse
: the default PulseAudio device
default: default
note: the default audio recording backend used by screencast is ALSA. If your FFmpeg build has no support for ALSA, it will fallback to use the PulseAudio backend (a warning message will be displayed), and in this case you can use this option to specify a PulseAudio input source name. To determine possible PulseAudio input source names you can use the pactl
utility ($ pactl list sources
).
Audio encoder that will be used to encode the recorded audio. For details about the special value none
, please see the REMARKS section bellow.
default: aac
supported types: aac
, opus
, vorbis
, mp3lame
, shine
, wma
, none
Video encoder that will be used to encode the recorded video. If using a hardware accelerated video encoder please make sure that you have a graphics card that supports the specified encoder. Note that hardware accelerated video encoders have additional requirements: NVENC requires NVIDIA drivers to be installed, VAAPI requires libva and libdrm to be installed and QSV requires Intel Media SDK to be installed. For details about the special value none
, please see the REMARKS section bellow.
default: x264
- supported types:
x264
,h264_nvenc
,h264_vaapi
,h264_qsv
,x265
,kvazaar
,svt_hevc
,hevc_nvenc
,hevc_vaapi
,hevc_qsv
,vp8
,vp8_vaapi
,vp9
,svt_vp9
,vp9_vaapi
,theora
,wmv
,aom_av1
,svt_av1
,rav1e
,none
DRM render node (VAAPI device) that will be used to encode the recorded video. This option can be used only when specifying a VAAPI hardware accelerated video encoder with the -v
option and cannot be used when selecting other video encoders. Please make sure that the specified DRM render node is the right one.
default: /dev/dri/renderD128
Enable video fade effect, setting the fade type to TYPE. When setted to none
the recorded video will have no fade effect.
default: none
supported types: in
, out
, both
, none
Volume increase effect factor. This will increase the volume of the recorded audio. Usually, audio volume is low with default settings, even if you increse your microphone capture volume. Use this to give your videos a better hearing experience, letting your viewers fell more confortable to watch it whithout needing to rise their sound volume.
It works as a percentage factor. For example, a value of 1.5
will increase volume by 50% and a value of 2.0
will double volume. It is also possible to set a volume decrease effect, although this is not recommended since for this you can simply decrease your microphone recording volume (for example, a value of 0.5
will decrease volume by 50%).
This option can be used only when the -i
and -a
options are not setted to none
. When setted to 1.0
or 0.0
this effect is disabled.
default: 1.0
(disabled)
Enable text watermark effect, setting the text to TEXT. Although it is a text, it is generated as a PNG image so it can be integrated in the video.
default: disabled
Set text watermark size (resolution). Note that the generated image will be trimmed to remove the unneeded transparent areas. As a result, the actual PNG image that will be added to the video will have a slightly smaller size than the one specified here. This option can be used only with the -w
option.
default: 255x35
Set text watermark position inside the video. This option can be used only with the -w
option.
- It accepts two types of values:
NxN
: X and Y offsets from the video top left corner (not from the screen)PRE
: a predefined special value
supported predefined special values: topleft
/tl
, topright
/tr
, bottomleft
/bl
, bottomright
/br
default: bottomright
Set text watermark font to NAME. To get a list of the available font names for text watermarking on your system you can use the magick
(ImageMagick) utility and execute this command: $ magick -list font
. You can also specify a full filepath of a font file. This option can be used only with the -w
option.
default: DejaVu-Sans
note: if the default or setted font is not installed it will be auto chosen
Enable webcam overlay effect. Before recording with webcam you can adjust your webcam settings like brightness, contrast and gamma correction with the v4l2-ctl
utility (use $ v4l2-ctl -L
to show available values and $ v4l2-ctl -c <option>=<value>
to set values).
default: disabled
Webcam input device, usually in the form of /dev/videoN
. To list video capture devices on your system you can use the v4l2-ctl
utility ($ v4l2-ctl --list-devices
). This option can be used only with the -W
option.
default: /dev/video0
Set webcam video size (resolution). To get a list of supported resolutions for your webcam device you can execute $ ffmpeg -f v4l2 -list_formats all -i <device>
or use the v4l2-ctl
utility ($ v4l2-ctl --list-formats-ext
). This option can be used only with the -W
option.
default: 320x240
Set the webcam overlay position inside the video. This option can be used only with the -W
option.
- It accepts two types of values:
N,N
: X and Y offsets from the video top left corner (not from the screen)PRE
: a predefined special value
supported predefined special values: topleft
/tl
, topright
/tr
, bottomleft
/bl
, bottomright
/br
default: topright
Set webcam framerate (fps). To get a list of supported framerates for your webcam device you can use the v4l2-ctl
utility ($ v4l2-ctl --list-formats-ext
). This option can be used only with the -W
option.
default: device default
Do a live streaming to the server address specified in URL. Please make sure to have a working connection to the specified server address and sufficient upload bandwidth to send the data. Note that the higher the video size (resolution) and framerate (fps), the higher will be the needed upload bandwidth. Use the -K
option if you want to save a local copy of the live streamed video. It uses a one step process (record and encode at the same time). screencast will record offline when this option is not specified. It has been tested only with the YouTube live streaming service. It is recommended to use a hardware accelerated video encoder with this option.
- Some restrictions apply:
- can be used only with audio encoders:
aac
,mp3lame
andshine
- can be used only with video encoders:
x264
,h264_nvenc
,h264_vaapi
andh264_qsv
- can be used only with container formats (when saving the live streamed video with
-K
option):mp4
,mov
,mkv
,flv
,nut
,wmv
,asf
andavi
- cannot be used with fade effect (
-e
option) - must be recorded with audio (
-i
and-a
options cannot be setted tonone
)
- can be used only with audio encoders:
default: disabled
Enable recording in a one step process (record and encode at the same time, without a second encoding step). It will produce a larger video filesize, take less time and require less CPU power when compared to recording in two steps (CPU power comparison is when not using a hardware accelerated encoder). Regarding to filesize and CPU power, this option affects only the x264
, x265
and kvazaar
software-based video encoders. This option cannot be used with fade effect (-e
option). This option is worth to be used with a hardware accelerated encoder, like the NVENC or VAAPI ones, or when using CPU-intensive tasks accompanied by one of the affected software-based encoders that were mentioned (and not needing the fade effect). You do not need to specify this option when doing a live streaming (-L
option) because it already works in a one step process. Note that the default screencast behavior is to record in a two step process (1st step: lossless recording. 2nd step: encoding). This option can cause buffer problems that may lead to packet loss (most notably audio packet loss). It is not recommended to use it with software-based video encoders.
default: disabled
Set the video to have a fixed length of N seconds. When setted to 0
this is disabled, meaning a indefinite video length that will be recorded until the user stops it by presing the q key in the terminal window.
default: 0
(disabled)
Disable desktop notifications. Desktop notifications are shown by default, allowing a better visual control of the recording. Use this option to disable them.
Use PNG optimizer NAME and advdef (advancecomp) in the PNG image generated by the -w
option that will be used as a text watermark. This option is useful when you want to use a big text watermark in a big video, allowing the video to be a bit smaller. Not really needed if using the default watermark settings with a small text. When setted to none
, PNG optimization is disabled. This option can be used only with the -w
option.
default: none
supported ones: optipng
, oxipng
, opt-png
, truepng
, pingo
, none
Set the output video to be saved in DIR. This option can be used only with the -u
option (if you want to specify a save directory when using automatic output filename choosing). This option cannot be used when entering an output filename. When not using the -u
option, the output directory needs to be specified directly in the output filename.
default: the local directory
Set temporary files to be placed in DIR. By default, the ${XDG_CACHE_HOME}/screencast
directory will be used for temporary files (which usually points to ${HOME}/.cache
on most systems). If the $XDG_CACHE_HOME
environment variable is not set, it will default to ${HOME}/.screencast
. Make sure to have enough free space in the specified directory.
default: ${XDG_CACHE_HOME}/screencast
(${HOME}/.screencast
if the $XDG_CACHE_HOME
environment variable is not set)
When recording offline, it will keep (don't delete) the temporary video in the temporary directory. When doing a live streaming, it will keep (save) a copy of the live streamed video in the output directory.
Auto choose output filename based on date and time. The output filename will have the following format:
screencast-YEAR-MONTH-DAY_HOUR.MINUTE.SECOND.FORMAT
List arguments supported by these options.
Help screen.
Show program version information.
-
Use all default settings, specifying filename of the output video:
$ screencast myvideo.mp4
-
Use default settings for a 1280x720 video from screen positon 200,234 (with auto chosen output filename, default
mp4
format):$ screencast -u -s 1280x720 -p 200,234
-
Changing just the container format without specifying encoders will make it to auto choose them if needed. In this case, the
webm
format will produce a video withopus
andvp9
encoders:$ screencast /home/user/webmvideos/myvideo.webm
-
Use hardware accelerated video encoders:
-
NVENC HEVC:
$ screencast -u -v hevc_nvenc
-
VAAPI VP9 using the defafult DRM render node (/dev/dri/renderD128):
$ screencast -u -v vp9_vaapi
-
VAAPI H.264 using the defafult DRM render node (/dev/dri/renderD128):
$ screencast -u -v h264_vaapi
-
VAAPI H.264 using the DRM render node /dev/dri/renderD129:
$ screencast -u -v h264_vaapi -A /dev/dri/renderD129
-
-
Live streaming:
-
Live streaming only, without saving a local output video:
$ screencast -L <URL> -v h264_vaapi
-
Live streaming and also saving a copy to a local output video (with auto chosen output filename, default
mp4
format):$ screencast -L <URL> -v h264_nvenc -K -u
-
-
1280x720 video from screen positon 200,234 , 30 fps,
mp3lame
audio encoder,x265
video encoder,mkv
container format, fade-in video effect, volume increase effect of 50%, small text watermark effect in bottom right video corner (using the default values for watermark size, position and font) and webcam overlay effect at top right video corner (using the default values for webcam input, size, position and framerate):$ screencast -s 1280x720 -p 200,234 -r 30 -a mp3lame -v x265 -e in -m 1.5 -w www.mysitehere.com -W myvideo.mkv
NOTE:
When not using the -x
option, press the q key in terminal window to end the recording.
Installation is done through make. A simple installation procedure would be:
$ make
$ sudo make install
The provided Makefile supports the common DESTDIR
, PREFIX
, BINDIR
, DOCDIR
and MANDIR
variables. If you are using bash and bash-completion, the bash-completion directory can be changed with the BCOMPDIR
variable.
-
The minimum requirements are a POSIX-compatible shell, a running X session, a recent FFmpeg version and xdpyinfo. It's advised to use FFmpeg version git master. FFmpeg needs to be compiled with support for x11grab (libxcb) and the desired encoders and muxers/formats. When recording offline in the default two step process behavior (see REMARKS), FFmpeg needs to be compiled with support for ffv1 encoder, ffv1 decoder, matroska muxer and matroska demuxer (screencast will try to auto-fallback to ffvhuff or huffyuv encoder/decoder if ffv1 is not supported and to nut muxer/demuxer if matroska is not supported, but ffv1 and matroska are preferred). When live streaming, FFmpeg needs to be compiled with support for flv muxer. You can see a FFmpeg compilation guide and screencast packages at the LINKS section.
-
When recording audio (
-i
and-a
options not setted tonone
), FFmpeg must have been compiled with support for ALSA demuxer (screencast will try to auto-fallback to PulseAudio demuxer if ALSA is not supported, but ALSA is preferred). arecord (alsa-utils) will be required for ALSA when specifying a short or long ALSA input device name with the-i
option. If the PulseAudio demuxer is being used in the described auto-fallback situation, pactl will be required when specifying a PulseAudio input source name with with the-i
option. When using webcam overlay effect (-W
option), FFmpeg must have been compiled with support for Video4Linux2. -
notify-send (libnotify) is needed for desktop notifications. Note that desktop notifications are enabled by default. They can be disabled by using the
-n
option, eliminating the need of notify-send. Running screencast in a system without notify-send and without using the-n
option will result in error. -
screencast will try to play a sound notification when the recording/encoding process is finished. For this, it will use FFplay and a sound file from the freedesktop sound theme (usually a package called sound-theme-freedesktop in most Linux distributions). Although not a requirement, they are recommended to be installed for a better user experience. Note that FFplay must have been compiled with support for ogg demuxer and libvorbis (or vorbis) decoder in order to play the needed sound file.
-
Other requirements are needed according to additional options that may be specified by the user:
-
slop is needed for selecting the screen region with mouse (
-S
option). -
FFprobe is needed for video fade effect (
-e
option). -
ImageMagick is needed for text watermark effect (
-w
option). Both IM6 and IM7 are supported, but IM7 is preferred. -
At least one supported PNG optimizer and advdef (advancecomp) are needed for PNG (watermark) optimization (
-g
option).
-
-
screencast is written in pure POSIX shell code and has been tested in bash, dash, yash, ksh and zsh.
-
When recording offline, the default screencast behavior is to use a two step process: firstly the audio and video are recorded to a lossless format, and at a second step it is encoded to produce the final output video. That's why you see a desktop notification saying 'encoding...'. This mechanism produces a better video, avoids problems and allows to use fade effect. When live streaming or when using the
-1
/--one-step
option, screencast uses a one step process, with recording and encoding at the same time. Note that the-1
/--one-step
option is not recommended to be used with software-based video encoders, since it can cause buffer problems that may lead to packet loss (most notably audio packet loss). -
The
-a
/--audio-encoder
and-v
/--video-encoder
options have both a special value ofnone
. Setting-a none
and-v none
at the same time will make screecast to record a lossless video in a one step process. No encoding step will be made and the resulting video will be lossless. The-1
/--one-step
option will be automatically setted in this situation, as there is no second encoding step to be made. Only themkv
andnut
container formats are supported when recording in this lossless way. Note:-a none
can be used only with-v none
, and-v none
can be used only with-a none
(they must be specified in conjuntion, or it can be setted-v none
and-i none
if wanting to a record a video without audio input). -
When using
aac
audio encoder (which is the default setting), screencast will check if the detected FFmpeg build has support for libfdk_aac and use it if present, otherwise it will use the FFmpeg built-in AAC audio encoder. Make sure to have a recent FFmpeg version as older versions do not support the built-in AAC audio encoder without being experimental, or do not support it at all. -
FFmpeg encoder names have the 'lib' prefix removed for simplicity. For example, libx264 is called
x264
in this program. -
For vorbis and opus audio, FFmpeg has both an external library encoder (named 'libvorbis' and 'libopus' encoders) and a native built-in encoder (named 'vorbis' and 'opus' encoders). Although the
vorbis
andopus
audio encoders are mentioned in the options, it is made this way just for simplicity as stated right above. When the user selects thevorbis
oropus
audio encoder, screencast uses respectively the FFmpeg libvorbis or libopus encoder, which has a much superior quality than the FFmpeg native built-in vorbis and opus encoders. -
The
mkv
andnut
container formats are the only ones that support a combination of all audio and video encoders. All other container formats have restrictions. screencast will exit with error if an unsupported encoder is chosen for a given container format. For example, you cannot use theaac
audio encoder withwebm
container format. -
When using the
mp4
container format, the moov atom will be automatically moved to the beginning of the output video file. This is the same as running qt-faststart in the output video and is useful for uploading to streaming websites like YouTube. -
The default settings for container format and audio/video encoders will produce a video that is ready to be uploaded to YouTube.
It has been reported that screencast does not work under Wayland. This is a FFmpeg limitation, since FFmpeg currently does not support recording Wayland sessions.
-
FFmpeg:
-
screencast packages:
Daniel Bermond
https://github.com/dbermond/screencast/
Copyright © 2015-2020 Daniel Bermond
GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.
For details see the file COPYING or visit: http://www.gnu.org/licenses/