librifygen 0.2.5
Thumbnail + preview tools for media folders (ffmpeg + pillow helpers).

# Librifygen

### *High-performance thumbnail & preview generator for videos and images.*

Librifygen is a cross-platform media processing toolkit that generates:

* **Image thumbnails**
* **Video thumbnails** (single-frame extraction)
* **Video preview clips** (random segments stitched together)
* **Full CLI tool** + clean Python API
* Designed for automation, content pipelines, and library indexing tools.

Uses **ffmpeg** for video operations and **Pillow** for image processing.

---

# 🚀 Features

* Extract thumbnails from videos at midpoint or a provided timestamp
* Resize images intelligently (crop or letterbox)
* Batch-scan directories recursively
* Create multi-clip video previews
* CLI + Python module
* Works on Linux, Windows, macOS
* Safe and predictable processing (temp dirs, logging, error handling)

---

# 📦 Installation

Requires:

```
Python 3.8+
Pillow
ffmpeg-python
ffmpeg (system binary)
```

Install Librifygen:

```bash
pip install librifygen
```

---

# 🔧 Installing ffmpeg (Required)

Librifygen **depends on the ffmpeg binary** being present in your system PATH.
Here are the easiest installation methods per OS:

---

## 🟦 Windows

### Option A — Use Chocolatey (recommended)

```bash
choco install ffmpeg
```

### Option B — Use Scoop

```bash
scoop install ffmpeg
```

### Option C — Manual Download

1. Download from: [https://www.gyan.dev/ffmpeg/builds/](https://www.gyan.dev/ffmpeg/builds/)
2. Extract the folder
3. Add the `bin/` directory to your **PATH** environment variable

Verify:

```bash
ffmpeg -version
```

---

## 🍎 macOS

### Using Homebrew (recommended)

```bash
brew install ffmpeg
```

### Using MacPorts

```bash
sudo port install ffmpeg
```

Verify:

```bash
ffmpeg -version
```

---

## 🐧 Linux

### Debian / Ubuntu

```bash
sudo apt update
sudo apt install ffmpeg
```

### Fedora

```bash
sudo dnf install ffmpeg
```

### Arch Linux

```bash
sudo pacman -S ffmpeg
```

Verify:

```bash
ffmpeg -version
```

---

# 🖥️ CLI Usage

After installation, the `librifygen` command becomes available:

```
librifygen <command> [options]
```

Available commands:

* `thumbs` — generate thumbnails for images/videos in a directory
* `preview` — generate multi-clip preview videos

---

## ▶️ Generate Thumbnails

### Basic usage

```bash
librifygen thumbs /path/to/media /path/to/output
```

### With workers & custom size

```bash
librifygen thumbs ~/Pictures ~/Thumbs --workers 8
```

---

## 🎬 Generate Preview Videos

```bash
librifygen preview ./videos ./previews
```

### Custom clips, duration, audio, transitions

```bash
librifygen preview ./videos ./previews \
    --num-clips 4 \
    --clip-duration 3 \
    --workers 4
```

A preview is generated like:

```
input.mp4 → previews/input_preview.mp4
```

---

# 🐍 Python API Usage

Use Librifygen directly in your Python code:

---

## ✔ Generate image thumbnail

```python
from librifygen.thumbnail import generate_image_thumbnail

output = generate_image_thumbnail(
    "media/photo.png",
    "thumbnails/photo.jpg"
)

print(output)
```

---

## ✔ Generate video thumbnail

```python
from librifygen.thumbnail import generate_video_thumbnail

thumb = generate_video_thumbnail(
    "media/video.mp4",
    "thumbnails/video.jpg"
)
print("Thumbnail:", thumb)
```

---

## ✔ Generate preview video

```python
from librifygen.preview import generate_video_preview

preview = generate_video_preview(
    "media/video.mp4",
    "previews",
    num_clips=4,
    clip_duration=5,
)
print(preview)
```

---

## ✔ Batch processing

```python
from librifygen.thumbnail import generate_thumbnails

results = generate_thumbnails(
    input_dir="media",
    output_dir="thumbs",
    max_workers=6
)

for src, out in results:
    print(src, "->", out)
```

---

# 📂 Example Project Structure

You can integrate Librifygen into your own project like:

```
project/
│
├── media/
│   ├── images/
│   ├── videos/
│
├── thumbs/
│
├── previews/
│
└── generate_media_assets.py
```

Example script:

```python
from librifygen.thumbnail import generate_thumbnails
from librifygen.preview import batch_create_previews

generate_thumbnails("media", "thumbs", max_workers=8)
batch_create_previews("media/videos", "previews", num_clips=4)
```

---

# ⚙️ Supported Formats

### Images

```
jpg, jpeg, png, bmp, tiff, webp
```

### Videos

```
mp4, mov, mkv, webm, avi, flv, m4v
```

Formats are customizable using:

```python
from librifygen.config import set_extensions
set_extensions(video_exts=[".mp4", ".mov"], image_exts=[".jpg"])
```

---

# 🧩 Roadmap

* GPU-accelerated previews (via CUDA / Vulkan / Metal)
* Progress bars & verbose CLI
* Config file support
* Parallel image-resizing via ProcessPool optimization
* WebAssembly build (ffmpeg-wasm) for browser-based pipelines

---

# 📝 License

MIT License © Me

---

# 🤝 Contributing

Pull requests welcome.
Please open issues for bugs, feature requests, or ffmpeg compatibility questions.

---

# 🧪 Testing your installation

```bash
pip install librifygen
librifygen --help
```