airclip 0.1.0__tar.gz

airclip-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: airclip
+Version: 0.1.0
+Summary: Convert any video to an ultra-lightweight WebM that blends seamlessly into web pages.
+Author: Akash Chekka
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/akashchekka/airclip
+Project-URL: Repository, https://github.com/akashchekka/airclip
+Keywords: video,webm,vp9,compression,web,ffmpeg
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Multimedia :: Video :: Conversion
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: bundled-ffmpeg
+Requires-Dist: imageio-ffmpeg; extra == "bundled-ffmpeg"
+
+# airclip
+
+Convert any video to an ultra-lightweight WebM that blends seamlessly into web pages.
+
+**30 seconds of video → ~50-200 KB** without visible quality loss.
+
+## Why
+
+Embedding videos on the web usually means large files, slow loads, and visible player chrome. `airclip` solves this for animation and diagram content:
+
+| Metric | Before | After |
+|--------|--------|-------|
+| 30s video | ~1-3 MB | ~50-200 KB |
+| Format | MP4 (H.264) | WebM (VP9) |
+| FPS | 60 | 24 |
+| Resolution | 1080p | 720p |
+| Audio | Included | Stripped |
+
+The output blends into dark backgrounds — no borders, no player UI, just content that looks native to the page.
+
+## How it works
+
+1. **VP9 encoding** — modern codec designed for web, much better compression than H.264
+2. **High CRF** — animation content (solid backgrounds, vector shapes) compresses extremely well at CRF 35-45
+3. **Reduced framerate** — 24fps is visually identical to 60fps for slides and diagrams
+4. **Downscale to 720p** — on web, nobody notices the difference from 1080p
+5. **Two-pass encoding** — analyzes content first, then allocates bits where they matter
+6. **No audio** — animations don't need it, saves ~30% file size
+
+## Install
+
+```bash
+pip install imageio-ffmpeg
+```
+
+Or have `ffmpeg` available on your PATH.
+
+## Usage
+
+```bash
+# Single file
+python -m airclip video.mp4
+
+# Entire directory
+python -m airclip videos/
+
+# Custom settings
+python -m airclip video.mp4 --fps 15 --crf 42 --height 480
+
+# Fast mode (skip 2-pass, ~2x faster)
+python -m airclip video.mp4 --no-2pass
+
+# Output to a different directory
+python -m airclip videos/ --outdir dist/
+```
+
+### As a library
+
+```python
+from airclip import convert_lightweight
+
+result = convert_lightweight(
+    "input.mp4",
+    output_path="output.webm",
+    target_fps=24,
+    crf=38,
+    max_height=720,
+)
+
+print(f"{result['input_kb']:.0f} KB → {result['output_kb']:.0f} KB")
+print(f"{result['ratio']:.1f}x smaller")
+```
+
+## Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--fps` | 24 | Target framerate. Use 15 for near-static content. |
+| `--crf` | 38 | Quality level. Higher = smaller. 35-45 works well for animations. |
+| `--height` | 720 | Max output height in pixels. |
+| `--no-2pass` | off | Skip 2-pass encoding (faster, slightly larger output). |
+| `--outdir` | same as input | Output directory for converted files. |
+
+## CRF guide
+
+| CRF | Quality | Best for |
+|-----|---------|----------|
+| 30-34 | High | Live action, complex motion |
+| 35-38 | Good | Animations with fine detail |
+| 39-42 | Small | Diagrams, slides, code demos |
+| 43-50 | Tiny | Static content, simple shapes |
+
+## Embedding on web
+
+The output is designed to look native on dark-themed pages:
+
+```html
+<video autoplay muted loop playsinline>
+    <source src="animation.webm" type="video/webm">
+    <source src="animation.mp4" type="video/mp4"> <!-- fallback -->
+</video>
+```
+
+```css
+video {
+    width: 100%;
+    background: transparent;
+    border: none;
+    border-radius: 12px;
+}
+```
+
+For autoplay-on-scroll:
+
+```javascript
+const observer = new IntersectionObserver((entries) => {
+    entries.forEach(e => {
+        e.isIntersecting ? e.target.play() : e.target.pause();
+    });
+}, { threshold: 0.5 });
+
+document.querySelectorAll('video').forEach(v => observer.observe(v));
+```
+
+## Best results when
+
+- Background is a solid or near-solid color (dark themes work great)
+- Content is vector-like: shapes, text, diagrams, code
+- Motion is smooth and predictable (not chaotic)
+- No audio needed
+
+## Results
+
+Across 6 test videos: **~1.2 MB → ~93 KB average (12x compression)**. No visible quality loss in browser playback.
+
+## License
+
+MIT

airclip-0.1.0/README.md

@@ -0,0 +1,138 @@
+# airclip
+
+Convert any video to an ultra-lightweight WebM that blends seamlessly into web pages.
+
+**30 seconds of video → ~50-200 KB** without visible quality loss.
+
+## Why
+
+Embedding videos on the web usually means large files, slow loads, and visible player chrome. `airclip` solves this for animation and diagram content:
+
+| Metric | Before | After |
+|--------|--------|-------|
+| 30s video | ~1-3 MB | ~50-200 KB |
+| Format | MP4 (H.264) | WebM (VP9) |
+| FPS | 60 | 24 |
+| Resolution | 1080p | 720p |
+| Audio | Included | Stripped |
+
+The output blends into dark backgrounds — no borders, no player UI, just content that looks native to the page.
+
+## How it works
+
+1. **VP9 encoding** — modern codec designed for web, much better compression than H.264
+2. **High CRF** — animation content (solid backgrounds, vector shapes) compresses extremely well at CRF 35-45
+3. **Reduced framerate** — 24fps is visually identical to 60fps for slides and diagrams
+4. **Downscale to 720p** — on web, nobody notices the difference from 1080p
+5. **Two-pass encoding** — analyzes content first, then allocates bits where they matter
+6. **No audio** — animations don't need it, saves ~30% file size
+
+## Install
+
+```bash
+pip install imageio-ffmpeg
+```
+
+Or have `ffmpeg` available on your PATH.
+
+## Usage
+
+```bash
+# Single file
+python -m airclip video.mp4
+
+# Entire directory
+python -m airclip videos/
+
+# Custom settings
+python -m airclip video.mp4 --fps 15 --crf 42 --height 480
+
+# Fast mode (skip 2-pass, ~2x faster)
+python -m airclip video.mp4 --no-2pass
+
+# Output to a different directory
+python -m airclip videos/ --outdir dist/
+```
+
+### As a library
+
+```python
+from airclip import convert_lightweight
+
+result = convert_lightweight(
+    "input.mp4",
+    output_path="output.webm",
+    target_fps=24,
+    crf=38,
+    max_height=720,
+)
+
+print(f"{result['input_kb']:.0f} KB → {result['output_kb']:.0f} KB")
+print(f"{result['ratio']:.1f}x smaller")
+```
+
+## Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--fps` | 24 | Target framerate. Use 15 for near-static content. |
+| `--crf` | 38 | Quality level. Higher = smaller. 35-45 works well for animations. |
+| `--height` | 720 | Max output height in pixels. |
+| `--no-2pass` | off | Skip 2-pass encoding (faster, slightly larger output). |
+| `--outdir` | same as input | Output directory for converted files. |
+
+## CRF guide
+
+| CRF | Quality | Best for |
+|-----|---------|----------|
+| 30-34 | High | Live action, complex motion |
+| 35-38 | Good | Animations with fine detail |
+| 39-42 | Small | Diagrams, slides, code demos |
+| 43-50 | Tiny | Static content, simple shapes |
+
+## Embedding on web
+
+The output is designed to look native on dark-themed pages:
+
+```html
+<video autoplay muted loop playsinline>
+    <source src="animation.webm" type="video/webm">
+    <source src="animation.mp4" type="video/mp4"> <!-- fallback -->
+</video>
+```
+
+```css
+video {
+    width: 100%;
+    background: transparent;
+    border: none;
+    border-radius: 12px;
+}
+```
+
+For autoplay-on-scroll:
+
+```javascript
+const observer = new IntersectionObserver((entries) => {
+    entries.forEach(e => {
+        e.isIntersecting ? e.target.play() : e.target.pause();
+    });
+}, { threshold: 0.5 });
+
+document.querySelectorAll('video').forEach(v => observer.observe(v));
+```
+
+## Best results when
+
+- Background is a solid or near-solid color (dark themes work great)
+- Content is vector-like: shapes, text, diagrams, code
+- Motion is smooth and predictable (not chaotic)
+- No audio needed
+
+## Results
+
+Across 6 test videos: **~1.2 MB → ~93 KB average (12x compression)**. No visible quality loss in browser playback.
+
+## License
+
+MIT

airclip-0.1.0/airclip/__init__.py

@@ -0,0 +1 @@
+from .airclip import convert_lightweight, get_video_info

airclip-0.1.0/airclip/__main__.py

@@ -0,0 +1,3 @@
+from .airclip import main
+
+main()

airclip-0.1.0/airclip/airclip.py

@@ -0,0 +1,200 @@
+"""airclip — Convert videos to ultra-lightweight web-embeddable format.
+
+Takes any video and produces a tiny WebM (VP9) that blends seamlessly
+into web pages. Optimized for animation/diagram content where
+solid backgrounds and limited motion allow extreme compression.
+
+Usage:
+    python -m airclip video.mp4                     # Single file
+    python -m airclip video.mp4 --fps 15 --crf 40   # Custom
+"""
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+# imageio-ffmpeg bundles ffmpeg so we don't need a system install
+try:
+    import imageio_ffmpeg
+    FFMPEG = imageio_ffmpeg.get_ffmpeg_exe()
+except ImportError:
+    FFMPEG = "ffmpeg"
+
+
+def get_video_info(path: str) -> dict:
+    """Get duration and resolution using ffprobe."""
+    ffprobe = Path(FFMPEG).parent / Path(FFMPEG).name.replace("ffmpeg", "ffprobe")
+    if not ffprobe.exists():
+        # Fall back: try without info
+        return {"duration": 0, "width": 0, "height": 0, "fps": 30}
+    cmd = [
+        ffprobe, "-v", "quiet",
+        "-print_format", "json",
+        "-show_format", "-show_streams",
+        path,
+    ]
+    import json
+    r = subprocess.run(cmd, capture_output=True, text=True)
+    if r.returncode != 0:
+        return {}
+    data = json.loads(r.stdout)
+    stream = next((s for s in data.get("streams", []) if s["codec_type"] == "video"), {})
+    return {
+        "duration": float(data.get("format", {}).get("duration", 0)),
+        "width": int(stream.get("width", 0)),
+        "height": int(stream.get("height", 0)),
+        "fps": eval(stream.get("r_frame_rate", "30/1")),
+    }
+
+
+def convert_lightweight(
+    input_path: str,
+    output_path: str | None = None,
+    target_fps: int = 24,
+    crf: int = 38,
+    max_height: int = 720,
+    two_pass: bool = True,
+) -> dict:
+    """Convert a video to ultra-lightweight WebM VP9.
+
+    Args:
+        input_path: Source video file.
+        output_path: Output path. Default: same name with .webm extension.
+        target_fps: Target framerate. 15-24 is ideal for animations.
+        crf: Constant Rate Factor. Higher = smaller. 35-45 for animations.
+        max_height: Max output height. 720 is good for web.
+        two_pass: Use 2-pass encoding for better quality/size ratio.
+
+    Returns:
+        Dict with input_size, output_size, ratio, duration.
+    """
+    inp = Path(input_path)
+    if output_path is None:
+        output_path = str(inp.with_suffix(".webm"))
+    out = Path(output_path)
+
+    input_size = inp.stat().st_size
+
+    # Scale filter: only downscale, keep aspect ratio
+    scale_filter = f"scale=-2:'min({max_height},ih)'"
+    vf = f"{scale_filter},fps={target_fps}"
+
+    if two_pass:
+        # Pass 1: analyze
+        pass1 = [
+            FFMPEG, "-y", "-i", str(inp),
+            "-vf", vf,
+            "-c:v", "libvpx-vp9",
+            "-b:v", "0", "-crf", str(crf),
+            "-pass", "1",
+            "-an",
+            "-f", "null",
+            "NUL" if sys.platform == "win32" else "/dev/null",
+        ]
+        subprocess.run(pass1, capture_output=True)
+
+        # Pass 2: encode
+        pass2 = [
+            FFMPEG, "-y", "-i", str(inp),
+            "-vf", vf,
+            "-c:v", "libvpx-vp9",
+            "-b:v", "0", "-crf", str(crf),
+            "-pass", "2",
+            "-an",  # no audio for animations
+            "-auto-alt-ref", "1",
+            "-lag-in-frames", "25",
+            "-row-mt", "1",
+            str(out),
+        ]
+        subprocess.run(pass2, capture_output=True)
+
+        # Cleanup pass log files
+        for f in Path(".").glob("ffmpeg2pass-0*"):
+            f.unlink(missing_ok=True)
+    else:
+        cmd = [
+            FFMPEG, "-y", "-i", str(inp),
+            "-vf", vf,
+            "-c:v", "libvpx-vp9",
+            "-b:v", "0", "-crf", str(crf),
+            "-an",
+            "-row-mt", "1",
+            str(out),
+        ]
+        subprocess.run(cmd, capture_output=True)
+
+    output_size = out.stat().st_size if out.exists() else 0
+    info = get_video_info(str(inp))
+
+    return {
+        "input": str(inp.name),
+        "output": str(out.name),
+        "input_size": input_size,
+        "output_size": output_size,
+        "ratio": input_size / output_size if output_size else 0,
+        "duration": info.get("duration", 0),
+        "input_kb": input_size / 1024,
+        "output_kb": output_size / 1024,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Convert videos to lightweight web-embeddable format")
+    parser.add_argument("input", help="Video file or directory of videos")
+    parser.add_argument("--fps", type=int, default=24, help="Target FPS (default: 24)")
+    parser.add_argument("--crf", type=int, default=38, help="Quality (higher=smaller, default: 38)")
+    parser.add_argument("--height", type=int, default=720, help="Max height in px (default: 720)")
+    parser.add_argument("--no-2pass", action="store_true", help="Skip 2-pass encoding (faster)")
+    parser.add_argument("--outdir", type=str, default=None, help="Output directory")
+    args = parser.parse_args()
+
+    target = Path(args.input)
+    if target.is_dir():
+        files = sorted(target.glob("*.mp4"))
+    else:
+        files = [target]
+
+    if not files:
+        print("No MP4 files found.")
+        return
+
+    print(f"\n  Converting {len(files)} video(s) to lightweight WebM")
+    print(f"  Settings: {args.fps}fps, CRF {args.crf}, max {args.height}p, 2-pass={not args.no_2pass}")
+    print(f"  {'─' * 60}")
+
+    total_in = 0
+    total_out = 0
+
+    for f in files:
+        out_dir = Path(args.outdir) if args.outdir else f.parent
+        out_dir.mkdir(parents=True, exist_ok=True)
+        out_path = out_dir / f"{f.stem}.webm"
+
+        result = convert_lightweight(
+            str(f), str(out_path),
+            target_fps=args.fps,
+            crf=args.crf,
+            max_height=args.height,
+            two_pass=not args.no_2pass,
+        )
+
+        total_in += result["input_size"]
+        total_out += result["output_size"]
+
+        print(
+            f"  {result['input']:40s} "
+            f"{result['input_kb']:7.0f} KB → {result['output_kb']:6.0f} KB "
+            f"({result['ratio']:5.1f}x smaller)"
+        )
+
+    print(f"  {'─' * 60}")
+    print(
+        f"  Total: {total_in/1024:,.0f} KB → {total_out/1024:,.0f} KB "
+        f"({total_in/total_out:.1f}x compression)"
+    )
+    print()
+
+
+if __name__ == "__main__":
+    main()

airclip-0.1.0/airclip.egg-info/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: airclip
+Version: 0.1.0
+Summary: Convert any video to an ultra-lightweight WebM that blends seamlessly into web pages.
+Author: Akash Chekka
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/akashchekka/airclip
+Project-URL: Repository, https://github.com/akashchekka/airclip
+Keywords: video,webm,vp9,compression,web,ffmpeg
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Multimedia :: Video :: Conversion
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: bundled-ffmpeg
+Requires-Dist: imageio-ffmpeg; extra == "bundled-ffmpeg"
+
+# airclip
+
+Convert any video to an ultra-lightweight WebM that blends seamlessly into web pages.
+
+**30 seconds of video → ~50-200 KB** without visible quality loss.
+
+## Why
+
+Embedding videos on the web usually means large files, slow loads, and visible player chrome. `airclip` solves this for animation and diagram content:
+
+| Metric | Before | After |
+|--------|--------|-------|
+| 30s video | ~1-3 MB | ~50-200 KB |
+| Format | MP4 (H.264) | WebM (VP9) |
+| FPS | 60 | 24 |
+| Resolution | 1080p | 720p |
+| Audio | Included | Stripped |
+
+The output blends into dark backgrounds — no borders, no player UI, just content that looks native to the page.
+
+## How it works
+
+1. **VP9 encoding** — modern codec designed for web, much better compression than H.264
+2. **High CRF** — animation content (solid backgrounds, vector shapes) compresses extremely well at CRF 35-45
+3. **Reduced framerate** — 24fps is visually identical to 60fps for slides and diagrams
+4. **Downscale to 720p** — on web, nobody notices the difference from 1080p
+5. **Two-pass encoding** — analyzes content first, then allocates bits where they matter
+6. **No audio** — animations don't need it, saves ~30% file size
+
+## Install
+
+```bash
+pip install imageio-ffmpeg
+```
+
+Or have `ffmpeg` available on your PATH.
+
+## Usage
+
+```bash
+# Single file
+python -m airclip video.mp4
+
+# Entire directory
+python -m airclip videos/
+
+# Custom settings
+python -m airclip video.mp4 --fps 15 --crf 42 --height 480
+
+# Fast mode (skip 2-pass, ~2x faster)
+python -m airclip video.mp4 --no-2pass
+
+# Output to a different directory
+python -m airclip videos/ --outdir dist/
+```
+
+### As a library
+
+```python
+from airclip import convert_lightweight
+
+result = convert_lightweight(
+    "input.mp4",
+    output_path="output.webm",
+    target_fps=24,
+    crf=38,
+    max_height=720,
+)
+
+print(f"{result['input_kb']:.0f} KB → {result['output_kb']:.0f} KB")
+print(f"{result['ratio']:.1f}x smaller")
+```
+
+## Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--fps` | 24 | Target framerate. Use 15 for near-static content. |
+| `--crf` | 38 | Quality level. Higher = smaller. 35-45 works well for animations. |
+| `--height` | 720 | Max output height in pixels. |
+| `--no-2pass` | off | Skip 2-pass encoding (faster, slightly larger output). |
+| `--outdir` | same as input | Output directory for converted files. |
+
+## CRF guide
+
+| CRF | Quality | Best for |
+|-----|---------|----------|
+| 30-34 | High | Live action, complex motion |
+| 35-38 | Good | Animations with fine detail |
+| 39-42 | Small | Diagrams, slides, code demos |
+| 43-50 | Tiny | Static content, simple shapes |
+
+## Embedding on web
+
+The output is designed to look native on dark-themed pages:
+
+```html
+<video autoplay muted loop playsinline>
+    <source src="animation.webm" type="video/webm">
+    <source src="animation.mp4" type="video/mp4"> <!-- fallback -->
+</video>
+```
+
+```css
+video {
+    width: 100%;
+    background: transparent;
+    border: none;
+    border-radius: 12px;
+}
+```
+
+For autoplay-on-scroll:
+
+```javascript
+const observer = new IntersectionObserver((entries) => {
+    entries.forEach(e => {
+        e.isIntersecting ? e.target.play() : e.target.pause();
+    });
+}, { threshold: 0.5 });
+
+document.querySelectorAll('video').forEach(v => observer.observe(v));
+```
+
+## Best results when
+
+- Background is a solid or near-solid color (dark themes work great)
+- Content is vector-like: shapes, text, diagrams, code
+- Motion is smooth and predictable (not chaotic)
+- No audio needed
+
+## Results
+
+Across 6 test videos: **~1.2 MB → ~93 KB average (12x compression)**. No visible quality loss in browser playback.
+
+## License
+
+MIT

airclip-0.1.0/airclip.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+airclip/__init__.py
+airclip/__main__.py
+airclip/airclip.py
+airclip.egg-info/PKG-INFO
+airclip.egg-info/SOURCES.txt
+airclip.egg-info/dependency_links.txt
+airclip.egg-info/entry_points.txt
+airclip.egg-info/requires.txt
+airclip.egg-info/top_level.txt

airclip-0.1.0/airclip.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

airclip-0.1.0/airclip.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+airclip = airclip.airclip:main

airclip-0.1.0/airclip.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[bundled-ffmpeg]
+imageio-ffmpeg

airclip-0.1.0/airclip.egg-info/top_level.txt

@@ -0,0 +1 @@
+airclip

airclip-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "airclip"
+version = "0.1.0"
+description = "Convert any video to an ultra-lightweight WebM that blends seamlessly into web pages."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Akash Chekka" }]
+keywords = ["video", "webm", "vp9", "compression", "web", "ffmpeg"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Multimedia :: Video :: Conversion",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = []
+
+[project.optional-dependencies]
+bundled-ffmpeg = ["imageio-ffmpeg"]
+
+[project.scripts]
+airclip = "airclip.airclip:main"
+
+[project.urls]
+Homepage = "https://github.com/akashchekka/airclip"
+Repository = "https://github.com/akashchekka/airclip"
+
+[tool.setuptools.packages.find]
+include = ["airclip*"]

airclip-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+