If you've ever tried adding a GIF or animated WebP of a screen recording to your project's README, you know how annoying it can be. You just want to show people how your product works without spending 20 minutes editing a video, but a few friction points always pop up.
A good README is important. Seeing an app in action builds way more trust than a wall of text. So I built GiffyPy, a lightweight video editor specifically designed to make editing screen recordings for project READMEs fast and effortless.
Here are the main problems it solves (or click here to skip directly to the GitHub repository).
Removing the taskbar and black borders
When recording your screen with OBS Studio, even if you use Window Capture, you can end up with black bars or the taskbar stuck in the recording.
Cropping it cleanly in a regular video editor can involve trial and error with resolutions. GiffyPy lets you drag and resize a crop rectangle directly over the video preview, just like cropping an image.
It also includes rule-of-thirds guides to help position the crop.
A proper multi-clip timeline
Previously, I mainly needed to trim the beginning and end of a recording. But sometimes you want to remove a few sections in the middle or rearrange parts of a demo.
GiffyPy now has a non-destructive, multi-clip timeline that lets you:
- Split clips at the current playhead position using
S. - Trim the start and end of clips by dragging their edges.
- Reorder segments using drag and drop.
- Delete unwanted segments.
- Undo the last edit using
Ctrl + Z.
The original video stays untouched, so you can experiment with the edit without permanently modifying the source file.
Instant scrubbing without loading screens
I usually only need to make a few quick edits, so waiting for a heavy editor to load or dealing with sluggish timeline scrubbing feels unnecessary.
GiffyPy opens in under a second. During import, it generates a low-resolution image sequence so the preview can update quickly while you scrub.
While dragging the playhead, it displays these lightweight images. Once you release the mouse, it switches back to the full-resolution frame.
It can also generate background proxy files for video codecs that Qt cannot play natively, helping expand the range of videos you can edit.
Optimizing GIFs and videos
A screen recording doesn't need to be huge just to demonstrate a feature in a README.
GiffyPy lets you customize the export using three main settings:
- Framerate: Adjust the output from 0.5 to 60 FPS.
- Resolution: Scale the output dimensions as a percentage.
- Quality: Adjust the output quality to balance file size and visual clarity.
For GIF exports, it also supports automatic palette generation and dithering controls, giving you more control over the final result.
The goal is to keep demos lightweight while making sure they still look good.
Faster exports and four ways to save
Exporting shouldn't interrupt your workflow with a file dialog every time.
GiffyPy now provides four separate save options:
- Overwrite Existing File: Replace the source file's existing output, with a confirmation prompt first.
-
Save a Numbered Copy: Save a new version next to the source, using a name like
name (edited 1). - Save To…: Choose the output location and filename yourself.
- Copy to Clipboard: Export and copy the result directly to your clipboard.
The last option is particularly useful for README demos. You can copy an animated GIF or WebP and paste it directly into places that support image pasting, such as GitHub or DEV.to's editors.
No need to export to a folder, find the file, and manually attach it afterward.
Note: Clipboard export is currently available for GIF and WebP only.
Multiple export formats
Although the main goal is creating lightweight animations for project READMEs, GiffyPy isn't limited to GIFs.
It currently supports exporting to:
- Animated WebP
- GIF
- MP4
- WebM
- MOV
- MKV
So you can use it for ordinary video exports too, not just README demos.
Timeline navigation and keyboard shortcuts
The timeline also has a few navigation controls to make editing more comfortable, especially for longer recordings.
- Scroll to move through the timeline.
-
Zoom using
Ctrl + Scrollor a two-finger trackpad gesture. - Pan using middle-click and drag or a two-finger trackpad gesture.
- Move frame by frame using the left and right arrow keys.
There are also shortcuts for common actions, including splitting clips, deleting segments, undoing edits, and fitting the timeline to the view.
The idea is to keep the workflow fast without forcing you to reach for the mouse for every operation.
A custom app icon
Not a big feature, but a custom icon in the taskbar matters to me!
It's a small detail, but it makes the app feel more complete.
How it was made
GiffyPy is built with Python and PySide6, with FFmpeg handling video processing and export.
The source code is available on GitHub:
Requirements
FFmpeg needs to be installed and available in your system's PATH.
On Windows, you can install it from the command prompt using:
winget install Gyan.FFmpeg
Building a standalone Windows executable
GiffyPy also includes a packaging script for building a standalone Windows executable using PyInstaller.
From the project directory, run:
package.bat
The script packages the app using main.py and includes the custom icon.ico.
What's next?
GiffyPy already covers most of my personal needs for creating screen recordings for READMEs, but there's always room for improvement.
I'd love to hear what you think:
- What features would make this kind of editor more useful to you?
- Are there any annoying steps in your current screen-recording workflow that could be automated?
- Would you use a lightweight editor specifically designed for creating README demos?
If you work on open-source projects, I'd especially love to hear how you currently create and optimize your demo GIFs.
@ssapable created a cartoon for GiffyPy using a tool he built called ScriptToon. Click here to view it; it's really good!
Give GiffyPy a try, check out the GitHub repository, and let me know what you think!
Top comments (9)
"Waiting for the editor to load takes longer than the edit itself" is exactly why I never add GIFs to READMEs, and the low-res-while-scrubbing / full-res-on-release trick is a nicer fix than most "fast" editors manage. I turned the post into a 69-second hand-drawn cartoon: the black bars and the taskbar, the crop box, the six formats, and your open PyInstaller question, left open. No strings, yours to use or ignore, on a plain page with no sign-up:
ssap-pa.github.io/scripttoon-samples/
If any detail is off, say which shot and I'll re-render it. On the freeze: is it a onefile build? With PySide6, a onefile exe unpacks the Qt plugins (platforms, multimedia, imageformats) into a temp folder on first use, and the first file-open often lands exactly on that unpack. A onedir build, or warming the plugins at startup, is the usual way to find out whether that's it.
Wow! 😮 How did you do that???! It's a onedir build. But the freeze happens after the editor has been loaded and when we try to load a video file in that editor. It's really confusing why that happens only on the packaged version. But how did you make that video? Is it something that you built? Thanks a lot! Really appreciate your effort 🥹 The only off thing that I was able to catch was the pronunciation (in the video: giffy-P-Y, actual: giffy-pie). But it's already really good!
Fixed: the narration now says "Giffy Pie". The file on the page is replaced (same link, give GitHub Pages a minute). Sorry for the P-Y, the voice reads unknown names letter by letter and I didn't catch it.
How it's made: it's a small tool I built called ScriptToon. The storyboard is a Markdown file (narration, action, camera per shot), each shot is a Python function that draws on a hand-drawn background with tags and two cut-out characters, the narration is synthetic, and the characters were generated once from a character sheet. Your post was the whole input; nothing in the video came from anywhere else.
On the freeze: onedir rules out the unpack, so scratch that. Since it happens exactly when a file is loaded, my next suspect would be the FFmpeg subprocess you spawn for the low-res sequence: in a windowed (no console) PyInstaller build, a child process started without stdin/stdout/stderr redirected can block until its pipes are consumed, and it looks like a short freeze in the UI. Passing stdin=DEVNULL, stdout/stderr=PIPE (and reading them) plus CREATE_NO_WINDOW on Windows is the usual fix. If it's not that, the plain-script vs packaged difference points at something resolved by path: ffmpeg found through PATH in one case and not the other.
This fast??? 😱😱😱
But when I checked ssap-pa.github.io/scripttoon-samples/, it still says "giffy-p-y". At 0:18. Am I looking in the right place?
You were looking in the right place. You checked about four minutes after I pushed the fix, so the page was most likely still serving the cached file. It says "Giffy Pie" at 0:18 now; a hard reload should pick it up. Thanks for checking it that closely.
Wow! It now correctly says GiffyPy! Good luck with Scriptoon. It's really impressive! 😊
Việc tối ưu dung lượng file GIF/WebP cho README thường là một cực hình vì nếu để file quá nặng sẽ làm chậm tốc độ load trang GitHub. Mình từng mất rất nhiều thời gian để cân bằng giữa chất lượng hình ảnh và dung lượng file sao cho vừa đủ rõ nét mà vẫn nhẹ nhàng. Nếu GiffyPy xử lý được việc cắt tỉa nhanh gọn mà không làm giảm quá nhiều bitrate thì thực sự rất hữu ích cho quy trình làm documentation. Một mẹo nhỏ là sau khi crop xong, mọi người nên kiểm tra thêm độ phân giải thực tế hiển thị trên trình duyệt để tránh việc file trông quá mờ trên màn hình Retina.
Thanks 😊 Glad it helped!