SPB Git

Repository Public License

cli.md 44.5 KB 1,105 lines markdown

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
Files main
Menu

Theme