FlowVision for macOS: A Waterfall Image Viewer with Finder-Like Navigation

Why FlowVision Exists for Local Media Browsing

FlowVision addresses a specific problem: viewing large collections of images and videos stored in ordinary macOS folders without moving them into a separate media library. Its intended users are people who already keep photos, screenshots, or videos in Finder-like directory structures and want to inspect them directly. The application is not described as a photo-management suite with catalogs, tagging, editing, or synchronization. Instead, the repository presents it as a waterfall-style viewer with file management similar to Finder.

That positioning explains why folder navigation is central to the project. FlowVision can move to the previous or next folder containing images or videos, move to the parent directory, return to the previous directory, and search for another image folder at the same level. The recursive mode extends browsing beyond one directory. This design is useful for collections assembled in batches, such as exported screenshots, downloaded reference images, or media stored in a deep project directory.

The README also says that FlowVision requires no Internet connection. That makes its local-first behavior a central part of the product rather than a minor implementation detail. It does not mean that installation, updates, or every supporting dependency are offline operations, so users who need a completely self-contained deployment should still examine the build process and package sources.

How FlowVision Organizes the Viewing Experience

The visible design combines an adaptive layout, light and dark appearance, and media browsing that follows the directory tree. FlowVision distinguishes between a waterfall-style browser and an image view. In the browser, its file-management behavior is compared with Finder. In the image view, the application provides direct manipulation through mouse gestures and limited keyboard shortcuts.

Image viewing begins with a double-click that opens or closes the image. Holding the right or left mouse button while using the scroll wheel changes zoom. Holding the middle mouse button and dragging moves the window. A long press with the left mouse button switches to 100% zoom, while a long press with the right mouse button fits the image to the view. The README also states that scaling is designed to reduce moiré and related visual artifacts, which matters when an image is enlarged beyond its native resolution.

Media support extends beyond still images. The project documents video playback and HDR display support. The build instructions include ffmpeg-kit as a library, which is the stated media-processing dependency for the project, although the repository does not provide a detailed format matrix. The feature list also mentions performance optimizations for directories containing many images, but it does not describe the implementation technique or a measured limit.

Navigation is deliberately modal. Right-click gestures and keyboard keys map to directory actions rather than conventional image-editing commands. The README defines W, A, D, and S as equivalents for upward, left, right, and downward gestures. This keeps navigation available without requiring a separate command palette, but it also means that the application may feel unfamiliar to users who expect standard media-viewer shortcuts.

Installing FlowVision and Opening the First Folder

FlowVision documents macOS 11.0 or later as the minimum system requirement. The documented package-manager installation is Homebrew-based, and the project provides separate commands for the initial installation and later upgrades. These instructions install the released application rather than compiling the Xcode project.

Use the following command to install FlowVision with Homebrew:

brew install flowvision

After installation, launch FlowVision from macOS and open a folder containing images or videos. The README does not document a command-line interface for selecting the first directory, so it does not provide a reproducible terminal command for opening a particular folder. The first usable workflow is therefore the graphical one: launch the application, use its file browser to select a directory, and double-click an image to enter the image view.

For an existing installation, the documented upgrade path is:

brew update
brew upgrade flowvision

The README does not describe automatic update behavior, rollback steps, or how Homebrew identifies the package owner. Those details should be checked in the local Homebrew installation before relying on the upgrade command in a managed environment.

Building FlowVision from Source with Xcode

Source builds have a higher setup cost because the README requires Xcode 15.2 or later and lists separate libraries. The project names ffmpeg-kit, BTree, and Settings. The documented build procedure also requires the ffmpeg-kit framework to exist in a particular directory structure before the Xcode project is opened.

The instructions say that ffmpeg-kit must be built to binary first, or that a pre-built archive can be downloaded. Because the upstream project is described in the README as discontinued, the prebuilt binaries were removed for project and copyright reasons. The README links a backup archive and gives a command for removing the macOS quarantine attribute:

sudo xattr -rd com.apple.quarantine ./ffmpeg-kit-full-gpl-6.0-macos-xcframework

That command should be treated as a build-preparation step only. It requires administrator privileges and changes an extended attribute on the named framework. The README then specifies a directory layout containing `FlowVision.xcodeproj`, the FlowVision sources, `ffmpeg-kit-build/bundle-apple-xcframework-macos/ffmpegkit.xcframework`, and the BTree and Settings packages. Open `FlowVision.xcodeproj` in Xcode, choose `Product` -> `Build For` -> `Profiling`, then use `Product` -> `Show Build Folder in Finder` to locate the application.

The resulting app is documented at `Products/Release/FlowVision.app`. The source-build instructions do not explain dependency version selection beyond the framework archive name and Xcode requirement, nor do they provide automated project setup.

Navigation Controls and Media Constraints

FlowVision offers two navigation systems that target directory movement. Right-click gestures can switch to the next or previous folder containing images or videos, move to the parent directory, return to the previous directory, find the next folder with images at the same level, or close the current tab or window. The keyboard mappings cover four of these actions: `W` moves up, `A` moves left, `D` moves right, and `S` moves down.

This model is efficient for a fixed directory hierarchy, but it has limits. The README does not define behavior for empty folders, unreadable folders, broken symlinks, network-mounted directories, or mixed trees containing both images and videos without playable media. It also does not document a search interface for finding a file by name. Users with collections spread across many locations may find the recursive mode useful, but they may still need Finder for initial organization.

The documented zoom and window gestures are mouse-centric. The README does not say whether equivalent touch gestures exist for trackpads, nor does it list keyboard shortcuts for zoom, fit-to-view, or window movement. It also does not document video controls, supported codecs, subtitle support, or playback failure messages. Those omissions make codec and input-device testing important before adoption.

The GPL-3.0 license is also relevant to distribution. The README points to the repository's `LICENSE` file for the full terms. This review does not interpret the license or provide legal advice, but anyone distributing a modified build should review that file and any obligations it creates.

FlowVision Compared with Finder Preview and Browser-Based Galleries

The closest documented alternative is macOS Finder-style previewing, since FlowVision itself describes its file management as similar to Finder. The practical difference is the viewing model. Finder is the system file manager, while FlowVision is a dedicated media surface with waterfall browsing, recursive mode, image scaling controls, mouse gestures, video playback, and HDR support. A user who mainly needs to open one image or inspect a handful of files may already have enough functionality in Finder. A user who spends time moving through nested directories and switching between media folders is the more direct audience for FlowVision.

A browser-based gallery is a different approach because it requires a web interface and usually a page or application loaded in a browser. FlowVision's README explicitly states that it needs no Internet connection, which favors local directories and removes the need for a hosted gallery service. It does not provide the browser model, URL sharing, or web deployment workflow, so it should not be treated as a replacement for a web-based viewer.

The difference matters when comparing maintenance. Finder is part of macOS, while FlowVision is a separate GPL-3.0 application with its own release and build process. FlowVision can offer a focused media interaction model, but users accept responsibility for compatibility, updates, and source-build dependencies.

FlowVision Release Status and Upgrade Surface

The repository is not archived, and its recorded last push was on 2026-10-14. The listed releases include FlowVision 1.7.6 on 2026-09-08, 1.7.5 on 2026-07-22, and 1.7.4 on 2026-06-08. That release history gives users identifiable versions to compare, but the repository material does not provide release notes describing individual changes, compatibility fixes, or migration requirements.

For package users, Homebrew provides the documented upgrade path. For source users, the README points to Xcode 15.2 or later and a dependency layout that includes ffmpeg-kit, BTree, and Settings. The ffmpeg-kit situation is the clearest upgrade constraint because the README states that the upstream prebuilt binaries were removed and provides a separate backup archive. A developer should therefore expect build-environment work when dependencies change.

The project is licensed under GPL-3.0. The README describes FlowVision as open source and links to the `LICENSE` file. Users who only install the package should distinguish personal use from redistribution or modification, while organizations embedding or modifying the application need to review the license text themselves.

Editorial conclusion

Adopt FlowVision if your priority is a local-first macOS viewer with waterfall browsing, recursive folders, video playback, and mouse-driven navigation. Do not choose it if you need documented Windows or Linux support, cross-device access, or a simple source build without resolving the ffmpeg-kit dependency. Before adoption, verify the Homebrew package on your macOS version, test your folder structure and media formats, and review the GPL-3.0 obligations if you plan to modify or redistribute the application.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. netdcy/FlowVision on GitHub
3. Project website
4. README
5. Releases