SPB Git

Repository Public License

README.md 104.7 KB 1,329 lines markdown

1<!-- ORIX Convert — README.md / Author: Simon-Pierre Boucher — contact@spboucher.ai -->2<p align="center">3  <img src="design/icon/ORIXConvert-1024.png" width="168" alt="ORIX Convert icon: the ORIX O drawn as a squared half and a circular half, each feeding the other">4</p>56<h1 align="center">ORIX Convert</h1>7<p align="center"><strong>Every Format. One App.</strong></p>8<p align="center">9A native macOS file-conversion studio.<br>10Images, vectors, video, audio, documents, PDF, spreadsheets, data, presentations, archives, 3D models, fonts,<br>11subtitles, ebooks, geospatial and scientific files — converted on your Mac, by engines that ship inside the app.<br>12No account. No API key. No upload. A conversion is offered only when a test converts a real file through it and checks the result.13</p>1415<p align="center">16  <img src="docs/badges/platform.svg" alt="macOS native" height="24">17  <img src="docs/badges/silicon.svg" alt="Apple Silicon, arm64" height="24">18  <img src="docs/badges/swift.svg" alt="Swift 6" height="24">19  <img src="docs/badges/ui.svg" alt="SwiftUI and AppKit" height="24">20  <img src="docs/badges/local.svg" alt="100% local processing" height="24">21  <img src="docs/badges/privacy.svg" alt="privacy first" height="24">22  <a href="docs/reports/offline.md"><img src="docs/badges/offline.svg" alt="offline: verified, see the offline report" height="24"></a>23  <img src="docs/badges/api.svg" alt="external API: none" height="24">24  <img src="docs/badges/multiformat.svg" alt="multi-format" height="24">25</p>26<!-- metrics:badges:start -->27<p align="center">28  <img src="docs/badges/build.svg" alt="builds on: macOS 27.0 · Xcode 27.2" height="24">29  <img src="docs/badges/tests.svg" alt="tests: 958 passing" height="24">30  <img src="docs/badges/selftest.svg" alt="in-app self-test: 142 checks passing" height="24">31  <img src="docs/badges/coverage.svg" alt="core line coverage: 94.1 %" height="24">32  <img src="docs/badges/formats.svg" alt="formats: 117" height="24">33  <img src="docs/badges/pairs.svg" alt="pairs verified end to end: 1 438" height="24">34  <img src="docs/badges/paths.svg" alt="paths incl. operations: 1 613" height="24">35  <img src="docs/badges/operations.svg" alt="named operations: 29" height="24">36</p>37<p align="center">38  <img src="docs/badges/version.svg" alt="version: 1.0.0 (1)" height="24">39  <img src="docs/badges/min-macos.svg" alt="minimum macOS: 15.0" height="24">40  <img src="docs/badges/notarization.svg" alt="notarization: accepted" height="24">41  <img src="docs/badges/dmg-size.svg" alt="DMG: 258 MB" height="24">42  <img src="docs/badges/release.svg" alt="release: True" height="24">43  <img src="docs/badges/languages.svg" alt="languages: English · Français (CA)" height="24">44</p>45<p align="center">46  <img src="docs/badges/bench-image.svg" alt="PNG → JPEG, 12 MP: 20.1 images/s" height="24">47  <img src="docs/badges/bench-video.svg" alt="4K H.264 → HEVC: 2.8× real time" height="24">48  <img src="docs/badges/bench-data.svg" alt="CSV → Parquet: 477 MB/s" height="24">49</p>50<!-- metrics:badges:end -->51<p align="center">52  <img src="https://git.spboucher.ai/badge/orix-convert/commits.svg" alt="commits" height="20">53  <img src="https://git.spboucher.ai/badge/orix-convert/last-commit.svg" alt="last commit" height="20">54  <img src="https://git.spboucher.ai/badge/orix-convert/language.svg" alt="main language" height="20">55  <img src="https://git.spboucher.ai/badge/orix-convert/size.svg" alt="repository size" height="20">56  <img src="https://git.spboucher.ai/badge/orix-convert/tags.svg" alt="tags" height="20">57</p>5859<p align="center"><img src="docs/screenshots/hero.png" width="100%" alt="Two real screenshots side by side: Smart Drop with a mixed batch grouped by detected format, and Quality Lab comparing an original image with its conversion"></p>6061> Every metric badge above is a local SVG written by [`Scripts/make-badges.py`](Scripts/make-badges.py) from files in this repository (the engine registry, the test logs, the end-to-end sweep, the benchmark report, `project.yml`). A value that was not measured reads “not measured”; a release fact that does not exist yet reads “pending”. “Builds on” names the machine the numbers come from: there is no CI service behind this repository. The five small badges are served by the forge and describe the repository itself.6263### Highlights6465- **One window for sixteen families of files.** Drop a mixed batch: files are identified from their content, grouped by format, and each group gets the destinations that really exist for it.66- **Honest by construction.** Every destination comes from a registry of declared conversion paths; each path carries its fidelity (lossless, structural, partial, lossy), what it preserves and what it cannot do, shown *before* you convert.67- **Verified output.** Each result is re-opened by an independent decoder where one exists, checked against concrete facts (dimensions, duration, page, row or triangle counts), and only then moved into place with an atomic rename.68- **Vector Studio.** A tracer written for this app turns logos, icons and line art into clean SVG or vector PDF, with a live preview and a measured similarity score.69- **Quality Lab.** Try a conversion and compare original and result side by side, with a split slider, a difference view, measured PSNR, waveforms for audio and frames for video.70- **Conversion Flow and Watch Folders.** Build a workflow of filter, branch, convert, rename and export steps, run it on files, or attach it to a folder.71- **Everything local.** Engines are bundled: Apple frameworks first, then FFmpeg, Pandoc, LibreOffice, DuckDB, libarchive, libwebp, Assimp, HDF5 and woff2 where the frameworks stop. Nothing is looked up on your Mac and nothing is sent anywhere.7273---7475## Contents7677[1. Overview](#1-overview) · [2. ORIX Philosophy](#2-orix-philosophy) · [3. Application Preview](#3-application-preview) · [4. Supported Formats](#4-supported-formats) · [5. Conversion Matrix](#5-conversion-matrix) · [6. Smart Drop](#6-smart-drop) · [7. Image Engine](#7-image-engine) · [8. Vector Studio](#8-vector-studio) · [9. Video Engine](#9-video-engine) · [10. Audio Engine](#10-audio-engine) · [11. Document Engine](#11-document-engine) · [12. PDF Engine](#12-pdf-engine) · [13. Spreadsheet Engine](#13-spreadsheet-engine) · [14. Presentation Engine](#14-presentation-engine) · [15. Archive Engine](#15-archive-engine) · [16. 3D Engine](#16-3d-engine) · [17. Font Engine](#17-font-engine) · [18. Subtitle Engine](#18-subtitle-engine) · [19. Ebook Engine](#19-ebook-engine) · [20. Geospatial Engine](#20-geospatial-engine) · [21. Scientific Data Engine](#21-scientific-data-engine) · [22. Quality Lab](#22-quality-lab) · [23. Conversion Flow](#23-conversion-flow) · [24. Folder Watching](#24-folder-watching) · [25. Performance](#25-performance) · [26. Architecture](#26-architecture) · [27. Technology Stack](#27-technology-stack) · [28. Installation](#28-installation) · [29. Build Instructions](#29-build-instructions) · [30. Testing](#30-testing) · [31. Benchmarks](#31-benchmarks) · [32. Privacy](#32-privacy) · [33. Security](#33-security) · [34. Accessibility](#34-accessibility) · [35. Localization](#35-localization) · [36. Roadmap](#36-roadmap) · [37. Release Status](#37-release-status) · [38. Known Limitations](#38-known-limitations) · [39. ORIX Ecosystem](#39-orix-ecosystem) · [40. License](#40-license)7879---8081## 1. Overview8283ORIX Convert is a Mac application written in Swift 6 (SwiftUI and AppKit) for Apple Silicon. It converts files between formats, and performs the operations that usually send people to a website or a command line: merging and splitting PDFs, making a scan searchable, extracting the audio of a video, changing a container without re-encoding, tracing a logo, building an archive, flattening an HDF5 dataset into a table.8485The design rule is that the app never offers something it cannot do. An *engine* declares *conversion paths*; a path may be declared only when the engine implements it and a test converts a real fixture through it and validates the output ([engine contract](docs/development/ENGINE-CONTRACT.md)). The registry of those paths is the single source for the destinations the interface lists, for the command-line tool, and for every count on this page.8687<!-- metrics:glance:start -->88| Measure | Value | Source |89|---|---:|---|90| Formats with at least one real conversion path | **117** (117 read, 111 written) | registry (`orix-convert formats --json`) |91| Conversion engines | **15** in 12 Swift packages | registry |92| Declared paths, operations included | **1 613** (1 328 conversions + 285 operation paths) | registry (`orix-convert matrix --json`) |93| Named operations (merge, split, OCR, extract, remux…) | **29** | registry |94| Distinct source → destination pairs | **1 533** (1 469 with a `supported` path) | registry |95| Paths marked `experimental` | 64 | registry |96| Paths run end to end by the sweep | **1 518 passed**, 0 failed, 95 skipped (no fixture) | [`docs/reports/e2e-matrix.md`](docs/reports/e2e-matrix.md) |97| Pairs verified end to end | **1 438** of 1 533 | same sweep |98| Automated tests | **958 passing** in 14 packages | [`docs/reports/tests.json`](docs/reports/tests.json) |99| In-app self-test | **142 checks passed**, 0 failed | [`docs/reports/selftest.json`](docs/reports/selftest.json) |100| Version | 1.0.0 (build 1), macOS 15.0 or later, arm64 | `project.yml` |101<!-- metrics:glance:end -->102103| You want to… | ORIX Convert gives you |104|---|---|105| convert a folder of mixed files | Smart Drop: content detection, groups by format, one destination per group, one queue |106| shrink or re-encode photos | the image engine with measured quality (PSNR), target file size, resize, colour profile and metadata control |107| turn a logo into a vector | Vector Studio: live trace, outline and node views, SVG or vector PDF |108| re-encode or remux video, extract audio or subtitles | the video engine on a bundled FFmpeg, with the Mac's hardware encoders |109| convert Word, Markdown, HTML, EPUB, PowerPoint | the document engines: Pandoc for structure, LibreOffice for layout, WebKit for print |110| work on PDFs | merge, split, extract, reorder, rotate, compress, OCR, export pages and text |111| move data between CSV, Excel, Parquet, SQLite, JSON, YAML… | the data engine on an embedded, locked-down DuckDB, larger than memory |112| check what a conversion costs in quality | Quality Lab, before committing to a batch |113| repeat it tomorrow | presets, Conversion Flow workflows and watch folders |114| script it | [`orix-convert`](docs/cli.md), the same engines on the command line |115116## 2. ORIX Philosophy117118The ORIX applications share a few rules; this is how they apply here.1191201. **Measure, do not promise.** A progress bar is determinate only when the engine measured a fraction. An estimated output size is not shown, because no engine has a real basis for one. A similarity score, a PSNR or a loudness figure is computed on the file that was written.1212. **Say what is lost before it is lost.** Each path lists its limitations in plain language; each file gets preflight warnings (transparency that will be flattened, an animation reduced to one frame, formulas that become values). During the conversion, dropped data raises a warning — there is no silent loss.1223. **Your files stay yours.** Conversion happens in a private work folder; the original is never written over unless you ask for exactly that; results appear under their final name only when complete and verified.1234. **Local means local.** No account, no telemetry, no update check, no network request. Where a bundled component contains networking code, it is blocked and the block is tested ([Privacy](#32-privacy)).1245. **Native.** Apple frameworks do the work wherever they are the right tool; third-party engines are bundled only where the frameworks stop, each with a pinned build script and its licence.1256. **Limits are part of the product.** What is experimental, untested or not implemented is listed in [Known Limitations](#38-known-limitations), not hidden.126127## 3. Application Preview128129All screenshots are captured from the real application by the application itself (it draws its own window into a PNG; nothing on screen is driven). Because that window is never the key window, native switches, selections and window buttons appear in their inactive style. The full set, with the command that produced each image, is in [`docs/screenshots/`](docs/screenshots/README.md).130131<p align="center"><img src="docs/screenshots/main-light.png" width="88%" alt="Main interface: the Convert workspace with its drop zone, example conversions and the sidebar listing Convert, Quality Lab, Vector Studio, Flow, Watch Folders, History, Metadata Studio and Formats"></p>132133| Light | Dark |134|---|---|135| <img src="docs/screenshots/quality-lab-split-light.png" width="100%" alt="Quality Lab in light mode: split comparison of a photo and its JPEG conversion"> | <img src="docs/screenshots/quality-lab-split-dark.png" width="100%" alt="The same Quality Lab comparison in dark mode"> |136137| Batch running | Batch finished |138|---|---|139| <img src="docs/screenshots/queue-running-light.png" width="100%" alt="The queue while a batch of 200 PDF files is converting: finished rows, rows with a measured percentage and the page being rendered, rows being verified, and the count of running and waiting jobs"> | <img src="docs/screenshots/queue-finished-light.png" width="100%" alt="The queue after a batch: a summary with the number of files done, the size before and after and the time, and the verification checks of the selected job"> |140141| Metadata Studio | Settings |142|---|---|143| <img src="docs/screenshots/metadata-studio-light.png" width="100%" alt="Metadata Studio inspecting a PDF: page previews and the fields read from the file"> | <img src="docs/screenshots/settings-general-light.png" width="100%" alt="Settings, General tab: output folder, name template, conflict policy, notifications and appearance"> |144145| Formats browser | History |146|---|---|147| <img src="docs/screenshots/formats-light.png" width="100%" alt="Formats browser: totals of the registry and the list of engines with their path counts"> | <img src="docs/screenshots/history-light.png" width="100%" alt="History: past conversions with the detail of the selected one, its options and verification checks"> |148149## 4. Supported Formats150151A format is listed when at least one declared path reads or writes it. “Read” means it is the source of a path, “write” that it is the destination of one. Formats the detector recognises but that no engine converts are marked as recognised only.152153<!-- metrics:formats:start -->154**117 formats** have at least one tested path: 117 are read, 111 are written. 6 are read only (`dng` `fbx` `kmz` `midi` `rar` `raw`). 3 more are recognised by the detector but have no conversion (JPEG XL, Pages, Keynote).155156| Category | Formats | Read | Write | Formats |157|---|---:|---:|---:|---|158| Image | 22 | 22 | 20 | PNG, JPEG, HEIC, HEIF, WebP, AVIF, TIFF, BMP, GIF, Animated PNG, Windows Icon, Apple Icon, Photoshop, Camera RAW, Digital Negative, OpenEXR, Radiance HDR, Targa, Portable Pixmap, Portable Graymap, Portable Bitmap, JPEG 2000 |159| Vector | 1 | 1 | 1 | SVG |160| Video | 11 | 11 | 11 | MP4, QuickTime Movie, Matroska, AVI, WebM, M4V, MPEG Program Stream, MPEG Transport Stream, AVCHD, Flash Video, Windows Media Video |161| Audio | 12 | 12 | 11 | MP3, WAV, FLAC, AAC (ADTS), M4A (AAC), Apple Lossless (M4A), AIFF, Ogg Vorbis, Opus, Windows Media Audio, MIDI, Core Audio Format |162| Document | 9 | 9 | 9 | Word (DOCX), Word 97–2004 (DOC), Rich Text, Plain Text, Markdown, HTML, OpenDocument Text, LaTeX, reStructuredText |163| PDF | 1 | 1 | 1 | PDF |164| Spreadsheet | 3 | 3 | 3 | Excel (XLSX), Excel 97–2004 (XLS), OpenDocument Spreadsheet |165| Data | 12 | 12 | 12 | CSV, TSV, JSON, JSON Lines, Parquet, Arrow IPC, SQLite, DuckDB, XML, YAML, TOML, Property List |166| Presentation | 3 | 3 | 3 | PowerPoint (PPTX), PowerPoint 97–2004 (PPT), OpenDocument Presentation |167| Archive | 12 | 12 | 11 | ZIP, 7-Zip, RAR, TAR, Gzip, Bzip2, XZ, Zstandard, TAR + Gzip, TAR + Bzip2, TAR + XZ, TAR + Zstandard |168| 3D | 12 | 12 | 11 | Wavefront OBJ, STL, PLY, glTF, glTF Binary, FBX, USD, USD (ASCII), USD (Crate), USDZ, COLLADA, 3MF |169| Font | 4 | 4 | 4 | TrueType Font, OpenType Font, WOFF, WOFF2 |170| Subtitle | 5 | 5 | 5 | SubRip, WebVTT, Advanced SubStation Alpha, SubStation Alpha, MicroDVD |171| Ebook | 1 | 1 | 1 | EPUB |172| Geospatial | 6 | 6 | 5 | GeoJSON, KML, KMZ, GPX, Shapefile, GeoPackage |173| Scientific | 2 | 2 | 2 | HDF5, NetCDF |174175<details>176<summary><b>Every format: extensions, read / write, number of destinations and sources</b></summary>177178| Category | Format | Extensions | Read | Write | Destinations | Sources | Operations |179|---|---|---|:-:|:-:|---:|---:|---:|180| Image | PNG (`png`) | .png | yes | yes | 22 | 28 | 2 |181| Image | JPEG (`jpeg`) | .jpg, .jpeg, .jpe | yes | yes | 22 | 28 | 2 |182| Image | HEIC (`heic`) | .heic | yes | yes | 22 | 22 | 1 |183| Image | HEIF (`heif`) | .heif | yes | yes | 20 | 22 | 0 |184| Image | WebP (`webp`) | .webp | yes | yes | 22 | 22 | 2 |185| Image | AVIF (`avif`) | .avif | yes | yes | 22 | 22 | 1 |186| Image | TIFF (`tiff`) | .tiff, .tif | yes | yes | 22 | 24 | 1 |187| Image | BMP (`bmp`) | .bmp | yes | yes | 22 | 22 | 1 |188| Image | GIF (`gif`) | .gif | yes | yes | 22 | 33 | 1 |189| Image | Animated PNG (`apng`) | .apng | yes | yes | 20 | 33 | 0 |190| Image | Windows Icon (`ico`) | .ico | yes | yes | 20 | 22 | 0 |191| Image | Apple Icon (`icns`) | .icns | yes | yes | 20 | 22 | 0 |192| Image | Photoshop (`psd`) | .psd | yes | yes | 22 | 22 | 1 |193| Image | Camera RAW (`raw`) | .cr2, .cr3, .nef, .arw, .raf, .orf, .rw2, .pef, .srw, .raw | yes | — | 20 | 0 | 0 |194| Image | Digital Negative (`dng`) | .dng | yes | — | 20 | 0 | 0 |195| Image | OpenEXR (`exr`) | .exr | yes | yes | 20 | 22 | 0 |196| Image | Radiance HDR (`hdr`) | .hdr | yes | yes | 20 | 22 | 0 |197| Image | Targa (`tga`) | .tga | yes | yes | 22 | 22 | 1 |198| Image | Portable Pixmap (`ppm`) | .ppm | yes | yes | 20 | 22 | 0 |199| Image | Portable Graymap (`pgm`) | .pgm | yes | yes | 20 | 22 | 0 |200| Image | Portable Bitmap (`pbm`) | .pbm | yes | yes | 20 | 22 | 0 |201| Image | JPEG 2000 (`jp2`) | .jp2, .j2k | yes | yes | 22 | 22 | 1 |202| Vector | SVG (`svg`) | .svg | yes | yes | 4 | 11 | 0 |203| Video | MP4 (`mp4`) | .mp4 | yes | yes | 24 | 11 | 3 |204| Video | QuickTime Movie (`mov`) | .mov, .qt | yes | yes | 24 | 11 | 3 |205| Video | Matroska (`mkv`) | .mkv | yes | yes | 24 | 11 | 3 |206| Video | AVI (`avi`) | .avi | yes | yes | 21 | 11 | 2 |207| Video | WebM (`webm`) | .webm | yes | yes | 24 | 11 | 3 |208| Video | M4V (`m4v`) | .m4v | yes | yes | 24 | 11 | 3 |209| Video | MPEG Program Stream (`mpeg`) | .mpg, .mpeg | yes | yes | 21 | 11 | 2 |210| Video | MPEG Transport Stream (`ts`) | .ts | yes | yes | 21 | 11 | 2 |211| Video | AVCHD (`mts`) | .mts, .m2ts | yes | yes | 21 | 11 | 2 |212| Video | Flash Video (`flv`) | .flv | yes | yes | 21 | 11 | 2 |213| Video | Windows Media Video (`wmv`) | .wmv, .asf | yes | yes | 21 | 11 | 2 |214| Audio | MP3 (`mp3`) | .mp3 | yes | yes | 11 | 23 | 0 |215| Audio | WAV (`wav`) | .wav, .wave | yes | yes | 11 | 23 | 0 |216| Audio | FLAC (`flac`) | .flac | yes | yes | 11 | 23 | 0 |217| Audio | AAC (ADTS) (`aac`) | .aac | yes | yes | 11 | 23 | 0 |218| Audio | M4A (AAC) (`m4a`) | .m4a | yes | yes | 11 | 23 | 0 |219| Audio | Apple Lossless (M4A) (`alac`) | .m4a | yes | yes | 11 | 12 | 0 |220| Audio | AIFF (`aiff`) | .aiff, .aif | yes | yes | 11 | 23 | 0 |221| Audio | Ogg Vorbis (`ogg`) | .ogg, .oga | yes | yes | 11 | 23 | 0 |222| Audio | Opus (`opus`) | .opus | yes | yes | 11 | 23 | 0 |223| Audio | Windows Media Audio (`wma`) | .wma | yes | yes | 11 | 12 | 0 |224| Audio | MIDI (`midi`) | .mid, .midi | yes | — | 11 | 0 | 0 |225| Audio | Core Audio Format (`caf`) | .caf | yes | yes | 11 | 12 | 0 |226| Document | Word (DOCX) (`docx`) | .docx | yes | yes | 11 | 10 | 1 |227| Document | Word 97–2004 (DOC) (`doc`) | .doc | yes | yes | 10 | 9 | 0 |228| Document | Rich Text (`rtf`) | .rtf | yes | yes | 10 | 10 | 0 |229| Document | Plain Text (`txt`) | .txt, .text | yes | yes | 10 | 25 | 0 |230| Document | Markdown (`markdown`) | .md, .markdown | yes | yes | 10 | 13 | 0 |231| Document | HTML (`html`) | .html, .htm | yes | yes | 10 | 9 | 0 |232| Document | OpenDocument Text (`odt`) | .odt | yes | yes | 11 | 9 | 1 |233| Document | LaTeX (`latex`) | .tex, .latex | yes | yes | 9 | 9 | 0 |234| Document | reStructuredText (`rst`) | .rst | yes | yes | 10 | 9 | 0 |235| PDF | PDF (`pdf`) | .pdf | yes | yes | 9 | 25 | 10 |236| Spreadsheet | Excel (XLSX) (`xlsx`) | .xlsx | yes | yes | 14 | 14 | 0 |237| Spreadsheet | Excel 97–2004 (XLS) (`xls`) | .xls | yes | yes | 14 | 14 | 0 |238| Spreadsheet | OpenDocument Spreadsheet (`ods`) | .ods | yes | yes | 14 | 14 | 0 |239| Data | CSV (`csv`) | .csv | yes | yes | 20 | 23 | 0 |240| Data | TSV (`tsv`) | .tsv, .tab | yes | yes | 15 | 15 | 0 |241| Data | JSON (`json`) | .json | yes | yes | 15 | 29 | 0 |242| Data | JSON Lines (`jsonl`) | .jsonl, .ndjson | yes | yes | 15 | 15 | 0 |243| Data | Parquet (`parquet`) | .parquet | yes | yes | 15 | 17 | 0 |244| Data | Arrow IPC (`arrow`) | .arrow, .feather | yes | yes | 14 | 14 | 0 |245| Data | SQLite (`sqlite`) | .sqlite, .sqlite3, .db | yes | yes | 14 | 14 | 0 |246| Data | DuckDB (`duckdb`) | .duckdb | yes | yes | 14 | 14 | 0 |247| Data | XML (`xml`) | .xml | yes | yes | 15 | 15 | 0 |248| Data | YAML (`yaml`) | .yaml, .yml | yes | yes | 15 | 15 | 0 |249| Data | TOML (`toml`) | .toml | yes | yes | 15 | 15 | 0 |250| Data | Property List (`plist`) | .plist | yes | yes | 15 | 15 | 0 |251| Presentation | PowerPoint (PPTX) (`pptx`) | .pptx | yes | yes | 8 | 2 | 1 |252| Presentation | PowerPoint 97–2004 (PPT) (`ppt`) | .ppt | yes | yes | 8 | 2 | 1 |253| Presentation | OpenDocument Presentation (`odp`) | .odp | yes | yes | 8 | 2 | 1 |254| Archive | ZIP (`zip`) | .zip | yes | yes | 10 | 9 | 3 |255| Archive | 7-Zip (`7z`) | .7z | yes | yes | 10 | 9 | 3 |256| Archive | RAR (`rar`) | .rar | yes | — | 10 | 0 | 2 |257| Archive | TAR (`tar`) | .tar | yes | yes | 10 | 9 | 3 |258| Archive | Gzip (`gz`) | .gz | yes | yes | 7 | 5 | 3 |259| Archive | Bzip2 (`bz2`) | .bz2 | yes | yes | 7 | 5 | 3 |260| Archive | XZ (`xz`) | .xz | yes | yes | 7 | 5 | 3 |261| Archive | Zstandard (`zst`) | .zst | yes | yes | 7 | 5 | 3 |262| Archive | TAR + Gzip (`tgz`) | .tgz, .tar.gz | yes | yes | 10 | 9 | 3 |263| Archive | TAR + Bzip2 (`tbz2`) | .tbz2, .tbz, .tar.bz2 | yes | yes | 10 | 9 | 3 |264| Archive | TAR + XZ (`txz`) | .txz, .tar.xz | yes | yes | 10 | 9 | 3 |265| Archive | TAR + Zstandard (`tzst`) | .tzst, .tar.zst | yes | yes | 10 | 9 | 3 |266| 3D | Wavefront OBJ (`obj`) | .obj | yes | yes | 11 | 12 | 1 |267| 3D | STL (`stl`) | .stl | yes | yes | 11 | 12 | 1 |268| 3D | PLY (`ply`) | .ply | yes | yes | 11 | 12 | 1 |269| 3D | glTF (`gltf`) | .gltf | yes | yes | 11 | 12 | 1 |270| 3D | glTF Binary (`glb`) | .glb | yes | yes | 11 | 12 | 1 |271| 3D | FBX (`fbx`) | .fbx | yes | — | 11 | 0 | 0 |272| 3D | USD (`usd`) | .usd | yes | yes | 11 | 12 | 1 |273| 3D | USD (ASCII) (`usda`) | .usda | yes | yes | 11 | 12 | 1 |274| 3D | USD (Crate) (`usdc`) | .usdc | yes | yes | 11 | 12 | 1 |275| 3D | USDZ (`usdz`) | .usdz | yes | yes | 11 | 12 | 1 |276| 3D | COLLADA (`dae`) | .dae | yes | yes | 11 | 12 | 1 |277| 3D | 3MF (`3mf`) | .3mf | yes | yes | 11 | 12 | 1 |278| Font | TrueType Font (`ttf`) | .ttf | yes | yes | 3 | 2 | 1 |279| Font | OpenType Font (`otf`) | .otf | yes | yes | 2 | 2 | 0 |280| Font | WOFF (`woff`) | .woff | yes | yes | 3 | 3 | 0 |281| Font | WOFF2 (`woff2`) | .woff2 | yes | yes | 3 | 3 | 0 |282| Subtitle | SubRip (`srt`) | .srt | yes | yes | 5 | 10 | 2 |283| Subtitle | WebVTT (`vtt`) | .vtt | yes | yes | 5 | 10 | 2 |284| Subtitle | Advanced SubStation Alpha (`ass`) | .ass | yes | yes | 5 | 10 | 2 |285| Subtitle | SubStation Alpha (`ssa`) | .ssa | yes | yes | 5 | 5 | 2 |286| Subtitle | MicroDVD (`sub`) | .sub | yes | yes | 5 | 5 | 2 |287| Ebook | EPUB (`epub`) | .epub | yes | yes | 13 | 9 | 3 |288| Geospatial | GeoJSON (`geojson`) | .geojson | yes | yes | 5 | 6 | 0 |289| Geospatial | KML (`kml`) | .kml | yes | yes | 5 | 6 | 0 |290| Geospatial | KMZ (`kmz`) | .kmz | yes | — | 6 | 0 | 0 |291| Geospatial | GPX (`gpx`) | .gpx | yes | yes | 5 | 6 | 0 |292| Geospatial | Shapefile (`shp`) | .shp | yes | yes | 5 | 6 | 0 |293| Geospatial | GeoPackage (`gpkg`) | .gpkg | yes | yes | 5 | 6 | 0 |294| Scientific | HDF5 (`hdf5`) | .h5, .hdf5, .hdf | yes | yes | 5 | 2 | 1 |295| Scientific | NetCDF (`netcdf`) | .nc, .nc4, .cdf | yes | yes | 5 | 2 | 1 |296| Image | JPEG XL (`jxl`) | .jxl | — | — | 0 | 0 | 0 (recognised only) |297| Document | Pages (`pages`) | .pages | — | — | 0 | 0 | 0 (recognised only) |298| Presentation | Keynote (`keynote`) | .key | — | — | 0 | 0 | 0 (recognised only) |299300“Destinations” counts the formats a file of this kind can be converted to directly; “Sources” the formats that can be converted into it. A folder is also a source and a destination (archives, splits, extractions): it is not counted as a format.301302</details>303<!-- metrics:formats:end -->304305## 5. Conversion Matrix306307The complete matrix — one row per declared path with its status, fidelity, what it preserves, its limitations and the test that covers it — is generated from the registry: [`docs/compatibility/conversion-matrix.md`](docs/compatibility/conversion-matrix.md) (machine-readable: [`matrix.json`](docs/compatibility/matrix.json)). The summary below is computed from the same data.308309<!-- metrics:matrix:start -->310Declared paths by category — rows are the source, columns the destination. `·` = no path; ▓ = 100 or more; █ = 300 or more.311312| From ↓ / To → | Img | Vec | Vid | Aud | Doc | PDF | Sheet | Data | Pres | Arch | 3D | Font | Sub | Ebook | Geo | Sci | Folder | Total |313|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|314| **Image** | **443** █ | **11** | · | · | · | **18** | · | · | · | · | · | · | · | · | · | · | · | 472 |315| **Vector** | 3 | · | · | · | · | 1 | · | · | · | · | · | · | · | · | · | · | · | 4 |316| **Video** | **22** | · | **177** ▓ | **88** | · | · | · | · | · | · | · | · | **15** | · | · | · | · | 302 |317| **Audio** | · | · | · | **132** ▓ | · | · | · | · | · | · | · | · | · | · | · | · | · | 132 |318| **Document** | · | · | · | · | **72** | 8 | · | · | · | · | · | · | · | 9 | · | · | 2 | 91 |319| **PDF** | 3 | · | · | · | 4 | 8 | · | · | · | · | · | · | · | · | · | · | 2 | 17 |320| **Spreadsheet** | · | · | · | · | · | · | 6 | **36** | · | · | · | · | · | · | · | · | · | 42 |321| **Data** | · | · | · | · | · | · | **36** | **141** ▓ | · | · | · | · | · | · | 5 | · | · | 182 |322| **Presentation** | 6 | · | · | · | 6 | 3 | · | · | 6 | · | · | · | · | · | · | · | 3 | 24 |323| **Archive** | · | · | · | · | **12** | · | · | **12** | · | **72** | · | · | · | · | · | · | **12** | 108 |324| **3D** | · | · | · | · | · | · | · | · | · | · | **132** ▓ | · | · | · | · | · | · | 132 |325| **Font** | · | · | · | · | · | · | · | · | · | · | · | **10** | · | · | · | · | 1 | 11 |326| **Subtitle** | · | · | · | · | · | · | · | · | · | · | · | · | **30** | · | · | · | · | 30 |327| **Ebook** | 2 | · | · | · | 9 | 1 | · | · | · | · | · | · | · | · | · | · | 2 | 14 |328| **Geospatial** | · | · | · | · | · | · | · | 6 | · | · | · | · | · | · | **25** | · | · | 31 |329| **Scientific** | · | · | · | · | · | · | · | 6 | · | · | · | · | · | · | · | 4 | · | 10 |330| **Folder** | · | · | · | · | · | · | · | · | · | **11** | · | · | · | · | · | · | · | 11 |331| **Total** | 479 | 11 | 177 | 220 | 103 | 39 | 42 | 201 | 6 | 83 | 132 | 10 | 45 | 9 | 30 | 4 | 22 | **1 613** |332333| Engine | Paths | Conversions | Operation paths | Supported | Experimental | Lossless | Structural | Partial | Lossy | Sweep: passed / skipped |334|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---|335| [`image`](docs/compatibility/engines/image.md) | 443 | 440 | 3 | 403 | 40 | 80 | 0 | 0 | 363 | 403 / 40 |336| [`pdf`](docs/compatibility/engines/pdf.md) | 24 | 14 | 10 | 22 | 2 | 14 | 1 | 5 | 4 | 24 / 0 |337| [`vector`](docs/compatibility/engines/vector.md) | 26 | 4 | 22 | 26 | 0 | 0 | 1 | 0 | 25 | 26 / 0 |338| [`video`](docs/compatibility/engines/media.md) | 302 | 143 | 159 | 302 | 0 | 56 | 0 | 103 | 143 | 302 / 0 |339| [`audio`](docs/compatibility/engines/media.md) | 132 | 132 | 0 | 132 | 0 | 25 | 11 | 0 | 96 | 132 / 0 |340| [`documents`](docs/compatibility/engines/documents.md) | 82 | 80 | 2 | 82 | 0 | 2 | 72 | 8 | 0 | 82 / 0 |341| [`ebooks`](docs/compatibility/engines/documents.md) | 23 | 19 | 4 | 23 | 0 | 2 | 19 | 1 | 1 | 23 / 0 |342| [`presentations`](docs/compatibility/engines/documents.md) | 24 | 21 | 3 | 23 | 1 | 2 | 13 | 6 | 3 | 24 / 0 |343| [`data`](docs/compatibility/engines/data.md) | 219 | 219 | 0 | 219 | 0 | 5 | 152 | 62 | 0 | 219 / 0 |344| [`archive`](docs/compatibility/engines/archive.md) | 119 | 61 | 58 | 109 | 10 | 95 | 0 | 24 | 0 | 81 / 38 |345| [`font`](docs/compatibility/engines/font.md) | 11 | 10 | 1 | 11 | 0 | 11 | 0 | 0 | 0 | 11 / 0 |346| [`subtitle`](docs/compatibility/engines/subtitle.md) | 30 | 20 | 10 | 30 | 0 | 0 | 30 | 0 | 0 | 30 / 0 |347| [`model3d`](docs/compatibility/engines/model3d.md) | 132 | 121 | 11 | 121 | 11 | 0 | 82 | 50 | 0 | 121 / 11 |348| [`geo`](docs/compatibility/engines/geo.md) | 36 | 36 | 0 | 36 | 0 | 0 | 21 | 15 | 0 | 30 / 6 |349| [`scientific`](docs/compatibility/engines/scientific.md) | 10 | 8 | 2 | 10 | 0 | 0 | 4 | 6 | 0 | 10 / 0 |350| **Total** | **1 613** | 1 328 | 285 | 1 549 | 64 | 292 | 406 | 280 | 635 | 1 518 / 95 |351352Registry fingerprint: `bb10f953b1dda4758eaef85a42eadbcaaee948576713005cb6fe646747f33edf`. The sweep ran on this same registry.353<!-- metrics:matrix:end -->354355**Fidelity** is declared per path: *lossless* (the content is identical after decoding), *structural* (the structure and values are kept, the representation changes), *partial* (some kinds of content are not carried), *lossy* (a lossy encoder is involved). **Status** is *supported* (implemented, tested, passing on the build machine) or *experimental* (works on a narrow corpus only; the reasons are in [Known Limitations](#38-known-limitations)).356357When no engine converts a pair directly, the planner may chain exactly two paths of different engines (for example DOCX → PDF → PNG). The rules are in [Architecture](#conversion-planning).358359## 6. Smart Drop360361Drop files or folders on the window, the Dock icon, or send them through Finder › Services. Each file is identified **from its content**, not its extension (signatures and container structure, at most 64 KiB read plus bounded container reads). Files are grouped by detected format; each group lists the destinations the registry really has for it, with a recommended one, the fidelity of the chosen path and its limitations. A file whose extension contradicts its content is flagged and converted as what it is.362363<p align="center"><img src="docs/screenshots/smart-drop-light.png" width="88%" alt="Smart Drop: a mixed batch grouped into PNG, JPEG, PDF and text groups; a file named .jpg whose content is PNG carries a wrong-extension warning"></p>364365- Folders are expanded (hidden files and symbolic links skipped); unrecognised files stay visible and can still go into an archive.366- Groups that choose the same multi-source operation (images into one PDF, files into one archive) can be combined into a single job.367- The output bar sets the destination folder, a name template (`{name}`, `{date}`, `{counter:3}`, `{width}`, `{height}`) and the conflict policy: keep both, skip, replace, or ask.368- Passwords typed for protected sources are used for that conversion only; they are never written to presets, history, workflows or watch rules.369370Details: [`docs/development/core-api.md`](docs/development/core-api.md) (detection, Smart Drop, capabilities).371372## 7. Image Engine373374Raster images are decoded and encoded by ImageIO, with the bundled libwebp for WebP output and the engine's own strict codecs for Netpbm, Radiance HDR and ICO. Resampling runs in linear light (Core Image Lanczos); colour and depth conversion go through vImage and ColorSync; HDR sources get a hue-preserving tone curve when the destination is SDR. Every written file is decoded again and compared with what was intended: pixel hash for lossless encoders, PSNR for lossy ones.375376<!-- metrics:engine-image:start -->377**Engine `image`** — 443 declared paths (440 conversions, 3 operation paths), 403 supported and 40 experimental. End-to-end sweep: 403 passed, 0 failed, 40 skipped for lack of a fixture.378379| From | To |380|---|---|381| `apng` `avif` `bmp` `dng` `exr` `gif` `hdr` `heic` `heif` `icns` `ico` `jp2` `jpeg` `pbm` `pgm` `png` `ppm` `psd` `raw` `tga` `tiff` `webp` (experimental: `dng` `raw`) | `apng` `avif` `bmp` `exr` `gif` `hdr` `heic` `heif` `icns` `ico` `jp2` `jpeg` `pbm` `pgm` `png` `ppm` `psd` `tga` `tiff` `webp` |382383| Operation | What it does | From | To |384|---|---|---|---|385| `image.optimize` | Optimise PNG (lossless) | `jpeg` `png` `webp` | `jpeg` `png` `webp` |386<!-- metrics:engine-image:end -->387388<p align="center"><img src="docs/screenshots/convert-image-light.png" width="88%" alt="Image conversion PNG to JPEG: the options panel (quality, target file size, resize) and two preflight warnings — transparency will be filled, and one file has the wrong extension"></p>389390**Preserved:** dimensions, ICC profile, EXIF / XMP / IPTC where the destination can hold them (with strip and strip-location options), alpha, animation between GIF, APNG and WebP, 16-bit depth where the format allows. **Options:** quality, target file size, resize modes, crop, rotation, flips, colour profile, bit depth, background for flattened alpha, grayscale, watermark, background removal (Vision, on device), PNG optimisation effort, icon sizes.391392**Limits:** camera RAW and DNG are experimental (tested only on a DNG generated in code); no JPEG XL; HEIC and AVIF output is SDR; PSD layers are flattened; animated AVIF and HEIC sequences are read but not written; no control of JPEG chroma subsampling. Full list: [`docs/compatibility/engines/image.md`](docs/compatibility/engines/image.md).393394## 8. Vector Studio395396Vector Studio traces a raster image into filled vector outlines. The tracer is written in Swift for this application (no Potrace, autotrace or vtracer code): colour quantisation with deterministic seeding, segmentation, sub-pixel contour extraction, corner detection and curve fitting. The same input always produces the same SVG. Seven modes (logo, line art, monochrome, illustration, icon, technical, high detail) set the controls; every change re-traces a preview within tens of milliseconds and then runs the full pass.397398<p align="center"><img src="docs/screenshots/vector-studio-split-light.png" width="88%" alt="Vector Studio split view on a logo: original bitmap on the left of the handle, traced vector on the right, with the controls and measured facts"></p>399400| 800 % zoom | Outline and nodes |401|---|---|402| <img src="docs/screenshots/vector-studio-800-percent-light.png" width="100%" alt="Vector Studio at 800 percent: bitmap pixels against the smooth traced edge"> | <img src="docs/screenshots/vector-studio-outline-light.png" width="100%" alt="Vector Studio outline view with the nodes of each path"> |403404<!-- metrics:engine-vector:start -->405**Engine `vector`** — 26 declared paths (4 conversions, 22 operation paths), 26 supported and 0 experimental. End-to-end sweep: 26 passed, 0 failed, 0 skipped for lack of a fixture.406407| From | To |408|---|---|409| `svg` | `jpeg` `pdf` `png` `tiff` |410411| Operation | What it does | From | To |412|---|---|---|---|413| `image.vectorize` | Trace to SVG | `avif` `bmp` `gif` `heic` `jp2` `jpeg` `png` `psd` `tga` `tiff` `webp` | `pdf` `svg` |414<!-- metrics:engine-vector:end -->415416**What the output is:** an SVG with one `<path>` per colour and never an embedded bitmap, or a PDF with the same geometry; both are checked for the absence of image objects. Each trace reports paths, nodes, colours and a **measured** similarity (mean ΔE in OKLab, mean absolute error, edge recall and precision) computed by rasterising the result and comparing it with the source. The engine also renders general SVG files to PDF and bitmaps through WebKit, with JavaScript off and every remote load blocked.417418**Limits:** flat opaque fills only — no gradients, no strokes, no centerline tracing, no text recognition. Photographs do not become compact faithful vectors; this is detected and announced before converting. Tracing is limited to 4096 × 4096 pixels (larger images are reduced, with a warning). Details: [`docs/compatibility/engines/vector.md`](docs/compatibility/engines/vector.md).419420## 9. Video Engine421422Video goes through a bundled FFmpeg (LGPL configuration, run as a separate process) and the Mac's own encoders: H.264, HEVC and ProRes through VideoToolbox (hardware by default), AV1 through SVT-AV1 and VP9 / VP8 through libvpx in software. Decoding is done in software by FFmpeg so that results are identical on every Mac. The network protocols are compiled out of the bundled build; inputs are opened with a `file,pipe` whitelist.423424<!-- metrics:engine-video:start -->425**Engine `video`** — 302 declared paths (143 conversions, 159 operation paths), 302 supported and 0 experimental. End-to-end sweep: 302 passed, 0 failed, 0 skipped for lack of a fixture.426427| From | To |428|---|---|429| `avi` `flv` `m4v` `mkv` `mov` `mp4` `mpeg` `mts` `ts` `webm` `wmv` | `apng` `avi` `flv` `gif` `m4v` `mkv` `mov` `mp4` `mpeg` `mts` `ts` `webm` `wmv` |430431| Operation | What it does | From | To |432|---|---|---|---|433| `video.extract-audio` | Extract audio | `avi` `flv` `m4v` `mkv` `mov` `mp4` `mpeg` `mts` `ts` `webm` `wmv` | `aac` `aiff` `flac` `m4a` `mp3` `ogg` `opus` `wav` |434| `video.extract-subtitles` | Extract subtitles | `m4v` `mkv` `mov` `mp4` `webm` | `ass` `srt` `vtt` |435| `video.remux` | Change container without re-encoding | `avi` `flv` `m4v` `mkv` `mov` `mp4` `mpeg` `mts` `ts` `webm` `wmv` | `flv` `m4v` `mkv` `mov` `mp4` `mpeg` `mts` `ts` `webm` |436<!-- metrics:engine-video:end -->437438<p align="center"><img src="docs/screenshots/convert-video-light.png" width="88%" alt="Video conversion MOV to MP4 with codec, quality, resolution and audio options"></p>439440**Checked:** a container change (`video.remux`) copies the streams and is verified by packet counts and decoded-picture hashes; trims are frame-accurate when re-encoding and announced as keyframe-limited when copying; HDR10 and HLG keep their signalling with 10-bit codecs and are tone-mapped (with a data-loss warning) for 8-bit ones; text subtitle tracks, chapters, several audio tracks and tags are kept where the container can hold them. The encoder that really ran (hardware or software) is reported in the facts of each result.441442**Limits:** no subtitle burn-in; no animated WebP export (GIF and APNG are supported); hardware decoding is not used; AV1 and VP9 encode in software; Dolby Vision metadata is dropped; fixtures are generated clips — real-world files with other codecs in the same containers are decoded by the same FFmpeg but are not covered by a test. Details: [`docs/compatibility/engines/media.md`](docs/compatibility/engines/media.md).443444## 10. Audio Engine445446The audio engine shares the bundled FFmpeg: AAC through Apple's AudioToolbox encoder, MP3 through LAME, Opus, Vorbis, FLAC, ALAC, PCM, WMA, AC-3 and MP2. MIDI files are rendered with the system General MIDI synthesiser in a helper process, then encoded.447448<!-- metrics:engine-audio:start -->449**Engine `audio`** — 132 declared paths (132 conversions, 0 operation paths), 132 supported and 0 experimental. End-to-end sweep: 132 passed, 0 failed, 0 skipped for lack of a fixture.450451| From | To |452|---|---|453| `aac` `aiff` `alac` `caf` `flac` `m4a` `midi` `mp3` `ogg` `opus` `wav` `wma` | `aac` `aiff` `alac` `caf` `flac` `m4a` `mp3` `ogg` `opus` `wav` `wma` |454<!-- metrics:engine-audio:end -->455456<p align="center"><img src="docs/screenshots/convert-audio-light.png" width="88%" alt="Audio conversion WAV to MP3 with bit rate, sample rate, channels and loudness options"></p>457458**Checked:** conversions between lossless formats (WAV, AIFF, FLAC, ALAC, CAF) are sample-exact at 16 and 24 bits, verified by comparing decoded PCM hashes; reducing to 16 bits applies triangular dither only when precision really drops; loudness normalisation measures the source (EBU R128), applies a plain gain when the true peak allows it, and reports the loudness measured on the written file; lossy → lossless and lossy → lossy conversions say what that means.459460**Limits:** MIDI rendering uses the system sound bank only; artwork cannot be written to Ogg, WAV, CAF, WMA or ADTS and tags cannot be written to ADTS (both announced); no WMA Pro / Lossless, DTS, E-AC-3 or TrueHD encoding. Details: [`docs/compatibility/engines/media.md`](docs/compatibility/engines/media.md).461462## 11. Document Engine463464Text documents are converted by the backend that keeps the most for each pair, measured on a reference document: **LibreOffice** (bundled, headless, one throw-away process and profile per conversion) for office ↔ office and → PDF with real page layout; **Pandoc** (bundled, separate process) for structural conversions between Markdown, HTML, LaTeX, reStructuredText, EPUB and office formats; **WebKit** for HTML → PDF with real pagination; the Apple text system as an optional alternative. Where several backends work, an *Engine* option lets you choose.465466<!-- metrics:engine-documents:start -->467**Engine `documents`** — 82 declared paths (80 conversions, 2 operation paths), 82 supported and 0 experimental. End-to-end sweep: 82 passed, 0 failed, 0 skipped for lack of a fixture.468469| From | To |470|---|---|471| `doc` | `docx` `html` `latex` `markdown` `odt` `pdf` `rst` `rtf` `txt` |472| `docx` | `doc` `html` `latex` `markdown` `odt` `pdf` `rst` `rtf` `txt` |473| `html` | `doc` `docx` `latex` `markdown` `odt` `pdf` `rst` `rtf` `txt` |474| `latex` | `doc` `docx` `html` `markdown` `odt` `rst` `rtf` `txt` |475| `markdown` | `doc` `docx` `html` `latex` `odt` `pdf` `rst` `rtf` `txt` |476| `odt` | `doc` `docx` `html` `latex` `markdown` `pdf` `rst` `rtf` `txt` |477| `rst` | `doc` `docx` `html` `latex` `markdown` `odt` `pdf` `rtf` `txt` |478| `rtf` | `doc` `docx` `html` `latex` `markdown` `odt` `pdf` `rst` `txt` |479| `txt` | `doc` `docx` `html` `latex` `markdown` `odt` `pdf` `rst` `rtf` |480481| Operation | What it does | From | To |482|---|---|---|---|483| `media.extract` | Extract embedded media | `docx` `odt` | `folder` |484<!-- metrics:engine-documents:end -->485486<p align="center"><img src="docs/screenshots/convert-document-light.png" width="88%" alt="Document conversion from plain text to Word with the document options and the limitations of the path"></p>487488**Safety:** macros are never executed (three independent layers, tested against a control that does run the macro in a stock LibreOffice); no remote resource is ever requested (tested with counting listeners); includes of LaTeX and reStructuredText stay inside the document's folder; protected files are refused, not opened.489490**Limits:** no Pages documents; no LaTeX → PDF (no TeX distribution is bundled — LaTeX is a structural source and target only); fonts missing on the Mac are substituted (listed before converting); rendering differs from Microsoft Office; the compatibility figures come from one synthetic reference document, not from a corpus of real-world files. Details: [`docs/compatibility/engines/documents.md`](docs/compatibility/engines/documents.md).491492## 12. PDF Engine493494PDF work uses Apple frameworks only: PDFKit, Core Graphics, Quartz filters and Vision. Pages are rendered to PNG, JPEG or TIFF; text is exported as plain text or Markdown; scans are made searchable by an invisible text layer recognised on device; images become PDFs without recompression when they are already JPEG.495496<!-- metrics:engine-pdf:start -->497**Engine `pdf`** — 24 declared paths (14 conversions, 10 operation paths), 22 supported and 2 experimental. End-to-end sweep: 24 passed, 0 failed, 0 skipped for lack of a fixture.498499| From | To |500|---|---|501| `bmp` `gif` `heic` `jpeg` `png` `tiff` `webp` | `pdf` |502| `pdf` (experimental) | `docx` `jpeg` `markdown` `png` `rtf` `tiff` `txt` |503504| Operation | What it does | From | To |505|---|---|---|---|506| `pdf.compress` | Compress PDF | `pdf` | `pdf` |507| `pdf.delete-pages` | Delete Pages | `pdf` | `pdf` |508| `pdf.extract-images` | Extract Images | `pdf` | `folder` |509| `pdf.extract-pages` | Extract Pages | `pdf` | `pdf` |510| `pdf.merge` | Merge PDFs | `pdf` | `pdf` |511| `pdf.ocr` | Make Searchable (OCR) | `pdf` | `pdf` |512| `pdf.reorder-pages` | Reorder Pages | `pdf` | `pdf` |513| `pdf.rotate` | Rotate Pages | `pdf` | `pdf` |514| `pdf.set-metadata` | Edit Metadata | `pdf` | `pdf` |515| `pdf.split` | Split PDF | `pdf` | `folder` |516<!-- metrics:engine-pdf:end -->517518<p align="center"><img src="docs/screenshots/pdf-merge-light.png" width="88%" alt="Merging three PDF files into one, with the order of the files and the merge options"></p>519520**Preserved by page operations:** vector content, images, links, outline, page sizes and document information. **Dropped (and announced):** tags, attachments, XMP, JavaScript, the form dictionary and digital signatures. Protected PDFs are opened with the password you supply; permission flags are respected and restrictions are never removed without the owner password.521522**Limits:** PDF → Word / RTF is experimental and rebuilds text only (no layout, columns, tables or images); compression re-encodes images only; no PDF/A, no redaction, no form flattening, no page cropping; several PDFKit behaviours this engine relies on were observed on macOS 27 only. Details: [`docs/compatibility/engines/pdf.md`](docs/compatibility/engines/pdf.md).523524## 13. Spreadsheet Engine525526The engine named `data` (“Spreadsheets & Data”) converts spreadsheets, tables and structured documents. An embedded **DuckDB** is the tabular hub: CSV, TSV, JSON, JSON Lines and Parquet are scanned by DuckDB itself, streaming and bounded by a memory limit; XLSX, ODS, SQLite and Arrow are read and written by the engine's own Swift code; XLS goes through the bundled LibreOffice. JSON, YAML, TOML, XML and property lists convert into each other as ordered trees, without passing through a table.527528<!-- metrics:engine-data:start -->529**Engine `data`** — 219 declared paths (219 conversions, 0 operation paths), 219 supported and 0 experimental. End-to-end sweep: 219 passed, 0 failed, 0 skipped for lack of a fixture.530531| From | To |532|---|---|533| `csv` `json` `jsonl` `parquet` `plist` `toml` `tsv` `xml` `yaml` | `arrow` `csv` `duckdb` `json` `jsonl` `ods` `parquet` `plist` `sqlite` `toml` `tsv` `xls` `xlsx` `xml` `yaml` |534| `arrow` | `csv` `duckdb` `json` `jsonl` `ods` `parquet` `plist` `sqlite` `toml` `tsv` `xls` `xlsx` `xml` `yaml` |535| `duckdb` | `arrow` `csv` `json` `jsonl` `ods` `parquet` `plist` `sqlite` `toml` `tsv` `xls` `xlsx` `xml` `yaml` |536| `ods` | `arrow` `csv` `duckdb` `json` `jsonl` `parquet` `plist` `sqlite` `toml` `tsv` `xls` `xlsx` `xml` `yaml` |537| `sqlite` | `arrow` `csv` `duckdb` `json` `jsonl` `ods` `parquet` `plist` `toml` `tsv` `xls` `xlsx` `xml` `yaml` |538| `xls` | `arrow` `csv` `duckdb` `json` `jsonl` `ods` `parquet` `plist` `sqlite` `toml` `tsv` `xlsx` `xml` `yaml` |539| `xlsx` | `arrow` `csv` `duckdb` `json` `jsonl` `ods` `parquet` `plist` `sqlite` `toml` `tsv` `xls` `xml` `yaml` |540<!-- metrics:engine-data:end -->541542<p align="center"><img src="docs/screenshots/convert-data-preview-light.png" width="88%" alt="Data conversion CSV to Parquet with the table preview of the first rows and the detected column types"></p>543544**Preserved:** values and types (integers beyond 2^53, decimals, dates, timestamps, NULL versus empty text, identifiers with leading zeros), sheet names, column order. Column types are detected conservatively and verified on the whole file. **Sandbox:** each job opens its own DuckDB session with extensions and external access disabled and the configuration locked; SQL cannot read or write any other file.545546**Limits:** formulas are not evaluated (cached values are read) and are not written; styles, charts, comments and hyperlinks are dropped (announced); no Numbers documents, no XLSB, no password-protected workbooks; Arrow buffers compressed with Zstandard are refused. Details: [`docs/compatibility/engines/data.md`](docs/compatibility/engines/data.md).547548## 14. Presentation Engine549550PowerPoint and OpenDocument presentations are converted by the bundled LibreOffice (layout, PDF, slide images) and by the engine's own package reader (text and speaker notes as Markdown or plain text).551552<!-- metrics:engine-presentations:start -->553**Engine `presentations`** — 24 declared paths (21 conversions, 3 operation paths), 23 supported and 1 experimental. End-to-end sweep: 24 passed, 0 failed, 0 skipped for lack of a fixture.554555| From | To |556|---|---|557| `odp` | `jpeg` `markdown` `pdf` `png` `ppt` `pptx` `txt` |558| `ppt` (experimental) | `jpeg` `markdown` `odp` `pdf` `png` `pptx` `txt` |559| `pptx` | `jpeg` `markdown` `odp` `pdf` `png` `ppt` `txt` |560561| Operation | What it does | From | To |562|---|---|---|---|563| `media.extract` | Extract embedded media | `odp` `ppt` `pptx` | `folder` |564<!-- metrics:engine-presentations:end -->565566**Preserved:** slide layout in PDF and image exports, slide order, titles and speaker notes in text exports, embedded media through `media.extract`.567568**Limits:** no Keynote documents; no presentation → HTML; PPT media extraction is experimental; text boxes that are not placeholders are exported as ordinary slide text; rendering depends on the fonts installed. Details: [`docs/compatibility/engines/documents.md`](docs/compatibility/engines/documents.md).569570## 15. Archive Engine571572Archives are handled by a bundled static libarchive (with liblzma and libzstd); extraction to disk is the engine's own code, confined to the destination folder with `openat` and `O_NOFOLLOW`. “Create archive” and “Compress” are offered for any selection of files and folders.573574<!-- metrics:engine-archive:start -->575**Engine `archive`** — 119 declared paths (61 conversions, 58 operation paths), 109 supported and 10 experimental. End-to-end sweep: 81 passed, 0 failed, 38 skipped for lack of a fixture.576577| From | To |578|---|---|579| `7z` | `tar` `tbz2` `tgz` `txz` `tzst` `zip` |580| `bz2` | `gz` `xz` `zst` |581| `gz` | `bz2` `xz` `zst` |582| `rar` (experimental) | `7z` `tar` `tbz2` `tgz` `txz` `tzst` `zip` |583| `tar` | `7z` `tbz2` `tgz` `txz` `tzst` `zip` |584| `tbz2` | `7z` `tar` `tgz` `txz` `tzst` `zip` |585| `tgz` | `7z` `tar` `tbz2` `txz` `tzst` `zip` |586| `txz` | `7z` `tar` `tbz2` `tgz` `tzst` `zip` |587| `tzst` | `7z` `tar` `tbz2` `tgz` `txz` `zip` |588| `xz` | `bz2` `gz` `zst` |589| `zip` | `7z` `tar` `tbz2` `tgz` `txz` `tzst` |590| `zst` | `bz2` `gz` `xz` |591592| Operation | What it does | From | To |593|---|---|---|---|594| `archive.compress` | Compress to Bzip2 | `folder` | `bz2` `gz` `xz` `zst` |595| `archive.create` | Create 7-Zip archive | `folder` | `7z` `tar` `tbz2` `tgz` `txz` `tzst` `zip` |596| `archive.extract` | Decompress | `7z` `bz2` `gz` `rar` `tar` `tbz2` `tgz` `txz` `tzst` `xz` `zip` `zst` | `folder` |597| `archive.recompress` | Recompress | `7z` `bz2` `gz` `tar` `tbz2` `tgz` `txz` `tzst` `xz` `zip` `zst` | `7z` `bz2` `gz` `tar` `tbz2` `tgz` `txz` `tzst` `xz` `zip` `zst` |598| `archive.verify` | Verify integrity | `7z` `bz2` `gz` `rar` `tar` `tbz2` `tgz` `txz` `tzst` `xz` `zip` `zst` | `json` `txt` |599<!-- metrics:engine-archive:end -->600601| Create an archive | Browse without extracting |602|---|---|603| <img src="docs/screenshots/archive-create-light.png" width="100%" alt="Creating a ZIP archive from a PDF, an image and a folder, with compression and encryption options"> | <img src="docs/screenshots/archive-browser-light.png" width="100%" alt="Archive browser in Metadata Studio listing the entries of a ZIP file"> |604605**Safety, tested with crafted archives:** path traversal, absolute paths, links that escape alone or together, hard links, devices, set-ID bits, decompression bombs, entry-count and size limits, truncated and mutated files. Nothing is ever written outside the destination; a failed extraction leaves nothing behind.606607**Limits:** RAR is read-only and experimental; no encrypted 7z or RAR; no multi-volume archives; 7z creation is single-threaded and slow at the normal level; extended attributes and resource forks are not restored. Details: [`docs/compatibility/engines/archive.md`](docs/compatibility/engines/archive.md).608609## 16. 3D Engine610611Every importer produces one neutral scene (node hierarchy, triangle meshes with normals, UVs and vertex colours, PBR materials, textures, unit and up-axis) and every exporter consumes it. STL, PLY, 3MF, OBJ, glTF / GLB and USD text layers are written by the engine's own Swift writers; Assimp (bundled) reads OBJ, glTF, FBX and COLLADA; Model I/O reads the USD family. Third-party and system parsers run in a helper process.612613<!-- metrics:engine-model3d:start -->614**Engine `model3d`** — 132 declared paths (121 conversions, 11 operation paths), 121 supported and 11 experimental. End-to-end sweep: 121 passed, 0 failed, 11 skipped for lack of a fixture.615616| From | To |617|---|---|618| `3mf` | `dae` `glb` `gltf` `obj` `ply` `stl` `usd` `usda` `usdc` `usdz` |619| `dae` | `3mf` `glb` `gltf` `obj` `ply` `stl` `usd` `usda` `usdc` `usdz` |620| `fbx` (experimental) | `3mf` `dae` `glb` `gltf` `obj` `ply` `stl` `usd` `usda` `usdc` `usdz` |621| `glb` | `3mf` `dae` `gltf` `obj` `ply` `stl` `usd` `usda` `usdc` `usdz` |622| `gltf` | `3mf` `dae` `glb` `obj` `ply` `stl` `usd` `usda` `usdc` `usdz` |623| `obj` | `3mf` `dae` `glb` `gltf` `ply` `stl` `usd` `usda` `usdc` `usdz` |624| `ply` | `3mf` `dae` `glb` `gltf` `obj` `stl` `usd` `usda` `usdc` `usdz` |625| `stl` | `3mf` `dae` `glb` `gltf` `obj` `ply` `usd` `usda` `usdc` `usdz` |626| `usd` | `3mf` `dae` `glb` `gltf` `obj` `ply` `stl` `usda` `usdc` `usdz` |627| `usda` | `3mf` `dae` `glb` `gltf` `obj` `ply` `stl` `usd` `usdc` `usdz` |628| `usdc` | `3mf` `dae` `glb` `gltf` `obj` `ply` `stl` `usd` `usda` `usdz` |629| `usdz` | `3mf` `dae` `glb` `gltf` `obj` `ply` `stl` `usd` `usda` `usdc` |630631| Operation | What it does | From | To |632|---|---|---|---|633| `model.reprocess` | Re-export 3MF (simplify, rescale, repair, re-encode) | `3mf` `dae` `glb` `gltf` `obj` `ply` `stl` `usd` `usda` `usdc` `usdz` | `3mf` `dae` `glb` `gltf` `obj` `ply` `stl` `usd` `usda` `usdc` `usdz` |634<!-- metrics:engine-model3d:end -->635636<p align="center"><img src="docs/screenshots/convert-3d-preview-light.png" width="88%" alt="3D conversion OBJ to GLB with the model preview of a torus and the mesh options"></p>637638**Preserved:** geometry, normals, UVs, vertex colours, base PBR materials and textures where the destination holds them, units and up-axis (converted exactly when asked, never guessed). **Options:** unit and axis conversion, normals, welding, simplification with a measured distance to the original.639640**Limits:** FBX is import-only and experimental; animations, skins, morph targets, cameras and lights are counted, never converted; polygons are always triangulated; point clouds and line sets are refused; Draco and meshopt compressed glTF are refused. Details: [`docs/compatibility/engines/model3d.md`](docs/compatibility/engines/model3d.md).641642## 17. Font Engine643644The sfnt container, WOFF 1.0 and all table readers are written in Swift; WOFF2 uses the bundled google/woff2 and Brotli. Conversions re-wrap the font: outlines, metrics and the embedding-permission field are identical before and after.645646<!-- metrics:engine-font:start -->647**Engine `font`** — 11 declared paths (10 conversions, 1 operation paths), 11 supported and 0 experimental. End-to-end sweep: 11 passed, 0 failed, 0 skipped for lack of a fixture.648649| From | To |650|---|---|651| `otf` `ttf` | `woff` `woff2` |652| `woff` | `otf` `ttf` `woff2` |653| `woff2` | `otf` `ttf` `woff` |654655| Operation | What it does | From | To |656|---|---|---|---|657| `font.split-collection` | Split font collection | `ttf` | `folder` |658<!-- metrics:engine-font:end -->659660**Preserved:** every table (WOFF2 re-encodes `glyf` / `loca` with identical outlines and removes the digital signature, which it cannot keep valid). The name-table licence, the vendor and the embedding permission are shown; a font marked “Restricted License embedding” raises a caution and the field is never modified.661662**Limits:** no TTF ↔ OTF outline conversion — it would mean re-encoding every glyph with an error bound, and a rename is never offered as a conversion; no subsetting, hinting changes or variable-font instancing; collections are split, not written. Details: [`docs/compatibility/engines/font.md`](docs/compatibility/engines/font.md).663664## 18. Subtitle Engine665666Pure Swift, no helper. Every cue is held with integer-millisecond timing, styled text runs, alignment and position; each writer states what it cannot hold.667668<!-- metrics:engine-subtitle:start -->669**Engine `subtitle`** — 30 declared paths (20 conversions, 10 operation paths), 30 supported and 0 experimental. End-to-end sweep: 30 passed, 0 failed, 0 skipped for lack of a fixture.670671| From | To |672|---|---|673| `ass` | `srt` `ssa` `sub` `vtt` |674| `srt` | `ass` `ssa` `sub` `vtt` |675| `ssa` | `ass` `srt` `sub` `vtt` |676| `sub` | `ass` `srt` `ssa` `vtt` |677| `vtt` | `ass` `srt` `ssa` `sub` |678679| Operation | What it does | From | To |680|---|---|---|---|681| `subtitle.clean` | Clean up subtitles | `ass` `srt` `ssa` `sub` `vtt` | `ass` `srt` `ssa` `sub` `vtt` |682| `subtitle.retime` | Retime subtitles | `ass` `srt` `ssa` `sub` `vtt` | `ass` `srt` `ssa` `sub` `vtt` |683<!-- metrics:engine-subtitle:end -->684685**Preserved:** timing at the destination's resolution, text, bold / italic / underline / colour where the destination supports them. `preflight` runs the whole pipeline in memory and returns the same warnings the conversion then emits. Operations shift or stretch timings and clean up cues.686687**Limits:** no TTML, SBV, LRC, SAMI, SCC, EBU STL or bitmap subtitles; ASS rendering semantics (style inheritance, animations, layers) are not modelled; no language detection. Details: [`docs/compatibility/engines/subtitle.md`](docs/compatibility/engines/subtitle.md).688689## 19. Ebook Engine690691EPUB is read by the engine's own package reader and converted by Pandoc; EPUB → PDF goes through a print rendering in WebKit.692693<!-- metrics:engine-ebooks:start -->694**Engine `ebooks`** — 23 declared paths (19 conversions, 4 operation paths), 23 supported and 0 experimental. End-to-end sweep: 23 passed, 0 failed, 0 skipped for lack of a fixture.695696| From | To |697|---|---|698| `doc` `docx` `html` `latex` `markdown` `odt` `rst` `rtf` `txt` | `epub` |699| `epub` | `doc` `docx` `html` `latex` `markdown` `odt` `pdf` `rst` `rtf` `txt` |700701| Operation | What it does | From | To |702|---|---|---|---|703| `epub.chapters` | Split into chapters | `epub` | `folder` |704| `epub.cover` | Extract cover image | `epub` | `jpeg` `png` |705| `media.extract` | Extract embedded media | `epub` | `folder` |706<!-- metrics:engine-ebooks:end -->707708**Preserved:** text structure, chapters, images, links, metadata and cover; `epub.chapters` splits a book per spine item and `epub.cover` extracts the cover.709710**Limits:** books with DRM or content encryption are refused (font obfuscation alone is accepted and reported); no MOBI, AZW or KFX; EPUB → PDF is a reflowed print rendering, not a page design; a spine item is not always one chapter. Details: [`docs/compatibility/engines/documents.md`](docs/compatibility/engines/documents.md).711712## 20. Geospatial Engine713714Pure Swift plus SQLite and the system Compression framework — no GDAL and no PROJ. GeoJSON, KML / KMZ, GPX, CSV with coordinates, Shapefile and GeoPackage are read and written by the engine's own code.715716<!-- metrics:engine-geo:start -->717**Engine `geo`** — 36 declared paths (36 conversions, 0 operation paths), 36 supported and 0 experimental. End-to-end sweep: 30 passed, 0 failed, 6 skipped for lack of a fixture.718719| From | To |720|---|---|721| `csv` | `geojson` `gpkg` `gpx` `kml` `shp` |722| `geojson` | `csv` `gpkg` `gpx` `kml` `shp` |723| `gpkg` | `csv` `geojson` `gpx` `kml` `shp` |724| `gpx` | `csv` `geojson` `gpkg` `kml` `shp` |725| `kml` | `csv` `geojson` `gpkg` `gpx` `shp` |726| `kmz` | `csv` `geojson` `gpkg` `gpx` `kml` `shp` |727| `shp` | `csv` `geojson` `gpkg` `gpx` `kml` |728<!-- metrics:engine-geo:end -->729730**Preserved:** geometries (points, lines, polygons with holes, multi-geometries, Z values), attributes with their types, layers. **A coordinate reference system is never changed silently:** each conversion reports the source system, what was done, and the destination system; a small tested set of transformations is offered, everything else is carried unchanged or refused.731732**Limits:** the whole dataset is held in memory (no streaming; text and XML sources are refused above 2 GiB); KMZ is read, not written; no rasters, tiles or coverages; KML styles and overlays are dropped (counted); no topology repair. Details: [`docs/compatibility/engines/geo.md`](docs/compatibility/engines/geo.md).733734## 21. Scientific Data Engine735736HDF5 and NetCDF-4 go through a bundled static HDF5 library; NetCDF classic (CDF-1, CDF-2, CDF-5) is read and written by the engine's own Swift code, tested against files assembled byte by byte. Datasets are flattened into CSV, JSON or Parquet tables, or converted between the container formats with their structure.737738<!-- metrics:engine-scientific:start -->739**Engine `scientific`** — 10 declared paths (8 conversions, 2 operation paths), 10 supported and 0 experimental. End-to-end sweep: 10 passed, 0 failed, 0 skipped for lack of a fixture.740741| From | To |742|---|---|743| `hdf5` | `csv` `json` `netcdf` `parquet` |744| `netcdf` | `csv` `hdf5` `json` `parquet` |745746| Operation | What it does | From | To |747|---|---|---|---|748| `hdf5.repack` | Repack / Recompress HDF5 | `hdf5` | `hdf5` |749| `netcdf.reformat` | Change NetCDF Variant | `netcdf` | `netcdf` |750<!-- metrics:engine-scientific:end -->751752**Preserved:** dimensions, variables, attributes, fill values, chunking and deflate filters between containers. Data moves in bounded blocks: conversions of multi-gigabyte files stayed under 130 MiB of resident memory in the measurements. External links are listed and never followed; plug-ins are disabled; a damaged file is first opened in a helper process so that a hang or crash of the C library is contained.753754**Limits:** tables (CSV, Parquet, JSON) → HDF5 or NetCDF are not offered; datasets compressed with szip or third-party filters are reported as unreadable; the helper pre-checks metadata and the first and last block of each dataset, the conversion itself reads the data in-process. Details: [`docs/compatibility/engines/scientific.md`](docs/compatibility/engines/scientific.md).755756## 22. Quality Lab757758Quality Lab answers “what will this conversion do to my file?” before a batch. It runs the real conversion — planner, engine, validation — on a private queue, into a scratch folder that never touches your files, then shows original and result together.759760<p align="center"><img src="docs/screenshots/quality-lab-split-light.png" width="88%" alt="Quality Lab: split slider over a photo, original on one side, low-quality JPEG on the other, with the measured facts"></p>761762| Difference view | Audio waveforms | Video frame |763|---|---|---|764| <img src="docs/screenshots/quality-lab-difference-dark.png" width="100%" alt="Quality Lab difference view: amplified absolute difference between original and result"> | <img src="docs/screenshots/quality-lab-audio-light.png" width="100%" alt="Quality Lab comparing the waveforms of a WAV file and its MP3 conversion"> | <img src="docs/screenshots/quality-lab-video-light.png" width="100%" alt="Quality Lab comparing a frame of a video before and after conversion"> |765766- Views: side by side, split slider, original, result, difference (amplified × 1, 4, 16 or 64). Zoom is expressed in device pixels per image pixel and switches to nearest-neighbour beyond 100 %.767- Measured: file sizes and ratio, PSNR, largest difference and share of differing pixels (when both pictures have the same pixel size; the panel says at which size the comparison was made).768- Bounded decoding: previews are at most 2048 px on the long side, the detail bitmap at most 8192 px; the pixel inspector says so when the file is larger.769- Changing an option re-runs the trial; “Use These Settings” stages the file in Convert with the same destination and options.770- When one side cannot be drawn (a text document, a scientific container), the stage says so and the facts remain.771772## 23. Conversion Flow773774A workflow is a list of nodes applied to each file: **filter** (by category, format, size, name), **branch** (one of two lanes), **convert** (a real path with its options), **rename** (a name template) and **export** (copy to a folder with a conflict policy). The validator checks every convert step against the registry for the formats that can reach it; a step that cannot work is marked on its card with the reason.775776<p align="center"><img src="docs/screenshots/flow-run-light.png" width="88%" alt="Conversion Flow: a built-in workflow that converts images to WebP, run over four files with the per-file results"></p>777778- Five built-in workflows are validated at launch and offered only when they are valid in the current registry; they are read-only and can be duplicated.779- Edits are undoable and saved automatically; runs are recorded in the history.780- A workflow handles files one by one. “Several inputs into one output” and “two outputs in parallel from one input” do not exist in the model.781- Secrets typed in a convert step stay in memory for runs started from it and are removed whenever the workflow is stored or exported.782- The same files run from the command line: `orix-convert workflow run flow.json files…` ([`docs/cli.md`](docs/cli.md)).783784Diagram: [workflow automation](#workflow-automation).785786## 24. Folder Watching787788A watch rule ties a folder to a destination format, a preset or a workflow. Only the folders of the rules are watched (FSEvents plus a periodic re-listing). A file is processed once its size and date have been stable for two seconds and its name is not a temporary one.789790<p align="center"><img src="docs/screenshots/watch-folders-light.png" width="88%" alt="Watch Folders: three rules with their status and the activity list of processed files"></p>791792- **Loop prevention:** a rule whose outputs could match its own folder is refused when it is created, and a file written by the watcher is never processed by any rule.793- **Duplicates:** an unchanged file is skipped; identical content arriving again is recorded as a duplicate (SHA-256).794- Files already present when a rule starts are ignored unless you ask otherwise. Rules never store secrets.795- Watching runs while the application runs (an optional menu-bar item keeps it alive when the window is closed). Nothing is registered at login.796797## 25. Performance798799- **Queue.** One job per performance core by default, at most eight; jobs that involve video, LibreOffice or the 3D helper, or sources of 1 GiB and more, are *heavy* and limited separately. Concurrency is halved in Low Power Mode and under serious thermal pressure, and no new job starts at critical thermal state.800- **Streaming where the format allows.** DuckDB conversions are bounded by a memory limit and spill to the job's work folder; HDF5 data moves in blocks; archives stream through a 1 MB buffer; FFmpeg runs as its own process.801- **Hardware.** H.264, HEVC and ProRes use the Mac's hardware encoders by default; what really ran is reported per file.802- **Honest cost of verification.** Every output is validated; for some paths (PNG → JPEG with measured PSNR, large spreadsheets, KML) validation costs about as much as the conversion. The figures in [Benchmarks](#31-benchmarks) include it.803804Measured figures and their conditions: [Benchmarks](#31-benchmarks) and [`docs/performance/benchmarks.md`](docs/performance/benchmarks.md).805806## 26. Architecture807808The core package (`ConvertCore`) contains **no conversion code**. Engines implement one protocol; the core detects, plans, schedules, validates, writes and records. The application and the command-line tool are two front ends on the same assembly. A deeper description is in [`docs/architecture/overview.md`](docs/architecture/overview.md).809810### Universal conversion pipeline811812```mermaid813flowchart LR814    A[Files and folders] --> B[Detector<br/>content signatures]815    B --> C[Smart Drop analysis<br/>groups, targets, warnings]816    C --> D[Planner<br/>direct path or 2-step chain]817    D --> E[Queue<br/>priorities, heavy-job limits]818    E --> F[Engine convert<br/>private work folder]819    F --> G[Generic output checks]820    G --> H[Engine validate<br/>independent re-read]821    H --> I[Safe writer<br/>atomic rename]822    I --> J[History]823    F -. warnings, measured progress .-> E824    G -- a check fails --> X[Job failed<br/>nothing delivered]825    H -- a check fails --> X826```827828### Format registry829830```mermaid831flowchart TB832    subgraph Engines["Engine packages"]833        E1[image] --- E2[pdf] --- E3[vector] --- E4[video / audio]834        E5[documents / ebooks / presentations] --- E6[data] --- E7[archive]835        E8[font] --- E9[subtitle] --- E10[model3d] --- E11[geo] --- E12[scientific]836    end837    Engines -- "paths: source, destination, operation,<br/>status, fidelity, preserves, limitations" --> R[FormatRegistry]838    K[FormatCatalog<br/>ids, names, extensions, traits] --> R839    R --> C1[Capability resolver<br/>targets and recommendations]840    R --> C2[Planner]841    R --> C3[Matrix generator<br/>conversion-matrix.md, matrix.json]842    R --> C4[App: destination pickers,<br/>Formats browser]843    R --> C5[orix-convert formats / paths / matrix]844```845846### Conversion planning847848```mermaid849flowchart TD850    S[Source format + destination] --> Q{A declared path<br/>source → destination?}851    Q -- yes --> P1[Pick the engine:<br/>supported before experimental,<br/>then best fidelity]852    P1 --> D1[Direct plan]853    Q -- no --> O{A named operation<br/>was requested?}854    O -- yes --> N[Unsupported: operations<br/>are never chained]855    O -- no --> CH[Enumerate chains A → X → B]856    CH --> R1[Rules: exactly two steps ·<br/>two different engines ·<br/>plain single-source steps ·<br/>no folder intermediate ·<br/>step 1 cannot yield several files]857    R1 --> R2[Drop chains through a lossy intermediate<br/>when a lossless one exists]858    R2 --> R3[Rank by step cost:<br/>lossless 0 · structural 1 · lossy 4 · partial 8 ·<br/>experimental +2]859    R3 --> D2[Chained plan:<br/>union of limitations,<br/>worst fidelity and status]860    R1 -- none left --> N861```862863### Engine selection864865```mermaid866flowchart LR867    P[Plan step] --> A{Engine available?<br/>tools and libraries present}868    A -- no --> U[Path listed as unavailable<br/>with the reason]869    A -- yes --> B{Several engines<br/>declare the pair?}870    B -- no --> E[That engine]871    B -- yes --> C[Status, then fidelity;<br/>an explicit engine choice wins]872    C --> E873    E --> F{Backend inside the engine}874    F --> F1[Apple framework<br/>in process]875    F --> F2[Bundled library<br/>in process]876    F --> F3[Helper process<br/>ffmpeg · pandoc · soffice ·<br/>model3d helper · hdf5 probe · midi render]877```878879### Batch processing and queue states880881```mermaid882stateDiagram-v2883    [*] --> queued884    queued --> paused: pause job (only before it starts)885    paused --> queued: resume886    queued --> preparing: a slot is free887    preparing --> skipped: destination exists, policy skip888    preparing --> awaitingDecision: destination exists, policy ask889    preparing --> running890    running --> validating891    validating --> awaitingDecision: conflict found after converting892    awaitingDecision --> running: resolved before converting893    awaitingDecision --> finished: resolved, output moved894    awaitingDecision --> skipped895    validating --> finished: checks passed, atomic move896    preparing --> failed897    running --> failed898    validating --> failed: a check failed, nothing delivered899    queued --> cancelled900    running --> cancelled901    failed --> queued: retry902    finished --> [*]903```904905### Output validation and safe writing906907```mermaid908flowchart TD909    W[Engine output in the job's work folder] --> G1{Inside the work folder,<br/>exists, not empty,<br/>not a symbolic link?}910    G1 -- no --> F[Fail the job · remove the work folder]911    G1 -- yes --> G2{Detected format =<br/>destination or an allowed equivalent?}912    G2 -- no --> F913    G2 -- yes --> V[Engine validate:<br/>re-open with an independent decoder,<br/>compare concrete facts]914    V -- failed --> F915    V -- passed --> C{Destination name exists?}916    C -- "no" --> S[Stage as hidden .partial<br/>in the destination folder]917    C -- "keep both" --> N[Number the name] --> S918    C -- "skip" --> K[Skipped]919    C -- "ask" --> A[Awaiting decision]920    C -- "replace" --> SR{Is it a source file?}921    SR -- "yes, not explicitly allowed" --> A922    SR -- "no" --> S923    S --> M[Single rename into place<br/>RENAME_EXCL or replaceItemAt]924    M --> H[History entry · secrets redacted]925```926927### Workflow automation928929```mermaid930flowchart LR931    T1[Run now on files] --> WR932    T2[Watch rule:<br/>stable file in a watched folder] --> WR933    T3[orix-convert workflow run] --> WR934    T4[Shortcuts: Run Workflow intent] --> WR935    WR[Workflow runner<br/>one file at a time] --> N1{filter}936    N1 -- no match --> X[Item filtered]937    N1 -- match --> N2{branch}938    N2 -- then --> N3[convert<br/>a queue job]939    N2 -- otherwise --> N4[rename]940    N3 --> N5[export<br/>copy with conflict policy]941    N4 --> N5942    N5 --> L[Run record in the history]943    N3 -. validated against the registry before the run .- VAL[Workflow validator]944    N5 -. outputs are never re-processed .-> T2945```946947### File security948949```mermaid950flowchart TB951    U[Untrusted file] --> D[Detector<br/>bounded reads, never trusts lengths]952    D --> APP953    subgraph APP["Application process · Hardened Runtime · no entitlement"]954        IP[In-process parsers:<br/>ImageIO · PDFKit · own Swift codecs ·<br/>libwebp · libarchive · woff2 · DuckDB locked down ·<br/>HDF5 after the probe]955        LIM[Limits: pixels, entries, sizes, depth,<br/>ratios, time, free disk space]956    end957    APP -- "argument arrays, no shell, no PATH" --> HP958    subgraph HP["Helper processes · one per job · killed on cancel or time limit"]959        H1[ffmpeg / ffprobe<br/>file and pipe protocols only]960        H2[pandoc<br/>dead-end proxy, content neutralised first]961        H3[soffice<br/>throw-away profile, macros off, allow-jit]962        H4[orix-model3d-helper<br/>Assimp, Model I/O]963        H5[orix-hdf5-probe]964        H6[orix-midi-render]965    end966    APP --> WK[WebKit content process<br/>JavaScript off, content rules,<br/>private URL scheme]967    HP --> WD[Private work folder, mode 0700]968    APP --> WD969    WD --> OV[Output validation] --> SW[Safe writer] --> OUT[Destination folder]970```971972The threat model, the limits of each engine and the residual risks are in [`docs/security/security-model.md`](docs/security/security-model.md).973974## 27. Technology Stack975976| Layer | Technology |977|---|---|978| Language | Swift 6 language mode, strict concurrency; small C shims around bundled C / C++ libraries |979| Interface | SwiftUI, with AppKit for the canvases, panels, Services and the menu bar item |980| Project | XcodeGen (`project.yml`), one SwiftPM package per engine family, core package `ORIXConvertCore`, assembly package `ConvertKit` |981| Images | ImageIO, Core Graphics, Core Image, vImage, ColorSync, Vision; libwebp 1.6.0 |982| Vector | own tracer in Swift; WebKit for SVG rendering |983| Video and audio | FFmpeg 9.1 (LGPL build: `ffmpeg`, `ffprobe`) with LAME, Opus, Vorbis, libvpx, SVT-AV1, dav1d, zimg; VideoToolbox, AudioToolbox, AVFoundation |984| Documents | Pandoc 3.14, LibreOffice 26.8.3 (slimmed), WebKit, the Apple text system |985| PDF | PDFKit, Core Graphics, Quartz filters, Vision |986| Data | DuckDB 2.0.1, system SQLite, Yams 6.2.2; own XLSX, ODS, Arrow IPC, TOML, JSON and XML codecs |987| Archives | libarchive 3.8.11 with xz 5.8.4 and zstd 1.5.7 |988| 3D | Assimp 6.0.2, Model I/O, SceneKit; own STL, PLY, 3MF, OBJ, glTF and USD writers |989| Fonts | own sfnt and WOFF code; google/woff2 1.0.2 with Brotli 1.2.1 |990| Scientific | HDF5 2.2.0; own NetCDF classic reader and writer |991| Storage | SQLite history, JSON settings, presets, workflows and watch rules in Application Support |992| System integration | Services menu, App Intents (Shortcuts), Dock drop, optional menu bar item, `orix-convert` command-line tool |993994Why each third-party engine was chosen, and what was rejected: [`docs/research/conversion-engine-evaluation.md`](docs/research/conversion-engine-evaluation.md).995996## 28. Installation997998> The first release is being prepared. Until the [Release Status](#37-release-status) table shows a published release, there is no download; build from source ([Build Instructions](#29-build-instructions)).99910001. Download the disk image from the release page of this repository and compare its SHA-256 with the value in [Release Status](#37-release-status).10012. Open the disk image and drag **ORIX Convert** to **Applications**.10023. Open it. It needs an Apple Silicon Mac and the minimum macOS shown in the table at the top of this page.10031004**First launch.** The application asks for no permission at launch. macOS asks for access to a folder (Desktop, Documents, Downloads, removable volumes) the first time you convert files stored there. The first OCR or background removal after a restart can take longer while the system loads its model. *Convert with ORIX Convert* appears in Finder › Services once macOS has rescanned the Applications folder; it may have to be enabled in System Settings › Keyboard › Keyboard Shortcuts › Services. Settings › Advanced shows the command that installs the `orix-convert` tool; the application itself writes nothing outside its own data.10051006**Where data lives.**10071008| What | Where |1009|---|---|1010| Settings, presets, workflows, watch rules, history | `~/Library/Application Support/ORIX Convert/` (`settings.json`, `presets.json`, `workflows.json`, `watch-rules.json`, `history.sqlite`) |1011| Work folders of running jobs | `$TMPDIR/ai.spboucher.orix.convert/` (removed when a job ends; stale ones are swept after a day) |1012| Converted files | where you choose — next to the source by default |10131014**Uninstall.** Move the application to the Trash and delete `~/Library/Application Support/ORIX Convert/`. If you installed the command-line tool, remove the symbolic link the install command created. Nothing else is installed: no login item, no launch agent, no kernel or system extension.10151016## 29. Build Instructions10171018Prerequisites: an Apple Silicon Mac, Xcode with the macOS SDK (the build machine runs the versions shown on the “builds on” badge), [XcodeGen](https://github.com/yonaskolb/XcodeGen), Python 3, and — to build the bundled libraries from source — CMake, Ninja and NASM. Roughly 6 GB of free space for sources and build products. The engine scripts download pinned archives and verify their SHA-256; they are the only step that uses the network.10191020```bash1021# 1. Bundled engines — each script pins a version and a SHA-256 (products are gitignored).1022#    Static libraries first (any order), then the helper tools.1023EmbeddedEngines/libwebp/build.sh1024EmbeddedEngines/libarchive/build.sh1025EmbeddedEngines/woff2/build.sh1026EmbeddedEngines/assimp/build.sh1027EmbeddedEngines/hdf5/build.sh1028EmbeddedEngines/duckdb/build.sh        # official library, thinned to arm641029EmbeddedEngines/ffmpeg/build.sh        # ffmpeg + ffprobe from source, LGPL configuration1030EmbeddedEngines/pandoc/fetch.sh        # official executable, unmodified1031EmbeddedEngines/libreoffice/fetch.sh   # official bundle, slimmed10321033# 2. The application1034Scripts/build.sh debug        # generates the string catalogs and the Xcode project, builds Debug1035Scripts/build.sh selftest     # end-to-end scenario inside the app, on generated files1036Scripts/build.sh run10371038# 3. The command-line tool1039cd Packages/ConvertKit && swift build --build-system native -c release --product orix-convert10401041# 4. Tests, matrix, sweep, reports1042Scripts/make-badges.py --run-tests    # swift test in every package, one after the other1043Scripts/matrix.sh --verify            # regenerates the matrix and runs every path end to end1044Scripts/offline-check.sh              # offline proof1045Scripts/bench.sh                      # end-to-end benchmarks (release build)1046Scripts/check.sh                      # documentation, secret scan, source headers1047```10481049`Scripts/build.sh release` builds the Release configuration signed with a Developer ID identity (`ORIX_RELEASE_ADHOC=1` signs ad hoc instead). How a distributable release is produced is described in [`docs/release/distribution.md`](docs/release/distribution.md).10501051## 30. Testing10521053Three layers, each with its own evidence:105410551. **Package tests** (Swift Testing). Every declared path has at least one test that converts a real fixture and validates the output; fixtures are generated in code or by the bundled tools at test time, never downloaded. Malformed input, cancellation and data-loss warnings are tested per engine.10562. **In-app self-test.** The application runs an end-to-end scenario through the same model code the interface calls: Smart Drop, conflicts, cancellation, the studios, a workflow, a watch rule, one real conversion per engine, previews, Services and App Intents.10573. **End-to-end sweep.** `orix-convert matrix --verify` runs every declared path as a user would — detector, planner, queue, engine, validation, safe writer — on real fixtures.10581059<!-- metrics:tests:start -->1060| Package | What it covers | Tests | Suites | Result | Wall time |1061|---|---|---:|---:|---|---:|1062| `ORIXConvertCore` | core: detection, registry, planner, queue, validation, safe writer, history, workflows, watcher | 333 | 43 | passed | 5 s |1063| `EngineSubtitle` | subtitles | 36 | 5 | passed | 28 s |1064| `EngineFont` | fonts | 18 | 3 | passed | 8 s |1065| `EngineGeo` | geospatial | 55 | 12 | passed | 9 s |1066| `EngineArchive` | archives | 33 | 4 | passed | 8 s |1067| `EnginePDF` | PDF | 58 | 13 | passed | 17 s |1068| `EngineImage` | raster images | 54 | 10 | passed | 18 s |1069| `EngineModel3D` | 3D models | 66 | 11 | passed | 34 s |1070| `EngineScientific` | HDF5 and NetCDF | 48 | 12 | passed | 28 s |1071| `EngineData` | spreadsheets and data | 70 | 6 | passed | 50 s |1072| `EngineDocuments` | documents, ebooks, presentations | 35 | 7 | passed | 83 s |1073| `EngineVector` | tracer and SVG rendering | 54 | 8 | passed | 159 s |1074| `EngineMedia` | video and audio | 47 | 7 | passed | 209 s |1075| `ConvertKit` | engine assembly and the `orix-convert` tool | 51 | 8 | passed | 17 s |1076| **Total** | | **958** passing | | all packages passing | |10771078`EngineData`: an earlier run the same day **failed** (“Test run with 70 tests in 6 suites failed after 49.778 seconds with 2 issues”) and the suite passed when run again alone; the failing test is the timing-sensitive cancellation test described under Known Limitations.10791080Run of 2026-11-21 on Apple M5 Max, macOS 27.0, Swift 6.4.2 — `swift test` in each package, one after the other on a machine shared with other work. Counts are test functions; the parameterised ones run one case per declared path. 11 of them are opt-in benchmarks or development aids that Swift Testing reports as skipped.10811082In-app self-test (`Scripts/build.sh selftest`, 2026-11-21): **PASS** — 142 checks passed, 0 failed.10831084| Coverage measured for | Lines | Line coverage | Functions | Function coverage |1085|---|---:|---:|---:|---:|1086| `ORIXConvertCore` (`Sources/`, 20 files) | 5 210 / 5 535 | **94.1 %** | 1 106 / 1 244 | 88.9 % |1087| `EngineSubtitle` (`Sources/`, 8 files) | 2 276 / 2 357 | **96.6 %** | 420 / 472 | 89.0 % |1088| `EngineFont` (`Sources/`, 6 files) | 1 190 / 1 247 | **95.4 %** | 230 / 264 | 87.1 % |1089| `EngineGeo` (`Sources/`, 16 files) | 4 399 / 4 577 | **96.1 %** | 677 / 799 | 84.7 % |1090| `EngineArchive` (`Sources/`, 9 files) | 2 392 / 2 573 | **93.0 %** | 363 / 422 | 86.0 % |1091| `EnginePDF` (`Sources/`, 12 files) | 3 285 / 3 494 | **94.0 %** | 397 / 484 | 82.0 % |10921093Coverage is `swift test --enable-code-coverage` (llvm-cov), debug build, counted on the package's own `Sources/` only. Not measured: `EngineImage`, `EngineModel3D`, `EngineScientific`, `EngineData`, `EngineDocuments`, `EngineVector`, `EngineMedia`, `ConvertKit`, and the app target.1094<!-- metrics:tests:end -->10951096**End-to-end sweep**10971098<!-- metrics:sweep:start -->1099| Paths | Passed | Failed | Crashed | Timed out | Skipped (no fixture) | Pairs verified | Chained plans run |1100|---:|---:|---:|---:|---:|---:|---:|---:|1101| 1 613 | **1 518** | 0 | 0 | 0 | 95 | 1 438 | 40 of 40 sampled passed |11021103Sweep of 2026-11-21 on Apple M5 Max, 18 cores, 48 GB (Mac17,6) (load average at start: 13.27). 22 of the passes needed a second fixture because the first one was legitimately refused. Skipped paths by source format: `bz2` 7, `dng` 20, `fbx` 11, `gz` 7, `kmz` 6, `rar` 10, `raw` 20, `xz` 7, `zst` 7.1104<!-- metrics:sweep:end -->11051106Also run: a mixed-batch robustness run (300 files — valid, garbage, empty, colliding names, one deleted while queued; every outcome matched the registry's prediction: [`docs/reports/mixed-batch.md`](docs/reports/mixed-batch.md)) and the offline proof ([`docs/reports/offline.md`](docs/reports/offline.md)).11071108**Not covered:** the interface itself has no automated UI test — interactive paths (drag and drop, panels, menus, keyboard navigation) were not hand-tested either; nothing was run on macOS 15 or 26; real-world files from other applications are represented only by what the generators and bundled tools can produce. More in [`docs/testing.md`](docs/testing.md).11091110## 31. Benchmarks11111112End-to-end figures: one `orix-convert convert` invocation per row, release build, the whole pipeline included.11131114> **Conditions.** The build machine is shared and was under load during every run (the 1-minute load average is in the table; the machine has 18 cores). Each case was run once. These are observations on a loaded machine — neither best cases nor averages — and they are valid for these generated inputs only.11151116<!-- metrics:benchmarks:start -->1117| Case | Input | Wall | Throughput | CPU | Peak RSS (tool) | Load avg (1 min) | Result |1118|---|---|---:|---|---:|---:|---:|---|1119| PNG → JPEG | 100 PNG, 4000 × 3000 (12 MP), 820.5 MB | 4.98 s | 20.1 images/s | 428 % | 1346 MB | 22.7 | ok — 100 file(s), 201.6 MB |1120| PNG → WebP | 100 PNG, 4000 × 3000 (12 MP), 820.5 MB | 11.47 s | 8.7 images/s | 593 % | 2045 MB | 21.77 | ok — 100 file(s), 53.6 MB |1121| PNG → SVG (image.vectorize) | 100 PNG, 4000 × 3000 (12 MP), 820.5 MB | 19.42 s | 5.1 images/s | 623 % | 2228 MB | 21.79 | **exit 1** (see the report) — 99 file(s), 172.2 MB |1122| HEIC → JPEG | 100 HEIC, 4000 × 3000 (12 MP), 75.8 MB | 5.07 s | 19.7 images/s | 320 % | 1042 MB | 27.67 | ok — 100 file(s), 194.5 MB |1123| 4K H.264 → HEVC (hardware encoder) | 3840 × 2160, 30 fps, 10 s, 36.5 MB | 3.54 s | 2.8 s of video/s | 292 % | 696 MB | 27.06 | ok — 1 file(s), 35.5 MB |1124| WAV → MP3 | 5 min, 44.1 kHz stereo 16-bit, 50.5 MB | 1.63 s | 184.0 s of audio/s | 123 % | 31 MB | 26.65 | ok — 1 file(s), 7.5 MB |1125| WAV → AAC (M4A) | 5 min, 44.1 kHz stereo 16-bit, 50.5 MB | 2.41 s | 124.5 s of audio/s | 113 % | 31 MB | 26.65 | ok — 1 file(s), 6.8 MB |1126| WAV → FLAC | 5 min, 44.1 kHz stereo 16-bit, 50.5 MB | 0.52 s | 576.9 s of audio/s | 165 % | 31 MB | 25.72 | ok — 1 file(s), 8.9 MB |1127| PDF → PNG, 150 dpi | 100 text pages, US Letter, 0.1 MB | 4.13 s | 24.2 pages/s | 96 % | 55 MB | 25.72 | ok — 100 file(s), 48.1 MB |1128| PDF OCR (pdf.ocr) | 20 page images at 150 dpi without text layer, 5.6 MB | 21.24 s | 0.9 pages/s | 44 % | 395 MB | 25.66 | ok — 1 file(s), 5.9 MB |1129| CSV → Parquet | 953.7 MB, 9 columns | 2.00 s | 476.9 MB of CSV/s | 473 % | 1136 MB | 21.57 | ok — 1 file(s), 129.4 MB |1130| DOCX → PDF | 16 KB DOCX made by the documents engine from generated Markdown (250 paragraphs, 10 tables) | 3.03 s | 13.2 pages/s | 89 % | 231 MB | 21.57 | ok — 1 file(s), 0.4 MB, 40 pages |1131| Folder → ZIP (archive.create) | 476.8 MB in 130 files: half repetitive text (very compressible), half pseudo-random bytes (incompressible) | 2.78 s | 171.5 MB/s | 95 % | 31 MB | 21.04 | ok — 1 file(s), 144.1 MB |1132| ZIP → folder (archive.extract) | ZIP of the same tree, 144.7 MB | 0.54 s | 883.0 MB/s | 85 % | 34 MB | 20.96 | ok — 130 file(s), 476.8 MB |11331134Run of 2026-11-21, release build, Apple M5 Max, 18 cores, 48 GB, macOS 27.0. One invocation per row, process start-up, validation of every output and the safe writer included.1135<!-- metrics:benchmarks:end -->11361137The vectorisation row ended with one failed file out of a hundred (“a contour leaves the viewBox”); the defect in the curve fitter was fixed afterwards ([vector notes](docs/compatibility/engines/vector.md)) and the benchmark has not been run again since. Per-engine measurements (codecs, memory, large files) are consolidated in [`docs/performance/benchmarks.md`](docs/performance/benchmarks.md); the generated report is [`docs/reports/benchmarks.md`](docs/reports/benchmarks.md).11381139## 32. Privacy11401141- **No network code of our own.** No first-party source file calls a networking API; the application has no account, no telemetry, no analytics, no crash reporter and no update check.1142- **Files are not uploaded.** Every conversion runs on the Mac, in the application or in a helper process it starts.1143- **Bundled binaries that contain networking code — blocked, not absent.** Pandoc contains an HTTP client; the DuckDB library imports socket functions; LibreOffice ships its own HTTP and TLS stack. They are prevented from using them: Pandoc and LibreOffice run with a proxy pointing at a closed local port and with remote content neutralised or link updates disabled; DuckDB runs with external access and extensions disabled and its configuration locked. The bundled FFmpeg is different: its network protocols are compiled out.1144- **WebKit** (a system framework with its own networking process) renders HTML and SVG with JavaScript disabled, content rules that block every URL except the document's own, and a navigation delegate that cancels anything else.1145- **Verified.** Under a sandbox profile that denies IP networking, one conversion per engine family succeeded; documents that reference a local canary server in every way their format allows were converted without the server receiving a single request. Method and results: [`docs/reports/offline.md`](docs/reports/offline.md).1146- **What is stored.** History (file paths, formats, options with secrets removed, results), presets, workflows and watch rules, on your Mac only. Passwords are never stored.11471148Details: [`docs/privacy.md`](docs/privacy.md).11491150## 33. Security11511152Files to convert are untrusted input. In short:11531154- **Bounded parsing.** Pixel, entry, size, depth, ratio and time limits in every engine; declared lengths are never trusted.1155- **Process isolation for the largest parsers.** FFmpeg, Pandoc, LibreOffice, Assimp and Model I/O, the HDF5 pre-check and the MIDI synthesiser run in helper processes started with argument arrays (no shell, no `PATH` lookup), one per job, terminated on cancel or time limit.1156- **Nothing in a document is executed.** Macros, JavaScript in PDFs and scripts in SVG or HTML are never run.1157- **Archives cannot write outside their destination.** Traversal, links, devices and bombs are tested with crafted archives.1158- **Safe output.** Results are verified in a private folder and moved with one atomic rename; a source file is never overwritten unless explicitly allowed.1159- **Hardened Runtime.** The application carries no entitlement; the nested LibreOffice carries a single one (`allow-jit`), which it needs to start. The application is not sandboxed, because it launches helper executables on arbitrary user files.11601161**Residual risks, stated plainly:** ImageIO, PDFKit, libwebp, libarchive, the woff2 decoder (last upstream release in 2017) and DuckDB parse in the application's process; HDF5 data blocks are read in-process after the helper's pre-check. The complete model, the tested attacks and these risks are in [`docs/security/security-model.md`](docs/security/security-model.md). To report a vulnerability, write to contact@spboucher.ai.11621163## 34. Accessibility11641165Implemented: labels, values and hints on the custom views (format badges, progress, drop zone, job rows, the comparison canvas, waveforms, workflow cards, rule cards); keyboard operation of the Prepare list, the Flow canvas and both studio canvases; colour is never the only signal (states, severities and fidelity pair a symbol and a word with their colour); stronger palette values with Increase Contrast; animations that stop or become static with Reduce Motion.11661167**Not verified:** VoiceOver has never been listened to on this application; the Increase Contrast and Reduce Motion paths exist in code but were not exercised on a running build; keyboard coverage of every control was not audited. What was verified, and how, is in [`docs/accessibility-report.md`](docs/accessibility-report.md).11681169## 35. Localization11701171English and French (Canada). Sizes, dates, numbers and durations use the system formatters.11721173<!-- metrics:localization:start -->1174| Strings | Count | With French (fr-CA) | Coverage |1175|---|---:|---:|---:|1176| Application interface | 1 191 | 1 191 | **100.0 %** |1177| Engine strings and message patterns (option labels, limitations, warnings, errors) | 3 751 | 3 751 | **100.0 %** |11781179Measured by `Scripts/localize.py --check` on 2026-11-21. An engine string without French is shown in English.1180<!-- metrics:localization:end -->11811182<p align="center"><img src="docs/screenshots/fr-smart-drop-light.png" width="88%" alt="The Smart Drop workspace in French (Canada): groups, warnings, options and the output bar are translated"></p>11831184The coverage above counts the strings the extraction script can see. About 850 longer engine messages built1185through local helper functions (some refusal reasons and error fragments, and the format detector's evidence such1186as "JPEG SOI marker") are outside that count and still appear in English in the French interface, as do composed1187inspection values. The command-line tool prints English. How strings are extracted and translated: [`docs/localization.md`](docs/localization.md).11881189## 36. Roadmap11901191Only items grounded in a known limitation; none is promised for a date.11921193- Run and verify on macOS 15 and macOS 26, starting with the PDFKit behaviours observed on macOS 27 only.1194- Test RAW, DNG, FBX and RAR on real-world files, then promote them from experimental or remove them.1195- A Finder Quick Action (an Action extension with its own sandboxed target).1196- JPEG XL, if a bundled encoder is justified.1197- Tabular sources → HDF5 and NetCDF.1198- Animated WebP export from video; subtitle burn-in (needs libass and a font stack).1199- Streaming for large geospatial datasets.1200- A VoiceOver pass with real listening, and a keyboard audit of every control.1201- Reduce the size of the application (the bundled LibreOffice and Pandoc are most of it).12021203## 37. Release Status12041205<!-- metrics:release:start -->1206| Stage | Status | Evidence |1207|---|---|---|1208| Built (Debug, Xcode 27.2, macOS 27.0) | yes — the screenshots and the self-test come from this build | `Scripts/build.sh debug` |1209| Built (Release, Developer ID) | yes — 1.0.0 (1) | `Scripts/build.sh release` |1210| Package tests | 958 passing, 0 package(s) failing | `docs/reports/tests.json` |1211| In-app self-test (Debug) | PASS — 142 passed, 0 failed | `docs/reports/selftest.json` |1212| In-app self-test (Release copy outside the repository) | SELFTEST RESULT: PASS (144 passed, 0 failed) | `ORIX_APP=… Scripts/build.sh selftest` |1213| End-to-end sweep | 1 518 passed, 0 failed, 95 skipped | `docs/reports/e2e-matrix.md` |1214| Signed (Developer ID, Hardened Runtime) | Developer ID Application (3YM54G49SN), Hardened Runtime | `codesign --verify --deep --strict` |1215| Notarization | accepted (submission: app e1e9a52f-0e8d-4aed-a6f0-e4955fa0a1e3, DMG ea046fda-4dd9-41ea-a4d6-d57ce2118475) | `notarytool` log |1216| Gatekeeper assessment | {'app': 'accepted — source=Notarized Developer ID', 'dmg': 'accepted — source=Notarized Developer ID', 'zip': 'accepted — source=Notarized Developer ID; stapled ticket validated', 'appInsideDmg': 'accepted — source=Notarized Developer ID'} | `spctl --assess` |1217| DMG | 258 MB — SHA-256 `60258e0318f7dfd3a9ea52810a4d40d085f964d30eab69f7a70048c9b73311f0` | release asset |1218| ZIP | 260 MB — SHA-256 `9ed9d0ff2487102b4fedf4fbba6f5604ff6d713001e5feafa226bca9be2194dd` | release asset |1219| Application size on disk | 849 MB | `du -sh` of the signed app |1220| Released | True (https://git.spboucher.ai/orix-convert/releases) | spbgit release page |1221| Tested on macOS 15.0 (the minimum) and macOS 26 | **no — never run there** | — |12221223Version 1.0.0 (build 1). Rows marked **pending** are filled from the facts `Scripts/release.sh` writes (`dist/release.json`, copied to `docs/reports/release.json`); until then nothing is claimed.1224<!-- metrics:release:end -->12251226The release report with the full evidence is [`RELEASE-REPORT.md`](RELEASE-REPORT.md); changes are listed in [`CHANGELOG.md`](CHANGELOG.md).12271228## 38. Known Limitations12291230Read this before relying on the application. Each engine note has the complete list for its formats; the items below are the ones most likely to matter.12311232**Platform and verification**12331234- **Tested on macOS 27 only.** The deployment target is macOS 15, but the application has never been run on macOS 15 or 26. Several PDFKit behaviours the PDF engine depends on were observed on macOS 27 only.1235- **Apple Silicon only.** There is no Intel build; the bundled libraries are built for arm64.1236- **Interactive paths were not hand-tested.** The interface is exercised by the in-app self-test (through the model code) and by self-screenshots; drag and drop, panels, menus and keyboard navigation were not tested by a person, and there is no automated UI test.1237- **VoiceOver has never been listened to**; Increase Contrast and Reduce Motion were not verified on a running build.1238- **No Finder extension.** The Services menu entry covers the same gesture; a Quick Action is not built.1239- **Application size.** The application is several hundred megabytes (the measured size is in [Release Status](#37-release-status)): the slimmed LibreOffice is about 460 MiB, Pandoc 188 MiB, DuckDB 62 MB, FFmpeg and ffprobe 56 MB. That is the cost of converting office formats with real layout without depending on software installed on the Mac.1240- **Fixtures are generated.** Tests use files produced in code or by the bundled tools. Files written by other applications, cameras and devices are expected to work where the same decoders apply, but are not claimed as verified.12411242**Experimental paths** (declared, but tested on a narrow corpus)12431244| Format | Why experimental |1245|---|---|1246| Camera RAW | no manufacturer RAW file was available; the paths are exercised with a generated DNG through the same decoder entry point; real CR2, CR3, NEF, ARW files are untested |1247| DNG | tested only with a linear (demosaiced) DNG generated in code; a mosaiced DNG generated the same way is rejected by Apple's decoder; camera DNGs are untested |1248| FBX (import only) | no FBX file from Maya, 3ds Max or Blender was available; the only evidence is a round trip through Assimp's own exporter and importer |1249| RAR (read only) | no free encoder exists to make varied fixtures; no encrypted RAR; RAR is never written |1250| PDF → Word / RTF | text reconstruction only, validated on one synthetic layout |1251| PPT media extraction | binary format, read only through LibreOffice |12521253The end-to-end sweep skips the paths whose source format has no fixture (RAW, DNG, FBX, RAR, KMZ, and the single-stream compression formats as sources); they are covered by package tests only.12541255**Not implemented**12561257| Area | Not available |1258|---|---|1259| Images | JPEG XL (read or write); RAW or DNG output; RAW development controls; HDR output to HEIC / AVIF; PSD layers; animated AVIF / HEIC output; choice of JPEG chroma subsampling; lossless JPEG optimisation; palette PNG output; images larger than memory |1260| Vector | gradients, strokes, centerline tracing, text recognition; EPS; compressed SVG (`.svgz`); transparent PDF pages from SVG |1261| Video | subtitle burn-in; animated WebP export; hardware decoding; AV1 / VP9 hardware encoding; deinterlacing, cropping, denoising, speed change; Dolby Vision and HDR10+ metadata; stream copy into AVI; WMV9 / VC-1 encoding |1262| Audio | user SoundFonts for MIDI; WMA Pro / Lossless, DTS, E-AC-3, TrueHD encoding; artwork in Ogg, WAV, CAF, WMA, ADTS |1263| Documents | Pages, Keynote and Numbers documents; LaTeX → PDF; presentation → HTML; RTFD; images written next to Markdown / LaTeX output |1264| PDF | PDF → HTML; PDF/A, PDF/X, linearised output; redaction; form flattening; cropping, N-up, watermarks, page numbers; preserving tags, attachments or signatures through page operations; removing restrictions without the owner password (by design) |1265| Spreadsheets and data | formula evaluation and formula output; styles, charts, comments; XLSB; password-protected workbooks; Zstandard-compressed Arrow buffers; SQLite → SQLite and DuckDB → DuckDB |1266| Archives | RAR creation; 7z and RAR decryption, 7z encryption; multi-volume archives; ISO, CAB, XAR, cpio; updating an archive in place; restoring extended attributes |1267| 3D | FBX export; animations, skins, morph targets, cameras, lights; quads (always triangulated); point clouds and line sets; Draco and meshopt; KTX2 / Basis textures; Alembic |1268| Fonts | TTF ↔ OTF outline conversion; subsetting; hinting changes; instancing variable fonts; writing collections; EOT, Type 1 |1269| Subtitles | TTML, SBV, LRC, SAMI, SCC, EBU STL, VobSub; ASS rendering semantics; language detection |1270| Ebooks | MOBI, AZW, KFX; books with DRM (refused by design) |1271| Geospatial | GDAL / PROJ-grade reprojection (a small tested set only); streaming; KMZ or zipped-shapefile output; rasters, tiles, coverages; TopoJSON; topology repair |1272| Scientific | tabular → HDF5 / NetCDF (not offered); szip and third-party filters; Arrow output; region and object references |1273| Application | pausing a running job (only cancel — engines have no suspension point); estimated output size; watching while the application is closed; a layered icon for the macOS 26+ appearance modes |12741275**Known defects and caveats**12761277- The data engine's cancellation test (CSV → Parquet) is timing-sensitive: under heavy load the conversion can finish before the cancellation is seen. See [Testing](#30-testing) for what happened in the recorded run.1278- LibreOffice can write a wrong text layer for a ligature with some substituted fonts (the page renders correctly; searching that word is affected).1279- 7z creation spools its compressed stream in an unlinked temporary file outside the job's work folder; the space is needed twice during the job.1280- Remuxing AAC into MP4 / MOV can omit a final padding-only frame (no audible sample is lost).1281- Dolby Vision profile 5 sources are not detected specially; their colours come out wrong.1282- “Fast” OCR was not faster than “accurate” in the measurements on macOS 27.1283- Validation re-reads the whole output; for large spreadsheets, KML and multi-million-triangle USDZ files it costs as much time or memory as the conversion.1284- The generated offline report predates the last changes of the registry; the checks it describes were not run again since.12851286## 39. ORIX Ecosystem12871288ORIX Convert belongs to a family of native Apple applications by the same author, all local-first. The repositories below are public on this forge.12891290| Application | What it is |1291|---|---|1292| [ORIX Clean](https://git.spboucher.ai/orix-clean) | macOS storage analyzer and cleanup utility |1293| [ORIX Sheet](https://git.spboucher.ai/orix-sheet) | macOS spreadsheet, financial-modelling and data-analysis workstation |1294| [ORIX Docs](https://git.spboucher.ai/orix-docs) | macOS word processor |1295| [ORIX Monitor](https://git.spboucher.ai/orix-monitor) | macOS system monitor |1296| [ORIX Scan](https://git.spboucher.ai/orix-scan) | iOS document scanner with on-device OCR |1297| [ORIX Calc](https://git.spboucher.ai/orix-calc) | iOS and iPadOS calculator |1298| [ORIX Audio](https://git.spboucher.ai/orix-audio) | iOS recorder with analysis and on-device transcription |1299| [ORIX Secure](https://git.spboucher.ai/orix-secure) | iOS security, privacy and diagnostics utility |1300| [ORIX Arcade](https://git.spboucher.ai/orix-arcade) | offline games for iPhone |13011302Product pages: [orix.spboucher.ai](https://orix.spboucher.ai).13031304## 40. License13051306ORIX Convert is proprietary software — © 2026 Simon-Pierre Boucher, all rights reserved; see [`LICENSE`](LICENSE). The source is published for reading; no licence to use, copy, modify or distribute it is granted without written permission.13071308Bundled third-party components keep their own licences. Their texts and notices ship inside the application (`Contents/Resources/Licenses`, and LibreOffice's own inside its bundle) and are listed in Settings › About.13091310| Component | Version | Licence | How it is shipped |1311|---|---|---|---|1312| FFmpeg (`ffmpeg`, `ffprobe`) with LAME | 9.1 / 3.100 | LGPL-2.1-or-later (LAME: LGPL-2.0-or-later) | separate, replaceable executables; build script and pinned sources published |1313| libopus, libogg, libvorbis, libvpx, SVT-AV1, dav1d, zimg | see the notice | BSD-3-Clause, BSD-2-Clause, BSD-3-Clause-Clear, WTFPL | static, inside the FFmpeg executables |1314| Pandoc | 3.14 | GPL-2.0-or-later | separate, unmodified executable run as its own process; written offer for the source |1315| LibreOffice | 26.8.3 | MPL-2.0, with third-party notices | separate, slimmed application bundle run as its own process |1316| DuckDB | 2.0.1 | MIT | dynamic library |1317| libarchive, liblzma, libzstd | 3.8.11, 5.8.4, 1.5.7 | BSD-2-Clause, 0BSD, BSD-3-Clause | static library |1318| libwebp | 1.6.0 | BSD-3-Clause | static library |1319| Assimp (with pugixml, RapidJSON, minizip, miniz, utf8cpp, poly2tri, clipper, openddlparser) | 6.0.2 | BSD-3-Clause (contrib: MIT, zlib, BSL-1.0, Unlicense) | static library |1320| HDF5 | 2.2.0 | BSD-3-Clause | static library |1321| google/woff2, Brotli | 1.0.2, 1.2.1 | MIT | static library |1322| Yams (with libyaml) | 6.2.2 | MIT | compiled from source by SwiftPM |13231324Sources, pinned hashes, obligations and how the application meets them: [`docs/licenses/dependency-license-report.md`](docs/licenses/dependency-license-report.md).13251326---13271328<p align="center">© 2026 Simon-Pierre Boucher — <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></p>1329
Files main
Menu

Theme