Reference, version 2026.2.25

VideoRecompress Studio CLI and MCP reference

videorecompress is the command line of VideoRecompress Studio, installed with the desktop app. videorecompress serve runs its MCP server for AI agents. This page lists every command, option, exit code and MCP tool.

videorecompress <command> [arguments] [options]
videorecompress recompress video.mp4 -o compressed --preset phone_archive

Generated from videorecompress catalog, version 2026.2.25. Every command also has --help. Older spellings of some commands and options still work, so existing scripts keep running, but this page and --help leave them out. The same reference is on GitHub: cli.md and mcp-server.md.

Commands

Command	What it does
`videorecompress batch <input-dir>`	Batch recompress all videos in a directory.
`videorecompress catalog`	Print every CLI command and MCP tool as JSON (for AI agents, docs and the website).
`videorecompress formats`	List the containers and codecs it reads and writes.
`videorecompress info <file>`	Show video file information (codec, resolution, duration, HDR, audio, subtitles).
`videorecompress presets`	List available recompression presets.
`videorecompress profile`	Save, load, or validate recompression profiles.
`videorecompress profile load <file>`	Load and display a profile from JSON.
`videorecompress profile save <file>`	Build a profile from options and save to JSON.
`videorecompress profile validate <file>`	Validate a profile JSON file.
`videorecompress recompress <input>`	Recompress a single video file.
`videorecompress register <email> <key>`	Register your license key.
`videorecompress serve`	Start MCP server for AI agent integration.
`videorecompress status`	Show tool availability, license state, and GPU info.
`videorecompress watch <dir>`	Monitor a folder and auto-recompress new video files.

Output options

These options work the same way in the four ContentaSoft command lines. catalog and serve take none of them: catalog always prints JSON and serve keeps stdout for the MCP protocol.

Option	Description
`--json`	Print one JSON object on stdout (success, exitCode, error, warnings, errors, outputs + the command's fields); nothing else goes to stdout.
`--plain`	Plain text: no colours, no escape codes, ASCII tables. Automatic when stdout is a pipe or a file, or when NO_COLOR is set.
`--quiet`	Print errors only.
`--verbose`	Verbose output: details and, on an error, the stack trace.
`--progress`	With --json: before the result object, one line per finished item, {"type":"progress","file":NAME,"completed":N,"total":T}.

Exit codes

The same table in the four ContentaSoft command lines. --help ends with it and catalog lists it.

Code	Name	Meaning
0	`ok`	OK: everything asked for was done.
1	`unexpected_error`	Unexpected error (a bug or a broken install); see the log.
2	`invalid_arguments`	Invalid arguments: unknown option, missing or malformed value; nothing was done.
3	`input_not_found`	Input not found or unreadable; nothing was done.
4	`partial_failure`	Partial failure: some items succeeded, some failed.
5	`all_failed`	All failed: no item succeeded.
6	`license_refused`	License or trial refused the run.
130	`cancelled`	Cancelled (Ctrl+C).

JSON output

With --json a command prints one JSON object on stdout and nothing else; logs go to stderr. Every object has these keys, beside the fields of the command itself:

Key	Meaning
`success`	`true` when the run did everything it was asked to do
`exitCode`	the process exit code (see Exit codes)
`error`	one sentence when the run failed, otherwise `null`
`warnings`	notes about the run that did not stop it
`errors`	one entry per item that failed (a batch keeps going)
`outputs`	the files the run wrote

Trial keys, present only when they apply:

Key	Meaning
`trialWatermarked`	the output carries the trial watermark
`trialExport`	the output is a trial export
`trialNotice`	one sentence about the trial, for the user
`freeFilesRemaining`	free full-quality files left on this computer
`buyUrl`	where to buy a licence

With --json --progress a long command first prints one progress line per finished item (NDJSON), then the result object last. A script that wants only the result skips the lines that start with {"type":"progress". Progress keys:

Key	Meaning
`type`	always `"progress"`
`file`	the file that finished
`completed`	items finished so far
`total`	items in the run

Command reference

`videorecompress batch`

Batch recompress all videos in a directory.

videorecompress batch <input-dir> [options]

Argument	Description
`<input-dir>`	Path to the directory containing video files.

Option	Type	Description
`--include`	string[]	Only videos matching this pattern (e.g. "*.mp4"); repeat the option or separate patterns with ';' or ','.
`--exclude`	string[]	Leave out videos matching this pattern (same forms as --include).
`--recursive`	boolean	Include subdirectories.
`--workers`	integer	Number of parallel workers.
`--report`	string	Write a CSV report, one row per input file (file, status, output, outputCodec, trialWatermarked, error).
`--output`	string	Output directory.
`--codec`	string	Video codec: h264, h265, av1, vp9, copy.
`--crf`	integer	Constant Rate Factor (0-63).
`--quality-mode`	string	Quality mode: crf, cbr, twopass.
`--bitrate`	integer	Target bitrate in kbps (for cbr/twopass).
`--encoder-preset`	string	Encoder speed preset (ultrafast..veryslow, or an SVT-AV1 number 0-13; mapped to what each encoder accepts).
`--preset`	string	Named recompression preset to use as base settings (e.g. phone_archive — run 'videorecompress presets' for the list). Explicit flags override preset values.
`--hw-accel`	string	Hardware acceleration: auto, nvenc, qsv, amf, software.
`--audio-mode`	string	Audio mode: copy, reencode, remove.
`--audio-codec`	string	Audio codec: aac, opus, mp3, flac, ac3, eac3.
`--audio-bitrate`	integer	Audio bitrate in kbps.
`--container`	string	Container format: mp4, mkv, webm.
`--width`	integer	Target width (0 = keep original).
`--height`	integer	Target height (0 = keep original).
`--denoise`	string	Denoise: off, light, medium, strong.
`--deinterlace`	string	Deinterlace: off, yadif, yadif-bob.
`--watermark-text`	string	Apply a text watermark.
`--watermark-image`	string	Apply an image watermark (PNG/JPG path).
`--watermark-position`	string	Watermark position: TopLeft, TopCenter, TopRight, CenterLeft, Center, CenterRight, BottomLeft, BottomCenter, BottomRight.
`--watermark-opacity`	integer	Watermark opacity 0-100.
`--watermark-scale`	integer	Watermark size as % of video width (5-100).
`--trim-mode`	string	Trim mode: none, skip-start, skip-end, keep-first, custom.
`--trim-start`	number	Trim start time in seconds (for custom range).
`--trim-end`	number	Trim end time in seconds (for custom range).
`--trim-duration`	number	Trim duration in seconds (for skip-start, skip-end, keep-first).
`--fps`	number	Target frame rate.
`--fps-mode`	string	Frame rate mode: auto, cfr, vfr.
`--hdr`	string	HDR sources (HDR10, HLG): keep (stay 10-bit HDR where the codec can hold it; H.264 is always converted) or sdr (tone-map to SDR BT.709). SDR sources are not affected.
`--overwrite`	boolean	Overwrite existing output files.
`--skip-existing`	boolean	Skip a file whose output already exists, so a re-run only does what is missing.
`--profile`	string	Load settings from a JSON profile file.
`--measure-quality`	boolean	Measure SSIM/VMAF quality after encoding.

Output options: --json, --plain, --quiet, --verbose, --progress.

`videorecompress catalog`

Print every CLI command and MCP tool as JSON (for AI agents, docs and the website).

videorecompress catalog

`videorecompress formats`

List the containers and codecs it reads and writes.

videorecompress formats [options]

Option	Type	Description
`--input`	boolean	Show what it reads only.
`--output`	boolean	Show what it writes only.

Output options: --json, --plain, --quiet, --verbose, --progress.

`videorecompress info`

Show video file information (codec, resolution, duration, HDR, audio, subtitles).

videorecompress info <file>

Argument	Description
`<file>`	Path to the video file.

Output options: --json, --plain, --quiet, --verbose, --progress.

`videorecompress presets`

List available recompression presets.

videorecompress presets [options]

Option	Type	Description
`--preset`	string	Show full details for a specific preset by ID.

Output options: --json, --plain, --quiet, --verbose, --progress.

`videorecompress profile`

Save, load, or validate recompression profiles.

Subcommands: profile load, profile save, profile validate.

`videorecompress profile load`

Load and display a profile from JSON.

videorecompress profile load <file>

Argument	Description
`<file>`	Path to the profile JSON file.

Output options: --json, --plain, --quiet, --verbose, --progress.

`videorecompress profile save`

Build a profile from options and save to JSON.

videorecompress profile save <file> [options]

Argument	Description
`<file>`	Path to save the profile JSON file.

Option	Type	Description
`--output`	string	Output directory.
`--codec`	string	Video codec: h264, h265, av1, vp9, copy.
`--crf`	integer	Constant Rate Factor (0-63).
`--quality-mode`	string	Quality mode: crf, cbr, twopass.
`--bitrate`	integer	Target bitrate in kbps (for cbr/twopass).
`--encoder-preset`	string	Encoder speed preset (ultrafast..veryslow, or an SVT-AV1 number 0-13; mapped to what each encoder accepts).
`--preset`	string	Named recompression preset to use as base settings (e.g. phone_archive — run 'videorecompress presets' for the list). Explicit flags override preset values.
`--hw-accel`	string	Hardware acceleration: auto, nvenc, qsv, amf, software.
`--audio-mode`	string	Audio mode: copy, reencode, remove.
`--audio-codec`	string	Audio codec: aac, opus, mp3, flac, ac3, eac3.
`--audio-bitrate`	integer	Audio bitrate in kbps.
`--container`	string	Container format: mp4, mkv, webm.
`--width`	integer	Target width (0 = keep original).
`--height`	integer	Target height (0 = keep original).
`--denoise`	string	Denoise: off, light, medium, strong.
`--deinterlace`	string	Deinterlace: off, yadif, yadif-bob.
`--watermark-text`	string	Apply a text watermark.
`--watermark-image`	string	Apply an image watermark (PNG/JPG path).
`--watermark-position`	string	Watermark position: TopLeft, TopCenter, TopRight, CenterLeft, Center, CenterRight, BottomLeft, BottomCenter, BottomRight.
`--watermark-opacity`	integer	Watermark opacity 0-100.
`--watermark-scale`	integer	Watermark size as % of video width (5-100).
`--trim-mode`	string	Trim mode: none, skip-start, skip-end, keep-first, custom.
`--trim-start`	number	Trim start time in seconds (for custom range).
`--trim-end`	number	Trim end time in seconds (for custom range).
`--trim-duration`	number	Trim duration in seconds (for skip-start, skip-end, keep-first).
`--fps`	number	Target frame rate.
`--fps-mode`	string	Frame rate mode: auto, cfr, vfr.
`--hdr`	string	HDR sources (HDR10, HLG): keep (stay 10-bit HDR where the codec can hold it; H.264 is always converted) or sdr (tone-map to SDR BT.709). SDR sources are not affected.
`--overwrite`	boolean	Overwrite existing output files.
`--skip-existing`	boolean	Skip a file whose output already exists, so a re-run only does what is missing.
`--profile`	string	Load settings from a JSON profile file.
`--measure-quality`	boolean	Measure SSIM/VMAF quality after encoding.

Output options: --json, --plain, --quiet, --verbose, --progress.

`videorecompress profile validate`

Validate a profile JSON file.

videorecompress profile validate <file>

Argument	Description
`<file>`	Path to the profile JSON file to validate.

Output options: --json, --plain, --quiet, --verbose, --progress.

`videorecompress recompress`

Recompress a single video file.

videorecompress recompress <input> [options]

Argument	Description
`<input>`	Path to the video file.

Option	Type	Description
`--output`	string	Output directory.
`--codec`	string	Video codec: h264, h265, av1, vp9, copy.
`--crf`	integer	Constant Rate Factor (0-63).
`--quality-mode`	string	Quality mode: crf, cbr, twopass.
`--bitrate`	integer	Target bitrate in kbps (for cbr/twopass).
`--encoder-preset`	string	Encoder speed preset (ultrafast..veryslow, or an SVT-AV1 number 0-13; mapped to what each encoder accepts).
`--preset`	string	Named recompression preset to use as base settings (e.g. phone_archive — run 'videorecompress presets' for the list). Explicit flags override preset values.
`--hw-accel`	string	Hardware acceleration: auto, nvenc, qsv, amf, software.
`--audio-mode`	string	Audio mode: copy, reencode, remove.
`--audio-codec`	string	Audio codec: aac, opus, mp3, flac, ac3, eac3.
`--audio-bitrate`	integer	Audio bitrate in kbps.
`--container`	string	Container format: mp4, mkv, webm.
`--width`	integer	Target width (0 = keep original).
`--height`	integer	Target height (0 = keep original).
`--denoise`	string	Denoise: off, light, medium, strong.
`--deinterlace`	string	Deinterlace: off, yadif, yadif-bob.
`--watermark-text`	string	Apply a text watermark.
`--watermark-image`	string	Apply an image watermark (PNG/JPG path).
`--watermark-position`	string	Watermark position: TopLeft, TopCenter, TopRight, CenterLeft, Center, CenterRight, BottomLeft, BottomCenter, BottomRight.
`--watermark-opacity`	integer	Watermark opacity 0-100.
`--watermark-scale`	integer	Watermark size as % of video width (5-100).
`--trim-mode`	string	Trim mode: none, skip-start, skip-end, keep-first, custom.
`--trim-start`	number	Trim start time in seconds (for custom range).
`--trim-end`	number	Trim end time in seconds (for custom range).
`--trim-duration`	number	Trim duration in seconds (for skip-start, skip-end, keep-first).
`--fps`	number	Target frame rate.
`--fps-mode`	string	Frame rate mode: auto, cfr, vfr.
`--hdr`	string	HDR sources (HDR10, HLG): keep (stay 10-bit HDR where the codec can hold it; H.264 is always converted) or sdr (tone-map to SDR BT.709). SDR sources are not affected.
`--overwrite`	boolean	Overwrite existing output files.
`--skip-existing`	boolean	Skip a file whose output already exists, so a re-run only does what is missing.
`--profile`	string	Load settings from a JSON profile file.
`--measure-quality`	boolean	Measure SSIM/VMAF quality after encoding.

Output options: --json, --plain, --quiet, --verbose, --progress.

`videorecompress register`

videorecompress register <email> <key>

Argument	Description
`<email>`	Registration email.
`<key>`	License key.

Output options: --json, --plain, --quiet, --verbose, --progress.

`videorecompress serve`

Start MCP server for AI agent integration.

videorecompress serve

`videorecompress status`

Show tool availability, license state, and GPU info.

videorecompress status

Output options: --json, --plain, --quiet, --verbose, --progress.

`videorecompress watch`

Monitor a folder and auto-recompress new video files.

videorecompress watch <dir> [options]

Argument	Description
`<dir>`	Path to the folder to watch.

Option	Type	Description
`--preset`	string	Preset ID to use (e.g. security_archive, phone_archive, max_savings; default: phone_archive).
`--output`	string	Output directory for recompressed files (default: same as source).
`--recursive`	boolean	Include subfolders.
`--include`	string[]	Only videos matching this pattern (e.g. "*.mp4"); repeat the option or separate patterns with ';' or ','.
`--exclude`	string[]	Leave out videos matching this pattern (same forms as --include).
`--watermark-text`	string	Apply a text watermark to all videos.
`--watermark-image`	string	Apply an image/logo watermark from a file (PNG, JPG).
`--watermark-position`	string	Watermark position: TopLeft, TopCenter, TopRight, CenterLeft, Center, CenterRight, BottomLeft, BottomCenter, BottomRight.
`--watermark-opacity`	integer	Watermark opacity 0-100.
`--watermark-scale`	integer	Watermark size as % of video width (5-100).

Output options: --json, --plain, --quiet, --verbose, --progress.

MCP server

videorecompress serve exposes 7 tools over the Model Context Protocol (stdio, newline-delimited JSON-RPC 2.0; protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05), so an AI agent such as Claude Code, Claude Desktop, Cursor or Codex can work on files on your PC. Server name: videorecompress-studio. Pass absolute paths to every tool.

{
  "mcpServers": {
    "videorecompress-studio": {
      "command": "videorecompress",
      "args": [
        "serve"
      ]
    }
  }
}

In Claude Code one command adds it: claude mcp add videorecompress-studio -- videorecompress serve. Stdout carries JSON-RPC only, ping is answered while a tool runs, notifications/cancelled stops a running call, and a tool that cannot do its job returns isError: true with a sentence that names the problem.

Tool	Title	Read-only	Destructive	Idempotent	Network
`batch_recompress`	Batch recompress videos	no	no	no	no
`estimate_savings`	Estimate space savings	yes	no	yes	no
`get_file_info`	Get video file info	yes	no	yes	no
`get_license_status`	Get license and trial status	yes	no	yes	no
`list_formats`	List formats	yes	no	yes	no
`list_presets`	List presets	yes	no	yes	no
`recompress_video`	Recompress video	no	no	no	no

Destructive: the tool can replace a file that already exists. Network: the tool uses the internet.

`batch_recompress`

writes files

Batch recompress videos. Batch recompress all videos in a directory.

Parameter	Type	Required	Description
`input_dir`	string	yes	Directory containing video files to recompress.
`output_dir`	string	yes	Output directory for recompressed files.
`preset`	string	no	Preset ID, one of: phone_archive, youtube_raw, security_archive, wedding_archive, max_savings, av1_max_savings, quick_h264, web_optimized, drone_footage, screen_recording, 4k_to_1080p, dashcam_archive, gaming_clips, old_video_rescue, gif_creator, youtube_thumbnails, video_contact_sheet, whatsapp, email_attachment, discord_free, twitter_x, instagram_reels, tiktok, iphone_to_mp4 (custom presets saved in the app work too; list_presets shows them all).
`codec`	string	no	Video codec: h264, h265, av1, vp9 (used when no preset specified).
`crf`	integer	no	Constant Rate Factor (used when no preset specified). Range: 0 to 63.
`workers`	integer	no	Number of parallel workers (default: 1 for software, 2 for hardware). Minimum: 1.
`hdr`	string	no	HDR sources (HDR10, HLG): keep (default; stays 10-bit HDR with H.265/AV1/VP9, H.264 is always tone-mapped) or sdr (tone-map to SDR BT.709). Single-layer Dolby Vision is kept only by the H.265 software encoder (hw_accel software) into MP4/MKV without a resize; HDR10+ only by VP9. Otherwise the base HDR10/HLG picture is kept and the result's hdrNote says what was not.
`overwrite`	boolean	no	Replace the output when it already exists (default: an existing output is kept and the new file gets a free name).
`skip_existing`	boolean	no	Leave an input alone when its output already exists, so a re-run only does what is missing.

`estimate_savings`

read-onlyidempotent

Estimate space savings. Estimate how much smaller ONE video gets with a preset (or codec/crf) by actually encoding it: three 4-second samples spread over the file (the whole file when it is 20 s or shorter) with the same settings and encoder recompress_video uses, scaled to the full file. Takes a few seconds per file and writes only temporary files. Use it to compare presets on a representative file. Returns estimatedReductionPercent, a low-high range across the samples, the method (full_encode = exact size, sample_encode = typically within a few points, heuristic = a per-codec guess when no sample could be encoded) and the encoder. It does not measure quality: run recompress_video on one file (CLI: recompress --measure-quality for VMAF/SSIM) to check the picture before converting a whole folder.

Parameter	Type	Required	Description
`input_path`	string	yes	Absolute path to the video file.
`preset`	string	no	Preset ID, one of: phone_archive, youtube_raw, security_archive, wedding_archive, max_savings, av1_max_savings, quick_h264, web_optimized, drone_footage, screen_recording, 4k_to_1080p, dashcam_archive, gaming_clips, old_video_rescue, gif_creator, youtube_thumbnails, video_contact_sheet, whatsapp, email_attachment, discord_free, twitter_x, instagram_reels, tiktok, iphone_to_mp4 (custom presets saved in the app work too; list_presets shows them all).
`codec`	string	no	Video codec: h264, h265, av1, vp9 (used when no preset specified).
`crf`	integer	no	Constant Rate Factor (used when no preset specified, default: 23). Range: 0 to 63.

`get_file_info`

read-onlyidempotent

Get video file info. Analyze a video file and return codec, resolution, duration, bitrate, HDR, audio and subtitle information.

Parameter	Type	Required	Description
`input_path`	string	yes	Absolute path to the video file.

`get_license_status`

read-onlyidempotent

Get license and trial status. Get the license and trial state before compressing: registered or trial, clean files left (freeFilesRemaining), and what files become after the free ones (afterFreeFiles: watermark = a watermark and a 10-minute length cap). nextOutput says what the next file will be: clean or watermark.

No parameters.

`list_formats`

read-onlyidempotent

List formats. List the containers and codecs VideoRecompress reads (input) and writes (output), with the video codecs each output container holds.

Parameter	Type	Required	Description
`direction`	string	no	input = only what it reads, output = only what it writes, all (default) = both (the CLI's formats --input / --output). One of: `input`, `output`, `all`.

`list_presets`

read-onlyidempotent

List presets. List available video recompression presets with codec, quality, and estimated savings.

No parameters.

`recompress_video`

writes files

Recompress video. Recompress a video file with modern codecs (H.265, AV1, VP9) for smaller file size.

Parameter	Type	Required	Description
`input_path`	string	yes	Absolute path to the source video file.
`output_path`	string	no	Output file path (default: auto-generated in same directory).
`preset`	string	no	Preset ID, one of: phone_archive, youtube_raw, security_archive, wedding_archive, max_savings, av1_max_savings, quick_h264, web_optimized, drone_footage, screen_recording, 4k_to_1080p, dashcam_archive, gaming_clips, old_video_rescue, gif_creator, youtube_thumbnails, video_contact_sheet, whatsapp, email_attachment, discord_free, twitter_x, instagram_reels, tiktok, iphone_to_mp4 (custom presets saved in the app work too; list_presets shows them all).
`codec`	string	no	Video codec: h264, h265, av1, vp9 (overrides preset if both specified).
`crf`	integer	no	Constant Rate Factor (overrides preset if both specified). Range: 0 to 63.
`hw_accel`	string	no	Hardware acceleration: auto, nvenc, qsv, amf, software.
`hdr`	string	no	HDR sources (HDR10, HLG): keep (default; stays 10-bit HDR with H.265/AV1/VP9, H.264 is always tone-mapped) or sdr (tone-map to SDR BT.709). Single-layer Dolby Vision is kept only by the H.265 software encoder (hw_accel software) into MP4/MKV without a resize; HDR10+ only by VP9. Otherwise the base HDR10/HLG picture is kept and the result's hdrNote says what was not.
`overwrite`	boolean	no	true: replace the output when it exists. false: give the new file a free name instead. Default: an explicit output_path is replaced, the generated name (<name>_recompressed) is never replaced.
`skip_existing`	boolean	no	true: when the output already exists, write nothing and answer skipped: true (safe re-runs).