Metadata-Version: 2.5
Name: mediapreview
Version: 0.2.0
Summary: Fast media preview images of photos, videos, PDFs and office documents.
Project-URL: Homepage, https://git.zi.fi/LeoVasanko/mediapreview
Project-URL: Repository, https://github.com/LeoVasanko/mediapreview
Author: Leo Vasanko
Maintainer: Leo Vasanko
Keywords: avif,docx,heic,image,office,pdf,thumbnail
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: Public Domain
Requires-Python: >=3.11
Requires-Dist: docopt-ng>=0.9.0
Requires-Dist: msgspec>=0.19.0
Requires-Dist: pyvips[binary]>=3.1.1
Provides-Extra: office
Requires-Dist: httpx>=0.28.0; extra == 'office'
Requires-Dist: pyjwt>=2.10.1; extra == 'office'
Provides-Extra: pdf
Requires-Dist: pymupdf>=1.26.3; extra == 'pdf'
Provides-Extra: standard
Requires-Dist: av>=15.0.0; extra == 'standard'
Requires-Dist: blake3>=1.0.5; extra == 'standard'
Requires-Dist: httpx>=0.28.0; extra == 'standard'
Requires-Dist: numpy>=2.3.2; extra == 'standard'
Requires-Dist: pyjwt>=2.10.1; extra == 'standard'
Requires-Dist: pymupdf>=1.26.3; extra == 'standard'
Requires-Dist: tracerite>=2.3.1; extra == 'standard'
Provides-Extra: video
Requires-Dist: av>=15.0.0; extra == 'video'
Requires-Dist: numpy>=2.3.2; extra == 'video'
Provides-Extra: worker
Requires-Dist: blake3>=1.0.5; extra == 'worker'
Requires-Dist: tracerite>=2.3.1; extra == 'worker'
Description-Content-Type: text/markdown

# mediapreview

Generate compact AVIF preview images from images, videos, PDFs and office documents.

`mediapreview` is a small library of low-level converters. Give it a file path and
it returns AVIF bytes plus a response object telling you which backend handled it
and whether it succeeded.

## Install

```sh
uv add mediapreview[standard]
```

`[standard]` pulls in every backend and the optional worker pool. Use the feature-specific extras to avoid dependencies not needed for your application.

## Quick start

```python
from pathlib import Path
from mediapreview import dispatch

avif_bytes, resp = dispatch(
    Path("photo.jpg"),
    quality=60,
    maxsize=512,
    maxzoom=2.0,
)

if resp.ok:
    Path("preview.avif").write_bytes(avif_bytes)
else:
    print(resp.error)
```

`dispatch` picks the backend from the file extension or mimetype. You can also
call the backend functions directly:

```python
from mediapreview import process_image, process_pdf, process_video

avif, resp = process_image(Path("photo.jpg"), maxsize=512, quality=60)
avif, resp = process_pdf(Path("doc.pdf"), maxsize=512, quality=60, page_number=0)
avif, resp = process_video(Path("clip.mp4"), maxsize=512, quality=60)
```

## Worker pool (optional)

Heavy native dependencies and crashes stay out of your async loop by running
previews in a pool of persistent subprocess workers.

```python
from mediapreview.pool import (
    start_preview_workers,
    shutdown_preview_workers,
    run_preview,
)

await start_preview_workers()
try:
    avif, resp = await run_preview(Path("doc.pdf"))
finally:
    await shutdown_preview_workers()
```

Add the `worker` extra to use the pool.

## CLI

```bash
mediapreview photo.jpg -o preview.avif
mediapreview doc.pdf -q 70 --maxsize 1024
mediapreview oosetup    # build + run the bundled OnlyOffice container
```

## OnlyOffice setup

Office previews need an OnlyOffice Document Server. A patched Docker image ships
inside the package and can be started with:

```bash
mediapreview oosetup [name] [port]
```

`oosetup` logs to stderr and prints one line on stdout:

```
ONLYOFFICE_JWT_SECRET=<token>
```

Set `ONLYOFFICE_JWT_SECRET` yourself to reuse an existing secret; otherwise a
random one is generated.
