vidio-cli 0.1.0__tar.gz

vidio_cli-0.1.0/.gitattributes

@@ -0,0 +1 @@
+*.mp4 filter=lfs diff=lfs merge=lfs -text

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

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  fast-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync --group dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Fast tests (non-integration)
+        run: uv run pytest -q -m "not integration"
+
+  integration-tests:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          lfs: true
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install ffmpeg
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ffmpeg
+
+      - name: Sync dependencies
+        run: uv sync --group dev
+
+      - name: Integration tests
+        run: uv run pytest -q -m "integration"

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

@@ -0,0 +1,72 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      repository:
+        description: "Package repository target"
+        required: true
+        default: testpypi
+        type: choice
+        options:
+          - testpypi
+          - pypi
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Validate distributions
+        run: |
+          python -m pip install --upgrade pip twine
+          python -m twine check dist/*
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+    env:
+      TARGET_REPOSITORY: ${{ github.event_name == 'release' && 'pypi' || github.event.inputs.repository }}
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        if: env.TARGET_REPOSITORY == 'testpypi'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+      - name: Publish to PyPI
+        if: env.TARGET_REPOSITORY == 'pypi'
+        uses: pypa/gh-action-pypi-publish@release/v1

vidio_cli-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.python-version
+
+# IDE - PyCharm
+.idea/
+*.iws
+*.iml
+*.ipr
+
+# IDE - VSCode
+.vscode/
+*.code-workspace
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+.env/
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+.tox/
+.nox/
+
+# OS specific
+.DS_Store
+Thumbs.db
+
+# Temporary files
+tmp/
+
+tasks.md

vidio_cli-0.1.0/AGENTS.md

@@ -0,0 +1,143 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`vidio-cli` is a Python-based CLI tool that provides a simple, user-friendly wrapper around ffmpeg for common video operations. It uses Typer for CLI framework and Rich for terminal output formatting.
+
+## Development Setup
+
+This project uses `uv` for package management:
+
+```bash
+# Install dependencies
+uv sync
+
+# Install with dev dependencies
+uv sync --group dev
+
+# Install in development mode (editable install)
+uv pip install -e .
+```
+
+## Running Commands
+
+```bash
+# Run the CLI during development
+uv run vidio <command>
+
+# Or after installing in dev mode
+vidio <command>
+
+# Run tests
+uv run pytest
+
+# Run tests with verbose output
+uv run pytest -v
+
+# Run specific test file
+uv run pytest tests/test_concat.py
+
+# Lint with ruff
+uv run ruff check .
+
+# Format with ruff
+uv run ruff format .
+```
+
+## Architecture
+
+### Command Registration System
+
+Commands are **dynamically discovered and registered** at startup via `src/vidio_cli/commands/__init__.py`:
+
+1. The `get_commands()` function scans the `commands/` directory for Python modules
+2. Each module with a `register()` function is treated as a command
+3. Module names (with underscores) become command names (with hyphens), e.g., `to_gif.py` → `to-gif`
+4. Commands are registered with the main Typer app in `src/vidio_cli/cli.py`
+
+### Command Module Pattern
+
+Each command module follows this structure:
+
+```python
+def register(app: typer.Typer) -> None:
+    """Register the command with the Typer app."""
+    app.command(no_args_is_help=True)(command_function)
+
+def command_function(
+    ctx: typer.Context,
+    # ... command arguments and options
+) -> None:
+    """Command implementation."""
+    verbose = ctx.obj.get("VERBOSE", False) if ctx.obj else False
+    # ... command logic using ffmpeg_utils
+```
+
+### Shared Utilities
+
+- **`ffmpeg_utils.py`**: Core utilities for running ffmpeg/ffprobe commands
+  - `ensure_ffmpeg()`: Verifies ffmpeg is installed
+  - `run_ffmpeg()`: Executes ffmpeg commands with error handling
+  - `get_video_info()`: Retrieves video metadata using ffprobe
+  - `check_output_file()`: Handles output file overwrite checks
+
+- **`config.py`**: Default settings for video encoding (codec, quality, preset)
+
+### Global Context
+
+The verbose flag (`--verbose` / `-v`) is stored in the Typer context object and accessed by commands via `ctx.obj.get("VERBOSE", False)`.
+
+## Adding a New Command
+
+1. Create `src/vidio_cli/commands/<command_name>.py`
+2. Implement the `register(app: typer.Typer)` function
+3. Implement the command function with appropriate arguments/options
+4. Use `ffmpeg_utils` functions for running ffmpeg operations
+5. Access verbose flag from context: `verbose = ctx.obj.get("VERBOSE", False)`
+6. Create corresponding test file: `tests/test_<command_name>.py`
+7. The command will be automatically discovered and registered (no manual registration needed)
+
+## Testing
+
+Tests use pytest and should cover:
+- Command registration
+- Argument/option validation
+- ffmpeg command generation (can mock `run_ffmpeg`)
+- Error handling
+
+Test videos can be placed in `tests/assets/` if needed.
+
+## Dependencies
+
+- **typer**: CLI framework with type annotations
+- **rich**: Terminal formatting and colors
+- **ffmpeg**: External dependency (must be in PATH)
+
+## PyPI Release Workflow
+
+Use this release flow for `vidio-cli`:
+
+1. Update version in `pyproject.toml`.
+2. Update `CHANGELOG.md` with the release date and notable changes.
+3. Run quality checks locally:
+   - `uv run ruff check .`
+   - `uv run pytest -q`
+4. Build and validate the distribution:
+   - `uv build`
+   - `python -m twine check dist/*`
+5. Commit and tag:
+   - `git tag v<version>`
+   - `git push origin main --tags`
+6. Publish:
+   - Preferred: create a GitHub Release from the version tag; this triggers `.github/workflows/publish.yml` and publishes to PyPI.
+   - Optional: run the publish workflow manually with `workflow_dispatch` to publish to TestPyPI first.
+
+### Trusted Publishing Setup
+
+The project should use PyPI Trusted Publishing with GitHub Actions:
+
+- In PyPI/TestPyPI project settings, add a trusted publisher for this repository.
+- Point it to workflow file `.github/workflows/publish.yml`.
+- Restrict to the `main` branch and/or release tags as needed.

vidio_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0 - 2026-02-06
+
+First public release of `vidio-cli`.
+
+- Added core commands for everyday video workflows:
+  - `list` / `ls`
+  - `info`
+  - `trim`
+  - `resize`
+  - `crop`
+  - `concat`
+  - `grid`
+  - `to-gif`
+- Added dynamic command discovery and registration.
+- Added test coverage for command behavior and output handling.
+- Added distribution build support for wheel and source tarball.

vidio_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matan Ben-Yosef
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vidio_cli-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: vidio-cli
+Version: 0.1.0
+Summary: A simple and easy-to-use ffmpeg wrapper for common video operations
+Project-URL: Homepage, https://github.com/matanb/vidio-cli
+Project-URL: Repository, https://github.com/matanb/vidio-cli
+Project-URL: Issues, https://github.com/matanb/vidio-cli/issues
+Author-email: Matan Ben-Yosef <matan.ben.yosef@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,ffmpeg,gif,media,video
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: rich>=13.5.0
+Requires-Dist: typer>=0.9.0
+Description-Content-Type: text/markdown
+
+# vidio-cli
+
+A simple and easy-to-use ffmpeg wrapper for common video operations.
+
+## Features
+
+- **Stupidly Easy:** Simple CLI commands for common video operations.
+- **Powerful Defaults:** Sensible defaults make it work great out of the box.
+- **Focused v1 Scope:** Core commands people use repeatedly, without feature bloat.
+
+## Requirements
+
+- Python 3.10+
+- ffmpeg (must be installed and in your PATH)
+
+## v1 Command Scope
+
+`vidio-cli` 0.1.0 intentionally focuses on practical, high-frequency tasks:
+
+- `list` / `ls`: find video files quickly
+- `info`: inspect metadata and streams
+- `trim`: cut clips by time range
+- `resize`: scale for delivery targets
+- `crop`: convert to target aspect ratios
+- `concat`: place videos side-by-side or stacked
+- `grid`: build multi-video collages
+- `to-gif`: convert clips to GIF with good defaults
+
+Commands that are less consistently useful (for example, niche one-off transforms) are deferred to later releases.
+
+## Installation
+
+```bash
+# Using pip
+pip install vidio-cli
+
+# Using uv
+uv pip install vidio-cli
+```
+
+## Usage
+
+```bash
+# Get help
+vidio --help
+
+# Get help for a specific command
+vidio concat --help
+```
+
+### Concatenate Videos
+
+```bash
+# Concatenate videos horizontally
+vidio concat video1.mp4 video2.mp4 output.mp4
+
+# Concatenate videos vertically
+vidio concat video1.mp4 video2.mp4 output.mp4 --vertical
+```
+
+### List Video Files
+
+```bash
+# List videos in current directory (ls-style output)
+vidio list
+# or use the shorter alias
+vidio ls
+
+# List with detailed information (duration, resolution, codec)
+vidio ls --list
+
+# Search recursively in subdirectories
+vidio ls --recursive
+
+# Use table format instead of ls-style
+vidio ls --table
+
+# Get JSON output for scripting
+vidio ls --json
+```
+
+### Video Information
+
+```bash
+# Display detailed metadata about a video file
+vidio info video.mp4
+
+# Get machine-readable JSON output
+vidio info video.mp4 --json
+
+# Calculate exact frame count (slower but accurate)
+vidio info video.mp4 --exact-frames
+```
+
+### Create Video Grids
+
+```bash
+# Arrange videos in a 2x2 grid (auto-calculated)
+vidio grid video1.mp4 video2.mp4 video3.mp4 video4.mp4 output.mp4
+
+# Specify grid dimensions
+vidio grid video1.mp4 video2.mp4 video3.mp4 video4.mp4 output.mp4 --rows 2 --cols 2
+
+# Control cell size and add padding
+vidio grid video1.mp4 video2.mp4 video3.mp4 video4.mp4 output.mp4 --width 640 --height 360 --padding 10
+
+# Change background color
+vidio grid video1.mp4 video2.mp4 video3.mp4 video4.mp4 output.mp4 --background white
+```
+
+### Trim Videos
+
+```bash
+# Trim from 30 seconds to 90 seconds
+vidio trim input.mp4 output.mp4 --start 30 --end 90
+
+# Trim from 1:30 for 45 seconds duration
+vidio trim input.mp4 output.mp4 --start 1:30 --duration 45
+
+# Trim from beginning to 2:15
+vidio trim input.mp4 output.mp4 --end 2:15
+
+# Trim using different time formats
+vidio trim input.mp4 output.mp4 --start 0:01:30 --end 0:02:45
+```
+
+### Resize Videos
+
+```bash
+# Resize to specific dimensions (maintains aspect ratio)
+vidio resize input.mp4 output.mp4 --width 1920 --height 1080
+
+# Scale by percentage
+vidio resize input.mp4 output.mp4 --scale 0.5  # 50% of original size
+
+# Resize width only (height auto-calculated)
+vidio resize input.mp4 output.mp4 --width 1280
+
+# Resize height only (width auto-calculated)  
+vidio resize input.mp4 output.mp4 --height 720
+
+# Force exact dimensions (may distort)
+vidio resize input.mp4 output.mp4 -w 1920 -h 1080 --force-aspect
+```
+
+### Convert to GIF
+
+```bash
+# Basic conversion with optimized palette
+vidio to-gif video.mp4 output.gif
+
+# High quality with custom frame rate
+vidio to-gif video.mp4 output.gif --fps 15 --quality high
+
+# Small file size for web
+vidio to-gif video.mp4 output.gif --scale 0.3 --fps 8 --quality low
+
+# Convert specific time range
+vidio to-gif video.mp4 output.gif --start 10 --duration 5
+
+# Custom width with different dithering
+vidio to-gif video.mp4 output.gif --width 800 --dither bayer
+
+# Fast conversion (skip optimization)
+vidio to-gif video.mp4 output.gif --no-optimize
+```
+
+### Crop Videos
+
+```bash
+# Crop to center square (perfect for Instagram)
+vidio crop input.mp4 output.mp4 --preset center-square
+
+# Crop to 16:9 aspect ratio
+vidio crop input.mp4 output.mp4 --preset 16:9
+
+# Crop to 9:16 aspect ratio (vertical/portrait)
+vidio crop input.mp4 output.mp4 --preset 9:16
+
+# Crop to 4:3 aspect ratio
+vidio crop input.mp4 output.mp4 --preset 4:3
+
+# Custom crop region (centered)
+vidio crop input.mp4 output.mp4 --width 1280 --height 720
+
+# Custom crop with specific position
+vidio crop input.mp4 output.mp4 -w 1280 -h 720 --x 100 --y 50
+```
+
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/matanb/vidio-cli.git
+cd vidio-cli
+
+# Install dependencies
+uv sync --group dev
+
+# Run tests
+uv run pytest -q
+
+# Run lint
+uv run ruff check .
+```
+
+## License
+
+MIT