---
title: File conversion and compression options
description: FileHop conversion targets, selection options, output behavior and compression caveats for agents.
order: 2
---

# 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 |
| PDF | 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_width` and `max_height` keep aspect ratio. `target_size_kb` is 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 as `1920x1080`, keeps aspect ratio and never upscales. It is not a byte-size guarantee.
- PDF: optional `password` and `remove_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 `convert` to 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.