clipr-video 0.1.1

CLIPR: Clip Improvement, Processing, and Reframing for Python.

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:

pip install -e .

Quick Python Example

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

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

Full single-video processing

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

Batch processing

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:

PYTHONPATH=src python3 examples/example_usage.py

Development

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.