93 lines
2.2 KiB
Markdown
93 lines
2.2 KiB
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.
|