Drive pconv from scripts and agents

pconv is meant to be driven by scripts and agents as much as by hand.

Nothing to parse but the result

When stderr is a pipe or a file, as it is under a script, an agent or CI, pconv draws no progress line. stdout then carries only the result: the output’s path and, for a join or --loudness, the lines after it. stderr carries only an error.

On a terminal, --no-progress turns the line off and keeps the plain output; TERM=dumb does the same.

One JSON document

--json prints one JSON document instead of the plain lines, and never draws progress, even on a terminal:

$ pconv talk.mp4 small.mp4 --size 480 --json | jq -c '{file: .files[0].file, bytes: .files[0].bytes, seconds}'
{"file":"small.mp4","bytes":517216,"seconds":0.488273628}

It names the tool and version, the source with its sha256, the settings pconv chose, the device, the time taken, and each file written with its sha256, size and the ffmpeg arguments of every step. The formats reference lists every field.

pconv probe <input> prints what pconv reads from a file as JSON, and pconv profiles lists the profiles as plain lines.

Exit codes

Code	Meaning
0	It worked.
1	The conversion failed or was refused once the input was read: no audio to level, an existing output, ffmpeg’s own error. One line on stderr starting pconv: .
2	The command line is wrong.
128 plus the signal	A signal stopped it (130 for Ctrl-C on Windows).

A refusal is one line:

$ pconv talk.mp4 small.mp4
pconv: small.mp4 already exists; use --force to replace it
$ echo $?
1

A command line pconv can’t parse is answered the way clap-based tools answer, on stderr with exit 2:

$ pconv talk.mp4 small.mp4 --profile quick
error: invalid value 'quick' for '--profile <PROFILE>'
  [possible values: fast, balanced, best]

For more information, try '--help'.
$ pconv talk.mp4
error: the following required arguments were not provided:
  <OUTPUT>

Usage: pconv [OPTIONS] <INPUT> <OUTPUT>

For more information, try '--help'.

On a terminal these are coloured as clap colours them; piped, or with NO_COLOR set, they are plain.

No half files

pconv writes to a hidden partial file beside the output and renames it into place when it is done. A failed, refused or stopped run never leaves a partial file behind, so a script can treat the output’s existence as success.

Stopping

Ctrl-C, SIGTERM or SIGHUP stops ffmpeg, removes the partial and exits 128 plus the signal. On Windows, Ctrl-C or Ctrl-Break exits 130. On Linux, with setpriv on the PATH, an ffmpeg step also ends when pconv is killed outright.