📖 Table of Contents

1. 🔹 About The Project
   • 🔹 Built With
2. 🔹 Getting Started
   • 🔹 Prerequisites
   • 🔹 Installation
3. 🔹 Usage
4. 🔹 Roadmap
5. 🔹 Contributing
6. 🔹 License
7. 🔹 Contact
8. 🔹 Acknowledgments

🎬 About The Project

"Creating clean, visually appealing demo screenshots for command-line tutorials can often be a tedious hassle—working with asciinema and ffmpeg involves a convoluted workflow. In reality, however, simply feeding it an API will resolve all such issues."

termgif is a cross-platform lightweight terminal GIF recorder for Windows, macOS and Linux. It captures live terminal command execution via pixel recording and exports directly to an animated GIF.

The goal is simple: create clean, shareable command-line demo GIFs with minimal dependencies.

Main flow:

1. 🎥 Record: Launch target terminal commands, capture live screen frames (platform-aware window/region capture)
2. 🔄 Stream: Continuously collect pixel frames while the command runs
3. 🧩 Generate: Encode frames and export a final animated GIF on Ctrl+C

🔝back to top

📸 Screenshot

🛠️ Built With

• 
• 
• 
• 

🔝back to top

🚀 Getting Started

This is an example of how you may give instructions on setting up your project locally. To get a local copy up and running follow these simple example steps.

✅ Prerequisites

This is an example of how to list things you need to use the software and how to install them.

• Hatch (if exists)

  # print all dependencies
  hatch dep show
  # print dependencies on group dep
  hatch dep show dev
  

See pyproject.toml for complete content.

📦 Installation

Install with PIP:

# Don't use termgif, it's registered; use term2gif instead.
pip install term2gif

🔝back to top

💡 Usage

import os
import subprocess as sp

import termgif

GIF_PATH: str = f"{os.path.dirname(__file__)}/dist.gif"
termgif.make_gif(
    'cmd /c "echo hello world!"', GIF_PATH # Specify the command to execute.
)
_ = sp.run([GIF_PATH], shell=True)  # Open it with the default program.

For more examples, please refer to the Documentation or Examples

🔝back to top

🗺️ Roadmap

• v0.1.0: Basic recording for Windows
• v0.2.0:
  • Support for macOS and Linux
  • Support for recording live inputting text on console (stdin)
  • Support recording live console (with echo and color)

See the open issues for a full list of proposed features (and known issues).

🔝back to top

🤝 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

🔝back to top

🌟 Top contributors:

📃 License

Distributed under the project_license. See LICENSE for more information.

🔝back to top

📬 Contact

Nicola Grey - popxh@outlook.com

Project Link: https://github.com/FishgameStudio/termgif

🔝back to top

🙏 Acknowledgments

• Best-README-Template
• Pillow
• PythonMSS
• PyGetWindow

🔝back to top