MaChap is a simple desktop video chapter editor designed to detect and manage chapters based on black frames, using FFmpeg as the underlying engine.
This is a learning project, and I'm still figuring things out as I go. The code isn't perfect, and I'm sure there's a better way to do a lot of what I've written. Feedback, suggestions, and improvements are welcome.
- Scans video files and identifies likely chapter locations based on black segments.
- Adjustable detection settings: minimum black duration, pixel ratio, luminance threshold.
- Displays video alongside a visual chapter timeline.
- Chapter list shows all detected and manual chapters with timestamps.
- Allows manual creation and deletion of chapters via the timeline or buttons.
- Batch file import for scanning, reviewing, and exporting chapters across multiple files.
- (WIP) Export support for
.mp4,.mkv, and.txtchapter formats (MKVmerge-compatible).
- Click Load Video.
- Use default detection settings or open Scan Settings to adjust parameters.
- Click Detect Black Frames. (This may take a few seconds to a few minutes depending on the file.)
- Use the chapter list on the right to jump to chapters. Press
Deleteor click Remove Chapter to remove unwanted chapters. - Navigate frames using the arrow keys or frame buttons.
- Add chapters manually by clicking Add Chapter Here or pressing the
Akey. - (WIP) Click Export File or Add to Export Queue to prepare a file for output with chapters.
- Click Open Queue Manager.
- Click Load Files and select multiple video files.
- Adjust scan settings if needed.
- Click Scan All Files. A loading dialog will appear.
- After scanning, double-click a file to open it in the main editor with its chapters preloaded.
- Make any manual adjustments as needed.
- (WIP) Click Export File or Add to Export Queue to prepare a file for output with chapters.
- Minimum Black Seconds: The minimum duration for a black frame sequence to be considered a chapter boundary.
- Black Pixel Ratio: How much of the frame must be dark to count as a black frame.
- Black Pixel Threshold: How dark a pixel has to be to qualify as “black.”
- Scan Time Windows: Time ranges (formatted as
HH:MM:SS:HH:MM:SS, comma-separated) to restrict detection to specific portions of the video. - Export Format: Choose between
.mp4,.mkv, or.txt (MKVmerge).
- Spacebar — Play/Pause
- Left Arrow — Step one frame backward
- Right Arrow — Step one frame forward
- M — Mute/Unmute
- A — Add chapter at current time
- Delete — Remove selected chapter in the list
- Export functionality:
- Embed chapters directly into
.mp4or.mkv - Convert and re-encode AVI/WMV files to selected format with settings to maintain visual quality and similar file size
- Embed chapters directly into
- Export queue processing
- Settings persistence across sessions
- Video Splitter Mode: Automatically split video into segments based on chapter markers. Useful for cutting out commercial blocks.
- Profiles: Save and switch between different scan/export presets.
- Keyboard shortcuts remain active even when focus is on other windows (e.g. settings).
- Python 3.10+
- FFmpeg installed and accessible via command line
- PySide6 (Qt for Python)
- Install dependencies:
pip install -r requirements.txt
- Launch the app:
python3 main.py
This project was built as a way to learn desktop app development and work with video tools. I'm learning as I go and welcome any kind of constructive feedback. If you have ideas, fixes, or suggestions, feel free to open an issue or a pull request.
– trebory6
The chapter detection logic used in this project is derived from mkchap, and this tool is designed with use alongside ErsatzTV to inject commercials at chapter points.
Thanks to @jasongdove for both projects and for his work making these kinds of tools possible.