Satsuma
A native macOS clone of Tangerine, reverse engineered from a screen recording
and the product website. See docs/TEARDOWN.md for how Tangerine works and how each part maps here.
Drag any file, and while still holding the mouse button tap a key:
| key | wheel |
|---|
| ⇧ Shift | Convert to another format (~310 paths across images, audio, video, PDF, documents, slides, sheets, EPUB, subtitles, archives) |
| ⌘ Command | Tools: compress, metadata, edit, annotate, add background, crop, redact, collage, create/merge/split/organize PDF, trim, split, crop, speed, snapshots, join, mute, normalize, channels, visualize, bleep, extract |
| ⌃ Control | Actions: AirDrop, Float shelf, Copy, Move, Copy Path, Terminal |
The wheel stays open after you let go of the key. Drop on a petal to run it, or press Escape to cancel. Results
are saved next to the original (photo.png, photo Cropped.jpg, clip Trimmed.mp4…). Keys and save location
are in Settings (menu bar icon).
Build and run
git clone https://github.com/ryanwong312/satsuma.git && cd satsuma
scripts/build-app.sh --install
This builds build/Satsuma.app (release, ad-hoc signed) and copies it to ~/Applications. Satsuma lives in the
menu bar and needs no Accessibility or Input Monitoring permission.
Website and download
site/ is the landing page, live at https://satsuma-mac.vercel.app. It has an interactive wheel demo and a
download button for Satsuma.dmg, and it's deployed as the Vercel project ryanwong/satsuma. To ship a new version:
scripts/build-app.sh && scripts/make-dmg.sh
cd site && vercel deploy --prod
The app is ad-hoc signed, not notarized. On first launch macOS blocks it until you click Open Anyway in
System Settings › Privacy & Security.
Engines
Everything runs locally.
- Built in: ImageIO (JPG, PNG, HEIC, AVIF, TIFF, BMP, PDF), PDFKit, Vision OCR, Core Image, AVFoundation,
rich text (DOCX, RTF, HTML, ODT), and hand-written writers for PPTX, XLSX, ODS and EPUB.
- ffmpeg (
brew install ffmpeg) for audio and video beyond MP4, MOV and M4A.
- cwebp (
brew install webp) for WebP export.
- Pages, Keynote, Numbers for
.pages, PPT/PPTX/Keynote and XLS/Numbers. These are driven by AppleScript,
and macOS asks for Automation permission the first time.
Settings › Engines shows what's available.
Command line
The binary doubles as a test harness:
B=.build/debug/Satsuma
$B --targets photo.jpg # what each wheel offers
$B --convert png photo.jpg # run a conversion
$B --tool splitPDF notes.pdf # instant tools: muteVideo, splitPDF, extractArchive, createPDF
$B --selftest test/out/selftest # exercise all 36 tool operations on fixtures
$B --render-wheel tools wheel.png photo.jpg --highlight 2
$B --render-tool cropImage crop.png photo.jpg
scripts/make-fixtures.sh <video> builds sample files in test/fixtures from any short clip with audio.
scripts/watchdog.sh <cmd> runs a command and kills any ffmpeg that grows past 1.5 GB.
Layout
Sources/Satsuma/
App/ entry point, menu bar, Settings, Welcome, CLI
Drag/ DragMonitor: notices file drags and modifier taps system-wide
Wheel/ petal geometry (ported from the site), wheel view, drop-target panel
Model/ Catalog: formats, conversion matrix, tools, actions
Engine/ converters per category, output naming, jobs, ffmpeg/iWork bridges
Actions/ file actions and the Float shelf
HUD/ progress panels
Tools/ the 22 tool windows, ToolOps (their processing), instant tools
UI/ theme, controls, icons
