CamoConvert User Guide

CamoConvert runs fully offline. Files stay on your device, and every conversion happens locally with bundled engines — Pillow + pillow-heif for images, FFmpeg for video and audio, and a local document stack for PDFs and Office files.

1. GUI — Desktop App #

Windows: Launch CamoConvert.exe from the install folder or Start menu. macOS: Open CamoConvert from Applications (or wherever you installed the app). The app opens to a single window with a drop zone, an output-format dropdown, and a Convert button.

1.1 Single-file conversion #

1. Drag a supported file into the drop zone, or click Load to browse.
2. The drop zone shows the file's type badge (IMAGE, VIDEO, AUDIO, or DOCUMENT), name, path, and size.
3. Pick a target format from the dropdown — only formats valid for the detected file type are listed.
4. Click Convert. The progress bar and status text update live.
5. When the job finishes, a Save As dialog opens, defaulting to your Downloads folder. Pick a location and confirm.
6. Click Cancel at any point during conversion to stop the job and remove the partial staged output.

1.2 Batch (folder) mode #

1. Drag a folder onto the drop zone, or click Load and select a folder.
2. CamoConvert scans the folder's top-level files and opens the Batch Convert dialog.
3. Compatible files appear in a list; unsupported files are listed but not converted, with a reason shown next to each.
4. Each compatible row has its own output-format dropdown — pick a different target format per file if you want.
5. Choose Save beside each input or click Select Output Folder to write all outputs into one destination.
6. If outputs would conflict with existing files, CamoConvert prompts once before the run starts: overwrite all, auto-rename, or cancel.
7. Click Start. Files convert sequentially with per-file progress and a per-file Cancel button.

Batch limits, by design, to keep performance predictable on a normal laptop:

• Top-level files only (no recursion in batch mode — use the CLI for recursive runs)
• Cap of 250 files per batch
• Cap of 10 GB total across compatible inputs
• Warns before processing more than 50 files, more than 2 GB, or any single file over 1 GB

1.3 Metadata scrubbing #

CamoConvert removes embedded metadata on every image, video, and audio output.

• Images are written as fresh saves; all EXIF tags are removed from the output.
• Video & audio outputs use FFmpeg with -map_metadata -1 and -map_chapters -1 — embedded metadata and chapters are dropped.
• To strip metadata without changing the file type, pick the same output format as the input. CamoConvert will re-encode the file in place.
• Image conversions targeting non-alpha formats (e.g., JPEG) flatten transparency onto a white background.
• Icon outputs (ICO, ICNS) are centered onto a square transparent canvas before save.

1.4 Supported formats #

Document outputs are extracted text content (Markdown, HTML, or plain text), not pixel-perfect recreations of the source layout. The first document conversion in a session takes a moment longer while the local document stack initializes.

1.5 Notes & behavior #

• The output dropdown only shows formats valid for the selected input.
• Video inputs can convert to video outputs or audio-only outputs (audio extraction).
• Animated GIF input is supported; GIF output preserves frames, timing, and loop settings.
• Converted files are staged in a local cache until you pick a save location.
• Canceling a conversion removes the partial staged file, if one was created.
• Use Open Downloads in the menu to jump to the default destination folder.
• FFmpeg is bundled with the app; CamoConvert does not use any system-installed FFmpeg, conda FFmpeg, or PATH fallback.

2. CLI — camoconvert-cli #

The Pro install includes a headless CLI next to the GUI: on Windows, camoconvert-cli.exe alongside CamoConvert.exe; on macOS, a camoconvert-cli binary (no .exe) in the same layout as your install. The CLI shares the same conversion engines as the GUI and is suited for scripts, folder watchers, and AI agent workflows.

2.1 Examples #

Examples use Windows-style paths (.\). On macOS, use ./ for relative paths if you prefer.

Convert one file, inferring the output format from the output extension:

camoconvert-cli -i .\photo.heic -o .\photo.jpg

Convert one file into a destination folder with an explicit format:

camoconvert-cli -i .\clip.mp4 --format mp3 --output-dir .\audio

Batch convert a folder recursively to WEBP:

camoconvert-cli --input-dir .\incoming --output-dir .\converted --format webp --recursive

Auto-rename on output conflicts instead of failing:

camoconvert-cli --input-dir .\incoming --format jpg --on-conflict rename

Filter by extension during a batch run (only HEIC and PNG inputs):

camoconvert-cli --input-dir .\photos --format jpg --extensions heic,png

Dry run — print the plan without writing any files:

camoconvert-cli --input-dir .\incoming --format md --dry-run

Parallel batch with 4 workers:

camoconvert-cli --input-dir .\photos --format jpg --workers 4

JSON output for agents and scripts:

camoconvert-cli -i .\report.pdf -o .\report.md --json

2.2 All options #

Exit codes:

• 0 — success
• 1 — conversion failed
• 2 — usage error (bad flags or arguments)

2.3 JSON output for agents #

Pass --json to emit a machine-readable report on STDOUT. Each entry includes the input path, output path, target format, status, message, and input/output sizes in bytes — easy to consume from a folder watcher, CI pipeline, or AI agent.

camoconvert-cli --input-dir .\incoming --format md --recursive --json

Need help? Reach us at contact@camotext.ai.