Getting started
- 01
Open FrameShelf and select Choose Folder… or press ⌘O.
- 02
Choose a folder on your Mac, an external drive, or an available network volume. You can also drag a folder onto the window.
- 03
Wait while the app scans that folder and all its subfolders. Your movies remain in their existing locations.
- 04
Use arrow keys to select, Space to preview, and Enter or a double-click to open a movie. The full guide is available with ⌘?.
// library_basics
Libraries, thumbnails, and tags
Access is remembered
FrameShelf runs in App Sandbox. A secure macOS bookmark lets the last folder reopen after an app restart. Close Folder clears the current selection and its remembered access.
Vision chooses clearer frames
For clip.mp4, the app uses clip.mp4.jpg. When that image is missing, it creates a 4×4 sheet. On macOS 15+, Vision locally selects a better frame from each section of the movie.
Tags are part of the filename
Example: clip [travel].mp4. Editing tags and the [★] favorite marker rename the movie and its related images. Conflicts stop the operation without overwriting files.
Combine scopes and criteria
Search covers filenames and paths. Combine it with folders, All/Any tags, exclusions, and scopes for favorites, recently opened, recently changed, untagged, missing thumbnails, and similar to favorites.
Move the complete asset set
Move a movie to another folder inside the library together with its related contact sheets. Library Health also finds gaps, ghost entries, and likely duplicates.
Shape the view for the task
Sort by name, date, size, tag count, or a stable random order. Adjust tile scale and crop tiles to the most interesting part of each contact sheet.
// local_intelligence
AI features and requirements
FrameShelf shows the status of every AI feature in the guide available with ⌘?. All available analysis runs locally, and file operations require your approval.
Frames, tags, and similarity
Vision selects clearer contact-sheet frames, suggests tags, and compares images to find similar movies and likely duplicates.
Tags in the interface language
Tag suggestions can be translated locally into English or Polish. This feature does not require Apple Intelligence.
Questions, names, and patterns
On a compatible Mac running macOS 26+, Apple Intelligence interprets library questions, refines tags, suggests clearer filenames, and detects filename patterns.
A suggestion is not a command
Filters, tags, filenames, and bulk operations are shown for review first. FrameShelf never applies suggestions automatically.
Availability depends on the Mac model, macOS version, system language, and enabled system components. The core library, filters, contact sheets, and manual tagging still work without Apple Intelligence.
// controls
Keyboard shortcuts
// troubleshooting
Frequently asked questions
Why do I need to choose a folder again?
The drive may have disconnected, the folder may have moved, or its access bookmark may no longer be valid. Reconnect the drive and choose the folder again with ⌘O.
Why does a movie have no thumbnail?
Make sure the JPEG sits beside the movie and uses the movie’s complete filename followed by .jpg. You can also generate a 4×4 sheet; success depends on macOS codec support.
Can custom cover art replace a sheet?
Yes. Use any landscape JPEG with the same filename. Artwork close to a 16:9 aspect ratio usually looks best.
Why can’t a tag be saved?
A tag cannot be empty or contain [ ] / :. FrameShelf also rejects a rename when the destination filename already exists.
Why is scanning taking a long time?
Large libraries and slow network drives need more time. Keep the drive connected and use ⌘R only after the folder contents change.
Why is an Apple Intelligence feature unavailable?
It requires a compatible Mac running macOS 26 or later with Apple Intelligence ready for the current system language. Check the live status of every AI feature in the guide with ⌘?.
Why can’t FrameShelf find similar movies?
Visual comparison uses contact sheets. Generate a missing sheet for the selected movie and for the other footage you want included.