161 lines
5.3 KiB
Markdown
161 lines
5.3 KiB
Markdown
# Video Montage Linker
|
|
|
|
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
|
|
|
|
### Source Folder Management
|
|
- Add multiple source folders to merge images from different locations
|
|
- 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)
|
|
|
|
### Cross-Dissolve Transitions
|
|
Smooth blending between folder boundaries with four blend methods:
|
|
|
|
| Method | Description | Quality | Speed |
|
|
|--------|-------------|---------|-------|
|
|
| **Cross-Dissolve** | Simple alpha blend | Good | Fastest |
|
|
| **Optical Flow** | Motion-compensated blend using OpenCV Farneback | Better | Medium |
|
|
| **RIFE (ncnn)** | Neural network interpolation via rife-ncnn-vulkan | Best | Fast (GPU) |
|
|
| **RIFE (Practical)** | PyTorch-based Practical-RIFE (v4.25/v4.26) | Best | Medium (GPU) |
|
|
|
|
- **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
|
|
- **Practical-RIFE models**: Auto-downloads from Google Drive on first use
|
|
|
|
### 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
|
|
|
|
### Requirements
|
|
- Python 3.10+
|
|
- PyQt6
|
|
- Pillow
|
|
- NumPy
|
|
- OpenCV (optional, for Optical Flow)
|
|
|
|
```bash
|
|
pip install PyQt6 Pillow numpy opencv-python
|
|
```
|
|
|
|
**Note:** Practical-RIFE creates its own isolated venv with PyTorch. The `gdown` package is installed automatically for downloading models from Google Drive.
|
|
|
|
### RIFE ncnn (Optional)
|
|
For AI-powered frame interpolation using Vulkan GPU acceleration:
|
|
- Select **RIFE (ncnn)** as the blend method
|
|
- Click **Download** to auto-fetch [rife-ncnn-vulkan](https://github.com/nihui/rife-ncnn-vulkan)
|
|
- Or specify a custom binary path
|
|
- Models: rife-v4.6, rife-v4.15-lite, etc.
|
|
|
|
### Practical-RIFE (Optional)
|
|
For PyTorch-based frame interpolation with latest models:
|
|
- Select **RIFE (Practical)** as the blend method
|
|
- Click **Setup PyTorch** to create an isolated venv with PyTorch (~2GB)
|
|
- Models auto-download from Google Drive on first use
|
|
- Available models: v4.26, v4.25, v4.22, v4.20, v4.18, v4.15
|
|
- Optional ensemble mode for higher quality (slower)
|
|
|
|
The venv is stored at `~/.cache/video-montage-linker/venv-rife/`
|
|
|
|
## Usage
|
|
|
|
### GUI Mode
|
|
|
|
```bash
|
|
python symlink.py # Launch GUI (default)
|
|
python symlink.py --gui # Explicit GUI launch
|
|
```
|
|
|
|
**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 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
|
|
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, Practical-RIFE env
|
|
│ ├── rife_worker.py # Practical-RIFE inference (runs in isolated venv)
|
|
│ └── 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)
|
|
|
|
```bash
|
|
# Make executable
|
|
chmod +x symlink.py
|
|
|
|
# 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 with cross-dissolve transitions
|
|
Exec=/full/path/to/symlink.py
|
|
Icon=emblem-symbolic-link
|
|
Terminal=false
|
|
Type=Application
|
|
Categories=Utility;Graphics;AudioVideo;
|
|
EOF
|
|
|
|
update-desktop-database ~/.local/share/applications/
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|