orix-convert — the ORIX Convert engines on the command line
orix-convert is the command-line front end of ORIX Convert. It uses exactly what the app uses: the same engines, the same
registry, planner, queue, validation and safe writer (Packages/ConvertKit assembles them). Everything runs on this Mac; the tool
has no network code of its own and never looks for software in PATH, Homebrew or /Applications.
Every example below was executed; the output is pasted as printed (long listings are cut, with the number of lines left out; the
repository path is shown as <repo>). The demonstration files (photo.png, notes.md, table.csv, a.pdf, b.pdf, tone.wav)
were generated by the tool itself.
Building and running
cd Packages/ConvertKit
swift build --build-system native -c release --product orix-convert
swift build --build-system native -c release --product orix-model3d-helper # helper started by the 3D engine
.build/release/orix-convert help
swift test --build-system native--build-system native is required for now: with SwiftPM's default build system, the binary targets of several engine packages
(CDuckDB, CArchive, CWebP, CAssimp) each install a module.modulemap at the same path and the build stops with
"Multiple commands produce …/include/module.modulemap".
In the app bundle the tool is ORIX Convert.app/Contents/Helpers/orix-convert. At start-up it points ORIX_CONVERT_TOOLS at its own
folder when that folder holds bundled tools (ffmpeg, pandoc, LibreOffice.app…), so the engines find them next to it; its dynamic
library (libduckdb.dylib) is looked for next to the tool and in Contents/Frameworks. In a development build the tools come from
EmbeddedEngines/tools. orix-convert doctor shows what was found and where.
$ orix-convert help
orix-convert 1.0.0 — the ORIX Convert engines on the command line. Everything runs on this Mac.
Usage: orix-convert <command> [options]
Commands:
formats Formats with at least one real conversion path.
paths The capability matrix: every declared conversion path.
detect Identify files from their content.
inspect Metadata of a file, read by the engine that knows its format.
plan Show how a file would be converted, before converting it.
options Settings offered by a conversion path.
convert Convert files (real queue, validation, safe writer).
workflow Run or validate a Conversion Flow file (JSON).
presets Saved presets (the file shared with the app).
doctor Engines, bundled tools and their versions; checks nothing comes from outside.
matrix Generate the conversion matrix; --verify runs every path end to end.
Run 'orix-convert help <command>' for the options of a command.
Exit status: 0 done · 1 a conversion failed · 2 usage · 3 input missing or unrecognised · 4 unsupported conversion ·
5 destination exists (--on-conflict fail) · 6 a check failed · 130 interrupted.Exit status: 0.
Exit status
| Status | Meaning |
|---|---|
| 0 | Everything asked for was done. Files left alone by --on-conflict skip count as done. |
| 1 | At least one conversion failed (the others were delivered), or a verification run found a failure. |
| 2 | The command line is wrong: unknown command or option, missing value, unknown format, option value out of range. |
| 3 | Input problem: a file does not exist, cannot be read or is of unrecognised format — and no job succeeded for another reason. |
| 4 | Unsupported: no engine converts that source to that destination (every failed job failed for that reason). |
| 5 | The destination exists and --on-conflict fail was given (every failed job failed for that reason). |
| 6 | A check found a problem: doctor, workflow validate, an unreadable preset file. |
| 130 | Interrupted (Ctrl-C or SIGTERM): running jobs were cancelled, their temporary folders removed. A second Ctrl-C exits at once. |
Errors go to standard error; results (text or JSON) to standard output. --json output is one JSON document with sorted keys.
formats — what can be read and written
formats [--category <category>] [--json] lists the formats that have at least one real path in this build.
$ orix-convert formats --category font
FORMAT NAME CATEGORY EXTENSIONS READ WRITE TO FROM OPS
------ ------------- -------- ---------- ---- ----- -- ---- ---
ttf TrueType Font font ttf yes yes 14 2 3
otf OpenType Font font otf yes yes 13 2 2
woff WOFF font woff yes yes 14 3 2
woff2 WOFF2 font woff2 yes yes 14 3 2
4 format(s) with at least one path. TO = destinations reachable from the format, FROM = sources that can become it.Exit status: 0.
$ orix-convert formats --category subtitle --json
{
"count" : 5,
"formats" : [
{
"category" : "subtitle",
"destinations" : 16,
"extensions" : [
"srt"
],
"id" : "srt",
"name" : "SubRip",
"operations" : 4,
"readable" : true,
"sources" : 10,
"writable" : true
},
{
"category" : "subtitle",
"destinations" : 16,
"extensions" : [
"vtt"
],
"id" : "vtt",
"name" : "WebVTT",
… (46 more lines)Exit status: 0.
paths — the capability matrix
paths [--from X] [--to Y] [--engine E] [--operation OP] [--json] prints the declared paths, straight from the registry.
$ orix-convert paths --from png --to pdf
SOURCE DESTINATION OPERATION ENGINE STATUS FIDELITY PRESERVES
------ ----------- --------------- ------ --------- -------- -----------------------
png pdf — pdf supported lossless dimensions,transparency
png pdf image.vectorize vector supported lossy dimensions,transparency
2 path(s).Exit status: 0.
$ orix-convert paths --from srt --to vtt --json
{
"count" : 1,
"paths" : [
{
"acceptsMultipleSources" : false,
"destination" : "vtt",
"engine" : "subtitle",
"fidelity" : "structural",
"limitations" : [
"WebVTT has no font tag and no strike-through; colours are written as cue classes with a STYLE block."
],
"preserves" : [
"textStyles",
"timing"
],
"source" : "srt",
"status" : "supported"
}
],
"unavailable" : [
]
}Exit status: 0.
detect — identify files from their content
detect <files…> [--json]. The extension is only a hint; a name that contradicts the content is reported as a mismatch.
$ orix-convert detect photo.png mislabeled.jpg notes.md table.csv a.pdf tone.wav
photo.png: png (PNG) — certain — PNG signature
mislabeled.jpg: png (PNG) — certain — PNG signature; extension .jpg says jpeg — MISMATCH: the name says .jpg
notes.md: markdown (Markdown) — likely — Markdown constructs: heading
table.csv: csv (CSV) — likely — consistent comma-separated columns
a.pdf: pdf (PDF) — certain — PDF header
tone.wav: wav (WAV) — certain — RIFF/WAVE containerExit status: 0.
$ orix-convert detect mislabeled.jpg --json
[
{
"category" : "image",
"confidence" : "certain",
"evidence" : "PNG signature; extension .jpg says jpeg",
"extensionFormats" : [
"jpeg"
],
"fileExtension" : "jpg",
"format" : "png",
"formatName" : "PNG",
"isDirectory" : false,
"mismatch" : true,
"path" : "/tmp/orix-demo/mislabeled.jpg"
}
]Exit status: 0.
inspect — metadata read by the engines
inspect <file> [--json]: generic file facts, then what the engine in charge of the format really read. A value that could not be
read is absent, never guessed.
$ orix-convert inspect photo.png
photo.png
File
Format PNG
Detection certain: PNG signature
Size 1613857 bytes
Created 2026-11-21T17:21:26Z
Modified 2026-11-21T17:21:26Z
Permissions 644
Type identifier public.png
Quarantine attribute Absent
Download origin attribute Absent
General
Type identifier public.png
Dimensions 1600 × 1200
Orientation 1
File size 1613857
Color
Model RGB
ICC profile sRGB IEC61966-2.1
Bits per component 8
EXIF
ColorSpace 1
PixelXDimension 1600
PixelYDimension 1200
PNG
Chromaticities 0.3127, 0.329, 0.64, 0.33, 0.3, 0.6000000000000001, 0.15, 0.06
Gamma 0.45455
InterlaceType 0
sRGBIntent 0
XMP
exif:ColorSpace 1
exif:PixelXDimension 1600
exif:PixelYDimension 1200
Read by engine 'image'.Exit status: 0.
$ orix-convert inspect tone.wav --json
{
"detection" : {
"category" : "audio",
"confidence" : "certain",
"evidence" : "RIFF/WAVE container",
"extensionFormats" : [
"wav"
],
"fileExtension" : "wav",
"format" : "wav",
"formatName" : "WAV",
"isDirectory" : false,
"mismatch" : false,
"path" : "/tmp/orix-demo/tone.wav"
},
"engine" : "audio",
"inspection" : {
"audioCodec" : "pcm_s16le",
"bitDepth" : 16,
"bitRate" : 1411317,
"channels" : 2,
"durationSeconds" : 3,
"fields" : [
{
"group" : "File",
"key" : "Format",
"value" : "WAV"
},
{
"group" : "File",
"key" : "Detection",
"value" : "certain: RIFF/WAVE container"
},
{
"group" : "File",
"key" : "Size",
"value" : "529244 bytes"
},
{
"group" : "File",
… (98 more lines)Exit status: 0.
plan — what would happen to this file
plan <file> --to <format> [--operation OP] [--engine E] [--option key=value …] [--json] shows the route (direct, or chained through
an intermediate file), the fidelity, what is preserved, the limitations the user must know, and the engine's warnings for this
particular file.
$ orix-convert plan photo.png --to jpeg
photo.png: png (certain: PNG signature)
Plan: png → jpeg — direct
1. png → jpeg with engine 'image' — supported, lossy
Fidelity: lossy Status: supported
Preserves: colorProfile, dimensions, metadata
Limitations:
- Lossy compression; the PSNR of the result is measured.
- JPEG has no transparency: transparent areas are filled with the background colour.
- Samples deeper than 8-bit are reduced to 8-bit.
- Largest side: 65535 pixels.
Preflight warnings for this file: none.Exit status: 0.
A pair with no direct path is bridged in two steps when the planner finds a route:
$ orix-convert plan notes.md --to png
notes.md: markdown (likely: Markdown constructs: heading)
Plan: markdown → pdf → png — chained, 2 steps through an intermediate file
1. markdown → pdf with engine 'documents' — supported, structural
2. pdf → png with engine 'pdf' — supported, lossy
Fidelity: lossy Status: supported Heavy job (limited concurrency)
Preserves: —
Limitations:
- Rendered by WebKit with JavaScript disabled and without any network access: remote images, fonts and stylesheets are missing.
- Typeset with ORIX Convert's built-in print stylesheet; this is a reflowed rendering, not the source's own page design.
- No table structure, bookmarks or tagged-PDF accessibility information.
- Pages become flat images: text is no longer selectable and links, form fields and the outline are gone.
- Several pages produce a folder with one image per page (or one multi-page TIFF when that option is on).
- A page above 256 megapixels or 32000 pixels a side is rendered at a lower resolution, with a warning.
Preflight warnings for this file: none.Exit status: 0.
$ orix-convert plan tone.wav --to docx
orix-convert: Converting WAV to DOCX is not supported. wav converts to: mp3, m4a, wav, flac, aiff, ogg, opus, alac, caf, aac, wma.Exit status: 4.
options — settings of a path
options --from X --to Y [--operation OP] [--engine E] [--json] prints the option descriptors the app builds its panels from: key,
type, range or choices, default, help.
$ orix-convert options --from png --to jpeg
png → jpeg — engine 'image'
--option quality=<integer 1…100> default: 85
Quality · Quality — Encoder quality, 1 (smallest) to 100 (best).
--option target.size-kb=<number 0.0…1000000.0 kB> default: 0.0
Quality · Target file size — When above 0, the highest quality whose file fits in this size is found by encoding and measuring.
--option jpeg.progressive=<bool> default: false [advanced]
Quality · Progressive — Write a progressive JPEG.
--option resize.mode=<choice {none|fit|fill|exact|percent|long-edge}> default: none
Size · Resize
--option resize.width=<integer 0…100000 px> default: 0
Size · Width
--option resize.height=<integer 0…100000 px> default: 0
Size · Height
--option resize.percent=<number 1.0…1000.0 %> default: 100.0
Size · Percentage
--option resize.long-edge=<integer 0…100000 px> default: 0
Size · Long edge
--option resize.upscale=<bool> default: false
Size · Allow enlarging — Without it, “fit” and “long edge” never make an image larger.
--option crop.mode=<choice {none|rect|aspect}> default: none
Size · Crop
--option crop.x=<integer 0…1000000 px> default: 0 [advanced]
Size · Crop left
--option crop.y=<integer 0…1000000 px> default: 0 [advanced]
Size · Crop top
--option crop.width=<integer 0…1000000 px> default: 0 [advanced]
Size · Crop width
--option crop.height=<integer 0…1000000 px> default: 0 [advanced]
Size · Crop height
--option crop.aspect=<text> default: 1:1 [advanced]
Size · Aspect ratio
--option rotate.angle=<number -360.0…360.0 °> default: 0.0
Size · Rotate — Clockwise, in degrees. Multiples of 90° move pixels without resampling.
--option flip.horizontal=<bool> default: false
Size · Flip horizontally
--option flip.vertical=<bool> default: false
Size · Flip vertically
--option orientation.normalize=<bool> default: true [advanced]
Size · Apply EXIF orientation — Turn the pixels upright and reset the orientation tag.
--option color.profile=<choice {keep|srgb|display-p3|adobe-rgb|gray}> default: keep
Colour · Colour profile — Conversions are colour-managed (ColorSync).
--option background.color=<text> default: #FFFFFF
Colour · Background colour — Used when transparency has to be flattened.
--option metadata=<choice {keep|strip-location|strip}> default: keep
Metadata · Metadata
--option watermark.text=<text> default: (empty)
Watermark · Watermark text
--option watermark.image=<text> default: (empty)
Watermark · Watermark image — Path of an image file to overlay.
--option watermark.position=<choice {top-left|top|top-right|left|center|right|bottom-left|bottom|bottom-right}> default: bottom-right
Watermark · Position
--option watermark.opacity=<number 0.0…100.0 %> default: 50.0
Watermark · Opacity
--option watermark.scale=<number 1.0…100.0 %> default: 25.0
Watermark · Width — Width of the watermark as a share of the image width.
--option watermark.margin=<number 0.0…50.0 %> default: 3.0
Watermark · Margin — Distance from the edges as a share of the shorter side.
--option watermark.color=<text> default: #FFFFFF [advanced]
Watermark · Text colour
--option limit.megapixels=<integer 1…4000 MP> default: 400 [advanced]
Safety · Pixel limit — Images that would decode to more pixels are refused (protection against decompression bombs).
--option verify.measure=<bool> default: true [advanced]
Safety · Measure the result — Decode the written file and report whether its pixels are identical, or the PSNR.Exit status: 0.
$ orix-convert options --from pdf --to png --json
{
"chained" : false,
"destination" : "png",
"engine" : "pdf",
"options" : [
{
"advanced" : false,
"defaultValue" : "",
"group" : "Pages",
"help" : "Pages to export; leave empty for all. Example: 1-3,7,10- (10- means page 10 to the end).",
"key" : "pages",
"label" : "Pages",
"placeholder" : "All pages",
"secret" : false,
"type" : "text"
},
{
"advanced" : false,
"defaultValue" : "150",
"group" : "Size",
"key" : "resolution.dpi",
"label" : "Resolution",
"maximum" : 2400,
"minimum" : 18,
"secret" : false,
"type" : "integer",
"unit" : "dpi"
},
{
"advanced" : false,
"defaultValue" : "0",
"group" : "Size",
"help" : "When above 0, each page is rendered this many pixels wide and the resolution is ignored.",
"key" : "resize.width",
"label" : "Width in pixels",
"maximum" : 32000,
… (87 more lines)Exit status: 0.
convert — convert files
$ orix-convert help convert
Convert files (real queue, validation, safe writer).
Usage: 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]
--to <format> destination format (identifier or extension: jpeg, jpg, pdf, folder…)
--operation <op> named operation (pdf.merge, image.vectorize, video.extract-audio…); see 'paths'
--option key=value a setting of the path (see 'options'); repeatable. For a key containing 'password',
the value @env:NAME reads an environment variable and @stdin reads standard input
--output-dir <dir> write there (created if needed); default: next to each source
--output <file> exact output file, for a single job
--name-template <t> tokens {name} {ext} {date} {counter} {counter:3} {width} {height}; default {name}
--on-conflict <policy> rename (default: 'name 2.ext'), skip, replace, or fail. Nothing is ever overwritten
without 'replace'; a source file is never replaced
--jobs <n> conversions running at once (default: performance cores, at most 8)
--recursive convert the files inside the given folders (hidden files and links skipped)
--combine one job from all the files, for paths taking several sources (images → PDF);
implied by --operation when that operation takes several sources
--from <format> do not detect: treat the sources as this format
--engine <id> force one engine's direct path
--no-chain refuse two-step plans
--json print one JSON document (summary + every job) instead of text
--quiet print only failures
--verbose print every validation check and measured fact
--no-history do not open or write the history databaseExit status: 0.
Each file is a job of the real queue: detection, plan, engine, generic validation, the engine's own validation, then an atomic move to the destination. On a terminal a progress line is drawn on standard error; a percentage appears only when the engine measured one, otherwise the line says that progress is not measurable.
$ orix-convert convert photo.png --to jpeg --option quality=80 --output-dir out
ok photo.png → /private/tmp/orix-demo/out/photo.jpg (png → jpeg, image, 1.6 MB → 448.8 KB, 0.70 s)
validated: 8 check(s) passed (alpha, decodes, dimensions, format limit, frame count, output.format, output.not-empty, pixels)
Summary: 1 job(s) — 1 converted, 0 failed, 0 skipped — 1.6 MB in, 448.8 KB out — 0.70 sExit status: 0.
$ orix-convert convert photo.png pics --recursive --to webp --output-dir out --name-template "{counter:2}-{name}-{width}x{height}" --verbose
ok image-0002.png → /tmp/orix-demo/out/02-image-0002-1600x1200.webp (png → webp, image, 1.7 MB → 161.8 KB, 0.82 s)
check passed output.not-empty: 02-image-0002-1600x1200.webp: 161846 bytes
check passed output.format: 02-image-0002-1600x1200.webp: detected webp (RIFF/WEBP container).
check passed decodes: Decoded by libwebp 1.6.0: 1 image(s).
check passed dimensions: Output 1600×1200; expected 1600×1200.
check passed frame count: 1 image(s) in the output; expected 1.
check passed format limit: Largest side 1600 px; WEBP allows 16383.
check passed pixels: Lossy encoding: PSNR 36.17 dB against the pixels given to the encoder (measured during conversion).
fact alpha = no
fact bits = 8
fact bytes = 161846
fact color.space = SRGB
fact encoder = libwebp 1.6.0
fact frames = 1
fact height = 1200
fact metadata.exif = 1 fields
fact metadata.gps = none
fact metadata.iptc = none
fact metadata.xmp = 3 tags
fact psnr.db = 36.17
fact quality = 80
fact source.height = 1200
… (63 more lines)Exit status: 0.
Nothing is overwritten unless asked: the default policy numbers the new file.
$ orix-convert convert photo.png --to jpeg --output-dir out
ok photo.png → /tmp/orix-demo/out/photo 2.jpg (png → jpeg, image, 1.6 MB → 513.6 KB, 0.76 s)
renamed: /tmp/orix-demo/out/photo 2.jpg
validated: 8 check(s) passed (alpha, decodes, dimensions, format limit, frame count, output.format, output.not-empty, pixels)
Summary: 1 job(s) — 1 converted, 0 failed, 0 skipped — 1.6 MB in, 513.6 KB out — 0.76 sExit status: 0.
$ orix-convert convert photo.png --to jpeg --output-dir out --on-conflict fail
FAILED photo.png: /tmp/orix-demo/out/photo.jpg already exists. Nothing was written (use --on-conflict rename, skip or replace).
Summary: 1 job(s) — 0 converted, 1 failed, 0 skipped — 0.01 sExit status: 5.
$ orix-convert convert photo.png --to jpeg --output-dir out --on-conflict skip
skipped photo.png: Skipped: photo.jpg already exists in the destination folder.
Summary: 1 job(s) — 0 converted, 0 failed, 1 skipped — 0.01 sExit status: 0.
$ orix-convert convert photo.png --to jpeg --output-dir out --on-conflict replace --quiet
Exit status: 0.
Operations taking several sources make one job (--operation pdf.merge); --output names the result:
$ orix-convert convert a.pdf b.pdf --to pdf --operation pdf.merge --output merged.pdf
ok a.pdf (+1 more) → /private/tmp/orix-demo/merged.pdf (pdf → pdf [pdf.merge], pdf, 37.2 KB → 36.3 KB, 0.06 s)
validated: 6 check(s) passed (PDF reopens, merge order, outline, output.format, output.not-empty, page count)
Summary: 1 job(s) — 1 converted, 0 failed, 0 skipped — 37.2 KB in, 36.3 KB out — 0.06 sExit status: 0.
A chained conversion reports the checks of both steps:
$ orix-convert convert notes.md --to png --output-dir pages --verbose
ok notes.md → /private/tmp/orix-demo/pages/notes (markdown → png, chained: documents + pdf, 5.8 KB → 613.8 KB, 0.63 s)
check passed step1.output.not-empty: notes.pdf: 23603 bytes
check passed step1.output.format: notes.pdf: detected pdf (PDF header).
check passed step1.PDF opens: 2 page(s)
check passed step1.At least one page: 2
check passed step1.Output re-opens: 978 words
check passed step1.Source text present: 8/8 probe words found
check passed step2.output.not-empty: notes: 2 file(s)
check passed step2.output.no-symlink-escape: No link leaves the folder.
check passed step2.image count: 2 image(s) for 2 selected page(s).
check passed step2.pixel dimensions: Every image has the expected size (first: 1240 × 1754).
fact dpi = 150.0
fact files = 2
fact height = 1754
fact pages = 2
fact width = 1240
… (1 more lines)Exit status: 0.
Failures are per file; the status tells whether anything failed:
$ orix-convert convert photo.png tone.wav missing.png --to pdf --output-dir out
FAILED missing.png: The file could not be read. missing.png no longer exists.
FAILED tone.wav: Converting WAV to PDF is not supported.
ok photo.png → /tmp/orix-demo/out/photo.pdf (png → pdf, pdf, 1.6 MB → 1.6 MB, 0.11 s)
validated: 5 check(s) passed (PDF reopens, image embedded, output.format, output.not-empty, page count)
Summary: 3 job(s) — 1 converted, 2 failed, 0 skipped — 1.6 MB in, 1.6 MB out — 0.11 sExit status: 1.
--json prints one document: the summary, then every job with its outputs, warnings, validation checks, measured facts and error.
$ orix-convert convert table.csv --to parquet --output-dir out --json
{
"jobs" : [
{
"bytesAfter" : 2808,
"bytesBefore" : 4120,
"chained" : false,
"checks" : [
{
"detail" : "table.parquet: 2808 bytes",
"name" : "output.not-empty",
"passed" : true
},
{
"detail" : "table.parquet: detected parquet (PAR1 header and footer).",
"name" : "output.format",
"passed" : true
},
{
"detail" : "The output opens as Parquet with 1 table.",
"name" : "reopen",
"passed" : true
},
{
"detail" : "33 rows read back, as written.",
"name" : "row-count",
"passed" : true
},
{
"detail" : "9 columns read back.",
"name" : "column-count",
"passed" : true
},
{
"detail" : "Column names read back identical.",
"name" : "column-names",
"passed" : true
},
{
"detail" : "297 cells of the first 1000 rows read back equal to the source.",
"name" : "sample-values",
"passed" : true
}
],
"destinationFormat" : "parquet",
"engines" : [
"data"
],
"facts" : {
"columns" : "9",
"engine" : "DuckDB v2.0.1",
"rows" : "33",
"tables" : "1"
},
"outputs" : [
{
"outcome" : "written",
"path" : "/tmp/orix-demo/out/table.parquet"
}
],
"seconds" : 0.12321305274963379,
"sourceFormat" : "csv",
"sources" : [
"/tmp/orix-demo/table.csv"
],
"state" : "finished",
"warnings" : [
]
}
],
… (16 more lines)Exit status: 0.
Option values are checked against the path's descriptors before anything runs:
$ orix-convert convert photo.png --to jpeg --option quality=900
orix-convert: --option quality: expected a whole number between 1 and 100, not '900'.Exit status: 2.
Passwords
For an option whose key contains password, the value can come from an environment variable (@env:NAME) or from standard input
(@stdin, one line), so that it never appears in the process list. A password typed directly on the command line works too, with a
warning. Passwords are never printed and never written to the history (@@text gives a literal value starting with @).
$ orix-convert convert a.pdf --to txt --output-dir out --option password=@env:PDF_PASSWORD
ok a.pdf → /tmp/orix-demo/out/a.txt (pdf → txt, pdf, 17.7 KB → 6.5 KB, 0.04 s)
validated: 4 check(s) passed (output.format, output.not-empty, text decodes, text probes)
Summary: 1 job(s) — 1 converted, 0 failed, 0 skipped — 17.7 KB in, 6.5 KB out — 0.04 sExit status: 0.
$ echo "example-only" | orix-convert convert a.pdf --to txt --output-dir out --option password=@stdin --quiet
Exit status: 0.
$ orix-convert convert a.pdf --to txt --output-dir out --option password=@env:NOT_SET
orix-convert: --option password=@env:NOT_SET: the environment variable NOT_SET is not set.Exit status: 2.
History
Ended jobs are recorded in the same history database as the app (~/Library/Application Support/ORIX Convert/history.sqlite, or
$ORIX_CONVERT_SUPPORT_DIR); file contents and secret options are never stored. --no-history neither opens nor writes it (the
examples of this page were run with ORIX_CONVERT_SUPPORT_DIR pointing at a scratch folder).
workflow — Conversion Flow files
workflow example prints a complete file (the core's Workflow model as JSON); workflow validate checks it against the live
registry; workflow run applies it to files through the queue.
$ orix-convert workflow example
{
"errorPolicy" : "stopItem",
"id" : "00000000-0000-4000-8000-000000000001",
"name" : "Web images",
"nodes" : [
{
"filter" : {
"_0" : {
"categoryIs" : {
"_0" : "image"
}
}
}
},
{
"branch" : {
"condition" : {
"width" : {
"_0" : "greaterThan",
"_1" : 1600
}
},
"otherwise" : [
{
"convert" : {
"destination" : "webp",
"options" : {
"values" : {
}
}
}
}
],
"then" : [
{
"convert" : {
"destination" : "jpeg",
"options" : {
"values" : {
"quality" : {
"int" : {
"_0" : 82
}
},
"resize.width" : {
"int" : {
"_0" : 1600
}
}
}
}
}
},
{
"rename" : {
"template" : "{name}-web"
}
}
]
… (11 more lines)Exit status: 0.
$ orix-convert workflow example > flow.json && orix-convert workflow validate flow.json
Web images: valid — 3 top-level node(s), 0 error(s), 0 warning(s)
exports: jpeg, webpExit status: 0.
$ orix-convert workflow run flow.json photo.png pics/image-0002.png notes.md
filtered notes.md
ok image-0002.png → /tmp/orix-web-images/image-0002.webp
ok photo.png → /tmp/orix-web-images/photo.webp
Summary: 3 file(s) — 2 done, 0 done with errors, 0 failed, 1 filtered, 0 cancelled — 0.86 sExit status: 0.
A convert node that no input can satisfy is an error (bad.json asks for WAV → DOCX):
$ cat bad.json; orix-convert workflow validate bad.json --for wav
{"name": "Impossible", "nodes": [{"convert": {"destination": "docx", "options": {"values": {}}}}]}
Impossible: INVALID — 1 top-level node(s), 1 error(s), 1 warning(s)
error at node 1: No conversion to DOCX exists for: WAV.
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).
exports: docxExit status: 6.
presets list
Lists the user's saved presets (the file the app writes). Built-in presets belong to the app, which registers them at start-up.
$ orix-convert presets list
No preset saved in /tmp/orix-demo-support/presets.json.
Built-in presets belong to the app (it registers them at start-up); the command-line tool lists the user's saved presets.Exit status: 0.
doctor — engines, tools, provenance
doctor [--json] lists the engines and their availability, the tool search directories, each bundled tool with its version and
resolved path, the linked libraries with the version they report, and every image loaded from outside /System and /usr/lib. It
exits with status 6 when an engine is unavailable, or when a tool, a search directory or a loaded library lies outside the app bundle
and the repository (Homebrew, /usr/local, /Applications, PATH directories).
$ orix-convert doctor
orix-convert 1.0.0
Executable: <repo>/Packages/ConvertKit/.build/arm64-apple-macosx/debug/orix-convert (development build, outside an app bundle)
Engines (15, from 12 package(s))
ENGINE NAME PACKAGE PATHS HEAVY AVAILABLE
------------- ------------------- ---------------- ----- ----- ---------
image Images EngineImage 443 — yes
pdf PDF EnginePDF 24 — yes
vector Vector Studio EngineVector 26 — yes
video Video EngineMedia 302 yes yes
audio Audio EngineMedia 132 — yes
documents Documents EngineDocuments 82 yes yes
ebooks Ebooks EngineDocuments 23 — yes
presentations Presentations EngineDocuments 24 yes yes
data Spreadsheets & Data EngineData 219 — yes
archive Archives EngineArchive 1378 — yes
font Fonts EngineFont 11 — yes
subtitle Subtitles EngineSubtitle 30 — yes
model3d 3D Models EngineModel3D 132 — yes
geo Geospatial EngineGeo 30 — yes
scientific Scientific Data EngineScientific 10 — yes
Registry: 119 formats, 2730 source → destination pairs, 2866 paths, 29 named operations
Tool search directories (in order; PATH is never searched)
<repo>/Packages/ConvertKit/.build/arm64-apple-macosx/debug [ORIX_CONVERT_TOOLS]
<repo>/Packages/ConvertKit/.build/debug/Contents/Helpers [repository, absent]
<repo>/EmbeddedEngines/tools [repository]
Bundled tools
TOOL VERSION SIZE FROM PATH
------------------- -------- -------- ------------------ -------------------------------------------------------------------------------------------------------------------------------…
ffmpeg 9.1 29.6 MB repository <repo>/EmbeddedEngines/tools/ffmpeg
ffprobe 9.1 29.4 MB repository <repo>/EmbeddedEngines/tools/ffprobe
pandoc 3.14 197.0 MB repository <repo>/EmbeddedEngines/tools/pandoc
LibreOffice 26.8.3.1 34.4 KB repository <repo>/EmbeddedEngines/tools/LibreOffice.app/Contents/MacOS/soffice
orix-model3d-helper n/a 11.1 MB ORIX_CONVERT_TOOLS <repo>/Packages/ConvertKit/.build/arm64-apple-macosx/debug/orix-model3d-helper
orix-hdf5-probe n/a 10.9 MB ORIX_CONVERT_TOOLS <repo>/Packages/ConvertKit/.build/arm64-apple-macosx/debug/orix-hdf5-probe
Linked libraries
LIBRARY VERSION LINKAGE USED BY
-------------- ----------------- ----------------------------------------- ------------------
DuckDB v2.0.1 bundled dynamic library (libduckdb.dylib) data
SQLite 3.54.0 macOS system library data, geo, history
libarchive libarchive 3.8.11 static (CArchive.xcframework) archive
libwebp 1.6.0 static (CWebP.xcframework) image
Assimp 6.0.2 static (CAssimp.xcframework) model3d
woff2 + brotli not reported static (CWOFF2.xcframework) font
HDF5 2.2.0 static (CHDF5.xcframework) scientific
Images loaded from outside /System and /usr/lib
<repo>/Packages/ConvertKit/.build/arm64-apple-macosx/debug/orix-convert
<repo>/Packages/ConvertKit/.build/arm64-apple-macosx/debug/libduckdb.dylib
No problem found: every engine is available and every tool and library comes from the bundle or the repository.Exit status: 0.
matrix — the conversion matrix and its end-to-end verification
matrix --markdown | --json [--output FILE]generates the matrix from the live registry (whatScripts/matrix.shwrites todocs/compatibility/conversion-matrix.mdandmatrix.json). Tests and performance figures are read from the engine notes.matrix --verifyruns every declared path end to end on real fixtures and writesdocs/reports/e2e-matrix.mdand.json(Scripts/matrix.sh --verify). It is resumable (--work-dir), bounded (--jobs,--heavy-jobs) and time-limited per path (--timeout);--engine,--from,--torestrict it (the report is then namede2e-matrix-partial).
$ orix-convert matrix --json
{
"identity" : {
"engines" : [
"image",
"pdf",
"vector",
"video",
"audio",
"documents",
"ebooks",
"presentations",
"data",
"archive",
"font",
"subtitle",
"model3d",
"geo",
"scientific"
],
"notWiredPackages" : [
],
"registryFingerprint" : "dab44b20534c5c71d8b8523f170e2a315fe6464817fec6e7bdc8b853ee989b60",
"tool" : "orix-convert 1.0.0",
"wiredPackages" : [
"EngineImage",
"EnginePDF",
"EngineVector",
"EngineMedia",
"EngineDocuments",
… (62430 more lines)Exit status: 0.
$ orix-convert matrix --verify --engine subtitle --work-dir sweep-work --report-dir sweep-report
Preparing fixtures in /private/tmp/orix-demo/sweep-work …
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.
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.
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.
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.
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.
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.
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.
Fixtures: 112 format(s); 7 source format(s) without a fixture.
Running 30 of 30 path(s) (0 already recorded) — 6 at once, 3 heavy, limit 300 s each.
End-to-end sweep: 30 path(s) — 30 passed, 0 failed, 0 crashed, 0 timed out, 0 skipped — 10.2 s
Temporary work folders left behind: none
Report: /private/tmp/orix-demo/sweep-report/e2e-matrix-partial.mdExit status: 0.
Development commands
orix-convert dev … is not listed in the overview: dev seed generates test material in code (pictures, WAV, CSV, Markdown, PDF,
video, folder trees) for Scripts/bench.sh; dev fixtures <dir> builds one real file per format; dev stress runs the mixed-batch
robustness scenario (docs/reports/mixed-batch.md).
$ orix-convert help dev
Development helpers: generated test material and the mixed-batch robustness run.
Usage: orix-convert dev seed images <dir> [--count <n>] [--width <w>] [--height <h>]
orix-convert dev seed wav <file> [--seconds <s>]
orix-convert dev seed csv <file> [--bytes <n>]
orix-convert dev seed markdown <file> [--pages <n>]
orix-convert dev seed pdf <file> [--pages <n>] [--scanned]
orix-convert dev seed video <file> [--seconds <s>] [--width <w>] [--height <h>] [--codec <ffmpeg encoder>]
orix-convert dev seed folder <dir> [--bytes <n>]
orix-convert dev stress [--work-dir <dir>] [--report-dir <dir>] [--jobs <n>]
orix-convert dev fixtures <dir>Exit status: 0.
JSON output at a glance
| Command | Top-level shape |
|---|---|
formats --json |
{count, formats: [{id, name, category, extensions, readable, writable, destinations, sources, operations}]} |
paths --json |
{count, paths: [{source, destination, operation?, title?, engine, status, fidelity, preserves, limitations, acceptsMultipleSources}], unavailable: [{engine, reason, paths}]} |
detect --json |
[{path, format?, formatName?, category?, confidence, evidence, mismatch, fileExtension, extensionFormats, textEncoding?, isDirectory}] |
inspect --json |
{path, detection, engine?, engineError?, inspection: FileInspection} |
plan --json |
{path, sourceFormat, detection, destinationFormat, operation?, chained, steps: [{source, destination, operation?, engine, status, fidelity}], status, fidelity, preserves, limitations, warnings, heavy} |
options --json |
{source, destination, operation?, engine, chained, note?, options: [{key, label, group, type, defaultValue, minimum?, maximum?, step?, unit?, choices?, placeholder?, help?, advanced, secret}]} |
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} |
workflow validate --json |
{name, valid, issues: [{severity, node, message}], exportedFormats, canExportUnconverted} |
workflow run --json |
{name, succeeded, succeededWithErrors, failed, filtered, cancelled, seconds, items: [{source, status, outputs, errors, warnings}]} |
presets list --json |
{file, loadError?, presets: [{id, name, summary, appliesTo, destination, operation?, options, builtIn}]} |
doctor --json |
{version, executable, insideAppBundle, toolsEnvironment?, wiredPackages, notWiredPackages, engines, searchDirectories, tools, libraries, loadedImagesOutsideSystem, registry, diagnostics, problems} |
matrix --json |
{identity: {tool, wiredPackages, notWiredPackages, engines, registryFingerprint}, totals, rows} |
Members marked ? are absent when unknown. errorKind is one of unsupportedPath, unreadableInput, malformedInput,
encryptedInput, engineUnavailable, invalidOption, limitExceeded, toolFailed, outputInvalid, writeFailed,
destinationExists, internalError.
The ConvertKit library (for the app)
Packages/ConvertKit is the single place where the engines are assembled; the tool is a thin layer over it.
import ConvertKit // re-uses ConvertCore types
let engines = ORIXEngines.all() // every wired engine, in registration order
let heavy = ORIXEngines.heavyEngineIDs // ["video", "documents", "presentations"]
let service = ConversionService() // registry + planner + queue (heavy rule set) + history + presets + workflows
let ids = await service.convert(urls, to: .jpeg, destination: OutputDestination(directory: folder))
for id in ids { _ = await service.queue.waitForJob(id) }- Wiring an engine package = one line: its name in the
enginesarray ofPackages/ConvertKit/Package.swift. The matching#if canImport(Engine…)block ofSources/ConvertKit/ORIXEngines.swiftthen compiles in (a block exists for each of the twelve known packages; a thirteenth needs its own three-line block). - Registration order matters for inspection: when several engines list a format in
inspectableFormats, the registry asks the first one.ORIXEnginesregisters the image engine before the PDF engine for that reason (otherwise PNG, JPEG, HEIC, TIFF, GIF, BMP and WebP files are inspected by the PDF engine, which reports no pixel dimensions). ToolEnvironment.bootstrap()(called byORIXEngines.all()andConversionService.init) setsORIX_CONVERT_TOOLSfrom the executable's own folder when that folder holds bundled tools.ConversionService.Configurationoverrides the concurrency, the history file, the work root and the preset/workflow files;ORIX_CONVERT_SKIP_ENGINES=EngineX,EngineYbuilds without packages that are being edited (development only).