Sparklux Library Help

What Sparklux Library does

It lists the videos you shot or collected, right where they are in your folders, and lets you find them with tags and favorites. Playback uses the same engine as Sparklux: SDR videos are shown in HDR and upscaled.

• Your video files are never moved or modified. Tags are stored only inside the app (Finder tags are not used)
• The list stays responsive even with more than 100,000 videos

Requirements

Getting started — add a folder (⌘O)

1. Click “Add Folder…” and choose a folder that contains videos. The first time, it opens in your Movies folder, so clicking Add right away adds Movies (you can also drag a folder onto the window)
2. The app finds the videos inside and lists them as they are found, so you can start before it finishes
3. From then on, the folder is checked automatically

• If you choose a folder you have already added (or a folder inside it), the app shows that folder
• Folders inside another app’s storage, in a temporary location or inside a package can’t be added
• To stop using a folder, right-click it in the sidebar and choose “Remove Folder…”. Your video files are not touched

Browsing and searching

• Switch views with Grid / Album in the toolbar (⌘1 / ⌘2; the table-style list is in the View menu or ⌘3). Each library remembers its view, on this Mac only
  • Grid: evenly sized thumbnails, for searching and picking. Change the thumbnail size with the Size slider in the toolbar
  • Album: one chapter per day the videos were taken. Each chapter shows the highest-rated video large and 8 more. On busier days, click “+N … See the rest of this day” to see a grid of that day only (click the date in the filter bar to go back)
  • Dates and places come from the date and location recorded in each video (no tags are created). Place names are looked up on this Mac only, using a place list built into the app. Videos without a recorded date go in the last “No date” chapter
• Sort by name, date added, date modified, duration or rating
• The search field finds part of a file name or tag name (even two characters)
• Use the filter bar to narrow the list
  • Tags: click a tag in the sidebar. ⌘-click to add more (switch between “Match All” and “Match Any”), ⌥-click to exclude
  • Resolution, HDR, duration, available only: choose from the chips. “Custom Range…” lets you set just one end of a duration range
  • Videos whose metadata hasn’t been read yet aren’t included in resolution, HDR or duration filters (the count is shown)
• Your filters are kept the next time you open the library

Tags and favorites

• Select a video and press ⌘T (Add Tag…). Type a name and press Return. A new name creates a new tag
• Select several videos to tag them all at once
• Favorite with ⌘D (or ♥). Press again to remove it
• To rename or delete a tag, right-click it in the sidebar. Renaming to an existing name merges the two tags
• Tags belong to the contents of a video. Copies of the same video get the same tags, and tags stay when you move a video to another folder
• Tags can be nested. Type a name with “/”, such as Places/Kyoto, to put “Kyoto” under “Places” (a missing parent is created for you). Choosing a parent also shows videos with any tag under it. Only the child tag is added to a video
• To change a tag’s parent, drag it in Tags ▸ Tags… (⇧⌘T) › List (select several to move them together, or right-click › Group Under New Parent…). Deleting a parent moves its tags up one level

When a video isn’t available (status)

• If you moved a whole folder to another disk, right-click it in the sidebar and choose “Locate Folder…”
• To remove videos that can’t be found, choose “Remove from Library…” (⌘⌫). Your video files are not touched
• When the app notices that videos were moved and follows them, a short notice appears at the bottom and fades away

Playback

• Double-click a video (or click “Play” in the inspector). Playback controls are the same as Sparklux (Space, ← →, ⌘K display calibration and so on)
• Resume: videos you watched for 10 seconds or more start where you stopped. Watching into the last 5% marks the video as watched, and it starts from the beginning next time
• “Mark as Watched” and “Mark as Unwatched” are in the inspector
• Open in Another App (⇧⌘O): opens the selected videos in the video player you usually use. Use the button in the inspector, Control-click in the list, or the File menu. When you select several, they are passed together (you’re asked first if there are more than 10)
  • Choose the app with “Choose Default App…” under “Open With ▸” (the macOS default app at first). “Open With ▸” also lets you pick another app just this once
  • Videos on a disk or share that isn’t connected, and videos that are only in iCloud, aren’t passed (the reason is shown). For a video that is only in iCloud, play it once in this app or download it in Finder first
• Show in Finder (⌥⌘R): selects the chosen videos in Finder. Use the button in the inspector (for one video), Control-click in the list, or the File menu. When you select several, they are all selected in Finder together (you’re asked first if there are more than 10; videos in different folders open one Finder window per folder)
  • Videos on a disk or share that isn’t connected, and videos that can’t be found, aren’t shown (the reason is shown). Videos that are only in iCloud can be shown
• Location (full path): when you select one video, its full path (for example /Volumes/External/Trips/2024/IMG_0001.MOV) appears as “Location” at the end of the details (length, size, folder and so on) in the inspector. Long paths are shortened in the middle; hold the pointer over it to see the whole path (and the server name for videos on a NAS). Select the text to copy it, or Control-click and choose “Copy Path” (⌥⌘C)
  • For a video that isn’t connected or can’t be found, it shows “Last Seen At” with the last known location and the current status. For a video that is only in iCloud, it says so
  • In a password-protected library, the location is shown while the library is open. A copied path stays on the clipboard even after you lock the library
• In a password-protected library, using “Open in Another App” or “Show in Finder” leaves the item in that app’s or Finder’s recent items (you’re told before you click)

Separate libraries and passwords

• “New Library…” (⌘⇧N) creates a library with its own folders, tags and favorites
• To switch libraries, click the library name at the top of the sidebar (marked ⌄) and choose one, or choose Library ▸ Switch Library. A library with no folders yet also shows “Other Library ▾”
• To rename or delete a library, click the library name at the top of the sidebar (or use the Library menu) and choose “Rename…” or “Delete Library…”. These apply to the open library
  • Deleting removes the library’s tags, favorites, ratings, shelves, playback positions, list of added folders and thumbnails from this Mac (this can’t be undone). Your video files aren’t touched
  • You can’t delete the only library (create a new library first)
  • On other Macs that sync, the library stays and stops syncing
• If you protect it with a password, the list, tags and thumbnails are stored encrypted
  • The library locks with “Lock Library” (⌘⌃L), when your Mac sleeps, or after 15 minutes without activity
  • While it is open, its names aren’t left in Recent Items or in the Now Playing title
  • ⚠️ If you forget the password, the library can’t be opened (your video files are safe). The password isn’t stored anywhere, so the developer can’t recover it either
• You can also do this later: choose Set Password… / Change Password… / Remove Password… from the Library menu, or click the library name at the top of the sidebar (applies to the open library)
  • Setting or removing a password saves the contents again, so a large library can take a few minutes. If you cancel, the library stays as it was
  • When it’s done, the unencrypted files are deleted from this Mac (Time Machine backups may still contain them)
  • Other Macs that sync receive it as a new, password-protected library. The current library on those Macs stays there — if you don’t need it, delete it on that Mac: open it, click its name at the top of the sidebar, and choose “Delete Library…” (your video files aren’t touched)

iCloud sync

Tags, favorites, playback positions and watched status stay in step between Macs using the same Apple Account.

• Videos are matched by their contents, so it works even if each Mac keeps them in a different place
• File names and folder locations are never sent to iCloud. What is sent is encrypted on your Mac first
• A password-protected library can be opened on your other Macs with the same password
• Everything except sync works without signing in to iCloud

Price

One-time purchase. After a 3-day free trial, buy once to use it on all your Macs with the same Apple Account. There is no subscription.

• The first time you open the app, it tells you once how long the free trial lasts, what stops when it ends, and the price (“Purchase…” / “Later”)
• During the free trial, the bottom of the library window shows the days left and “Purchase…” (it disappears once you buy)
• You can close the purchase screen with “Close”. After the trial ends, it appears again when you try to play a video
• On another Mac, choose “Restore Purchase” from the app menu (you’ll see “Purchase restored” when it works)
• iCloud is used to manage the free trial (the start date only; see the Privacy Policy)
• Your libraries and tags are kept after the trial ends. Playing a video, “Open in Another App” and “Show in Finder” show the purchase screen (the items stay visible, grayed out). Browsing, tagging and searching keep working

Removing your data

• The app’s data (libraries, tags, thumbnails) is in ~/Library/Containers/dev.monneural.sparklux.library on your Mac. macOS may keep it after you delete the app, so delete that folder to remove it
• You can delete the iCloud data in System Settings → Apple Account → iCloud → Manage storage

Acknowledgments

The app includes the following software (also shown in “Acknowledgments…” in the app menu):

• SQLCipher Community Edition (Zetetic LLC) — BSD 3-Clause License. Full text below
• SQLite — public domain (included as part of SQLCipher)
• Parts for “judge by name” in Auto Tagging — MLX Swift, MLX, MLX C, MLX Swift LM, {fmt}, JSON for Modern C++, yyjson, EventSource (MIT License); metal-cpp, Swift Transformers, Swift Jinja, Swift Hugging Face, Swift Collections, Swift Crypto, Swift Numerics (Apache License 2.0). The full texts are in the app’s “Acknowledgments…” menu item
• Qwen3-VL (Alibaba Cloud) model weights — Apache License 2.0. Not included in the app; downloaded from Hugging Face only when you press Download

The playback, HDR conversion and upscaling parts come from Sparklux by the same developer (mon neural) and contain no third-party code.

Copyright (c) 2025, ZETETIC LLC
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of the ZETETIC LLC nor the
      names of its contributors may be used to endorse or promote products
      derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY ZETETIC LLC ''AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL ZETETIC LLC BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Contact

hello@monneural.dev

Provided by mon neural