File conversion and compression options
convert routes by input kind and target extension. The list below reflects current source routing; check the installed capabilities for supported pairs and engine availability. An extension that can be previewed is not necessarily an export target.
Conversion map
| Input | Targets exposed by convert |
|---|---|
| Images | jpg/jpeg, png, webp, gif, bmp, heic/heif, tiff/tif, avif, ico, icns, pdf |
| Animated GIF | Also mp4, webm |
| Video | mp4, webm, mov, mkv, avi; audio extraction to mp3, aac, m4a, wav, flac |
| Audio | mp3, aac, m4a, wav, flac, aiff, alac, ogg, opus |
| Spreadsheet/data | csv, tsv, xlsx, json, parquet; pairs depend on source kind |
| png, jpg/jpeg, md/markdown, docx, txt | |
| Markdown | pdf, docx, html, txt |
| DOCX | md/markdown, pdf, html, rtf, txt |
| RTF, ODT, old DOC, plain text | html, txt |
| PPTX | pdf, png, jpg/jpeg, txt |
| Pages, Keynote, Numbers | pdf, txt, using the embedded PDF when present |
| Subtitles: srt, vtt, ass, ssa | srt, vtt, ass |
Embedded-PDF conversion of an iWork file is not native reconstruction of its editable content. Converting a PDF to Word or Markdown also changes representation; inspect layout and text before handing it back.
Important convert options
| Option | Meaning or boundary |
|---|---|
paths, to, output_dir | Absolute inputs, target format, optional destination; otherwise next to inputs |
quality | Video: high, medium (default), low; higher means better-looking and larger |
bitrate, sample_rate | Lossy audio defaults to 192k; sample rate is in Hz. Omit it to retain the source rate where supported; Opus uses 48000 |
video_codec | h264, hevc, av1; availability and container compatibility matter |
max_height, crop | Video height cap; crop rectangle in pixels from top-left |
deinterlace | yadif or bwdif |
denoise, denoise_strength | hqdn3d or nlmeans; light, medium, strong |
fps | Constant frame rate, including a rational string such as 30000/1001 |
audio_tracks, subtitle_tracks, burn_subtitle | Stream indexes from media_probe; selected subtitle can be burned into pixels |
trim_start, trim_end | Seconds for a video conversion |
pages, dpi | PDF/slide images: all, odd, even, 1-3,5; 1-based pages; 36–600 DPI, default 150, at most 100 megapixels per rendered page |
sheet, all_sheets | Named worksheet or one file per sheet for tabular exports; otherwise first sheet; XLSX output preserves all sheets |
page_size | Markdown PDF: a4 default, a5, a3, letter, legal, tabloid; Word keeps its own page size |
background | #RRGGBB, default white, when flattening image transparency into jpg/bmp/gif |
password | Open password for protected PDF conversions |
Subtitle format changes can lose features such as positioning or regions. Inspect conversion warnings before claiming the result looks or behaves like the original.
Options are format-specific. Supplying an audio flag to an image operation does not imply the image engine uses it. Retrieve the installed schema for the exact operation.
Compression
compress takes paths, optional output_dir and level: light, balanced (default), or strong. Strong trades quality for size. These levels are not the same labels as conversion’s quality.
- Images: optional
max_widthandmax_heightkeep aspect ratio.target_size_kbis available for JPEG, PNG and WebP; HEIC uses a quality level instead. Inspect returned dimensions, actual bytes and warnings before claiming a strict upload-size requirement is met. - Video:
max_resolution, such as1920x1080, keeps aspect ratio and never upscales. It is not a byte-size guarantee. - PDF: optional
passwordandremove_metadata. Compression does not imply redaction or removal of active content. If no savings are possible, a successful result can report that no file was written. - Audio: lower bitrate compression can change a lossless source into a lossy output. Use explicit
convertto FLAC or ALAC when lossless output is required.
Never promise that every file shrinks, or that a lossy export retains the original quality. Check the returned size and output format. Re-encoding already compressed material can lose quality without meaningful savings.
Batch behavior
Inputs remain separate unless the tool explicitly combines them (images_to_pdf, pdf_merge, media_join). Outputs use unique names rather than replacing existing files. A batch can partially succeed; report failed inputs and retain successful output paths. A retry may create another uniquely named output.