Expand description
Resource discovery and recoverable, pixel-verified optimization plans.
The first backend recompresses static catalog PNGs without changing their filenames, decoded samples, or non-IDAT chunks. Plans measure source bytes, not compiled catalog or App Store download sizes.
§resopt
Find smaller app resources, review the real candidates, and apply only what you approve — with every change reversible.
resopt scans Xcode, Swift package, Android and plain resource directories. It finds smaller image and ZIP candidates, groups similar images, and previews animations in a local review page with explicit apply and restore controls.
Your files never leave your computer. Analysis never modifies your project.
New in v0.9.0: localization review (translation coverage and placeholder checks for .xcstrings, .strings, .stringsdict and Android string resources) and protected Icon Composer .icon app icons. Release notes.
§Resource support
| Resource | Optimization | Review |
|---|---|---|
| PNG | Verified lossless recompression, optional lossy palette reduction | Previews, quality scores, pixel differences |
| JPEG / HEIC | Lossy candidates on macOS | PNG previews, quality scores, alpha checks |
| Static WebP | Same-format lossy recompression; PNG → WebP candidates | Lossless PNG → WebP verified sample-for-sample |
| SVGA 2.x | Lossless embedded-PNG recompression for supported files | Poster, timeline and live frame playback |
| ZIP resource packages | Lossless embedded-PNG recompression in eligible packages | Searchable contents, stored/expanded sizes, image previews |
| VAP inside MP4 | Preview only | Reconstructed transparency, playback and frame scrubbing |
| PAG / TCMP4 | Preview only; recognized by PAG content signature | Playback, frame scrubbing, editable-text/image and video counts |
Localization: .xcstrings, .strings, .stringsdict, Android strings.xml | Inspection only | Coverage per language, empty values, placeholder mismatches with the source language, Xcode stale keys |
| Audio, ordinary video, fonts, SVG, PDF, recognized Lottie JSON | Inventory only | Format and size; optional audio/video metadata via ffprobe |
Optimization and preview support have different limits. See platform support and important limits.
§Review before you apply
- Scan a whole project. Asset catalogs, loose resources, Android
res/andassets/, with Git ignore rules respected. Results stream into the review page; analysis can be stopped. Eligible image and SVGA results are reused through a verified cache. - Compare image candidates. Use 2-up, swipe, onion skin or an amplified pixel difference. Lossy image candidates show SSIMULACRA2 quality scores and RGB/alpha errors. Lossless candidates undergo pixel and metadata verification.
- Review similar images as groups. One row represents each group, with thumbnails, total size and a similarity range. Every member is scored against the largest reference file. Only identical file bytes score 100; other scores are approximate and capped at 99.9. Search keeps the entire group visible. Intended scale/density variants do not form findings on their own. Nothing is merged or deleted automatically. Scoring details.
- Decide on warnings. Candidates below quality or alpha thresholds remain reviewable but are excluded from recommended savings. Accepting a warning is explicit and recorded. Approval cannot bypass corrupt files, stale source hashes, changed dimensions or protected resources.
- Apply and restore. Apply one candidate or a reviewed batch. Changes are journaled and restorable across restarts; later edits are never overwritten. Asset-catalog entries and statically resolvable references are updated together when a format change requires it.
§Install
Download a ready-to-run binary from GitHub Releases:
- macOS — Apple Silicon or Intel
- Linux — x86_64
- Windows — x86_64
Extract the archive and put resopt (or resopt.exe) on your PATH. Binaries need no Rust, Node.js, Bun, ffmpeg or Android SDK. Verify a download with the published SHA256SUMS.
With Rust installed:
cargo install resopt-cli --locked
resopt --versionThe package is named resopt-cli; the command is resopt. Building from source needs Rust 1.89+ and a C compiler.
§Start with your project
§Command line
resopt web /path/to/projectresopt opens your browser on a page served from 127.0.0.1 only. The printed URL contains a session key; the page and its data are not served without it. Results stream in as files finish. When analysis completes you can compare candidates, apply a change, restore it, or batch-apply under a policy you choose.
After analysis completes, live sessions check file presence every two seconds. Deleted resources disappear from the list, counts and similarity groups; files returned to their original paths reappear. New files and changed image contents still require re-analysis. Static HTML reports remain snapshots.
The terminal prints the report directory. It holds the report and the restore backups — keep it for as long as you may want to undo changes. To reopen it later (open the URL it prints):
resopt serve /path/to/report§macOS app (build from source)
On a Mac with Xcode and Rust installed, run macos/build-app.sh to create
dist/Resopt.app, then open the app and choose a project directory. The native
SwiftUI shell bundles the same Rust engine and local review UI as the CLI. It
keeps reports and restore backups under
~/Library/Application Support/resopt/Reports.
Choose 2, 4, or 8 parallel image tasks before starting a scan. In the results, Shift-click selects a range and Option/Alt-click toggles individual resources; when several resources are selected, batch apply and restore selected are scoped to that selection. Applied images use a green background and an aligned Applied label. The local build is ad-hoc signed for testing and is not notarized for distribution.
§ZIP packages and effect previews
Select a ZIP row to browse its contents, search paths, filter formats and compare stored versus expanded sizes. If a verified smaller ZIP is available, apply or restore it as one package. Filenames, pixels, atlas data and other payloads are preserved. Packages with recognized manifests or checksum maps require their publishing workflow. ZIP support and limits.
Select a VAP or PAG/TCMP4 row to play the original effect or scrub its frames. PAG playback uses a bundled renderer in an isolated frame with no CDN requests. These are previews, not optimization candidates; app-provided text/images can differ from the template shown. Open reports through resopt serve or a local HTTP server, since browser restrictions can block playback from file://. Effect support and limits.
To inspect resources without generating optimization candidates:
resopt analyze /path/to/project --probe-only --out /tmp/resopt-inspection
resopt serve /tmp/resopt-inspectionThe output directory must be new and outside the project being scanned.
§Useful options
resopt web . --no-webp # skip WebP candidates (on by default for loose files and Android)
resopt web . --no-lossy-png # skip palette-reduced PNG candidates (on by default)
resopt web . --no-near-lossless-heic # skip the HEIC quality-100 candidate (macOS, on by default)
resopt web . --png-reductions # allow lossless PNG palette/bit-depth reductions
resopt web . --qualities 85 # one quality level for a faster first pass
resopt web . --min-score 90 # stricter perceptual threshold (default 80)
resopt web . --android-min-sdk 21 # when minSdk cannot be read from Gradle files
resopt web . --out ~/resopt-report --no-open
resopt web . --include-ignored # also scan files matched by Git ignore rulesQuality values are encoder parameters, not savings percentages. --min-score sets the minimum SSIMULACRA2 quality score for recommended lossy candidates. It does not control the separate 0–100 similarity scores used in image groups.
Use --jobs to set parallel workers (default: CPU count, up to 8), --max-pixels for very large images, and --no-cache to skip the result cache. resopt cache prints the cache location; resopt cache --clear empties it.
§Reports, scripts and CI
Keep the entire report directory, including analysis.json, previews, candidates, bundled playback files and restore backups. Copying only report.html loses those resources.
resopt scan . --json # inventory only, nothing is encoded
resopt analyze . --out /tmp/report --json --timings # analysis.json, report.html, candidates
resopt apply /tmp/report --dry-run # what the default policy would apply
resopt apply /tmp/report # verified lossless, same-format only
resopt apply /tmp/report --lossy --min-score 92 # widen the policy explicitly
resopt restore /tmp/report # undo every applied change
resopt report /tmp/report # refresh HTML without re-analysisapply on a report never applies lossy candidates, format changes or warning candidates unless you pass --lossy, --cross-format or --accept-warning <kind>. Each file is applied as its own recoverable operation and gets its own outcome line; the command exits non-zero if any file failed.
Refreshing HTML does not create missing scores, previews or playback artifacts in an older report. Re-analyze the project to use newly added analysis features.
The original PNG-only plan workflow is still available: resopt plan, then resopt apply <plan> and resopt restore <plan>.
§Android projects
resopt treats Android resources as resources, not loose files:
- Files under
res/are identified by source set, resource type, qualifiers (density, RTL, locale, API level) and resource name. - PNG → WebP keeps the resource name, so
@drawable/nameandR.drawable.namekeep working and no source file is rewritten. A second file with the same name in the same directory blocks the change. The preview shows how many XML and code references use the name and flagsgetIdentifier()lookups. - WebP is gated by
minSdk, read from Gradle files and version catalogs: lossy WebP needs API 14, lossless or transparent WebP needs API 18. IfminSdkcannot be determined, WebP is not proposed until you pass--android-min-sdk. - Nine-patch (
.9.png) files stay PNG so AAPT can read their stretch and content markers; they still get pixel-identical PNG optimization. Launcher icons (mipmap-*) andres/rawfiles also keep their format. The reason is shown wherever a change is blocked. - JPEG and HEIC replacements are never proposed for Android resources.
- Files under
assets/are opened by path, so a format change migrates path references like a loose file — one file at a time, never in a batch, because asset paths are often built at runtime. - With the Android SDK build-tools installed, every
res/candidate is compiled with AAPT2 before it is applied, and the preview shows the measured compiled size. This matters: AAPT2 re-compresses PNG files during the build, so source savings on PNG do not translate one-to-one into the APK.
To measure what actually changed in a build, compare two packages:
resopt package-diff before.apk after.apk # also .aab, .ipa or any zip§Platform support
| Capability | macOS | Linux / Windows |
|---|---|---|
| Project inventory, Git ignore rules, scored similarity groups | Yes | Yes |
| PNG lossless optimization | Yes | Yes |
| SVGA lossless optimization | Yes | Yes |
| ZIP browsing and lossless embedded-PNG optimization | Yes | Yes |
| VAP / PAG / TCMP4 previews | Compatible browser required | Compatible browser required |
Lossy PNG candidates (palette reduction; --no-lossy-png to skip) | Yes | Yes |
WebP candidates, lossy and lossless (on by default; --no-webp to skip) | Yes | Yes¹ |
| JPEG and HEIC candidates; decoding JPEG/HEIC/GIF/TIFF inputs | Yes (Apple ImageIO) | No |
| Local review page, apply, batch, restore | Yes | Yes |
AAPT2 validation (optional Android SDK), ffprobe media details (optional) | Yes | Yes |
¹ Without ImageIO, WebP conversion accepts PNG and WebP inputs that carry no embedded color profile or EXIF orientation; other inputs are reported as unsupported rather than converted incorrectly.
resopt doctor shows what is available on your machine and how to install optional tools. resopt never installs anything itself.
A browser-only edition (static site, WebAssembly) optimizes individual PNG files entirely inside the browser. It has no server component and nothing is uploaded. Whole-project scanning, other formats and applying changes need the resopt command.
§Important limits
- Savings are source-file bytes. They are not IPA/APK size or store download size: Xcode compiles asset catalogs and AAPT2 re-compresses PNGs. Use
package-diffon real builds to measure shipped size. - The inventory lists files on disk. It does not know which files a particular build target, flavor or variant includes.
- Quality and similarity scores help prioritize review; they do not replace looking at the image. Similarity uses 16×16 summaries and may miss tiny details or local color changes. Matching files are not necessarily interchangeable.
- Lossy PNG uses at most 256 palette colours without dithering. Images with soft transparency usually exceed the default Alpha tolerance and are offered as warnings rather than recommendations; raise
--max-alpha-errorif that trade-off is acceptable for your artwork. - HEIC candidates are always lossy: Apple’s encoder has no lossless mode (at quality 100, 2–17% of samples still change), so resopt does not offer a “lossless HEIC”. It offers quality 100 as a clearly labelled near-lossless candidate instead.
- Existing HEIC files are not rewritten losslessly. Measured on 692 real app HEIC files, removable metadata (Exif, XMP) was 0.15% of their bytes and none contained a thumbnail, which does not justify rewriting the container.
- App icons (AppIcon sets and Icon Composer
.iconbundles), sliced (resizable) catalog images and animated images are inspected but never converted. Animated images are never flattened. - WebP is not offered for asset-catalog renditions.
- Reference migration covers statically resolvable references. Names built at runtime, third-party decoders and references outside the scanned directory need your review; ambiguous references block the change instead of guessing.
- SVGA 1.x (zip) files, and SVGA files containing audio or unknown fields, are reported as unsupported rather than rewritten (they are still previewed). SVGA playback draws bitmaps, shapes, clip paths and mattes; dynamic text/images set by app code at runtime and JPEG-encoded embedded images are not drawn.
- ZIP inspection is bounded to 64 MiB input, 10,000 entries and 256 MiB expanded contents. Up to 32 large images receive previews. Nested archives are listed but not recursively rewritten; external signatures or hashes still require the package publisher.
- VAP/PAG playback depends on browser and decoder compatibility and previews original content only. It does not establish native-device pixel parity. No PAG/VAP transcoding, animated WebP optimization, audio transcoding or font subsetting is offered.
- Localization review compares languages within one table and never edits strings. Plural forms are not compared for arguments, and
.xcstringsdevice variations count as missing. Details. - Archive, effect and localization inspection currently bypass the image-result cache.
- HEIC candidates cannot be displayed by most browsers; the comparison uses a PNG preview and links the file so you can open it in Preview or Safari.
Run resopt --help or resopt <command> --help for every option.
Changelog · Development guide · Architecture · Validation evidence · Performance · MIT license · PAG runtime licenses
Modules§
- android
- Android resource semantics derived from a project-relative path.
- portable
- Platform-independent, in-memory PNG optimization and image scoring. In-memory operations shared by the native CLI and browser adapters. No filesystem, processes, sockets, or platform image framework is used here.
Structs§
- Analysis
Control - Cooperative cancellation shared with the caller.
- Analysis
Options - Analysis
Report - Animation
Info - Apply
Report - Archive
Entry - Archive
Info - Asset
- Batch
Item - Batch
Outcome - Batch
Plan - Batch
Policy - What a batch may do. The defaults apply only verified lossless, same-format candidates.
- Batch
Status - Candidate
- Capabilities
- Capability
- Entry
Change - Fingerprint
- Image
Candidate - Image
Difference - Image
Info - Inventory
- Language
Coverage - Localization
File - Localization
Info - Localization
Issue - Media
Info - MinSdk
- Package
Diff - PagInfo
- Performance
- Plan
- Policy
- Lossless PNG policy. Unknown fields are rejected (including lossy settings).
- Resource
- Resource
Analysis - Resource
Inventory - Scan
Options - Similar
Comparison - A heuristic fingerprint comparison, not replacement safety or SSIMULACRA2.
- Similar
Group - Tool
- VapInfo
- WebOptions
Constants§
- DEFAULT_
MAX_ PIXELS - Default decoded-pixel cap: a 256 MiB float buffer per decoded image.
- MAX_
PIXELS_ LIMIT - Hard ceiling for a configured pixel cap (1 GiB float buffer per image).
Functions§
- analyze
- Read-only analysis of all inventoried resources, with lossy candidates staged solely for review. This report is deliberately not an executable apply plan.
- analyze_
with_ progress - apply
- Apply a reviewed plan; no encoding or implicit approval occurs here.
- apply_
report - Apply every candidate the policy allows and return per-file outcomes.
Interrupting the process is safe: each file is a separate journaled
operation that
restore_report(or the web UI) can undo. - cache_
directory - Per-user cache location;
RESOPT_CACHE_DIRoverrides it. - capabilities
- create_
plan - Creates a new, self-contained plan directory. Sources are never modified. A partial directory may remain if IO fails; it cannot apply without plan.json.
- image_
backend_ available - inventory
- Inventory all files other than recognized source/tooling files and build/VCS directories. Unknown files stay visible. This is not build-target resolution.
- inventory_
with_ options - package_
diff - plan_
report - Plan a batch for the report in
directorywithout changing anything. - read_
plan - refresh_
report - Refresh presentation only. Does not encode, change JSON, or touch artifacts.
- restore
- Restore only files that still match this plan’s original or candidate hashes.
- restore_
report - Restore every operation recorded in the report directory.
- scan
- Discover catalogs recursively without following symlinks or build caches. This inventories disk resources; it does not prove target membership.
- scan_
with_ options - serve
- Serve an existing analysis on loopback. Port 0 chooses an available port. The printed URL is the entry point; terminate the process to stop serving.
- web
- Start a local-only project analysis and serve the review UI while it runs. Generated reports and restore backups are retained after the process exits.