From 6bfbefb058b0c282e263bd8d278c3545a0647d4d Mon Sep 17 00:00:00 2001 From: Ethanfel Date: Tue, 3 Feb 2026 18:51:50 +0100 Subject: [PATCH] Update README with comprehensive feature documentation - Document cross-dissolve transitions and blend methods - Add RIFE auto-download instructions - Document per-folder trim and per-transition overlap - Add file structure diagram - Update installation requirements - Expand supported formats list Co-Authored-By: Claude Opus 4.5 --- README.md | 134 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 89 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 22b0132..e5f9fe2 100644 --- a/README.md +++ b/README.md @@ -1,97 +1,141 @@ # Video Montage Linker -A PyQt6 application to create sequenced symlinks for image files. Useful for preparing image sequences for video editing or montage creation. +A PyQt6 application for creating sequenced symlinks from image folders with advanced cross-dissolve transitions. Perfect for preparing image sequences for video editing, time-lapse assembly, or montage creation. ## Features -### Multiple Source Folders +### Source Folder Management - Add multiple source folders to merge images from different locations -- Files are ordered by folder (first added = first in sequence), then alphabetically within each folder -- Drag & drop folders directly onto the window to add them -- Multi-select support for removing folders +- Drag & drop folders directly onto the window +- Alternating folder types: odd positions = **Main**, even positions = **Transition** +- Override folder types via right-click context menu +- Reorder folders with up/down buttons +- Per-folder trim settings (exclude frames from start/end) -### File Management -- Two-column view showing filename and source path -- Drag & drop to reorder files in the sequence -- Multi-select files (Ctrl+click, Shift+click) -- Remove files with Delete key or "Remove Files" button -- Refresh to rescan source folders +### Cross-Dissolve Transitions +Smooth blending between folder boundaries with three blend methods: -### Symlink Creation -- Creates numbered symlinks (`seq_0000.png`, `seq_0001.png`, etc.) -- Uses relative paths for portability -- Automatically cleans up old `seq_*` links before creating new ones +| Method | Description | Quality | Speed | +|--------|-------------|---------|-------| +| **Cross-Dissolve** | Simple alpha blend | Good | Fastest | +| **Optical Flow** | Motion-compensated blend using OpenCV Farneback | Better | Medium | +| **RIFE (AI)** | Neural network frame interpolation | Best | Fast (GPU) | -### Session Tracking -- SQLite database tracks all symlink sessions -- Located at `~/.config/video-montage-linker/symlinks.db` -- List past sessions and clean up by destination +- **Asymmetric overlap**: Set different frame counts for each side of a transition +- **Blend curves**: Linear, Ease In, Ease Out, Ease In/Out +- **Output formats**: PNG, JPEG (with quality), WebP (lossless with method setting) +- **RIFE auto-download**: Automatically downloads rife-ncnn-vulkan binary -### Supported Formats -- PNG, WEBP, JPG, JPEG +### Preview +- **Video Preview**: Play video files from source folders +- **Image Sequence Preview**: Browse frames with zoom (scroll wheel) and pan (drag) +- **Sequence Table**: 2-column view showing Main/Transition frame pairing +- **Trim Slider**: Visual frame range selection per folder + +### Dual Export Destinations +- **Sequence destination**: Regular symlinks only +- **Transition destination**: Symlinks + blended transition frames + +### Session Persistence +- SQLite database tracks all sessions and settings +- Resume previous session by selecting the same destination folder +- Restores: source folders, trim settings, folder types, transition settings, per-transition overlaps ## Installation -Requires Python 3 and PyQt6: +### Requirements +- Python 3.10+ +- PyQt6 +- Pillow +- NumPy +- OpenCV (optional, for Optical Flow) ```bash -pip install PyQt6 +pip install PyQt6 Pillow numpy opencv-python ``` +### RIFE (Optional) +For AI-powered frame interpolation, the app can auto-download [rife-ncnn-vulkan](https://github.com/nihui/rife-ncnn-vulkan) or you can install it manually: +- Select **RIFE (AI)** as the blend method +- Click **Download** to fetch the latest release +- Or specify a custom binary path + ## Usage ### GUI Mode ```bash -# Launch the graphical interface -python symlink.py -python symlink.py --gui +python symlink.py # Launch GUI (default) +python symlink.py --gui # Explicit GUI launch ``` -1. Click "Add Folder" or drag & drop folders to add source directories -2. Reorder files by dragging them in the list -3. Remove unwanted files (select + Delete key) -4. Select destination folder -5. Click "Generate Virtual Sequence" +**Workflow:** +1. Add source folders (drag & drop or click "Add Folder") +2. Adjust trim settings per folder if needed (right-click or use trim slider) +3. Set destination folder(s) +4. Enable transitions and configure blend method/settings +5. Click **Export Sequence** or **Export with Transitions** ### CLI Mode ```bash -# Create symlinks from a single source -python symlink.py --src /path/to/images --dst /path/to/dest - -# Merge multiple source folders -python symlink.py --src /folder1 --src /folder2 --dst /path/to/dest +# Create symlinks from source folders +python symlink.py --src /path/to/folder1 --src /path/to/folder2 --dst /path/to/dest # List all tracked sessions python symlink.py --list -# Clean up symlinks and remove session record +# Clean up symlinks and remove session python symlink.py --clean /path/to/dest ``` +## File Structure + +``` +video-montage-linker/ +├── symlink.py # Entry point, CLI +├── config.py # Constants, paths +├── core/ +│ ├── models.py # Enums, dataclasses +│ ├── database.py # SQLite session management +│ ├── blender.py # Image blending, RIFE downloader +│ └── manager.py # Symlink operations +└── ui/ + ├── widgets.py # TrimSlider, custom widgets + └── main_window.py # Main application window +``` + +## Supported Formats + +**Images:** PNG, WEBP, JPG, JPEG, TIFF, BMP, EXR + +**Videos (preview only):** MP4, MOV, AVI, MKV, WEBM + +## Database + +Session data stored at: `~/.config/video-montage-linker/symlinks.db` + ## System Installation (Linux) -To add as a system application: - ```bash -# Make executable and add to PATH +# Make executable chmod +x symlink.py -ln -s /path/to/symlink.py ~/.local/bin/video-montage-linker + +# Add to PATH +ln -s /full/path/to/symlink.py ~/.local/bin/video-montage-linker # Create desktop entry cat > ~/.local/share/applications/video-montage-linker.desktop << 'EOF' [Desktop Entry] Name=Video Montage Linker -Comment=Create sequenced symlinks for image files -Exec=/path/to/symlink.py +Comment=Create sequenced symlinks with cross-dissolve transitions +Exec=/full/path/to/symlink.py Icon=emblem-symbolic-link Terminal=false Type=Application -Categories=Utility;Graphics; +Categories=Utility;Graphics;AudioVideo; EOF -# Update desktop database update-desktop-database ~/.local/share/applications/ ```