SPB Git

Repository Public License

cli.md 44.5 KB

# 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

text
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.

text
$ 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.

text
$ 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.

text
$ 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.

text
$ 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.

text
$ 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.

text
$ 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 container

Exit status: 0.

text
$ 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.

text
$ 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.

text
$ 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.

text
$ 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:

text
$ 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.

text
$ 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.

text
$ 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.

text
$ 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

text
$ 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 database

Exit 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.

text
$ 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 s

Exit status: 0.

text
$ 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.

text
$ 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 s

Exit status: 0.

text
$ 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 s

Exit status: 5.

text
$ 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 s

Exit status: 0.

text
$ 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:

text
$ 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 s

Exit status: 0.

A chained conversion reports the checks of both steps:

text
$ 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:

text
$ 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 s

Exit status: 1.

--json prints one document: the summary, then every job with its outputs, warnings, validation checks, measured facts and error.

text
$ 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:

text
$ 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 @).

text
$ 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 s

Exit status: 0.

text
$ echo "example-only" | orix-convert convert a.pdf --to txt --output-dir out --option password=@stdin --quiet

Exit status: 0.

text
$ 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.

text
$ 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.

text
$ 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, webp

Exit status: 0.

text
$ 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 s

Exit status: 0.

A convert node that no input can satisfy is an error (bad.json asks for WAV → DOCX):

text
$ 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: docx

Exit 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.

text
$ 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).

text
$ 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 (what Scripts/matrix.sh writes to docs/compatibility/conversion-matrix.md and matrix.json). Tests and performance figures are read from the engine notes.
  • matrix --verify runs every declared path end to end on real fixtures and writes docs/reports/e2e-matrix.md and .json (Scripts/matrix.sh --verify). It is resumable (--work-dir), bounded (--jobs, --heavy-jobs) and time-limited per path (--timeout); --engine, --from, --to restrict it (the report is then named e2e-matrix-partial).
text
$ 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.

text
$ 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.md

Exit 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).

text
$ 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.

swift
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 engines array of Packages/ConvertKit/Package.swift. The matching #if canImport(Engine…) block of Sources/ConvertKit/ORIXEngines.swift then 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. ORIXEngines registers 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 by ORIXEngines.all() and ConversionService.init) sets ORIX_CONVERT_TOOLS from the executable's own folder when that folder holds bundled tools. ConversionService.Configuration overrides the concurrency, the history file, the work root and the preset/workflow files; ORIX_CONVERT_SKIP_ENGINES=EngineX,EngineY builds without packages that are being edited (development only).
Files main
Menu

Theme