vidfix 0.1.0__tar.gz

vidfix-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked
+      - run: uv run pytest --cov --cov-report=term

vidfix-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+# PyPI release via trusted publishing. Activates when the repo goes public at
+# v0.1.0 — configure the "vidfix" project on PyPI with this repo + workflow as
+# a trusted publisher first.
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - run: uv publish

vidfix-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# Build artifacts
+dist/
+build/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Local-only session notes (never publish)
+CLAUDE.md
+plan.md
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Test media output
+*.mp4
+*.mov
+*.webm
+*.mkv
+!tests/fixtures/*.mp4

vidfix-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

vidfix-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-18
+
+### Added
+
+- `vidfix convert` — transform videos to exact fps/duration/resolution/codec with
+  stream-copy fast path for trims, `--smooth` motion interpolation, `--extend-mode
+  freeze|loop`, aspect-preserving pad (or `--stretch`), `--no-audio`, `--audio-tone`,
+  `--precise`.
+- `vidfix generate` — synthetic test videos from FFmpeg lavfi sources: smpte,
+  color-bars, testsrc, gradient, solid:COLOR patterns; tone/silence/no audio;
+  `--timecode` real SMPTE timecode burn-in (drop-frame `HH:MM:SS;FF` with
+  semicolon, non-drop with colon); `--text` caption burn-in.
+- `vidfix caption` — burn text onto existing videos: positions top/center/bottom,
+  `--start`/`--end` time window.
+- `vidfix verify` — assert fps/duration/resolution/codec with tolerances; rich
+  pass/fail table or `--json`; exit 0/1 for CI.
+- `vidfix info` — metadata via system ffprobe (JSON) or `ffmpeg -i` banner
+  fallback; friendly container names ("mp4 (major_brand: isom)").
+- `vidfix format` — convert any picture or video to any format (image↔image,
+  video→any container, palette-optimized GIFs, first-frame thumbnails).
+- `vidfix variants` — parallel cartesian product of fps x resolution variants.
+- Interactive wizard — bare `vidfix` walks through action/file/preset/specs
+  step-by-step, prints the equivalent command, then runs it.
+- Presets: built-in broadcast rate family `df30`, `df60`, `ndf30`, `ndf60`,
+  `pal25` (alias `ndf25`), `pal50`, `film24`, `film23976`, plus
+  `broadcast-1080i`, `web-720p` (drop-frame rates as exact rationals); user
+  presets in `~/.config/vidfix/presets.yaml`; `vidfix preset list|show`.
+- Typed Python API: `convert`, `generate`, `verify`, `probe`, `to_format`.
+- Bundled FFmpeg via imageio-ffmpeg — no system install needed.
+
+[0.1.0]: https://github.com/gouravrana7/vidfix/releases/tag/v0.1.0

vidfix-0.1.0/LICENSE

@@ -0,0 +1,57 @@
+Required Notice: Copyright (c) 2026 Gourav Rana (https://github.com/gouravrana7/vidfix)
+
+# PolyForm Internal Use License 1.0.0
+
+<https://polyformproject.org/licenses/internal-use/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license), and you may not distribute the software.
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## Internal Business Use
+
+Use of the software for the internal business operations of you and your company is use for a permitted purpose.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

vidfix-0.1.0/PKG-INFO

@@ -0,0 +1,331 @@
+Metadata-Version: 2.4
+Name: vidfix
+Version: 0.1.0
+Summary: CLI toolkit to convert, generate, and verify videos and images to exact specs (fps, duration, resolution, format) — test fixtures, CI checks, and everyday conversions.
+Project-URL: Homepage, https://github.com/gouravrana7/vidfix
+Project-URL: Issues, https://github.com/gouravrana7/vidfix/issues
+Project-URL: Changelog, https://github.com/gouravrana7/vidfix/blob/main/CHANGELOG.md
+Author-email: Gourav Rana <gourav.rana70000@gmail.com>
+License: PolyForm-Internal-Use-1.0.0
+License-File: LICENSE
+Keywords: ci,ffmpeg,qa,test-fixtures,testing,video
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Video :: Conversion
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: imageio-ffmpeg>=0.6.0
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# vidfix
+
+<!-- badges: PyPI badges activate once published -->
+[![PyPI](https://img.shields.io/pypi/v/vidfix)](https://pypi.org/project/vidfix/)
+[![CI](https://github.com/gouravrana7/vidfix/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/gouravrana7/vidfix/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/vidfix)](https://pypi.org/project/vidfix/)
+[![License](https://img.shields.io/badge/License-PolyForm_Internal_Use-blue.svg)](LICENSE)
+
+**Videos and images, exactly the way you need them.** vidfix is a CLI-first
+media toolkit for anyone — developers, QA engineers, creators, or someone who
+just wants a file converted: force videos to exact specs (fps, duration,
+resolution), generate test clips from nothing, convert any picture or video to
+any format, grab thumbnails and GIFs, and verify media specs in CI with proper
+exit codes.
+
+FFmpeg is bundled (via imageio-ffmpeg), so `pip install vidfix` just works — no
+system FFmpeg required.
+
+## Install
+
+```bash
+pip install vidfix        # or: uv tool install vidfix
+```
+
+## Quick start
+
+**No syntax needed** — just run `vidfix` and answer the prompts:
+
+```
+$ vidfix
+What do you want to do? (convert/generate/caption/format/verify/info/variants): convert
+Which file do you want to convert?: raw.mov
+Preset (none/broadcast-1080i/df30/df60/film24/.../web-720p): df60
+Target duration (e.g. 30s, 1:30) (enter to skip): 10s
+...
+equivalent command: vidfix convert raw.mov --preset df60 --duration 10s --codec h264 -o raw_converted.mov
+```
+
+Every answer is validated on the spot, and the equivalent one-liner is printed
+so you can script it next time. Or go straight to the flags:
+
+```bash
+# A 60fps, 30s, 720p SMPTE-bars clip with a burned-in timecode
+vidfix generate -o fixture.mp4 --fps 60 --duration 30s --res 720p --timecode
+
+# Force real footage to exact specs
+vidfix convert raw.mov --fps 29.97 --duration 10s --res 1280x720 -o fixture.mp4
+
+# Assert specs in CI (exit 0 pass / 1 fail)
+vidfix verify fixture.mp4 --fps 29.97 --duration 10s --res 1280x720
+```
+
+## Commands
+
+Everything vidfix can do, at a glance (details in the sections below):
+
+| Command | What it does |
+|---|---|
+| `vidfix` (no args) | Interactive wizard — answer prompts, see the equivalent one-liner, run it |
+| `vidfix generate` | Create a synthetic test video to exact specs — patterns, test tone, timecode burn-in, no source file needed |
+| `vidfix convert` | Force an existing video to exact fps / duration / resolution / codec (stream-copies when possible) |
+| `vidfix caption` | Burn a text caption into a video — position, size, color, optional start/end window |
+| `vidfix format` | Convert any picture or video to any other format by output extension (incl. palette-optimized GIF, thumbnails) |
+| `vidfix verify` | Assert a file matches specs; exit 0 pass / 1 fail — wire straight into CI |
+| `vidfix info` | Pretty-print media metadata: container, duration, fps, resolution, codecs (`--json` for scripts) |
+| `vidfix variants` | Generate the fps × resolution cartesian product of variants, in parallel |
+| `vidfix preset list` / `preset show` | Inspect built-in + user presets (broadcast rate family, see [Presets](#presets)) |
+
+`info` and `variants` were previously named `probe` and `matrix`; the old names
+still work as hidden aliases, so existing scripts keep running.
+
+### `vidfix convert` — exact-spec transforms
+
+```bash
+vidfix convert in.mp4 --fps 60 --res 1080p -o out.mp4
+vidfix convert in.mp4 --fps 60 --smooth -o out.mp4          # motion-interpolated 30→60
+vidfix convert in.mp4 --duration 10s -o out.mp4             # trim: instant stream copy
+vidfix convert in.mp4 --duration 10s --precise -o out.mp4   # frame-accurate re-encode
+vidfix convert in.mp4 --duration 60s --extend-mode loop -o out.mp4
+vidfix convert in.mp4 --preset df60 -o out.mp4              # 59.94 = exact 60000/1001
+```
+
+Trims with an unchanged codec use FFmpeg stream copy (instant, no quality loss).
+Resolution changes pad with black bars to preserve aspect ratio (`--stretch` to
+disable). Drop-frame rates are passed to FFmpeg as exact rationals
+(`30000/1001`), never lossy floats.
+
+| Option | Meaning | Default |
+|---|---|---|
+| `-o, --output` | Output file path | required |
+| `--fps` | Target frame rate: `30`, `59.94`, `30000/1001` | keep source |
+| `--duration` | Target duration: `30s`, `1:30`, `90` — trims or extends | keep source |
+| `--res` | Target resolution: `1280x720`, `720p`, `4k` | keep source |
+| `--codec` | Video codec: `h264`, `h265`, `prores`, `vp9` | `h264` |
+| `--preset` | Preset name for defaults (`vidfix preset list`) | — |
+| `--smooth` | Motion-interpolate fps changes (minterpolate) | off |
+| `--extend-mode` | When target duration > source: `freeze` last frame or `loop` | `freeze` |
+| `--stretch` | Stretch to target resolution (no pad bars) | off |
+| `--no-audio` | Drop the audio track | off |
+| `--audio-tone` | Replace audio with a 440Hz test tone | off |
+| `--precise` | Force re-encode for frame-accurate trims | off |
+
+### `vidfix generate` — synthetic fixtures from nothing
+
+```bash
+vidfix generate -o bars.mp4 --fps 59.94 --duration 30s --res 1080p
+vidfix generate -o count.mp4 --pattern testsrc --timecode    # running timecode overlay
+vidfix generate -o df.mp4 --preset df30 --timecode           # drop-frame HH:MM:SS;FF burn-in
+vidfix generate -o red.mp4 --pattern solid:red --audio none
+```
+
+Patterns: `smpte`, `color-bars`, `testsrc`, `gradient`, `solid:COLOR`.
+Audio: 440Hz `tone` (default), `silence`, `none`.
+
+| Option | Meaning | Default |
+|---|---|---|
+| `-o, --output` | Output file path | required |
+| `--fps` | Frame rate: `30`, `59.94`, `30000/1001` | `30` |
+| `--duration` | Duration: `30s`, `1:30`, `90` | `5s` |
+| `--res` | Resolution: `1280x720`, `720p`, `4k` | `1280x720` |
+| `--pattern` | Test pattern: `smpte`, `color-bars`, `testsrc`, `gradient`, `solid:COLOR` | `smpte` |
+| `--codec` | Video codec: `h264`, `h265`, `prores`, `vp9` | `h264` |
+| `--audio` | Audio track: `tone` (440Hz), `silence`, `none` | `tone` |
+| `--timecode` | Burn in running timecode (`HH:MM:SS:FF`; drop-frame `;FF` for NTSC) | off |
+| `--text` | Burn a caption into the video | — |
+| `--preset` | Preset name for defaults (`vidfix preset list`) | — |
+
+### `vidfix verify` — spec assertions for CI
+
+```bash
+vidfix verify out.mp4 --fps 60 --duration 30s --res 1280x720 --codec h264
+vidfix verify out.mp4 --fps 29.97 --json | jq .passed
+```
+
+Prints a pass/fail table per property; exit code 0/1.
+
+| Option | Meaning | Default |
+|---|---|---|
+| `--fps` | Expected frame rate | not checked |
+| `--duration` | Expected duration | not checked |
+| `--res` | Expected resolution | not checked |
+| `--codec` | Expected video codec | not checked |
+| `--fps-tolerance` | Allowed fps deviation | `0.01` |
+| `--duration-tolerance` | Allowed duration deviation in seconds | `0.1` |
+| `--json` | Machine-readable JSON instead of a table | off |
+
+### `vidfix info` — metadata at a glance
+
+```bash
+vidfix info clip.mp4             # rich table
+vidfix info clip.mp4 --json      # jq-friendly
+```
+
+```
+$ vidfix info clip.mp4
+ container     mp4
+ duration      0:00:30.030 (30.030s)
+ resolution    1280x720
+ fps           29.970 (df30, 30000/1001)
+ video codec   h264
+ pixel format  yuv420p
+ bitrate       1200 kb/s
+ audio         aac 44100 Hz 2ch
+```
+
+The container name is resolved from the file's `major_brand` tag (mp4/mov/m4a/3gp)
+or the extension — not ffprobe's raw demuxer list (`mov,mp4,m4a,3gp,3g2,mj2`);
+`--json` keeps the raw string as `demuxer` and the tag as `major_brand` alongside
+the friendly `container`. Broadcast rates get their preset-family label in the fps
+line (`df30`, `df60`, `pal25`, `pal50`, `film24`, `film23976`) so QA can read them
+at a glance. Uses system `ffprobe` when available, otherwise parses FFmpeg output
+directly.
+
+### `vidfix caption` — burn text into a video
+
+```bash
+vidfix caption in.mp4 --text "Take 42" -o out.mp4
+vidfix caption in.mp4 --text "INTRO" --position top --color yellow -o out.mp4
+vidfix caption in.mp4 --text "3..2..1" --start 0 --end 3 -o out.mp4
+vidfix generate -o clip.mp4 --text "TEST CLIP"      # caption a generated video too
+```
+
+Positions: `top`, `center`, `bottom` (default). Audio is stream-copied untouched.
+
+| Option | Meaning | Default |
+|---|---|---|
+| `-o, --output` | Output file path | required |
+| `--text` | Caption text to burn in | required |
+| `--position` | Placement: `top`, `center`, `bottom` | `bottom` |
+| `--size` | Font size (pixels or expression like `h/12`) | `h/12` |
+| `--color` | Font color: `white`, `yellow`, `#ff0000` | `white` |
+| `--start` | Show caption from this second onward | whole video |
+| `--end` | Hide caption after this second | whole video |
+
+### `vidfix format` — any picture or video to any format
+
+```bash
+vidfix format clip.mov -o clip.mp4      # container conversion
+vidfix format clip.mp4 -o clip.gif      # palette-optimized gif
+vidfix format photo.png -o photo.webp   # image conversion
+vidfix format clip.mp4 -o thumb.jpg     # first-frame thumbnail
+```
+
+The output extension picks the format — the only option is `-o, --output` (required).
+
+### `vidfix variants` — variant grids in parallel
+
+```bash
+vidfix variants in.mp4 --fps 30,60 --res 720p,1080p -o out/
+# → variants/in_30fps_720p.mp4, in_30fps_1080p.mp4, in_60fps_720p.mp4, ...
+```
+
+| Option | Meaning | Default |
+|---|---|---|
+| `-o, --output` | Output directory | required |
+| `--fps` | Comma-separated frame rates, e.g. `30,60` | required |
+| `--res` | Comma-separated resolutions, e.g. `720p,1080p` | required |
+| `--codec` | Video codec for all variants | `h264` |
+| `--jobs` | Parallel FFmpeg processes | `min(4, cpus)` |
+
+Exit code is 1 if any variant fails. `vidfix info` takes just the file and
+`--json`; `vidfix preset list` / `preset show NAME` take no options.
+
+### Presets
+
+```bash
+vidfix preset list
+vidfix preset show df30
+vidfix generate -o pal.mp4 --preset pal25 --timecode
+```
+
+Built-in broadcast rate family:
+
+| Preset | fps | Timecode counting |
+|---|---|---|
+| `df30` | 29.97 (30000/1001) | drop-frame (`HH:MM:SS;FF`) |
+| `df60` | 59.94 (60000/1001) | drop-frame (`HH:MM:SS;FF`) |
+| `ndf30` | 29.97 (30000/1001) | non-drop (`HH:MM:SS:FF`) |
+| `ndf60` | 59.94 (60000/1001) | non-drop (`HH:MM:SS:FF`) |
+| `pal25` (alias `ndf25`) | exact 25 | non-drop (`HH:MM:SS:FF`) |
+| `pal50` | exact 50 | non-drop (`HH:MM:SS:FF`) |
+| `film24` | exact 24 | non-drop (`HH:MM:SS:FF`) |
+| `film23976` | 23.976 (24000/1001) | non-drop (`HH:MM:SS:FF`) |
+
+Plus `broadcast-1080i` (25 fps, 1920x1080) and `web-720p` (30 fps, 720p, h264).
+With `--timecode`, DF presets burn semicolon drop-frame notation and NDF/PAL/film
+presets colon notation, matching broadcast convention. Aliases (`alias: pal25`)
+work in user presets too. Add your own in `~/.config/vidfix/presets.yaml`;
+explicit flags always override.
+
+## Python API
+
+```python
+from vidfix import convert, generate, verify, probe
+
+generate("fixture.mp4", fps="59.94", duration="30s", res="720p")
+info = probe("fixture.mp4")           # MediaInfo (pydantic)
+result = verify("fixture.mp4", duration=30.0)
+assert result.passed
+```
+
+## vidfix vs moviepy vs raw FFmpeg
+
+| | vidfix | moviepy | raw ffmpeg |
+|---|---|---|---|
+| Exact-spec test fixtures | ✅ one command | ⚠️ manual | ⚠️ long filter incantations |
+| Spec verification + exit codes | ✅ built in | ❌ | ⚠️ ffprobe + shell glue |
+| Install without system FFmpeg | ✅ bundled | ✅ bundled | ❌ |
+| Editing/compositing/effects | ❌ not the goal | ✅ | ✅ |
+| Programmatic frame access | ❌ | ✅ numpy frames | ⚠️ |
+| Speed | ✅ direct filters, stream copy | ⚠️ python frame loop | ✅ |
+
+Use **moviepy** to *edit* videos, **raw ffmpeg** for full control, **vidfix**
+for exact-spec media, quick conversions, and CI checks with zero setup.
+
+## CI usage
+
+```yaml
+- name: Verify rendered output specs
+  run: |
+    pip install vidfix
+    vidfix verify build/output.mp4 --fps 60 --duration 30s --res 1280x720
+```
+
+## Development
+
+```bash
+uv sync                                   # install with dev deps
+uv run pytest                             # unit + integration tests
+uv run pytest -m "not integration"        # fast tests only (no FFmpeg)
+uv run ruff check . && uv run mypy        # lint + strict types
+```
+
+## License
+
+[PolyForm Internal Use 1.0.0](LICENSE) — you may use vidfix freely for personal
+and internal business purposes (commercial included). Copying, redistributing,
+or building products from this source code is not permitted. Contributions are
+welcome via pull request.