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

pme --version

pme --help

pme transcode

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

Multiple inputs encode in parallel using the same scheduler as the app — up to the hardware session limit (or --concurrency), with RAW formats held to their per-format isolation caps. Invalid flag values are rejected up front with exit code 2; they are never silently ignored.

Flags

Examples

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

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

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

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

pme transcode A001C001.CRM -o output.mov --codec prores422hq --canon-color canonlog2:cinemagamut

pme transcode shot.mxf -o output.mov --codec prores4444 --arri-color logc4

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

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

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

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

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

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

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

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

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

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

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.

pme probe /path/to/video.mxf

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

Example JSON response:

{
  "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.

pme inspect /path/to/video.mxf

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

Flags

pme presets

Manage encoding presets. Presets are shared with the app — a preset created via the CLI appears in the GUI and vice versa. Built-in presets cannot be modified or deleted.

List

pme presets list

pme presets list --json

Create

Creates a custom preset, starting from an existing preset's settings when --base is given, otherwise from app defaults. --codec is required unless --base is given. Requires a Pro license.

pme presets create "Proxy 1080p" --codec prores422proxy --resolution 1920x1080

pme presets create "YouTube 4K Stereo" --base "YouTube 4K H.265" --audio-channels stereo

Rename, delete, export, import

pme presets rename "Proxy 1080p" "Proxy FHD"

pme presets delete "Proxy FHD"

pme presets export "YouTube 4K H.265" ~/Desktop/youtube-4k.json

pme presets import ~/Desktop/youtube-4k.json

pme license

Manage your Pro license from the command line.

pme license status

pme license activate YOUR-LICENSE-KEY

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

pme service start

The default socket is ~/Library/Application Support/ParallelMediaEncoder/pme.sock. If you pass a custom --socket, keep the path short — macOS limits Unix socket paths to 104 characters.

pme service start --port 8080

pme service start --no-auth

pme service stop

pme service status

Auto-start with launchd

pme service install

pme service uninstall

Auth tokens

pme service 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

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

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

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

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

pme watch list

pme watch list --json

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

pme watch start all

pme watch start a1b2c3d4

pme watch start all --json

Example output while running:

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

pme watch stop all

pme watch stop a1b2c3d4

pme watch remove a1b2c3d4

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

Submit a job

All fields except inputs are optional. Invalid values (unknown codec, unknown preset, malformed resolution, unknown audio codec) are rejected with a 400/404 — never silently ignored.

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

By default the service listens on a Unix domain socket:

curl -X POST \
  --unix-socket "$HOME/Library/Application Support/ParallelMediaEncoder/pme.sock" \
  http://localhost/api/v1/jobs \
  -H "Authorization: Bearer $(pme service token)" \
  -H "Content-Type: application/json" \
  -d '{"inputs": ["/path/to/file.mxf"], "output_dir": "/output/", "codec": "hevc"}'

With pme service start --port 8080, the same API is available over TCP (localhost only):

curl -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $(pme service token)" \
  -H "Content-Type: application/json" \
  -d '{"inputs": ["/path/to/file.mxf"], "output_dir": "/output/", "codec": "hevc"}'

Server-Sent Events

Connect to /api/v1/events for real-time updates. Because EventSource can't set headers, this endpoint also accepts the token as a query parameter: /api/v1/events?token=<token>. The stream emits three event types:

• progress — per-file encoding progress (percentage, speed, 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.

Containers: H.264/HEVC/ProRes write .mov. Passing a DNx codec via --codec writes .mxf; DNx via a preset follows the preset's container setting (.mov wrapper by default, matching the app).

Exit Codes

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