---
name: Convert Image
description: Convert photos between formats through av-club — including HEIC from a phone, which most tools cannot read. Optionally shrink to fit a maximum size.
category: Image
version: 1
mode: script
language: typescript
inline: ask
args:
  - file_path
inputs:
  file_path:
    type: string
    description: An image, or a folder to convert recursively.
  target_format:
    type: string
    default: jpeg
    options: [jpeg, png, webp, avif, tiff]
    description: Format to convert to.
  max_dimension:
    type: string
    default: original
    options: [original, "3000", "2000", "1600", "1200", "800"]
    description: Shrink so neither side exceeds this, keeping the aspect ratio. Never enlarges.
  delete_source:
    type: boolean
    default: false
    description: Delete each source file once its conversion has been written.
trigger:
  - type: file
    extensions: [heic, heif, jpg, jpeg, png, webp, avif, tif, tiff, gif, bmp, jp2]
  - type: directory
---

# Convert Image

Writes the result **beside the original** — `IMG_3707.HEIC` becomes `IMG_3707.jpeg` in the same folder.

**HEIC works here**, which is worth saying because it does not work in most places. Every photo a
recent iPhone takes is HEVC-coded HEIF, and the libheif that ships inside sharp is built without the
decoder for it — so a HEIC reads its own header fine and then fails on the pixels, looking exactly
like a corrupt file. av-club routes those through ImageMagick, which links the system libheif and can
decode them, and hands sharp a lossless PNG. You do not have to know any of that; it just opens.

`max_dimension` shrinks so neither side is larger than the number, keeping the aspect ratio, and never
enlarges a small image. Leave it on `original` to convert without resizing.

Skips a file already in the target format, and never overwrites an existing output.

Quality is 82 for jpeg and webp and 55 for avif — the point where a photograph stops getting visibly
better and only gets bigger. EXIF orientation is applied, so a photo taken sideways comes out upright
rather than rotated.