image-to-webp 0.1.0__tar.gz

image_to_webp-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Virtual environment
+.venv/
+venv/
+env/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Partial conversion output
+*.webp.part
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/
+*.swp

image_to_webp-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 — unreleased
+
+- First release as a Python library (`import image_to_webp`).
+- Python API: `convert_file`, `convert_bytes`, `convert_image`, `convert_many`.
+- `image-to-webp` command (also `python -m image_to_webp`).
+- Optional installs for more formats: `[heif]`, `[raw]`, `[svg]`, `[all]`.

image_to_webp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stakmi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

image_to_webp-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.5
+Name: image-to-webp
+Version: 0.1.0
+Summary: Convert images in almost any format (PNG, JPEG, GIF, TIFF, HEIC, AVIF, RAW, SVG, ...) to WebP.
+Project-URL: Homepage, https://github.com/stakmi/image-to-webp
+Project-URL: Repository, https://github.com/stakmi/image-to-webp
+Project-URL: Issues, https://github.com/stakmi/image-to-webp/issues
+Project-URL: Changelog, https://github.com/stakmi/image-to-webp/blob/main/CHANGELOG.md
+Author: stakmi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: convert,converter,heic,image,pillow,raw,svg,webp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pillow>=10.0
+Provides-Extra: all
+Requires-Dist: cairosvg>=2.7; extra == 'all'
+Requires-Dist: pillow-heif>=0.16; extra == 'all'
+Requires-Dist: rawpy>=0.19; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: cairosvg>=2.7; extra == 'dev'
+Requires-Dist: pillow-heif>=0.16; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: rawpy>=0.19; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: heif
+Requires-Dist: pillow-heif>=0.16; extra == 'heif'
+Provides-Extra: raw
+Requires-Dist: rawpy>=0.19; extra == 'raw'
+Provides-Extra: svg
+Requires-Dist: cairosvg>=2.7; extra == 'svg'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# image-to-webp
+
+Convert images in almost any format to [WebP](https://developers.google.com/speed/webp), from Python or the command line.
+
+- Over 70 input formats with Pillow alone: PNG, JPEG, GIF, BMP, TIFF, ICO/ICNS, TGA, PSD, JPEG 2000, PCX, PPM/PGM/PBM, DDS, SGI, QOI, WebP, …
+- More formats through optional installs: HEIC/HEIF/AVIF, camera RAW (CR2, CR3, NEF, ARW, DNG, …) and SVG
+- Applies EXIF rotation, keeps transparency, and turns animated GIF/APNG into animated WebP
+- Converts files in parallel and writes each output in one step, so a failed run never leaves a half-written file
+
+## Install
+
+```bash
+pip install image-to-webp            # core formats (Pillow only)
+pip install "image-to-webp[all]"     # + HEIC/AVIF, RAW and SVG
+```
+
+| Optional install | Adds | Package |
+|---|---|---|
+| `[heif]` | HEIC / HEIF / AVIF | `pillow-heif` |
+| `[raw]` | Camera RAW | `rawpy` |
+| `[svg]` | SVG / SVGZ | `cairosvg` (also needs the system cairo library: `brew install cairo` or `apt install libcairo2`) |
+
+Requires Python 3.9+.
+
+## Library usage
+
+```python
+from image_to_webp import convert_file, convert_bytes, convert_image, convert_many, ConversionOptions
+
+# One file -> photo.webp next to it (returns the output Path)
+convert_file("photo.heic")
+convert_file("photo.png", "out/photo.webp", quality=90)
+
+# In memory
+webp_bytes = convert_bytes(png_bytes, lossless=True)
+webp_bytes = convert_bytes(open("img.cr2", "rb"), filename="img.cr2")  # filename hints RAW decoding
+webp_bytes = convert_image(pil_image, quality=75)
+
+# Reusable settings
+opts = ConversionOptions(quality=85, method=6, max_size=(2560, 2560), keep_metadata=True)
+convert_file("big.tif", options=opts)
+
+# Batch: files and/or directories, in parallel
+summary = convert_many(["images/", "extra.gif"], output_dir="webp", recursive=True,
+                       jobs=4, on_result=lambda r: print(r.status, r.src))
+print(summary.converted, summary.skipped, summary.failed, summary.bytes_saved)
+```
+
+### API reference
+
+| Name | Description |
+|---|---|
+| `convert_file(src, dst=None, options=None, *, overwrite=True, **opts) -> Path` | Convert one file. `dst` defaults to `src` with a `.webp` extension. |
+| `convert_bytes(data, options=None, *, filename=None, **opts) -> bytes` | Convert bytes or a binary file object. |
+| `convert_image(image, options=None, **opts) -> bytes` | Encode a `PIL.Image.Image`. |
+| `convert_many(inputs, output_dir=None, options=None, *, recursive, overwrite=False, delete_original, jobs, on_result, **opts) -> BatchSummary` | Convert many files. One failed file doesn't stop the run. |
+| `plan_conversions(inputs, output_dir=None, *, recursive, overwrite)` | Preview what `convert_many` would do (dry run). |
+| `ConversionOptions(quality=80, lossless=False, method=4, max_size=None, keep_metadata=False)` | Encoder settings, checked when created. |
+| `ConversionResult` / `BatchSummary` | Results for each file and for the whole batch. |
+| `supported_extensions()`, `is_supported(path)`, `plugin_status()` | See which formats work in the current environment. |
+| `open_image(source, filename=None)` | Open any supported input as a PIL image. |
+| `ImageToWebPError` → `UnsupportedFormatError`, `ConversionError` | Exceptions. |
+
+`**opts` accepts the same keywords as `ConversionOptions` (`quality`, `lossless`, `method`, `max_size`, `keep_metadata`).
+The library never prints. Messages go to Python's `logging` under the `image_to_webp` logger.
+
+## Command line
+
+```bash
+image-to-webp photo.jpg                        # -> photo.webp next to source
+image-to-webp ./images -r -o ./webp            # recursive, mirror tree into ./webp
+image-to-webp *.png --lossless
+image-to-webp ./raw -q 85 --max-size 2560x2560 -j 8
+image-to-webp ./images -r --dry-run
+image-to-webp --list-formats                   # formats + optional plugin status
+python -m image_to_webp --help                 # same tool
+```
+
+| Option | Description |
+|---|---|
+| `-r, --recursive` | Search directories recursively |
+| `-o, --output DIR` | Output directory (default: next to source) |
+| `-q, --quality N` | Quality 0–100 (default 80) |
+| `--lossless` | Lossless encoding |
+| `-m, --method N` | Compression effort 0–6 (default 4) |
+| `--max-size WxH` | Downscale to fit, keeping aspect ratio |
+| `--keep-metadata` | Keep EXIF and ICC profile |
+| `--overwrite` | Overwrite existing `.webp` (default: skip) |
+| `--delete-original` | Delete source after successful conversion |
+| `-j, --jobs N` | Parallel workers (default: CPU count) |
+| `--dry-run` | Show what would be converted |
+| `-v, --verbose` | Print each file |
+| `--list-formats` | Show supported formats and plugin status |
+
+Exit code is `0` on success, `1` if any file failed, `2` for invalid arguments.
+
+> The command is called `image-to-webp`, not `img2webp`, because libwebp already ships a tool named `img2webp`.
+
+## Development
+
+```bash
+./install.sh                    # .venv + editable install with all optional formats + link command to /usr/local/bin (macOS) or /usr/bin
+./install.sh --uninstall        # remove the linked command
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest
+```
+
+`install.sh` uses `sudo` only when the target directory isn't writable. Override with `BIN_DIR=~/.local/bin` or `CMD_NAME=...`.
+
+## Releasing
+
+1. Update `__version__` in `src/image_to_webp/__init__.py` and `CHANGELOG.md`.
+2. Check the build locally:
+   ```bash
+   python -m build && python -m twine check --strict dist/*
+   ```
+3. Publish:
+   - **Automated (recommended):** set up PyPI [trusted publishing](https://docs.pypi.org/trusted-publishers/) for `stakmi/image-to-webp` with workflow `publish.yml` and environment `pypi`, then create a GitHub release tagged `v<version>`.
+   - **Manual:** `python -m twine upload dist/*`
+
+## License
+
+MIT

image_to_webp-0.1.0/README.md

@@ -0,0 +1,123 @@
+# image-to-webp
+
+Convert images in almost any format to [WebP](https://developers.google.com/speed/webp), from Python or the command line.
+
+- Over 70 input formats with Pillow alone: PNG, JPEG, GIF, BMP, TIFF, ICO/ICNS, TGA, PSD, JPEG 2000, PCX, PPM/PGM/PBM, DDS, SGI, QOI, WebP, …
+- More formats through optional installs: HEIC/HEIF/AVIF, camera RAW (CR2, CR3, NEF, ARW, DNG, …) and SVG
+- Applies EXIF rotation, keeps transparency, and turns animated GIF/APNG into animated WebP
+- Converts files in parallel and writes each output in one step, so a failed run never leaves a half-written file
+
+## Install
+
+```bash
+pip install image-to-webp            # core formats (Pillow only)
+pip install "image-to-webp[all]"     # + HEIC/AVIF, RAW and SVG
+```
+
+| Optional install | Adds | Package |
+|---|---|---|
+| `[heif]` | HEIC / HEIF / AVIF | `pillow-heif` |
+| `[raw]` | Camera RAW | `rawpy` |
+| `[svg]` | SVG / SVGZ | `cairosvg` (also needs the system cairo library: `brew install cairo` or `apt install libcairo2`) |
+
+Requires Python 3.9+.
+
+## Library usage
+
+```python
+from image_to_webp import convert_file, convert_bytes, convert_image, convert_many, ConversionOptions
+
+# One file -> photo.webp next to it (returns the output Path)
+convert_file("photo.heic")
+convert_file("photo.png", "out/photo.webp", quality=90)
+
+# In memory
+webp_bytes = convert_bytes(png_bytes, lossless=True)
+webp_bytes = convert_bytes(open("img.cr2", "rb"), filename="img.cr2")  # filename hints RAW decoding
+webp_bytes = convert_image(pil_image, quality=75)
+
+# Reusable settings
+opts = ConversionOptions(quality=85, method=6, max_size=(2560, 2560), keep_metadata=True)
+convert_file("big.tif", options=opts)
+
+# Batch: files and/or directories, in parallel
+summary = convert_many(["images/", "extra.gif"], output_dir="webp", recursive=True,
+                       jobs=4, on_result=lambda r: print(r.status, r.src))
+print(summary.converted, summary.skipped, summary.failed, summary.bytes_saved)
+```
+
+### API reference
+
+| Name | Description |
+|---|---|
+| `convert_file(src, dst=None, options=None, *, overwrite=True, **opts) -> Path` | Convert one file. `dst` defaults to `src` with a `.webp` extension. |
+| `convert_bytes(data, options=None, *, filename=None, **opts) -> bytes` | Convert bytes or a binary file object. |
+| `convert_image(image, options=None, **opts) -> bytes` | Encode a `PIL.Image.Image`. |
+| `convert_many(inputs, output_dir=None, options=None, *, recursive, overwrite=False, delete_original, jobs, on_result, **opts) -> BatchSummary` | Convert many files. One failed file doesn't stop the run. |
+| `plan_conversions(inputs, output_dir=None, *, recursive, overwrite)` | Preview what `convert_many` would do (dry run). |
+| `ConversionOptions(quality=80, lossless=False, method=4, max_size=None, keep_metadata=False)` | Encoder settings, checked when created. |
+| `ConversionResult` / `BatchSummary` | Results for each file and for the whole batch. |
+| `supported_extensions()`, `is_supported(path)`, `plugin_status()` | See which formats work in the current environment. |
+| `open_image(source, filename=None)` | Open any supported input as a PIL image. |
+| `ImageToWebPError` → `UnsupportedFormatError`, `ConversionError` | Exceptions. |
+
+`**opts` accepts the same keywords as `ConversionOptions` (`quality`, `lossless`, `method`, `max_size`, `keep_metadata`).
+The library never prints. Messages go to Python's `logging` under the `image_to_webp` logger.
+
+## Command line
+
+```bash
+image-to-webp photo.jpg                        # -> photo.webp next to source
+image-to-webp ./images -r -o ./webp            # recursive, mirror tree into ./webp
+image-to-webp *.png --lossless
+image-to-webp ./raw -q 85 --max-size 2560x2560 -j 8
+image-to-webp ./images -r --dry-run
+image-to-webp --list-formats                   # formats + optional plugin status
+python -m image_to_webp --help                 # same tool
+```
+
+| Option | Description |
+|---|---|
+| `-r, --recursive` | Search directories recursively |
+| `-o, --output DIR` | Output directory (default: next to source) |
+| `-q, --quality N` | Quality 0–100 (default 80) |
+| `--lossless` | Lossless encoding |
+| `-m, --method N` | Compression effort 0–6 (default 4) |
+| `--max-size WxH` | Downscale to fit, keeping aspect ratio |
+| `--keep-metadata` | Keep EXIF and ICC profile |
+| `--overwrite` | Overwrite existing `.webp` (default: skip) |
+| `--delete-original` | Delete source after successful conversion |
+| `-j, --jobs N` | Parallel workers (default: CPU count) |
+| `--dry-run` | Show what would be converted |
+| `-v, --verbose` | Print each file |
+| `--list-formats` | Show supported formats and plugin status |
+
+Exit code is `0` on success, `1` if any file failed, `2` for invalid arguments.
+
+> The command is called `image-to-webp`, not `img2webp`, because libwebp already ships a tool named `img2webp`.
+
+## Development
+
+```bash
+./install.sh                    # .venv + editable install with all optional formats + link command to /usr/local/bin (macOS) or /usr/bin
+./install.sh --uninstall        # remove the linked command
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest
+```
+
+`install.sh` uses `sudo` only when the target directory isn't writable. Override with `BIN_DIR=~/.local/bin` or `CMD_NAME=...`.
+
+## Releasing
+
+1. Update `__version__` in `src/image_to_webp/__init__.py` and `CHANGELOG.md`.
+2. Check the build locally:
+   ```bash
+   python -m build && python -m twine check --strict dist/*
+   ```
+3. Publish:
+   - **Automated (recommended):** set up PyPI [trusted publishing](https://docs.pypi.org/trusted-publishers/) for `stakmi/image-to-webp` with workflow `publish.yml` and environment `pypi`, then create a GitHub release tagged `v<version>`.
+   - **Manual:** `python -m twine upload dist/*`
+
+## License
+
+MIT

image_to_webp-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "image-to-webp"
+dynamic = ["version"]
+description = "Convert images in almost any format (PNG, JPEG, GIF, TIFF, HEIC, AVIF, RAW, SVG, ...) to WebP."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "stakmi" }]
+keywords = ["webp", "image", "convert", "converter", "heic", "raw", "svg", "pillow"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Graphics :: Graphics Conversion",
+    "Typing :: Typed",
+]
+dependencies = ["Pillow>=10.0"]
+
+[project.optional-dependencies]
+heif = ["pillow-heif>=0.16"]
+raw = ["rawpy>=0.19"]
+svg = ["cairosvg>=2.7"]
+all = ["image-to-webp[heif,raw,svg]"]
+test = ["pytest>=7"]
+dev = ["image-to-webp[all,test]", "build", "twine"]
+
+[project.scripts]
+image-to-webp = "image_to_webp.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/stakmi/image-to-webp"
+Repository = "https://github.com/stakmi/image-to-webp"
+Issues = "https://github.com/stakmi/image-to-webp/issues"
+Changelog = "https://github.com/stakmi/image-to-webp/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/image_to_webp/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/image_to_webp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

image_to_webp-0.1.0/src/image_to_webp/__init__.py

@@ -0,0 +1,38 @@
+"""Convert images in almost any format to WebP.
+
+Quick start::
+
+    from image_to_webp import convert_file, convert_bytes, convert_many
+
+    convert_file("photo.heic")                       # -> photo.webp
+    webp = convert_bytes(png_bytes, quality=90)      # in memory
+    summary = convert_many("images/", recursive=True, output_dir="webp")
+"""
+
+from .batch import BatchSummary, ConversionResult, convert_many, plan_conversions
+from .converter import convert_bytes, convert_file, convert_image, default_output_path
+from .errors import ConversionError, ImageToWebPError, UnsupportedFormatError
+from .loaders import is_supported, open_image, plugin_status, supported_extensions
+from .options import ConversionOptions
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BatchSummary",
+    "ConversionError",
+    "ConversionOptions",
+    "ConversionResult",
+    "ImageToWebPError",
+    "UnsupportedFormatError",
+    "__version__",
+    "convert_bytes",
+    "convert_file",
+    "convert_image",
+    "convert_many",
+    "default_output_path",
+    "is_supported",
+    "open_image",
+    "plan_conversions",
+    "plugin_status",
+    "supported_extensions",
+]

image_to_webp-0.1.0/src/image_to_webp/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

image_to_webp-0.1.0/src/image_to_webp/batch.py

@@ -0,0 +1,194 @@
+"""Convert many files, optionally in parallel."""
+
+from __future__ import annotations
+
+import os
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Iterable, List, Optional, Union
+
+from .converter import PathLike, convert_file, default_output_path
+from .loaders import supported_extensions
+from .options import ConversionOptions, resolve_options
+
+PENDING = "pending"
+CONVERTED = "converted"
+SKIPPED = "skipped"
+FAILED = "failed"
+
+
+@dataclass
+class ConversionResult:
+    """Outcome for one input file.
+
+    ``status`` is one of ``"pending"`` (planned only), ``"converted"``, ``"skipped"`` or ``"failed"``.
+    """
+
+    src: Path
+    dst: Optional[Path]
+    status: str = PENDING
+    in_size: int = 0
+    out_size: int = 0
+    error: Optional[str] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.status in (CONVERTED, SKIPPED)
+
+
+@dataclass
+class BatchSummary:
+    """Aggregate result of :func:`convert_many`."""
+
+    results: List[ConversionResult] = field(default_factory=list)
+
+    def _count(self, status: str) -> int:
+        return sum(r.status == status for r in self.results)
+
+    @property
+    def converted(self) -> int:
+        return self._count(CONVERTED)
+
+    @property
+    def skipped(self) -> int:
+        return self._count(SKIPPED)
+
+    @property
+    def failed(self) -> int:
+        return self._count(FAILED)
+
+    @property
+    def bytes_in(self) -> int:
+        return sum(r.in_size for r in self.results if r.status == CONVERTED)
+
+    @property
+    def bytes_out(self) -> int:
+        return sum(r.out_size for r in self.results if r.status == CONVERTED)
+
+    @property
+    def bytes_saved(self) -> int:
+        return self.bytes_in - self.bytes_out
+
+    @property
+    def ok(self) -> bool:
+        return self.failed == 0
+
+
+def _as_list(inputs: Union[PathLike, Iterable[PathLike]]) -> List[Path]:
+    if isinstance(inputs, (str, os.PathLike)):
+        return [Path(inputs)]
+    return [Path(p) for p in inputs]
+
+
+def plan_conversions(
+    inputs: Union[PathLike, Iterable[PathLike]],
+    output_dir: Optional[PathLike] = None,
+    *,
+    recursive: bool = False,
+    overwrite: bool = False,
+) -> List[ConversionResult]:
+    """Work out what :func:`convert_many` would do, without converting anything.
+
+    Files given explicitly are always included; files found in directories are
+    included only if their extension is supported (and not already ``.webp``).
+    Output paths mirror the directory tree under ``output_dir`` when given.
+    """
+    exts = supported_extensions()
+    out_root = Path(output_dir) if output_dir is not None else None
+    results: List[ConversionResult] = []
+    seen: set = set()
+
+    def add(src: Path, dst: Path) -> None:
+        key = os.path.normcase(os.path.abspath(dst))
+        if key in seen:
+            results.append(ConversionResult(src, dst, SKIPPED, error="duplicate output name"))
+        elif dst.exists() and not overwrite:
+            results.append(ConversionResult(src, dst, SKIPPED, error="output exists"))
+        else:
+            results.append(ConversionResult(src, dst))
+        seen.add(key)
+
+    for item in _as_list(inputs):
+        if item.is_file():
+            add(item, (out_root / f"{item.stem}.webp") if out_root else default_output_path(item))
+        elif item.is_dir():
+            files = item.rglob("*") if recursive else item.iterdir()
+            for f in sorted(files):
+                ext = f.suffix.lower()
+                if ext == ".webp" or ext not in exts or not f.is_file():
+                    continue
+                dst_dir = out_root / f.parent.relative_to(item) if out_root else f.parent
+                add(f, dst_dir / f"{f.stem}.webp")
+        else:
+            results.append(ConversionResult(item, None, FAILED, error="no such file or directory"))
+    return results
+
+
+def _run_one(src: Path, dst: Path, opts: ConversionOptions, delete_original: bool) -> ConversionResult:
+    try:
+        in_size = src.stat().st_size
+        convert_file(src, dst, opts)
+        if delete_original and src.resolve() != dst.resolve():
+            src.unlink()
+        return ConversionResult(src, dst, CONVERTED, in_size, dst.stat().st_size)
+    except Exception as exc:
+        return ConversionResult(src, dst, FAILED, error=str(exc) or type(exc).__name__)
+
+
+def convert_many(
+    inputs: Union[PathLike, Iterable[PathLike]],
+    output_dir: Optional[PathLike] = None,
+    options: Optional[ConversionOptions] = None,
+    *,
+    recursive: bool = False,
+    overwrite: bool = False,
+    delete_original: bool = False,
+    jobs: Optional[int] = None,
+    on_result: Optional[Callable[[ConversionResult], None]] = None,
+    **kwargs: Any,
+) -> BatchSummary:
+    """Convert files and/or directories to WebP.
+
+    Args:
+        inputs: a path or iterable of paths (files or directories).
+        output_dir: where to write output; default is next to each source.
+        options: :class:`ConversionOptions`; keyword overrides (``quality=...``) are also accepted.
+        recursive: descend into sub-directories.
+        overwrite: replace existing ``.webp`` files (default: skip them).
+        delete_original: remove each source after it converts successfully.
+        jobs: worker processes (default: CPU count; 1 = run in this process).
+        on_result: called with each :class:`ConversionResult` as it completes (in the calling process).
+
+    Individual failures never raise; check :attr:`BatchSummary.failed`.
+    """
+    opts = resolve_options(options, kwargs)
+    planned = plan_conversions(inputs, output_dir, recursive=recursive, overwrite=overwrite)
+    summary = BatchSummary()
+
+    def done(result: ConversionResult) -> None:
+        summary.results.append(result)
+        if on_result is not None:
+            on_result(result)
+
+    todo = []
+    for r in planned:
+        if r.status == PENDING:
+            todo.append(r)
+        else:
+            done(r)
+
+    workers = max(1, min(jobs or os.cpu_count() or 1, len(todo) or 1))
+    if workers == 1:
+        for r in todo:
+            done(_run_one(r.src, r.dst, opts, delete_original))  # type: ignore[arg-type]
+    else:
+        with ProcessPoolExecutor(max_workers=workers) as pool:
+            futures = {pool.submit(_run_one, r.src, r.dst, opts, delete_original): r for r in todo}
+            for fut in as_completed(futures):
+                r = futures[fut]
+                try:
+                    done(fut.result())
+                except Exception as exc:  # worker crashed
+                    done(ConversionResult(r.src, r.dst, FAILED, error=str(exc) or type(exc).__name__))
+    return summary