Skip to main content

Crate resopt

Crate resopt 

Source
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

ResourceOptimizationReview
PNGVerified lossless recompression, optional lossy palette reductionPreviews, quality scores, pixel differences
JPEG / HEICLossy candidates on macOSPNG previews, quality scores, alpha checks
Static WebPSame-format lossy recompression; PNG → WebP candidatesLossless PNG → WebP verified sample-for-sample
SVGA 2.xLossless embedded-PNG recompression for supported filesPoster, timeline and live frame playback
ZIP resource packagesLossless embedded-PNG recompression in eligible packagesSearchable contents, stored/expanded sizes, image previews
VAP inside MP4Preview onlyReconstructed transparency, playback and frame scrubbing
PAG / TCMP4Preview only; recognized by PAG content signaturePlayback, frame scrubbing, editable-text/image and video counts
Localization: .xcstrings, .strings, .stringsdict, Android strings.xmlInspection onlyCoverage per language, empty values, placeholder mismatches with the source language, Xcode stale keys
Audio, ordinary video, fonts, SVG, PDF, recognized Lottie JSONInventory onlyFormat 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/ and assets/, 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 --version

The 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/project

resopt 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-inspection

The 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 rules

Quality 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-analysis

apply 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/name and R.drawable.name keep 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 flags getIdentifier() 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. If minSdk cannot 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-*) and res/raw files 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

CapabilitymacOSLinux / Windows
Project inventory, Git ignore rules, scored similarity groupsYesYes
PNG lossless optimizationYesYes
SVGA lossless optimizationYesYes
ZIP browsing and lossless embedded-PNG optimizationYesYes
VAP / PAG / TCMP4 previewsCompatible browser requiredCompatible browser required
Lossy PNG candidates (palette reduction; --no-lossy-png to skip)YesYes
WebP candidates, lossy and lossless (on by default; --no-webp to skip)YesYes¹
JPEG and HEIC candidates; decoding JPEG/HEIC/GIF/TIFF inputsYes (Apple ImageIO)No
Local review page, apply, batch, restoreYesYes
AAPT2 validation (optional Android SDK), ffprobe media details (optional)YesYes

¹ 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-diff on 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-error if 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 .icon bundles), 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 .xcstrings device 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§

AnalysisControl
Cooperative cancellation shared with the caller.
AnalysisOptions
AnalysisReport
AnimationInfo
ApplyReport
ArchiveEntry
ArchiveInfo
Asset
BatchItem
BatchOutcome
BatchPlan
BatchPolicy
What a batch may do. The defaults apply only verified lossless, same-format candidates.
BatchStatus
Candidate
Capabilities
Capability
EntryChange
Fingerprint
ImageCandidate
ImageDifference
ImageInfo
Inventory
LanguageCoverage
LocalizationFile
LocalizationInfo
LocalizationIssue
MediaInfo
MinSdk
PackageDiff
PagInfo
Performance
Plan
Policy
Lossless PNG policy. Unknown fields are rejected (including lossy settings).
Resource
ResourceAnalysis
ResourceInventory
ScanOptions
SimilarComparison
A heuristic fingerprint comparison, not replacement safety or SSIMULACRA2.
SimilarGroup
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_DIR overrides 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 directory without 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.