Repository files navigation

Simple screen recorder with an easy to use interface

• About
• Requirements
  • Runtime
  • Development
• Installation
  • Official distribution packages
  • Flatpak
  • Snappy
  • AppImage
  • Ubuntu
  • ElementaryOS
  • Debian
  • Fedora
  • Solus
  • Arch Linux
  • Other distributions
  • From source
• Frequently Asked Questions
  • How can I capture mouse clicks and/or keystrokes?
  • How can I improve the quality of recorded GIF files
  • Why are the GIF files so big?
  • If GIF is so bad why use it at all?
  • What about WebM or MP4? Those are well supported on the web.
  • What is the cause for "Could not start GNOME Shell recorder" errors?
  • Why can't I interact with the UI elements inside the recording area?
  • My recorded GIFs flicker, what is wrong?
  • On i3 the recording area is all black, how can I record anything?
  • Why no native Wayland support?
• Contribute
  • Development
  • Translations
• License

Peek makes it easy to create short screencasts of a screen area. It was builtfor the specific use case of recording screen areas, e.g. for easily showing UIfeatures of your own apps or for showing a bug in bug reports. With Peek, yousimply place the Peek window over the area you want to record and press"Record". Peek is optimized for generating animated GIFs, but you can alsodirectly record to WebM if you prefer.

Peek is not a general purpose screencast app with extended features butrather focuses on the single task of creating small, silent screencasts ofan area of the screen for creating GIF animations or silent WebM videos.

Peek runs on X11 or inside a GNOME Shell Wayland session using XWayland.Support for more Wayland desktops might be added in the future (see FAQs below).

• GTK+ >= 3.20
• GLib >= 2.38
• libkeybinder3
• FFmpeg >= 3
• GStreamer 'Good' plugins (for recording on GNOME Shell)
• gifski (optional but recommended for improved GIF quality)

• Vala compiler >= 0.22
• Meson >= 0.47.0
• Gettext (>= 0.19 for localized .desktop entry)
• txt2man (optional for building man page)

Peek is available in official package repositories for the followingdistributions:

• Alpine Linux
• Arch Linux
• Debian
• Fedora
• Gentoo
• NixOS
• OpenSUSE Tumbleweed
• Parabola
• Solus

Peek can be installed on all distributions supportingFlatpak fromFlathub.To install, either downloadcom.uploadedlobster.peek.flatpakrefand open it with GNOME Software or install via command line (first time flatpakusers need to follow theflatpak/flathub setup instructions first):

flatpak install flathub com.uploadedlobster.peek

For full functionality you should also installxdg-desktop-portal-gtk.It is available for most current distributions. Once installed, you can run Peekvia its application icon in your desktop environment or from the command line:

flatpak run com.uploadedlobster.peek

To update to the latest version run:

flatpak update --user com.uploadedlobster.peek

To test the latest development version you can installpeek-master.flatpakref

Peek no longer has officially supported Snap packages, seethe announcement.Please consider using the Flatpak or AppImage versions or use the Ubuntu PPAif you are using Ubuntu.

PeekAppImage packages are available on therelease page. To run download the.AppImage file and set it executable, then just run it. You can name the filehowever you want, e.g. you can name it justpeek and place it in$HOME/binfor easy access. See theAppImage wikifor more information on how to use AppImages and integrate them with your system.

You can install the latest versions of Peek from theUbuntu PPA.

sudo add-apt-repository ppa:peek-developers/stablesudo apt updatesudo apt install peek

If you want to use the latest development version there is also aPPA with daily buildsavailable. Use the repositoryppa:peek-developers/daily in the above commands.

Adding PPA repositories requires the packagesoftware-properties-common

sudo apt install software-properties-commonsudo add-apt-repository ppa:peek-developers/stablesudo apt updatesudo apt install peek

If you want to use the latest development version there is also aPPA with daily buildsavailable. Use the repositoryppa:peek-developers/daily in the above commands.

There are official Debian packages for Debian 11 ("Bullseye") and Debian 10 ("Buster") viamain repository and packages for Debian 9 ("Stretch") viastretch-backportsrepository. Please refer toDebian Backports Websitefor detailed usage ofstretch-backports repository.

After enablingstretch-backports for Debian 9 (Debian 10 or Debian 11 orSid don't needany tweaks at all), installation can be done by simply typing:

sudo apt install peek

Note: Fedora by default does not provide the requiredffmpeg package in itsrepositories. For this reason it is recommended for Fedora users to install Peekwith Flatpak, see above. If you prefer to install Peek from the repositoriesyou should installffmpeg separately as described below.

Peek is available in the default repositories (Fedora 29 and later):

sudo dnf install peek

To install the requiredffmpeg package you can use the RPM Fusion freerepository, see thesetup instructions for RPM Fusion.Once the repository is enabled install FFmpeg with:

sudo dnf install ffmpeg

Solus users can simply install with:

sudo eopkg it peek

Arch Linux users can simply install with:

sudo pacman -S peek

For GNOME Shell recording there are some optional packages you can choose from:

gst-plugins-good: Recording under Gnome Shellgifski: High quality GIF animations with thousands of colors

If you have a package manager for AUR (or fetch from AUR manually) the gitversion is availablehere

See theRepology package listfor a list of Peek packages for various distributions.

You can build and install Peek using Meson with Ninja:

git clone https://github.com/phw/peek.gitcd peekmeson --prefix=/usr/local builddircd builddirninja# Run directly from source./src/peek# Install system-widesudo ninja install

Note:ninja might be calledninja-build on some distributions.

Peek does not support this natively. But you could install an external toollikekey-mon which is usually includedin most distributions, so you can easily install with your package manager.Then start key-mon withkey-mon --visible_click. The--visible_click optionis for drawing small circles around mouse clicks.

To get the best possible quality you should install thegifskiGIF encoder. If available Peek will automatically use gifski and will providea quality slider in the preferences dialog. The default value will give abalanced result between quality and file size. Set the quality to maximum if youwant to get the highest possible quality even with thousands of colors. The filesize will increase significantly, though (see below).

The GIF format is highly inefficient and not well suited for doing largeanimations with a lot of changes and colors. Peek tries its best to reduce thefile size by using FFmpeg orgifski to generate optimizedGIF files. For best results:

• Use a lower frame rate. 10fps is the default and works well, but in manycases you can even get good results with lower framerates.
• If you havegifski installed you can adjust the GIFquality in the preferences. A lower quality gives a smaller file size at theexpense of visual quality (see above).
• Avoid too much change. If there is heavy animation the frames will differa lot.
• Record small areas or use the downsample option to scale the image. The GIFfile format is not well suited for high resolution or full-screen recording.
• Avoid too many colors, since GIF is limited to a 256 color palette per frame.This one is not so much about file size but more about visual quality.
• If the above suggestions are not suitable for your use case, consider usingWebM format (see below).

While GIF is a very old format, it has seen some rise in usage again in recentyears. One reason is its easy usage in the Web. GIF files are supported nearlyeverywhere, which means you can add animations easily to everywhere where youcan upload images. With real video files you are still more limited. Typical usecases for Peek are recording small user interactions for showing UI featuresof an app you developed, for making short tutorials or for reporting bugs.

Peek allows you to record in WebM format, just choose your preferred outputformat in the preferences. WebM is well supported by modern browsers, eventhough they are still not as universally supported by tools and online servicesas GIFs.

This usually indicates an error while starting the built-in GNOME shellrecorder. Unfortunately Peek does not receive any error details, to find outmore about this issues look at the GNOME Shell log output injournalctl.

A common cause for this is that the GNOME Shell recorder is already running,either because it was started via the GNOME Shell keyboard shortcut or byanother application.

If this error is shown when trying to record MP4 a common cause is that you aremissing theGStreamer uglyplugins, which provide MP4 encoding. Please refer to the documentation of yourdistribution on how to install these.Do note that you have to logout and login for Peek to recognize the newinstalled libraries if you are running the Wayland display server.

See also issue#287 for related discussion.

You absolutely should be able to click the UI elements inside the area you arerecording. If you use i3 you should stack Peek with the window you intend torecord or make sure all windows are floating and uncheck "Always on top" fromthe Peek settings. If you want to be able to control the area when recordingin i3 you can move Peek to the Scratchpad it will keep recording the area onceyou hide the window. If this does not work for you on any other window managerplease open anissue on GitHub.

Some users have experienced recorded windows flicker or other strange visualartifacts only visible in the recorded GIF. This is most likely a video driverissue. If you are using Intel video drivers switching between the SNA and UXAacceleration methods can help. For NVIDIA drivers changing the "Allow Flipping"setting in the NVIDIA control panelwas reported to help.

i3 does not support the X shape extension. In order to get a transparentrecording area, you have to run a compositor such as Compton.

Wayland has two restrictions that make it hard for Peek to support Waylandnatively:

1. The Wayland protocol does not define a standard way for applications toobtain a screenshot. That is intentional, as taking an arbitrary screenshotessentially means any application can read the contents of the whole display,and Wayland strives to offer improved security by isolating applications. Itis up to the compositors to provide screenshot capability, and most do. GNOMEShell also provides a public interface for applications to use which Peekdoes support.

2. The Wayland protocol does not provide absolute screen coordinates to theapplications. There is not even a coordinate system for windows at all. Againthis is intentional, as they are not needed in many cases and you do not needto follow restrictions imposed by the traditional assumption that the screenis a rectangular area (e.g. you can have circular screens orlayout windowsin 3D space).

Unfortunately, the whole concept of the Peek UI is that the window positionitself is used to obtain the recording coordinates. That means, for now, therecannot be any fully native Wayland support without special support for thisuse case by the compositor.

However, it is possible to use Peek in a GNOME Shell Wayland session usingXWayland by launching Peek with the X11 backend:

GDK_BACKEND=x11 peek

Support for compositors other than GNOME Shell can be added if a suitablescreencasting interface is provided.

If you want to help make Peek better the easiest thing you can do is toreport issues and feature requests.Or you can help in development and translation.

You are welcome to contribute code and provide pull requests for Peek. Theeasiest way to start is looking at the open issues tagged withgood first issue.Those are open issues which are not too difficult to solve and can be startedwithout too much knowledge about the code.

Another good starting point are issues tagged withhelp wanted. Those issues areprobably harder to solve, but for some reason I cannot work on it for now andwould love to see somebody jump in.

In any case, just leave a note on the issue itself that you are working on it,to avoid multiple people working on the same issue.

You can help translate Peek into your language. Peek is usingWeblate for translation management.

Go to thePeek localization projectto start translating. If the language you want to translate into is not alreadyavailable, youcan add it here.

If you want to be credited for your translation, please add your name to thetranslator-creditsfor your language. The translator credits are shown in Peek's About dialog.

Peek Copyright © 2015-2024 by Philipp Wolferph.wolfer@gmail.com

Peek is free software: you can redistribute it and/or modifyit under the terms of the GNU General Public License as published bythe Free Software Foundation, either version 3 of the License, or(at your option) any later version.

Peek is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See theGNU General Public License for more details.

You should have received a copy of the GNU General Public Licensealong with Peek. If not, seehttps://www.gnu.org/licenses/.