CLI & REST API Reference

Overview

The pme CLI lets you transcode, probe media files, manage presets, and run a headless encoding server — all from the terminal. It ships inside the application bundle.

Installation

Install the CLI from within the app: Parallel Media Encoder → Install CLI Tool… in the menu bar. This creates the symlink automatically. See the Getting Started guide for details.

Or create the symlink manually:

ln -s "/Applications/Parallel Media Encoder.app/Contents/MacOS/pme" /usr/local/bin/pme

License requirement

The transcode, service, and watch commands require an active Pro license. The probe and inspect commands are free for everyone.

Quick check

Check version

pme --version

Show help

pme --help

pme transcode

Transcode one or more media files. Requires a Pro license.

Flags

Flag	Description
`inputs` (positional)	Input file path(s)
`-o, --output`	Output file or directory
`--codec`	Output codec (see Available Codecs)
`--quality`	Quality 0.0 – 1.0 (automatic mode)
`--bitrate`	Target bitrate in Kbps (manual mode)
`--preset`	Apply a saved preset by name
`--resolution`	Output resolution, e.g. `1920x1080`, or `source`
`--resize-mode`	Resize mode when aspect ratio differs: `stretch`, `fit`, or `fill` (default: `stretch`)
`--rotate`	Rotate video: `cw90`, `ccw90`, or `180`
`--audio-codec`	`aac`, `alac`, or `pcm`. CLI has no separate track/channel selector flags.
`--audio-passthrough`	Pass audio through unchanged (default)
`--lut`	Path to a `.cube` LUT file
`--proresraw-color`	ProRes RAW color mode: `flat` (V-Log for grading) or `rec709` (V-Log + Rec.709 LUT for delivery). Default: `flat`
`--in`	In-point timecode (`HH:MM:SS:FF`). Encoding starts at this frame. Default: start of file
`--out`	Out-point timecode (`HH:MM:SS:FF`). Encoding ends at this frame. Default: end of file
`--timecode-burnin`	Burn in source timecode overlay
`--watermark`	Path to a transparent PNG to use as watermark (always centered)
`--watermark-scale`	Watermark scale as percentage of source PNG size (1–400, default 100)
`--json`	Machine-readable NDJSON output
`--overwrite`	Overwrite existing output files
`--concurrency`	Max parallel encodes

Examples

Basic transcode

pme transcode input.mxf -o output.mov --codec hevc --quality 0.8

Using a preset

pme transcode input.mxf -o output.mov --preset "YouTube 4K H.265"

ProRes with LUT

pme transcode input.mxf -o output.mov --codec prores422hq --lut /path/to/look.cube

ProRes RAW with Rec.709 color

pme transcode input.braw -o output.mov --codec prores422hq --proresraw-color rec709

Batch folder

pme transcode *.mxf -o /output/folder/

JSON progress

pme transcode input.mxf -o output.mov --json

Rotate 90° clockwise (vertical video)

pme transcode input.braw -o output.mov --codec hevc --rotate cw90

Rotate counter-clockwise with custom resolution

pme transcode input.R3D -o output.mov --codec prores422hq --rotate ccw90 --resolution 1080x1920

Fit to resolution (letterbox/pillarbox)

pme transcode input.mov -o output.mov --resolution 1920x1080 --resize-mode fit

Rotate + fill (combined)

pme transcode input.mxf -o output.mov --rotate cw90 --resolution 1080x1920 --resize-mode fill

Trim to in/out range

pme transcode input.mov -o clip.mov --in 00:01:30:00 --out 00:02:15:00 --codec hevc

Trim from in-point to end of file

pme transcode input.mov -o clip.mov --in 00:05:00:00

Centered watermark at 50% of native PNG size

pme transcode input.mov -o output.mov --watermark /path/to/logo.png --watermark-scale 50

Export as animated GIF

pme transcode input.mov -o output.gif --codec gif

Extract a short GIF clip

pme transcode input.mov -o clip.gif --codec gif --in 00:00:10:00 --out 00:00:13:00

pme probe

Inspect a media file and print its metadata. Works without a Pro license.

Human-readable output

pme probe /path/to/video.mxf

JSON output

pme probe --json /path/to/video.mxf

Example JSON response:

pme probe --json output

{
  "videoCodec": "H.264",
  "width": 3840,
  "height": 2160,
  "frameRate": 59.94,
  "duration": 60.5,
  "container": "MXF",
  "audioTracks": [
    {
      "index": 0,
      "codec": "PCM",
      "channels": 1,
      "sampleRate": 48000,
      "bitDepth": 24
    },
    {
      "index": 1,
      "codec": "PCM",
      "channels": 1,
      "sampleRate": 48000,
      "bitDepth": 24
    }
  ],
  "fileSize": 1073741824
}

pme inspect

Display full metadata for a media file — codec, resolution, bit depth, chroma subsampling, timecode, HDR info, and more. Works without a Pro license.

This is a deeper analysis than pme probe. Use probe for fast scripting; use inspect for detailed human inspection.

Human-readable metadata

pme inspect /path/to/video.mxf

JSON output

pme inspect --json /path/to/video.braw

Flags

Flag	Description
`input` (positional)	Path to the media file to inspect
`--json`	Output metadata as JSON

pme presets

List saved encoding presets. Presets created in the app are available to the CLI.

Human-readable list

pme presets list

JSON array

pme presets list --json

pme license

Manage your Pro license from the command line.

Check current license

pme license status

Activate Pro

pme license activate YOUR-LICENSE-KEY

Remove license from this machine

pme license deactivate

pme service

Run Parallel Media Encoder as a headless HTTP server. This enables remote job submission, queue management, and real-time progress monitoring through the REST API.

Start & stop

Start server (Unix socket)

pme service start

Custom port

pme service start --port 8080

Disable auth (local only)

pme service start --no-auth

Stop the server

pme service stop

Check if running

pme service status

Auto-start with launchd

Install launchd agent

pme service install

Remove launchd agent

pme service uninstall

Auth tokens

Show auth token

pme service token

Generate new token

pme service token --regenerate

pme watch

Manage watch folders for automatic transcoding. Drop media into a folder and PME picks it up, applies a preset, and transcodes to your output folder. Requires a Pro license.

Watch folder configurations are shared between the GUI and CLI — a folder added via the CLI appears in the app and vice versa. Configs are stored in ~/Library/Application Support/ParallelMediaEncoder/WatchFolders.json.

How it works

When a watch folder is active, PME polls the folder at a configurable interval (1–60 minutes). New media files are moved into a PickedUp subfolder (or a custom destination on the same volume) before transcoding begins. This prevents files from being processed twice. To re-process a file, move it back out of the PickedUp destination.

The output folder cannot be inside or the same as the watch folder (this would create an infinite loop). Watch folders also cannot overlap — a new watch folder cannot be a parent or subfolder of an existing one.

For network shares (SMB, NFS, AFP), PME can store credentials and automatically remount the share if it disconnects during polling.

Add a watch folder

Flag	Description
`--folder`	Folder path to watch for new media (required)
`--output`	Output directory for transcoded files (required)
`--preset`	Preset name to apply (required)
`--interval`	Polling interval in minutes, 1–60 (default: 5)
`--overwrite`	Allow overwriting existing output files
`--suffix`	Suffix to append to output filenames
`--picked-up-path`	Custom destination for picked-up files (must be on same volume as watch folder)
`--network-user`	Username for network share authentication (SMB/NFS/AFP)
`--network-password`	Password for network share authentication (stored securely in Keychain)
`--json`	Output config as JSON

Add a watch folder with proxy suffix

pme watch add \
  --folder /Volumes/Ingest/DailyRushes \
  --output /Volumes/Export/Proxies \
  --preset "ProRes 422 LT" \
  --interval 5 \
  --suffix "-Proxy"

Watch folder with overwrite enabled

pme watch add \
  --folder ~/Desktop/WatchMe \
  --output ~/Transcoded \
  --preset "HEVC Master" \
  --interval 10 \
  --overwrite

Network share with credentials for auto-remount

pme watch add \
  --folder /Volumes/NAS/Ingest \
  --output /Volumes/NAS/Transcoded \
  --preset "ProRes 422 HQ" \
  --network-user "[email protected]" \
  --network-password "secret"

Custom PickedUp destination on the same volume

pme watch add \
  --folder /Volumes/Rushes/Camera_A \
  --output /Volumes/Rushes/Proxies \
  --preset "ProRes 422 Proxy" \
  --picked-up-path /Volumes/Rushes/Processed

List watch folders

Human-readable list

pme watch list

JSON output

pme watch list --json

Example output:

pme watch list output

a1b2c3d4  enabled
  Watch:    /Volumes/Ingest/DailyRushes
  Output:   /Volumes/Export/Proxies
  Preset:   ProRes 422 LT
  Interval: 5 min
  Suffix:   -Proxy
  Overwrite: no

b5c6d7e8  enabled
  Watch:    /Volumes/NAS/Ingest
  Output:   /Volumes/NAS/Transcoded
  PickedUp: /Volumes/NAS/Processed
  Preset:   ProRes 422 HQ
  Interval: 5 min
  Overwrite: no
  Network User: [email protected]

Start watching (foreground)

The start command runs in the foreground and prints events as files are picked up. Press Ctrl+C to stop. You can start a specific watch folder by ID prefix, or all configured folders.

Start all watch folders

pme watch start all

Start a specific watch folder (by ID prefix)

pme watch start a1b2c3d4

JSON event stream (for scripting)

pme watch start all --json

Example output while running:

Foreground output

PME watch folders running. Press Ctrl+C to stop.
  [a1b2c3d4] /Volumes/Ingest/DailyRushes (every 5 min)

[14:32:01] [a1b2c3d4] Scanning /Volumes/Ingest/DailyRushes...
[14:32:02] [a1b2c3d4] 3 files picked up (3 total)
[14:37:01] [a1b2c3d4] Scanning /Volumes/Ingest/DailyRushes...

Stop & remove

Disable all watch folders

pme watch stop all

Disable a specific watch folder

pme watch stop a1b2c3d4

Remove a watch folder config

pme watch remove a1b2c3d4

Remove by folder path

pme watch remove /Volumes/Ingest/DailyRushes

Removing a watch folder also deletes any stored network credentials from the Keychain.

REST API

When the service is running, all endpoints are available over HTTP. Every request requires an Authorization: Bearer <token> header unless the server was started with --no-auth.

Endpoints

Endpoint	Method	Description
`/api/v1/health`	GET	Health check
`/api/v1/jobs`	POST	Submit transcode job(s)
`/api/v1/jobs`	GET	List all jobs
`/api/v1/jobs/:id`	GET	Get job status
`/api/v1/jobs/:id`	DELETE	Cancel a job
`/api/v1/queue/start`	POST	Start encoding
`/api/v1/queue/pause`	POST	Pause all encodes
`/api/v1/queue/status`	GET	Queue summary
`/api/v1/presets`	GET	List presets
`/api/v1/hardware`	GET	Hardware info
`/api/v1/license`	GET	License status
`/api/v1/events`	GET (SSE)	Real-time progress stream

Submit a job

POST /api/v1/jobs

{
  "inputs": ["/path/to/input1.mxf", "/path/to/input2.mov"],
  "output_dir": "/path/to/output/",
  "codec": "hevc",
  "quality": 0.8,
  "auto_start": true
}

curl example

curl -X POST http://localhost:9847/api/v1/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs": ["/path/to/file.mxf"], "output_dir": "/output/", "codec": "hevc", "auto_start": true}'

Server-Sent Events

Connect to /api/v1/events for real-time updates. The stream emits three event types:

progress — per-file encoding progress (percentage, fps, ETA)
state_change — job state transitions (queued, encoding, completed, failed)
queue_status — overall queue summary updates

Available Codecs

Pass these IDs to --codec. DNxHR codecs require a Pro license.

ID	Codec	Notes
`h264`	H.264/AVC	Default profiles
`hevc`	H.265/HEVC	Default codec
`prores422proxy`	ProRes 422 Proxy
`prores422lt`	ProRes 422 LT
`prores422`	ProRes 422
`prores422hq`	ProRes 422 HQ
`prores4444`	ProRes 4444
`prores4444xq`	ProRes 4444 XQ
`gif`	Animated GIF	15 fps default
`dnxhr-lb`	DNxHR LB	Pro
`dnxhr-sq`	DNxHR SQ	Pro
`dnxhr-hq`	DNxHR HQ	Pro
`dnxhr-hqx`	DNxHR HQX	Pro
`dnxhr-444`	DNxHR 444	Pro

Exit Codes

Use these codes to handle errors in scripts and CI pipelines.

Code	Meaning
`0`	Success
`1`	General error
`2`	Pro license required or invalid
`3`	Input file not found
`4`	Unsupported input format
`5`	Encoding failed
`10`	Partial failure (batch: some succeeded, some failed)

CLI & REST API Reference

Overview

Installation

License requirement

Quick check

pme transcode

Flags

Examples

pme probe

pme inspect

Flags

pme presets

pme license

pme service

Start & stop

Auto-start with launchd

Auth tokens

pme watch

How it works

Add a watch folder

List watch folders

Start watching (foreground)

Stop & remove

REST API

Endpoints

Submit a job

Server-Sent Events

Available Codecs

Exit Codes

You're on mobile

Get the download link

Check your inbox!

CLI & REST API Reference

Overview

Installation

License requirement

Quick check

pme transcode

Flags

Examples

pme probe

pme inspect

Flags

pme presets

pme license

pme service

Start & stop

Auto-start with launchd

Auth tokens

pme watch

How it works

Add a watch folder

List watch folders

Start watching (foreground)

Stop & remove

REST API

Endpoints

Submit a job

Server-Sent Events

Available Codecs

Exit Codes

You're on mobile

Get the download link

Check your inbox!

Cookie Preferences