Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Ambrevar/emacs-gif-screencast

[MOVED TO GITLAB] One-frame-per-action GIF recording for optimal quality/size ratio
https://github.com/Ambrevar/emacs-gif-screencast

emacs gif screencast screenshot

Last synced: 2 months ago
JSON representation

[MOVED TO GITLAB] One-frame-per-action GIF recording for optimal quality/size ratio

Awesome Lists containing this project

README 

        
#+TITLE: Emacs GIF Screencast



One-frame-per-action GIF recording for optimal quality/size ratio.



See [[https://github.com/emacs-helm/helm-system-packages][Helm System Packages]] for examples.



* Rationale



Most Emacs screencasts are done by first recording a video, then converting it

to a [[https://en.wikipedia.org/wiki/GIF][GIF]].  It seems like a waste of resources considering the little animation

Emacs features.



Most of the time, one user action equals one visual change.  By exploiting this

fact, this package tailors GIF-screencasting for Emacs and captures one frame

per user action.  It's much more efficient than capturing frames even at a

frequency as low as 10 per second.  You could roughly expect 3 to 10 times

smaller files compared to videos of the same quality.  (Benchmarks are welcome.)



Conversely, should your Emacs demo feature self-animated content (such as output

scrolling in Eshell), no frame will be captured.  A workaround consists in

hammering some no-op key such as ~forward-char~ or ~end-of-line~.



Another neat perk of action-based captures is that it produces /editable/ GIF files:

programs such as [[https://www.lcdf.org/gifsicle/][Gifsicle]] or [[https://www.gimp.org/][The GIMP]] can be used to edit the delays or rearrange frames.



This is particularly useful to fix mistakes in "post-processing", without having

to record the demo all over again.



* Features, pros and cons



- Recordings can be paused and resumed.



- Resulting GIF files are editable, which allows for post-processing / fixing.



- Quality is top notch.



- File-size is optimal.



- The result might feel a tad jittery sometimes.



- It won't render self-animated content such as auto-scrolling, this is

  workable however.



- It should be much lighter on memory and CPU than video recording.



* Implementation



Upon start, it adds ~gid-screencast-capture~ to ~pre-command-hook~ which makes

every command (including those called by key presses) take a screenshot.  On

each screenshot, it records the timestamp.



If paused then resumed, the timestamps are offset by the length of the pause.



When stopped, it compiles the screenshots together into a GIF file using the

timestamps to set the appropriate delays for each frame.



* Setup



You'll need a screenshot program and a GIF converter.  Defaults are:



- ~gif-screencast-program~: [[http://scrot.sourcearchive.com/][scrot]]

- ~gif-screencast-convert-program~: [[https://imagemagick.org/script/convert.php][convert]] (from the ImageMagick suite)

- Optional: ~gif-screencast-optimize-program~: [[https://www.lcdf.org/gifsicle/][Gifsicle]]



You can pass arguments to the screenshot program via ~git-screencast-args~ to

command it to capture only part of the screen, e.g. you can restrict the capture

to the Emacs frame with =scrot='s argument =--focused=



You might want to set some bindings for convenience.



#+BEGIN_SRC emacs-lisp

(with-eval-after-load 'gif-screencast

  (define-key gif-screencast-mode-map (kbd "") 'gif-screencast-toggle-pause)

  (define-key gif-screencast-mode-map (kbd "") 'gif-screencast-stop))

#+END_SRC



Start recording with ~gif-screencast~!



** macOS



macOS requires some additional settings:



#+BEGIN_SRC emacs-lisp

(with-eval-after-load 'gif-screencast

  (setq gif-screencast-args '("-x")) ;; To shut up the shutter sound of `screencapture' (see `gif-screencast-command').

  (setq gif-screencast-cropping-program "mogrify") ;; Optional: Used to crop the capture to the Emacs frame.

  (setq gif-screencast-capture-format "ppm") ;; Optional: Required to crop captured images.

#+END_SRC



[[https://imagemagick.org/script/mogrify.php][mogrify]] is part of the ImageMagick suite.



** Display pressed keys while recording



The [[https://github.com/tarsius/keycast][KeyCast]] package is useful to dispay the pressed keys in the modeline while recording.