Repository Public License
1# `orix-convert` — the ORIX Convert engines on the command line23`orix-convert` is the command-line front end of ORIX Convert. It uses exactly what the app uses: the same engines, the same4registry, planner, queue, validation and safe writer (`Packages/ConvertKit` assembles them). Everything runs on this Mac; the tool5has no network code of its own and never looks for software in `PATH`, Homebrew or `/Applications`.67Every example below was executed; the output is pasted as printed (long listings are cut, with the number of lines left out; the8repository path is shown as `<repo>`). The demonstration files (`photo.png`, `notes.md`, `table.csv`, `a.pdf`, `b.pdf`, `tone.wav`)9were generated by the tool itself.1011## Building and running1213```14cd Packages/ConvertKit15swift build --build-system native -c release --product orix-convert16swift build --build-system native -c release --product orix-model3d-helper # helper started by the 3D engine17.build/release/orix-convert help18swift test --build-system native19```2021`--build-system native` is required for now: with SwiftPM's default build system, the binary targets of several engine packages22(`CDuckDB`, `CArchive`, `CWebP`, `CAssimp`) each install a `module.modulemap` at the same path and the build stops with23"Multiple commands produce …/include/module.modulemap".2425In the app bundle the tool is `ORIX Convert.app/Contents/Helpers/orix-convert`. At start-up it points `ORIX_CONVERT_TOOLS` at its own26folder when that folder holds bundled tools (ffmpeg, pandoc, `LibreOffice.app`…), so the engines find them next to it; its dynamic27library (`libduckdb.dylib`) is looked for next to the tool and in `Contents/Frameworks`. In a development build the tools come from28`EmbeddedEngines/tools`. `orix-convert doctor` shows what was found and where.2930```31$ orix-convert help32orix-convert 1.0.0 — the ORIX Convert engines on the command line. Everything runs on this Mac.3334Usage: orix-convert <command> [options]3536Commands:37 formats Formats with at least one real conversion path.38 paths The capability matrix: every declared conversion path.39 detect Identify files from their content.40 inspect Metadata of a file, read by the engine that knows its format.41 plan Show how a file would be converted, before converting it.42 options Settings offered by a conversion path.43 convert Convert files (real queue, validation, safe writer).44 workflow Run or validate a Conversion Flow file (JSON).45 presets Saved presets (the file shared with the app).46 doctor Engines, bundled tools and their versions; checks nothing comes from outside.47 matrix Generate the conversion matrix; --verify runs every path end to end.4849Run 'orix-convert help <command>' for the options of a command.50Exit status: 0 done · 1 a conversion failed · 2 usage · 3 input missing or unrecognised · 4 unsupported conversion ·51 5 destination exists (--on-conflict fail) · 6 a check failed · 130 interrupted.52```5354Exit status: 0.555657## Exit status5859| Status | Meaning |60|---:|---|61| 0 | Everything asked for was done. Files left alone by `--on-conflict skip` count as done. |62| 1 | At least one conversion failed (the others were delivered), or a verification run found a failure. |63| 2 | The command line is wrong: unknown command or option, missing value, unknown format, option value out of range. |64| 3 | Input problem: a file does not exist, cannot be read or is of unrecognised format — and no job succeeded for another reason. |65| 4 | Unsupported: no engine converts that source to that destination (every failed job failed for that reason). |66| 5 | The destination exists and `--on-conflict fail` was given (every failed job failed for that reason). |67| 6 | A check found a problem: `doctor`, `workflow validate`, an unreadable preset file. |68| 130 | Interrupted (Ctrl-C or SIGTERM): running jobs were cancelled, their temporary folders removed. A second Ctrl-C exits at once. |6970Errors go to standard error; results (text or JSON) to standard output. `--json` output is one JSON document with sorted keys.7172## `formats` — what can be read and written7374`formats [--category <category>] [--json]` lists the formats that have at least one real path in this build.7576```77$ orix-convert formats --category font78FORMAT NAME CATEGORY EXTENSIONS READ WRITE TO FROM OPS79------ ------------- -------- ---------- ---- ----- -- ---- ---80ttf TrueType Font font ttf yes yes 14 2 381otf OpenType Font font otf yes yes 13 2 282woff WOFF font woff yes yes 14 3 283woff2 WOFF2 font woff2 yes yes 14 3 284854 format(s) with at least one path. TO = destinations reachable from the format, FROM = sources that can become it.86```8788Exit status: 0.899091```92$ orix-convert formats --category subtitle --json93{94 "count" : 5,95 "formats" : [96 {97 "category" : "subtitle",98 "destinations" : 16,99 "extensions" : [100 "srt"101 ],102 "id" : "srt",103 "name" : "SubRip",104 "operations" : 4,105 "readable" : true,106 "sources" : 10,107 "writable" : true108 },109 {110 "category" : "subtitle",111 "destinations" : 16,112 "extensions" : [113 "vtt"114 ],115 "id" : "vtt",116 "name" : "WebVTT",117… (46 more lines)118```119120Exit status: 0.121122123## `paths` — the capability matrix124125`paths [--from X] [--to Y] [--engine E] [--operation OP] [--json]` prints the declared paths, straight from the registry.126127```128$ orix-convert paths --from png --to pdf129SOURCE DESTINATION OPERATION ENGINE STATUS FIDELITY PRESERVES130------ ----------- --------------- ------ --------- -------- -----------------------131png pdf — pdf supported lossless dimensions,transparency132png pdf image.vectorize vector supported lossy dimensions,transparency1331342 path(s).135```136137Exit status: 0.138139140```141$ orix-convert paths --from srt --to vtt --json142{143 "count" : 1,144 "paths" : [145 {146 "acceptsMultipleSources" : false,147 "destination" : "vtt",148 "engine" : "subtitle",149 "fidelity" : "structural",150 "limitations" : [151 "WebVTT has no font tag and no strike-through; colours are written as cue classes with a STYLE block."152 ],153 "preserves" : [154 "textStyles",155 "timing"156 ],157 "source" : "srt",158 "status" : "supported"159 }160 ],161 "unavailable" : [162163 ]164}165```166167Exit status: 0.168169170## `detect` — identify files from their content171172`detect <files…> [--json]`. The extension is only a hint; a name that contradicts the content is reported as a mismatch.173174```175$ orix-convert detect photo.png mislabeled.jpg notes.md table.csv a.pdf tone.wav176photo.png: png (PNG) — certain — PNG signature177mislabeled.jpg: png (PNG) — certain — PNG signature; extension .jpg says jpeg — MISMATCH: the name says .jpg178notes.md: markdown (Markdown) — likely — Markdown constructs: heading179table.csv: csv (CSV) — likely — consistent comma-separated columns180a.pdf: pdf (PDF) — certain — PDF header181tone.wav: wav (WAV) — certain — RIFF/WAVE container182```183184Exit status: 0.185186187```188$ orix-convert detect mislabeled.jpg --json189[190 {191 "category" : "image",192 "confidence" : "certain",193 "evidence" : "PNG signature; extension .jpg says jpeg",194 "extensionFormats" : [195 "jpeg"196 ],197 "fileExtension" : "jpg",198 "format" : "png",199 "formatName" : "PNG",200 "isDirectory" : false,201 "mismatch" : true,202 "path" : "/tmp/orix-demo/mislabeled.jpg"203 }204]205```206207Exit status: 0.208209210## `inspect` — metadata read by the engines211212`inspect <file> [--json]`: generic file facts, then what the engine in charge of the format really read. A value that could not be213read is absent, never guessed.214215```216$ orix-convert inspect photo.png217photo.png218219File220 Format PNG221 Detection certain: PNG signature222 Size 1613857 bytes223 Created 2026-11-21T17:21:26Z224 Modified 2026-11-21T17:21:26Z225 Permissions 644226 Type identifier public.png227 Quarantine attribute Absent228 Download origin attribute Absent229230General231 Type identifier public.png232 Dimensions 1600 × 1200233 Orientation 1234 File size 1613857235236Color237 Model RGB238 ICC profile sRGB IEC61966-2.1239 Bits per component 8240241EXIF242 ColorSpace 1243 PixelXDimension 1600244 PixelYDimension 1200245246PNG247 Chromaticities 0.3127, 0.329, 0.64, 0.33, 0.3, 0.6000000000000001, 0.15, 0.06248 Gamma 0.45455249 InterlaceType 0250 sRGBIntent 0251252XMP253 exif:ColorSpace 1254 exif:PixelXDimension 1600255 exif:PixelYDimension 1200256257Read by engine 'image'.258```259260Exit status: 0.261262263```264$ orix-convert inspect tone.wav --json265{266 "detection" : {267 "category" : "audio",268 "confidence" : "certain",269 "evidence" : "RIFF/WAVE container",270 "extensionFormats" : [271 "wav"272 ],273 "fileExtension" : "wav",274 "format" : "wav",275 "formatName" : "WAV",276 "isDirectory" : false,277 "mismatch" : false,278 "path" : "/tmp/orix-demo/tone.wav"279 },280 "engine" : "audio",281 "inspection" : {282 "audioCodec" : "pcm_s16le",283 "bitDepth" : 16,284 "bitRate" : 1411317,285 "channels" : 2,286 "durationSeconds" : 3,287 "fields" : [288 {289 "group" : "File",290 "key" : "Format",291 "value" : "WAV"292 },293 {294 "group" : "File",295 "key" : "Detection",296 "value" : "certain: RIFF/WAVE container"297 },298 {299 "group" : "File",300 "key" : "Size",301 "value" : "529244 bytes"302 },303 {304 "group" : "File",305… (98 more lines)306```307308Exit status: 0.309310311## `plan` — what would happen to this file312313`plan <file> --to <format> [--operation OP] [--engine E] [--option key=value …] [--json]` shows the route (direct, or chained through314an intermediate file), the fidelity, what is preserved, the limitations the user must know, and the engine's warnings for this315particular file.316317```318$ orix-convert plan photo.png --to jpeg319photo.png: png (certain: PNG signature)320Plan: png → jpeg — direct321 1. png → jpeg with engine 'image' — supported, lossy322Fidelity: lossy Status: supported323Preserves: colorProfile, dimensions, metadata324Limitations:325 - Lossy compression; the PSNR of the result is measured.326 - JPEG has no transparency: transparent areas are filled with the background colour.327 - Samples deeper than 8-bit are reduced to 8-bit.328 - Largest side: 65535 pixels.329Preflight warnings for this file: none.330```331332Exit status: 0.333334335A pair with no direct path is bridged in two steps when the planner finds a route:336337```338$ orix-convert plan notes.md --to png339notes.md: markdown (likely: Markdown constructs: heading)340Plan: markdown → pdf → png — chained, 2 steps through an intermediate file341 1. markdown → pdf with engine 'documents' — supported, structural342 2. pdf → png with engine 'pdf' — supported, lossy343Fidelity: lossy Status: supported Heavy job (limited concurrency)344Preserves: —345Limitations:346 - Rendered by WebKit with JavaScript disabled and without any network access: remote images, fonts and stylesheets are missing.347 - Typeset with ORIX Convert's built-in print stylesheet; this is a reflowed rendering, not the source's own page design.348 - No table structure, bookmarks or tagged-PDF accessibility information.349 - Pages become flat images: text is no longer selectable and links, form fields and the outline are gone.350 - Several pages produce a folder with one image per page (or one multi-page TIFF when that option is on).351 - A page above 256 megapixels or 32000 pixels a side is rendered at a lower resolution, with a warning.352Preflight warnings for this file: none.353```354355Exit status: 0.356357358```359$ orix-convert plan tone.wav --to docx360orix-convert: Converting WAV to DOCX is not supported. wav converts to: mp3, m4a, wav, flac, aiff, ogg, opus, alac, caf, aac, wma.361```362363Exit status: 4.364365366## `options` — settings of a path367368`options --from X --to Y [--operation OP] [--engine E] [--json]` prints the option descriptors the app builds its panels from: key,369type, range or choices, default, help.370371```372$ orix-convert options --from png --to jpeg373png → jpeg — engine 'image'374375--option quality=<integer 1…100> default: 85376 Quality · Quality — Encoder quality, 1 (smallest) to 100 (best).377--option target.size-kb=<number 0.0…1000000.0 kB> default: 0.0378 Quality · Target file size — When above 0, the highest quality whose file fits in this size is found by encoding and measuring.379--option jpeg.progressive=<bool> default: false [advanced]380 Quality · Progressive — Write a progressive JPEG.381--option resize.mode=<choice {none|fit|fill|exact|percent|long-edge}> default: none382 Size · Resize383--option resize.width=<integer 0…100000 px> default: 0384 Size · Width385--option resize.height=<integer 0…100000 px> default: 0386 Size · Height387--option resize.percent=<number 1.0…1000.0 %> default: 100.0388 Size · Percentage389--option resize.long-edge=<integer 0…100000 px> default: 0390 Size · Long edge391--option resize.upscale=<bool> default: false392 Size · Allow enlarging — Without it, “fit” and “long edge” never make an image larger.393--option crop.mode=<choice {none|rect|aspect}> default: none394 Size · Crop395--option crop.x=<integer 0…1000000 px> default: 0 [advanced]396 Size · Crop left397--option crop.y=<integer 0…1000000 px> default: 0 [advanced]398 Size · Crop top399--option crop.width=<integer 0…1000000 px> default: 0 [advanced]400 Size · Crop width401--option crop.height=<integer 0…1000000 px> default: 0 [advanced]402 Size · Crop height403--option crop.aspect=<text> default: 1:1 [advanced]404 Size · Aspect ratio405--option rotate.angle=<number -360.0…360.0 °> default: 0.0406 Size · Rotate — Clockwise, in degrees. Multiples of 90° move pixels without resampling.407--option flip.horizontal=<bool> default: false408 Size · Flip horizontally409--option flip.vertical=<bool> default: false410 Size · Flip vertically411--option orientation.normalize=<bool> default: true [advanced]412 Size · Apply EXIF orientation — Turn the pixels upright and reset the orientation tag.413--option color.profile=<choice {keep|srgb|display-p3|adobe-rgb|gray}> default: keep414 Colour · Colour profile — Conversions are colour-managed (ColorSync).415--option background.color=<text> default: #FFFFFF416 Colour · Background colour — Used when transparency has to be flattened.417--option metadata=<choice {keep|strip-location|strip}> default: keep418 Metadata · Metadata419--option watermark.text=<text> default: (empty)420 Watermark · Watermark text421--option watermark.image=<text> default: (empty)422 Watermark · Watermark image — Path of an image file to overlay.423--option watermark.position=<choice {top-left|top|top-right|left|center|right|bottom-left|bottom|bottom-right}> default: bottom-right424 Watermark · Position425--option watermark.opacity=<number 0.0…100.0 %> default: 50.0426 Watermark · Opacity427--option watermark.scale=<number 1.0…100.0 %> default: 25.0428 Watermark · Width — Width of the watermark as a share of the image width.429--option watermark.margin=<number 0.0…50.0 %> default: 3.0430 Watermark · Margin — Distance from the edges as a share of the shorter side.431--option watermark.color=<text> default: #FFFFFF [advanced]432 Watermark · Text colour433--option limit.megapixels=<integer 1…4000 MP> default: 400 [advanced]434 Safety · Pixel limit — Images that would decode to more pixels are refused (protection against decompression bombs).435--option verify.measure=<bool> default: true [advanced]436 Safety · Measure the result — Decode the written file and report whether its pixels are identical, or the PSNR.437```438439Exit status: 0.440441442```443$ orix-convert options --from pdf --to png --json444{445 "chained" : false,446 "destination" : "png",447 "engine" : "pdf",448 "options" : [449 {450 "advanced" : false,451 "defaultValue" : "",452 "group" : "Pages",453 "help" : "Pages to export; leave empty for all. Example: 1-3,7,10- (10- means page 10 to the end).",454 "key" : "pages",455 "label" : "Pages",456 "placeholder" : "All pages",457 "secret" : false,458 "type" : "text"459 },460 {461 "advanced" : false,462 "defaultValue" : "150",463 "group" : "Size",464 "key" : "resolution.dpi",465 "label" : "Resolution",466 "maximum" : 2400,467 "minimum" : 18,468 "secret" : false,469 "type" : "integer",470 "unit" : "dpi"471 },472 {473 "advanced" : false,474 "defaultValue" : "0",475 "group" : "Size",476 "help" : "When above 0, each page is rendered this many pixels wide and the resolution is ignored.",477 "key" : "resize.width",478 "label" : "Width in pixels",479 "maximum" : 32000,480… (87 more lines)481```482483Exit status: 0.484485486## `convert` — convert files487488```489$ orix-convert help convert490Convert files (real queue, validation, safe writer).491492Usage: orix-convert convert <files…> --to <format> [--operation <op>] [--option key=value …] [--output-dir <dir> | --output <file>] [--name-template <t>] [--on-conflict rename|skip|replace|fail] [--jobs <n>] [--recursive] [--combine] [--from <format>] [--engine <id>] [--json] [--quiet] [--verbose] [--no-history]493494 --to <format> destination format (identifier or extension: jpeg, jpg, pdf, folder…)495 --operation <op> named operation (pdf.merge, image.vectorize, video.extract-audio…); see 'paths'496 --option key=value a setting of the path (see 'options'); repeatable. For a key containing 'password',497 the value @env:NAME reads an environment variable and @stdin reads standard input498 --output-dir <dir> write there (created if needed); default: next to each source499 --output <file> exact output file, for a single job500 --name-template <t> tokens {name} {ext} {date} {counter} {counter:3} {width} {height}; default {name}501 --on-conflict <policy> rename (default: 'name 2.ext'), skip, replace, or fail. Nothing is ever overwritten502 without 'replace'; a source file is never replaced503 --jobs <n> conversions running at once (default: performance cores, at most 8)504 --recursive convert the files inside the given folders (hidden files and links skipped)505 --combine one job from all the files, for paths taking several sources (images → PDF);506 implied by --operation when that operation takes several sources507 --from <format> do not detect: treat the sources as this format508 --engine <id> force one engine's direct path509 --no-chain refuse two-step plans510 --json print one JSON document (summary + every job) instead of text511 --quiet print only failures512 --verbose print every validation check and measured fact513 --no-history do not open or write the history database514```515516Exit status: 0.517518519Each file is a job of the real queue: detection, plan, engine, generic validation, the engine's own validation, then an atomic move to520the destination. On a terminal a progress line is drawn on standard error; a percentage appears only when the engine measured one,521otherwise the line says that progress is not measurable.522523```524$ orix-convert convert photo.png --to jpeg --option quality=80 --output-dir out525ok photo.png → /private/tmp/orix-demo/out/photo.jpg (png → jpeg, image, 1.6 MB → 448.8 KB, 0.70 s)526 validated: 8 check(s) passed (alpha, decodes, dimensions, format limit, frame count, output.format, output.not-empty, pixels)527Summary: 1 job(s) — 1 converted, 0 failed, 0 skipped — 1.6 MB in, 448.8 KB out — 0.70 s528```529530Exit status: 0.531532533```534$ orix-convert convert photo.png pics --recursive --to webp --output-dir out --name-template "{counter:2}-{name}-{width}x{height}" --verbose535ok image-0002.png → /tmp/orix-demo/out/02-image-0002-1600x1200.webp (png → webp, image, 1.7 MB → 161.8 KB, 0.82 s)536 check passed output.not-empty: 02-image-0002-1600x1200.webp: 161846 bytes537 check passed output.format: 02-image-0002-1600x1200.webp: detected webp (RIFF/WEBP container).538 check passed decodes: Decoded by libwebp 1.6.0: 1 image(s).539 check passed dimensions: Output 1600×1200; expected 1600×1200.540 check passed frame count: 1 image(s) in the output; expected 1.541 check passed format limit: Largest side 1600 px; WEBP allows 16383.542 check passed pixels: Lossy encoding: PSNR 36.17 dB against the pixels given to the encoder (measured during conversion).543 fact alpha = no544 fact bits = 8545 fact bytes = 161846546 fact color.space = SRGB547 fact encoder = libwebp 1.6.0548 fact frames = 1549 fact height = 1200550 fact metadata.exif = 1 fields551 fact metadata.gps = none552 fact metadata.iptc = none553 fact metadata.xmp = 3 tags554 fact psnr.db = 36.17555 fact quality = 80556 fact source.height = 1200557… (63 more lines)558```559560Exit status: 0.561562563Nothing is overwritten unless asked: the default policy numbers the new file.564565```566$ orix-convert convert photo.png --to jpeg --output-dir out567ok photo.png → /tmp/orix-demo/out/photo 2.jpg (png → jpeg, image, 1.6 MB → 513.6 KB, 0.76 s)568 renamed: /tmp/orix-demo/out/photo 2.jpg569 validated: 8 check(s) passed (alpha, decodes, dimensions, format limit, frame count, output.format, output.not-empty, pixels)570Summary: 1 job(s) — 1 converted, 0 failed, 0 skipped — 1.6 MB in, 513.6 KB out — 0.76 s571```572573Exit status: 0.574575576```577$ orix-convert convert photo.png --to jpeg --output-dir out --on-conflict fail578FAILED photo.png: /tmp/orix-demo/out/photo.jpg already exists. Nothing was written (use --on-conflict rename, skip or replace).579Summary: 1 job(s) — 0 converted, 1 failed, 0 skipped — 0.01 s580```581582Exit status: 5.583584585```586$ orix-convert convert photo.png --to jpeg --output-dir out --on-conflict skip587skipped photo.png: Skipped: photo.jpg already exists in the destination folder.588Summary: 1 job(s) — 0 converted, 0 failed, 1 skipped — 0.01 s589```590591Exit status: 0.592593594```595$ orix-convert convert photo.png --to jpeg --output-dir out --on-conflict replace --quiet596597```598599Exit status: 0.600601602Operations taking several sources make one job (`--operation pdf.merge`); `--output` names the result:603604```605$ orix-convert convert a.pdf b.pdf --to pdf --operation pdf.merge --output merged.pdf606ok a.pdf (+1 more) → /private/tmp/orix-demo/merged.pdf (pdf → pdf [pdf.merge], pdf, 37.2 KB → 36.3 KB, 0.06 s)607 validated: 6 check(s) passed (PDF reopens, merge order, outline, output.format, output.not-empty, page count)608Summary: 1 job(s) — 1 converted, 0 failed, 0 skipped — 37.2 KB in, 36.3 KB out — 0.06 s609```610611Exit status: 0.612613614A chained conversion reports the checks of both steps:615616```617$ orix-convert convert notes.md --to png --output-dir pages --verbose618ok notes.md → /private/tmp/orix-demo/pages/notes (markdown → png, chained: documents + pdf, 5.8 KB → 613.8 KB, 0.63 s)619 check passed step1.output.not-empty: notes.pdf: 23603 bytes620 check passed step1.output.format: notes.pdf: detected pdf (PDF header).621 check passed step1.PDF opens: 2 page(s)622 check passed step1.At least one page: 2623 check passed step1.Output re-opens: 978 words624 check passed step1.Source text present: 8/8 probe words found625 check passed step2.output.not-empty: notes: 2 file(s)626 check passed step2.output.no-symlink-escape: No link leaves the folder.627 check passed step2.image count: 2 image(s) for 2 selected page(s).628 check passed step2.pixel dimensions: Every image has the expected size (first: 1240 × 1754).629 fact dpi = 150.0630 fact files = 2631 fact height = 1754632 fact pages = 2633 fact width = 1240634… (1 more lines)635```636637Exit status: 0.638639640Failures are per file; the status tells whether anything failed:641642```643$ orix-convert convert photo.png tone.wav missing.png --to pdf --output-dir out644FAILED missing.png: The file could not be read. missing.png no longer exists.645FAILED tone.wav: Converting WAV to PDF is not supported.646ok photo.png → /tmp/orix-demo/out/photo.pdf (png → pdf, pdf, 1.6 MB → 1.6 MB, 0.11 s)647 validated: 5 check(s) passed (PDF reopens, image embedded, output.format, output.not-empty, page count)648Summary: 3 job(s) — 1 converted, 2 failed, 0 skipped — 1.6 MB in, 1.6 MB out — 0.11 s649```650651Exit status: 1.652653654`--json` prints one document: the summary, then every job with its outputs, warnings, validation checks, measured facts and error.655656```657$ orix-convert convert table.csv --to parquet --output-dir out --json658{659 "jobs" : [660 {661 "bytesAfter" : 2808,662 "bytesBefore" : 4120,663 "chained" : false,664 "checks" : [665 {666 "detail" : "table.parquet: 2808 bytes",667 "name" : "output.not-empty",668 "passed" : true669 },670 {671 "detail" : "table.parquet: detected parquet (PAR1 header and footer).",672 "name" : "output.format",673 "passed" : true674 },675 {676 "detail" : "The output opens as Parquet with 1 table.",677 "name" : "reopen",678 "passed" : true679 },680 {681 "detail" : "33 rows read back, as written.",682 "name" : "row-count",683 "passed" : true684 },685 {686 "detail" : "9 columns read back.",687 "name" : "column-count",688 "passed" : true689 },690 {691 "detail" : "Column names read back identical.",692 "name" : "column-names",693 "passed" : true694 },695 {696 "detail" : "297 cells of the first 1000 rows read back equal to the source.",697 "name" : "sample-values",698 "passed" : true699 }700 ],701 "destinationFormat" : "parquet",702 "engines" : [703 "data"704 ],705 "facts" : {706 "columns" : "9",707 "engine" : "DuckDB v2.0.1",708 "rows" : "33",709 "tables" : "1"710 },711 "outputs" : [712 {713 "outcome" : "written",714 "path" : "/tmp/orix-demo/out/table.parquet"715 }716 ],717 "seconds" : 0.12321305274963379,718 "sourceFormat" : "csv",719 "sources" : [720 "/tmp/orix-demo/table.csv"721 ],722 "state" : "finished",723 "warnings" : [724725 ]726 }727 ],728… (16 more lines)729```730731Exit status: 0.732733734Option values are checked against the path's descriptors before anything runs:735736```737$ orix-convert convert photo.png --to jpeg --option quality=900738orix-convert: --option quality: expected a whole number between 1 and 100, not '900'.739```740741Exit status: 2.742743744### Passwords745746For an option whose key contains `password`, the value can come from an environment variable (`@env:NAME`) or from standard input747(`@stdin`, one line), so that it never appears in the process list. A password typed directly on the command line works too, with a748warning. Passwords are never printed and never written to the history (`@@text` gives a literal value starting with `@`).749750```751$ orix-convert convert a.pdf --to txt --output-dir out --option password=@env:PDF_PASSWORD752ok a.pdf → /tmp/orix-demo/out/a.txt (pdf → txt, pdf, 17.7 KB → 6.5 KB, 0.04 s)753 validated: 4 check(s) passed (output.format, output.not-empty, text decodes, text probes)754Summary: 1 job(s) — 1 converted, 0 failed, 0 skipped — 17.7 KB in, 6.5 KB out — 0.04 s755```756757Exit status: 0.758759760```761$ echo "example-only" | orix-convert convert a.pdf --to txt --output-dir out --option password=@stdin --quiet762763```764765Exit status: 0.766767768```769$ orix-convert convert a.pdf --to txt --output-dir out --option password=@env:NOT_SET770orix-convert: --option password=@env:NOT_SET: the environment variable NOT_SET is not set.771```772773Exit status: 2.774775776### History777778Ended jobs are recorded in the same history database as the app (`~/Library/Application Support/ORIX Convert/history.sqlite`, or779`$ORIX_CONVERT_SUPPORT_DIR`); file contents and secret options are never stored. `--no-history` neither opens nor writes it (the780examples of this page were run with `ORIX_CONVERT_SUPPORT_DIR` pointing at a scratch folder).781782## `workflow` — Conversion Flow files783784`workflow example` prints a complete file (the core's `Workflow` model as JSON); `workflow validate` checks it against the live785registry; `workflow run` applies it to files through the queue.786787```788$ orix-convert workflow example789{790 "errorPolicy" : "stopItem",791 "id" : "00000000-0000-4000-8000-000000000001",792 "name" : "Web images",793 "nodes" : [794 {795 "filter" : {796 "_0" : {797 "categoryIs" : {798 "_0" : "image"799 }800 }801 }802 },803 {804 "branch" : {805 "condition" : {806 "width" : {807 "_0" : "greaterThan",808 "_1" : 1600809 }810 },811 "otherwise" : [812 {813 "convert" : {814 "destination" : "webp",815 "options" : {816 "values" : {817818 }819 }820 }821 }822 ],823 "then" : [824 {825 "convert" : {826 "destination" : "jpeg",827 "options" : {828 "values" : {829 "quality" : {830 "int" : {831 "_0" : 82832 }833 },834 "resize.width" : {835 "int" : {836 "_0" : 1600837 }838 }839 }840 }841 }842 },843 {844 "rename" : {845 "template" : "{name}-web"846 }847 }848 ]849… (11 more lines)850```851852Exit status: 0.853854855```856$ orix-convert workflow example > flow.json && orix-convert workflow validate flow.json857Web images: valid — 3 top-level node(s), 0 error(s), 0 warning(s)858 exports: jpeg, webp859```860861Exit status: 0.862863864```865$ orix-convert workflow run flow.json photo.png pics/image-0002.png notes.md866filtered notes.md867ok image-0002.png → /tmp/orix-web-images/image-0002.webp868ok photo.png → /tmp/orix-web-images/photo.webp869Summary: 3 file(s) — 2 done, 0 done with errors, 0 failed, 1 filtered, 0 cancelled — 0.86 s870```871872Exit status: 0.873874875A convert node that no input can satisfy is an error (`bad.json` asks for WAV → DOCX):876877```878$ cat bad.json; orix-convert workflow validate bad.json --for wav879{"name": "Impossible", "nodes": [{"convert": {"destination": "docx", "options": {"values": {}}}}]}880Impossible: INVALID — 1 top-level node(s), 1 error(s), 1 warning(s)881 error at node 1: No conversion to DOCX exists for: WAV.882 warning at node : Some paths have no export step: their results are written to the default folder (next to the source unless the run says otherwise).883 exports: docx884```885886Exit status: 6.887888889## `presets list`890891Lists the user's saved presets (the file the app writes). Built-in presets belong to the app, which registers them at start-up.892893```894$ orix-convert presets list895No preset saved in /tmp/orix-demo-support/presets.json.896Built-in presets belong to the app (it registers them at start-up); the command-line tool lists the user's saved presets.897```898899Exit status: 0.900901902## `doctor` — engines, tools, provenance903904`doctor [--json]` lists the engines and their availability, the tool search directories, each bundled tool with its version and905resolved path, the linked libraries with the version they report, and every image loaded from outside `/System` and `/usr/lib`. It906exits with status 6 when an engine is unavailable, or when a tool, a search directory or a loaded library lies outside the app bundle907and the repository (Homebrew, `/usr/local`, `/Applications`, `PATH` directories).908909```910$ orix-convert doctor911orix-convert 1.0.0912Executable: <repo>/Packages/ConvertKit/.build/arm64-apple-macosx/debug/orix-convert (development build, outside an app bundle)913914Engines (15, from 12 package(s))915 ENGINE NAME PACKAGE PATHS HEAVY AVAILABLE916 ------------- ------------------- ---------------- ----- ----- ---------917 image Images EngineImage 443 — yes918 pdf PDF EnginePDF 24 — yes919 vector Vector Studio EngineVector 26 — yes920 video Video EngineMedia 302 yes yes921 audio Audio EngineMedia 132 — yes922 documents Documents EngineDocuments 82 yes yes923 ebooks Ebooks EngineDocuments 23 — yes924 presentations Presentations EngineDocuments 24 yes yes925 data Spreadsheets & Data EngineData 219 — yes926 archive Archives EngineArchive 1378 — yes927 font Fonts EngineFont 11 — yes928 subtitle Subtitles EngineSubtitle 30 — yes929 model3d 3D Models EngineModel3D 132 — yes930 geo Geospatial EngineGeo 30 — yes931 scientific Scientific Data EngineScientific 10 — yes932 Registry: 119 formats, 2730 source → destination pairs, 2866 paths, 29 named operations933934Tool search directories (in order; PATH is never searched)935 <repo>/Packages/ConvertKit/.build/arm64-apple-macosx/debug [ORIX_CONVERT_TOOLS]936 <repo>/Packages/ConvertKit/.build/debug/Contents/Helpers [repository, absent]937 <repo>/EmbeddedEngines/tools [repository]938939Bundled tools940 TOOL VERSION SIZE FROM PATH941 ------------------- -------- -------- ------------------ -------------------------------------------------------------------------------------------------------------------------------…942 ffmpeg 9.1 29.6 MB repository <repo>/EmbeddedEngines/tools/ffmpeg943 ffprobe 9.1 29.4 MB repository <repo>/EmbeddedEngines/tools/ffprobe944 pandoc 3.14 197.0 MB repository <repo>/EmbeddedEngines/tools/pandoc945 LibreOffice 26.8.3.1 34.4 KB repository <repo>/EmbeddedEngines/tools/LibreOffice.app/Contents/MacOS/soffice946 orix-model3d-helper n/a 11.1 MB ORIX_CONVERT_TOOLS <repo>/Packages/ConvertKit/.build/arm64-apple-macosx/debug/orix-model3d-helper947 orix-hdf5-probe n/a 10.9 MB ORIX_CONVERT_TOOLS <repo>/Packages/ConvertKit/.build/arm64-apple-macosx/debug/orix-hdf5-probe948949Linked libraries950 LIBRARY VERSION LINKAGE USED BY951 -------------- ----------------- ----------------------------------------- ------------------952 DuckDB v2.0.1 bundled dynamic library (libduckdb.dylib) data953 SQLite 3.54.0 macOS system library data, geo, history954 libarchive libarchive 3.8.11 static (CArchive.xcframework) archive955 libwebp 1.6.0 static (CWebP.xcframework) image956 Assimp 6.0.2 static (CAssimp.xcframework) model3d957 woff2 + brotli not reported static (CWOFF2.xcframework) font958 HDF5 2.2.0 static (CHDF5.xcframework) scientific959960Images loaded from outside /System and /usr/lib961 <repo>/Packages/ConvertKit/.build/arm64-apple-macosx/debug/orix-convert962 <repo>/Packages/ConvertKit/.build/arm64-apple-macosx/debug/libduckdb.dylib963964No problem found: every engine is available and every tool and library comes from the bundle or the repository.965```966967Exit status: 0.968969970## `matrix` — the conversion matrix and its end-to-end verification971972- `matrix --markdown | --json [--output FILE]` generates the matrix from the live registry (what `Scripts/matrix.sh` writes to973 `docs/compatibility/conversion-matrix.md` and `matrix.json`). Tests and performance figures are read from the engine notes.974- `matrix --verify` runs every declared path end to end on real fixtures and writes `docs/reports/e2e-matrix.md` and `.json`975 (`Scripts/matrix.sh --verify`). It is resumable (`--work-dir`), bounded (`--jobs`, `--heavy-jobs`) and time-limited per path976 (`--timeout`); `--engine`, `--from`, `--to` restrict it (the report is then named `e2e-matrix-partial`).977978```979$ orix-convert matrix --json980{981 "identity" : {982 "engines" : [983 "image",984 "pdf",985 "vector",986 "video",987 "audio",988 "documents",989 "ebooks",990 "presentations",991 "data",992 "archive",993 "font",994 "subtitle",995 "model3d",996 "geo",997 "scientific"998 ],999 "notWiredPackages" : [10001001 ],1002 "registryFingerprint" : "dab44b20534c5c71d8b8523f170e2a315fe6464817fec6e7bdc8b853ee989b60",1003 "tool" : "orix-convert 1.0.0",1004 "wiredPackages" : [1005 "EngineImage",1006 "EnginePDF",1007 "EngineVector",1008 "EngineMedia",1009 "EngineDocuments",1010… (62430 more lines)1011```10121013Exit status: 0.101410151016```1017$ orix-convert matrix --verify --engine subtitle --work-dir sweep-work --report-dir sweep-report1018Preparing fixtures in /private/tmp/orix-demo/sweep-work …1019 fixture gpkg: geo:csv>gpkg did not produce it — A setting is not valid. No coordinate columns were recognised in the CSV file. Columns: id, name, city, amount, active, joined. Name the longitude / latitude (or X / Y) columns, or the WKT column, in the settings.1020 fixture gpx: geo:csv>gpx did not produce it — A setting is not valid. No coordinate columns were recognised in the CSV file. Columns: id, name, city, amount, active, joined. Name the longitude / latitude (or X / Y) columns, or the WKT column, in the settings.1021 fixture kml: geo:csv>kml did not produce it — A setting is not valid. No coordinate columns were recognised in the CSV file. Columns: id, name, city, amount, active, joined. Name the longitude / latitude (or X / Y) columns, or the WKT column, in the settings.1022 fixture shp: geo:csv>shp did not produce it — A setting is not valid. No coordinate columns were recognised in the CSV file. Columns: id, name, city, amount, active, joined. Name the longitude / latitude (or X / Y) columns, or the WKT column, in the settings.1023 fixture gpx: geo:geojson>gpx did not produce it — A setting is not valid. 1 feature(s) are polygons, and GPX can only hold points and lines. Turn on “Write polygons as closed tracks” to keep their outlines, or choose another format.1024 fixture gpx: geo:gpkg>gpx did not produce it — A setting is not valid. 1 feature(s) are polygons, and GPX can only hold points and lines. Turn on “Write polygons as closed tracks” to keep their outlines, or choose another format.1025 fixture gpx: geo:kml>gpx did not produce it — A setting is not valid. 1 feature(s) are polygons, and GPX can only hold points and lines. Turn on “Write polygons as closed tracks” to keep their outlines, or choose another format.1026Fixtures: 112 format(s); 7 source format(s) without a fixture.1027Running 30 of 30 path(s) (0 already recorded) — 6 at once, 3 heavy, limit 300 s each.1028End-to-end sweep: 30 path(s) — 30 passed, 0 failed, 0 crashed, 0 timed out, 0 skipped — 10.2 s1029Temporary work folders left behind: none1030Report: /private/tmp/orix-demo/sweep-report/e2e-matrix-partial.md1031```10321033Exit status: 0.103410351036## Development commands10371038`orix-convert dev …` is not listed in the overview: `dev seed` generates test material in code (pictures, WAV, CSV, Markdown, PDF,1039video, folder trees) for `Scripts/bench.sh`; `dev fixtures <dir>` builds one real file per format; `dev stress` runs the mixed-batch1040robustness scenario (`docs/reports/mixed-batch.md`).10411042```1043$ orix-convert help dev1044Development helpers: generated test material and the mixed-batch robustness run.10451046Usage: orix-convert dev seed images <dir> [--count <n>] [--width <w>] [--height <h>]1047 orix-convert dev seed wav <file> [--seconds <s>]1048 orix-convert dev seed csv <file> [--bytes <n>]1049 orix-convert dev seed markdown <file> [--pages <n>]1050 orix-convert dev seed pdf <file> [--pages <n>] [--scanned]1051 orix-convert dev seed video <file> [--seconds <s>] [--width <w>] [--height <h>] [--codec <ffmpeg encoder>]1052 orix-convert dev seed folder <dir> [--bytes <n>]1053 orix-convert dev stress [--work-dir <dir>] [--report-dir <dir>] [--jobs <n>]1054 orix-convert dev fixtures <dir>1055```10561057Exit status: 0.105810591060## JSON output at a glance10611062| Command | Top-level shape |1063|---|---|1064| `formats --json` | `{count, formats: [{id, name, category, extensions, readable, writable, destinations, sources, operations}]}` |1065| `paths --json` | `{count, paths: [{source, destination, operation?, title?, engine, status, fidelity, preserves, limitations, acceptsMultipleSources}], unavailable: [{engine, reason, paths}]}` |1066| `detect --json` | `[{path, format?, formatName?, category?, confidence, evidence, mismatch, fileExtension, extensionFormats, textEncoding?, isDirectory}]` |1067| `inspect --json` | `{path, detection, engine?, engineError?, inspection: FileInspection}` |1068| `plan --json` | `{path, sourceFormat, detection, destinationFormat, operation?, chained, steps: [{source, destination, operation?, engine, status, fidelity}], status, fidelity, preserves, limitations, warnings, heavy}` |1069| `options --json` | `{source, destination, operation?, engine, chained, note?, options: [{key, label, group, type, defaultValue, minimum?, maximum?, step?, unit?, choices?, placeholder?, help?, advanced, secret}]}` |1070| `convert --json` | `{summary: {total, finished, failed, skipped, cancelled, bytesBefore, bytesAfter, seconds, interrupted, exitCode}, jobs: [{sources, sourceFormat?, destinationFormat, operation?, state, engines, chained, outputs: [{path, outcome}], warnings, checks, facts, error?, errorKind?, seconds?, bytesBefore?, bytesAfter?}], leftoverTemporaryItems}` |1071| `workflow validate --json` | `{name, valid, issues: [{severity, node, message}], exportedFormats, canExportUnconverted}` |1072| `workflow run --json` | `{name, succeeded, succeededWithErrors, failed, filtered, cancelled, seconds, items: [{source, status, outputs, errors, warnings}]}` |1073| `presets list --json` | `{file, loadError?, presets: [{id, name, summary, appliesTo, destination, operation?, options, builtIn}]}` |1074| `doctor --json` | `{version, executable, insideAppBundle, toolsEnvironment?, wiredPackages, notWiredPackages, engines, searchDirectories, tools, libraries, loadedImagesOutsideSystem, registry, diagnostics, problems}` |1075| `matrix --json` | `{identity: {tool, wiredPackages, notWiredPackages, engines, registryFingerprint}, totals, rows}` |10761077Members marked `?` are absent when unknown. `errorKind` is one of `unsupportedPath`, `unreadableInput`, `malformedInput`,1078`encryptedInput`, `engineUnavailable`, `invalidOption`, `limitExceeded`, `toolFailed`, `outputInvalid`, `writeFailed`,1079`destinationExists`, `internalError`.10801081## The `ConvertKit` library (for the app)10821083`Packages/ConvertKit` is the single place where the engines are assembled; the tool is a thin layer over it.10841085```swift1086import ConvertKit // re-uses ConvertCore types10871088let engines = ORIXEngines.all() // every wired engine, in registration order1089let heavy = ORIXEngines.heavyEngineIDs // ["video", "documents", "presentations"]1090let service = ConversionService() // registry + planner + queue (heavy rule set) + history + presets + workflows1091let ids = await service.convert(urls, to: .jpeg, destination: OutputDestination(directory: folder))1092for id in ids { _ = await service.queue.waitForJob(id) }1093```10941095- Wiring an engine package = one line: its name in the `engines` array of `Packages/ConvertKit/Package.swift`. The matching1096 `#if canImport(Engine…)` block of `Sources/ConvertKit/ORIXEngines.swift` then compiles in (a block exists for each of the twelve known1097 packages; a thirteenth needs its own three-line block).1098- Registration order matters for inspection: when several engines list a format in `inspectableFormats`, the registry asks the first1099 one. `ORIXEngines` registers the image engine before the PDF engine for that reason (otherwise PNG, JPEG, HEIC, TIFF, GIF, BMP and1100 WebP files are inspected by the PDF engine, which reports no pixel dimensions).1101- `ToolEnvironment.bootstrap()` (called by `ORIXEngines.all()` and `ConversionService.init`) sets `ORIX_CONVERT_TOOLS` from the1102 executable's own folder when that folder holds bundled tools. `ConversionService.Configuration` overrides the concurrency, the1103 history file, the work root and the preset/workflow files; `ORIX_CONVERT_SKIP_ENGINES=EngineX,EngineY` builds without packages that are1104 being edited (development only).1105