Media workflow application for browsing, comparing, analyzing, and transforming visual files at scale. Combines embedding-driven search/classification with batch file actions, format conversion, and tool integrations for practical library curation.
Clone this repository and ensure Python 3 and the required packages are installed from requirements.txt. Optionally, run pip install -r requirements-optional.txt for platform-specific extras (e.g. keychain integration, EXIF tools). Note: some dependencies in requirements.txt (e.g. torch) may need to be installed from the provider’s site (e.g. pytorch.org) for GPU support specific to your system.
Run app_qt.py to start the PySide6 (Qt) UI. For more details, see USAGE.md.
The UI can be used as a media file browser. The following features are available that your OS default photo viewer application may not have:
View Features
- Auto-resize images to fill the screen
- Auto-refresh directory files
- Slideshow (customizable)
- Optionally play and compare video files and other media - typically will use the first image found for the comparison.
- Go to file by string search or by index (1-based)
- Mark groups of files to enable quick transitions and comparisons
- Mark favorite media and access them quickly via the Favorites window
- Move, copy, and delete marked file groups without overwriting system clipboard
- Revert and modify historical file action changes
- Quickly find directories via recent directory picker window
- Stores session info about seen directories (useful for directories with many media files)
- Can be set up to run on user-defined list of files in place of a directory
- sd-runner integration for image generation
- refacdir intgration for file operations
- Find related images and prompts from embedded Stable Diffusion workflows
- Sort files by related images and prompts
- View raw image metadata
- Content filtering of images and videos based on their text encoding similarity (automatically hide, move to dir, delete etc)
- Search and install image classifier models from Hugging Face directly in-app
- Create PDFs from marked files with customizable quality and compression options
- Password protection system for sensitive operations with configurable session timeouts
- Extract text using OCR from images
- Set custom title bar colors for specific directories
- In-window media playback controls (timeline and play/pause) for video and animated GIF files
- Apply custom aspect ratio settings to image display
- Capture screenshots from time-based media with a keyboard shortcut and configurable save directory
- diff-pdf integration for creating visual diffs from two files (including non-PDF)
For image files, zoom and drag functionality is available in both browsing mode as well as when viewing grouped media after a comparison has been run.
Note that depending on your configuration, videos, GIFs, PDFs, SVGs, and HTML may be disabled; use the file-type configuration window (Ctrl+J) or edit image_types / video_types in config. Default extensions and optional dependencies (HEIC, AVIF, VLC, etc.) are listed in USAGE.md.
You can mark any media file (image, video, etc.) as a favorite and access all favorites quickly using the Favorites window (Ctrl+F). This is especially useful when working with directories containing many files, as it allows you to keep persistent preferred items easily accessible for future searches and actions.
The Directory Notes feature allows you to maintain persistent notes and marked files for individual directories. You can add notes to specific files, mark files for later reference, and export or import your notes and marked files as text or JSON files. This is separate from the runtime marked files used for moving files, making it useful for long-term organization and documentation of your media collections.
Group large media sets by visual similarity using both embedding and color-comparison modes, or search by similarity to an input image or text embedding, then refine analysis with classifier models (H5/PyTorch) and rule-driven actions. For fine-point document/image review workflows, marked files can also be compared with diff-pdf output to highlight precise differences. Multiple embedding models are supported:
View Embedding Models
- CLIP (default): 512D embeddings, high zero-shot performance - SigLIP: 768D or 1024D embeddings, excellent retrieval performance - ALIGN: 640D embeddings, high accuracy for retrieval - FLAVA: 768D embeddings, good for complex reasoning - X-VLM: 256D embeddings, efficient for region-text tasks - requires local copy of [X-VLM](https://github.com/zengyan-97/X-VLM) - LAION: 1024D embeddings, high-quality visual-language understanding - based on CLIP ViT-H/14 architectureEach model offers different tradeoffs between accuracy, speed, and resource usage. The default CLIP model provides a good balance for most use cases.
The application includes a flexible prevalidation system that can automatically process media before they're shown to the user, as well as classifier actions that can be run ad-hoc on selected directories. Both are managed through a unified window. This is useful for:
View Use Cases
- Automatically skipping, hiding, blurring or deleting unwanted media
- Moving or copying media to specific directories based on content
- Filtering media using CLIP embeddings, embedding prototypes, H5 image classifiers, PyTorch image classifiers, prompt string detection
- Setting up rules that apply to specific directories
- Running one-off classification actions on selected directories
Prevalidation rules and classifier actions can be configured with:
View Rule Options
- Multiple validation types enabled simultaneously (OR logic - any type can trigger the action)
- Positive and negative text prompts shared across embedding and prompt validation
- Embedding prototypes: Create prototype embeddings from directories of sample images, then compare images against these prototypes. Supports both positive and negative prototypes with configurable weighting (lambda) for fine-tuning similarity matching
- Custom thresholds for embedding-based matching
- Different actions (skip, hide, notify, move, copy, delete, add mark, blur)
- Directory-specific rules
- H5 model-based classification rules
- PyTorch model-based classification rules (supports .pth, .pt, .safetensors, and .bin formats)
Prevalidations automatically run on media as you browse, while classifier actions can be executed manually on selected media directories when needed. These features are particularly useful for maintaining clean media collections and automating local content filtering, but can be disabled at any time if desired. The classifier action management window allows copying between types of classifier action to reduce the burden of action configuration.
Classifier models can be added manually or discovered through the in-app model manager, which supports searching Hugging Face repositories, viewing model cards, and installing selected model files.
You can find example classifier models that are known to work here:
- Coherence Detection - A PyTorch ResNet-34 model for classifying AI-generated images into coherent, incoherent, or semi-incoherent categories
- NSFW Model - An H5 classifier model for filtering out some types of NSFW content
NOTE - It is not currently possible to undo or modify a delete action, however unless the delete folder is explicitly set to null in the config it is likely the deleted items will be saved in a trash folder before being fully removed.
The face similarity measure used in comparisons is very crude and only compares the number of faces in each image, so it is off by default. At a future time more complex face comparison logic may be added, but for now the embedding comparison is helpful in matching faces.