Metadata-Version: 2.4
Name: clipr-video
Version: 0.1.1
Summary: CLIPR: Clip Improvement, Processing, and Reframing for Python.
Author: Meet Jethwa
License-Expression: MIT
Project-URL: Homepage, https://github.com/Meet2147/clipr
Project-URL: Repository, https://github.com/Meet2147/clipr.git
Project-URL: Issues, https://github.com/Meet2147/clipr/issues
Keywords: video,ffmpeg,split,enhance,orientation,clipr
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Multimedia :: Video :: Conversion
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

![CLIPR logo](assets/clipr-logo.svg)

# CLIPR

**CLIPR** stands for **Clip Improvement, Processing, and Reframing**.

`CLIPR` is a Python video-processing library built around local `ffmpeg`, with a clean API for splitting, enhancing, reframing, and batch-processing videos.

For portrait outputs like Reels and TikTok, CLIPR reframes footage into the target canvas instead of simply rotating the whole source video.

It supports:

- Splitting one video into `30s`, `60s`, and `90s` chunks
- Batch processing a whole directory of videos
- Smart social presets for YouTube, Instagram Reels, TikTok, WhatsApp, and presentations
- Trim and crop operations
- Audio enhancement with normalization, denoise, and volume adjustment
- Orientation changes for portrait, landscape, and rotation modes
- Progress tracking callbacks and a CLI percentage bar for long-running jobs

## Why CLIPR

The name reflects the core workflow:

- `C` for Clip
- `L` for Lifecycle
- `I` for Improvement
- `P` for Processing
- `R` for Reframing

## Installation

Install `ffmpeg`, then install the package:

```bash
pip install -e .
```

## Quick Python Example

```python
from pathlib import Path

from clipr import (
    AudioEnhancementSettings,
    EnhancementSettings,
    ProcessingOptions,
    SocialPreset,
    TrimSettings,
    batch_process_directory,
    make_4k_widescreen,
    make_instagram_reel,
    process_video,
    split_video,
)


def show_progress(percent: float, message: str) -> None:
    print(message)


split_video(
    Path("sample.mp4"),
    segment_lengths=(30, 60, 90),
    output_dir=Path("output/segments"),
    progress_callback=show_progress,
)

process_video(
    Path("sample.mp4"),
    Path("output/reel.mp4"),
    options=ProcessingOptions(
        enhancement=EnhancementSettings(),
        audio=AudioEnhancementSettings(normalize=True, denoise=True),
        trim=TrimSettings(start_time=5, duration=20),
        social_preset=SocialPreset.INSTAGRAM_REEL,
    ),
    progress_callback=show_progress,
)

batch_process_directory(
    Path("sample_videos"),
    Path("output/batch"),
    options=ProcessingOptions(
        enhancement=EnhancementSettings(),
        audio=AudioEnhancementSettings(normalize=True),
        social_preset=SocialPreset.WHATSAPP,
    ),
    progress_callback=show_progress,
)

make_4k_widescreen(
    Path("sample.mp4"),
    Path("output/movie_4k.mp4"),
    progress_callback=show_progress,
)

make_instagram_reel(
    Path("sample.mp4"),
    Path("output/reel_ready.mp4"),
    progress_callback=show_progress,
)
```

There is also a runnable example in `examples/example_usage.py`.

## Convenience Helpers

- `make_4k_widescreen(...)`: crops to widescreen, enhances video, upscales to `3840x2160`, and improves audio
- `make_instagram_reel(...)`: reframes to a vertical `1080x1920` canvas, enhances audio/video, and applies Reel-friendly defaults

## CLI

### Split video

```bash
clipr split sample.mp4 --durations 30 60 90 --output-dir output --show-progress
```

### Full single-video processing

```bash
clipr process sample.mp4 output/reel.mp4 \
  --social-preset instagram_reel \
  --start-time 5 \
  --duration 20 \
  --audio-denoise \
  --show-progress
```

### Batch processing

```bash
clipr batch sample_videos output/batch \
  --social-preset whatsapp \
  --duration 30 \
  --show-progress
```

When `--show-progress` is enabled, CLIPR prints a live percentage bar in the terminal while `ffmpeg` is processing.

## Social Presets

- `youtube`: 1920x1080 landscape output
- `instagram_reel`: 1080x1920 portrait canvas that preserves the original frame
- `tiktok`: 1080x1920 portrait canvas with preserved framing and audio denoise
- `whatsapp`: lighter 720x1280 portrait canvas for sharing
- `presentation`: 1920x1080 landscape output with slightly boosted audio

## Example File To Test

After install, place a sample video as `sample.mp4` in the project root and optionally add more videos in `sample_videos/`.

Run:

```bash
PYTHONPATH=src python3 examples/example_usage.py
```

## Development

```bash
PYTHONPATH=src python3 -m unittest discover -s tests
```

## Publishing

PyPI release settings live in `publish.toml`.

The repository includes `.github/workflows/publish.yml`, which builds and publishes the package to PyPI when you publish a GitHub Release.

Before the first release:

1. Create the PyPI project `clipr-video`.
2. Configure GitHub trusted publishing on PyPI for this repository.
3. Push a git tag and publish a GitHub Release.
