GuideFrame is a tool which allows software developers to produce detailed walkthrough videos of their projects using python code. It can be run locally, provided you have the required packages installed, or can be used as a GitHub action.
It uses a selection of open-source software to record a users screen, perform scripted UI interactions and generate a matching voiceover based on a user-defined markdown file. To see GuideFrame in action you can visit the Demos section of the GuideFrame Site.
GuideFrame can be installed in several ways depending on your use case:
pip install guideframeNote: You'll also need to install system dependencies (see below) for GuideFrame to work properly.
For contributors or advanced users who want to modify GuideFrame:
# Clone the repository
git clone https://github.com/chipspeak/GuideFrame.git
cd GuideFrame
# Install with pip in editable mode
pip install -e .For the easiest setup on Linux systems, use the included Justfile automation:
# Install Just first: https://github.com/casey/just
# Then run automated setup
just setup # Install system dependencies
just install-deps # Create virtual environment and install Python dependenciesGuideFrame requires several system packages to function:
For Fedora/RHEL/CentOS:
sudo dnf install -y ffmpeg xorg-x11-server-Xvfb chromium chromedriver python3-venvFor Ubuntu/Debian:
sudo apt-get update
sudo apt-get install -y ffmpeg xvfb chromium-driver chromium-browser python3-venvFor Arch Linux:
sudo pacman -Syu --noconfirm ffmpeg xorg-server-xvfb chromium chromedriver python-virtualenvGuideFrame works excellently as a GitHub Action. Use the GuideFrame Template Repository to get started quickly without dealing with local dependencies.
To verify your installation works:
# Start virtual display (Linux only)
just start-xvfb # or manually: Xvfb :99 -screen 0 1920x1080x24 &
# Run a demo
just run guideframe_demos/tutors_demo/guideframe_tutors_demo.pyFor more detailed installation instructions, visit the official documentation.
If you simply want to get started, a template repository exists to enable users to dive in without the need to navigate local dependencies, python environments etc. Simply clone or fork the repository listed below to have access to a correctly configured template. You can then modify the GuideFrame script and markdown as needed for your purpose. Then you need only enable the GitHub action to begin your first render.
GuideFrame Template Repository
If you wish to view the syntax of GuideFrame through the lense of examples, see the below links.
Tutors Demo - A brief GuideFrame walkthrough using tutors.dev
Magento Demo - A GuideFrame selenium function demo using the Magento test site
GuideFrame Code Walkthrough - An elaborate GuideFrame walkthrough where it works through its own code.
- GuideFrame Code Walkthrough script
- GuideFrame Code Walkthrough markdown
- GuideFrame Code Walkthrough video
ffmpeg- used to capture the virtual displays and combine clips.gTTS- used to generate the voiceover audio.xvfb- used to provide a virtual display server.mutagen- used to parse MP3 length.chromium- to provide a browser for interactions.selenium- the python package for interacting with the browser.
GuideFrame is an open-source project and contributions are greatly encouraged. Open an issue thread or fork the repo and open a pull request if you've got suggestions, fixes etc.
You can customize GuideFrame's behavior with these environment variables:
# Override browser and driver paths if needed
export GUIDEFRAME_BROWSER=/usr/bin/chromium
export GUIDEFRAME_CHROMEDRIVER=/usr/bin/chromedriver
# Override FFmpeg codec (default is libx264)
export GUIDEFRAME_FFMPEG_CODEC=libxvid- Screen capture uses
Xvfb :99withx11grab, which works on both Wayland and X11 systems requirements.txtcontains only Python dependencies; system packages must be installed separately via your distribution's package manager