LabelSmith for macOS

LabelSmith is a native macOS app for quickly reviewing and editing image captions in Ostris AI Toolkit-style datasets.

Drop in a folder of training images, move through the set with the keyboard, edit the caption, and let LabelSmith save the matching .txt sidecar file for you.

Features

• Native SwiftUI macOS interface.
• Drag-and-drop folder loading, with an Open Folder command as a fallback.
• Strict Ostris-style dataset support:
  • top-level .jpg, .jpeg, and .png files
  • same-basename .txt caption files
• Large image preview with a fast caption editor.
• Thumbnail/sidebar navigation.
• Search across filenames and captions.
• Missing-caption filter and dataset summary.
• Autosaves caption edits to sidecar .txt files.
• Unit-tested scanner and caption persistence logic.

Roadmap / TODOs

• Batch caption tools:

  • Find and replace text across all captions or the current filtered result set.
  • Add/remove prefixes, suffixes, and common trigger words in bulk.
  • Normalize comma-separated tags by trimming whitespace, removing duplicates, and sorting or preserving order.
  • Preview bulk edits before writing them to disk.

• Review workflow:

  • Add a reviewed/unreviewed state for each image.
  • Provide shortcuts for next missing caption, next unreviewed image, and mark reviewed.
  • Show review progress in the sidebar summary.
  • Support quick actions such as copy previous caption and clear current caption.

• Persistent workspace and folder management:

  • Remember the last opened folder and restore it when the app launches.
  • Support multiple recent or pinned dataset folders.
  • Let users switch between managed folders without reopening them through Finder.
  • Preserve per-folder UI state such as selected image, search text, filters, and review progress.
  • Clearly handle missing, moved, or unavailable folders on launch.

• Undo/history/backups:

  • Add per-caption undo for recent edits.
  • Keep a lightweight edit history during the current session.
  • Create optional timestamped backups before bulk operations.
  • Make failed saves and restore paths clear so captions are not silently lost.

• Better image inspection:

  • Add zoom, pan, fit-to-window, and actual-size controls.
  • Show image dimensions, file size, and format metadata.
  • Add keyboard shortcuts for zooming and switching inspection modes.
  • Improve thumbnail and preview behavior for very large datasets.

• Flexible dataset support:

  • Add optional recursive folder scanning.
  • Support additional image formats such as .webp where macOS can decode them.
  • Offer dataset profiles, including strict Ostris sidecars and more permissive sidecar modes.
  • Surface ignored files and folders so users understand what was skipped.

• Connect auto-captioning with LMStudio:

  • Add settings for a local LMStudio endpoint and model.
  • Send the selected image, or a batch of missing-caption images, for caption generation.
  • Let users review generated captions before saving them.
  • Track generated captions separately from manually reviewed captions.

• Stats/export:

  • Show caption completion, missing-caption count, review progress, and tag frequency.
  • Highlight duplicate captions, unusually short captions, and unusually long captions.
  • Export dataset summaries to CSV or JSON.
  • Export captions in additional training-friendly formats when useful.

Dataset Format

LabelSmith currently expects a flat folder:

dataset/
  image001.jpg
  image001.txt
  image002.png
  image002.txt
  image003.jpeg

Each .txt file contains the caption for the image with the same base name. If a caption file does not exist yet, LabelSmith creates it when you edit and save that image's caption.

For now, LabelSmith intentionally ignores subfolders and non-Ostris image extensions such as .webp, .gif, and .tiff.

Requirements

• macOS 14 or newer to run the app.
• Xcode 26 or newer for local development.
• Swift 6 toolchain for local development.

Download and Install

Most users should install LabelSmith from the GitHub Releases page instead of building it from source:

1. Open the LabelSmith releases page.
2. Choose the latest release at the top of the page.
3. Read the release notes for version-specific changes, fixes, and known issues.
4. In the release's Assets section, download the packaged app build, such as a .dmg or .zip containing LabelSmith.app.
5. If you downloaded a .zip, unzip it. If you downloaded a .dmg, open it.
6. Move LabelSmith.app to your Applications folder.
7. Launch LabelSmith from Applications.

The Source code archives attached to GitHub releases are for developers who want to inspect or build the project themselves. To run the app, download the packaged app asset from the release's Assets section.

If macOS blocks the app because the release is unsigned or from an unidentified developer, open System Settings > Privacy & Security and choose the option to open LabelSmith anyway. You can also Control-click LabelSmith.app, choose Open, and confirm the prompt.

Build and Run

Open the project in Xcode:

open LabelSmith.xcodeproj

Then select the LabelSmith scheme and run the app.

You can also build and test from the command line:

xcodebuild test \
  -project LabelSmith.xcodeproj \
  -scheme LabelSmith \
  -destination 'platform=macOS' \
  -derivedDataPath DerivedData

The debug app bundle is produced under:

DerivedData/Build/Products/Debug/LabelSmith.app

Usage

1. Launch LabelSmith.
2. Drag a dataset folder into the window, or use File > Open Folder.
3. Select an image in the sidebar.
4. Edit the caption in the caption field.
5. Move to the next image; edits autosave after a short delay.

Useful shortcuts:

• Command-O: open a folder.
• Command-S: save the current caption immediately.
• Up / Down: move to the previous or next visible image.