Metadata-Version: 2.4
Name: custom-ffmpeg-v
Version: 0.1.0
Summary: A custom FFmpeg and FFprobe wrapper for precise frame extraction and video metadata
Author-email: kishan0822 <kishan@sportzengage.ai>
Project-URL: Homepage, https://github.com/example/custom-ffmpeg
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# Custom FFmpeg

A custom FFmpeg and FFprobe wrapper for precise frame extraction and video metadata without OpenCV dependencies.

## Features
- **Variable Frame Rate (VFR) support**: Extracts precise timestamps using ffprobe.
- **Lazy Frame Loader**: Exact 1-to-1 mapping of encoded video frames to extracted images.
- **Video Utilities**: Extract rotation, dimensions, and FPS relying purely on FFmpeg/FFprobe.
- **Zero third-party dependencies**: Does not require `opencv-python` or other heavy image processing libraries.

## Prerequisites

This library requires FFmpeg and FFprobe to be installed on your system and available in your system's PATH. 
You can verify your installation by running:
```bash
ffmpeg -version
ffprobe -version
```

## Installation

You can install this module directly into any project using `pip`. 

### Install Locally
If you have cloned or downloaded this repository, navigate to your new project's environment and install it using the path to the `custom_ffmpeg` directory:

```bash
# Standard installation
pip install /path/to/custom_ffmpeg

# Editable installation (useful if you are actively developing the custom_ffmpeg module)
pip install -e /path/to/custom_ffmpeg
```

### Install via Git
If this module is hosted in a git repository, you can install it directly via Git:
```bash
pip install git+https://github.com/yourusername/your-repo.git#subdirectory=scripts/custom_ffmpeg
```

## Usage

### 1. Extracting Frames (LazyFrameLoader)

The `LazyFrameLoader` will use FFmpeg to extract frames into a temporary folder. Since there are no OpenCV dependencies, accessing an index will return the **absolute file path** to the extracted PNG frame.

```python
from custom_ffmpeg import LazyFrameLoader

# Initialize the loader (this will automatically run ffmpeg to extract frames)
video_path = "sample_video.mp4"
loader = LazyFrameLoader(video_path)

print(f"Total frames extracted: {len(loader)}")
print(f"Video FPS: {loader.fps}")

# Access the first frame
frame_path = loader[0]
print(f"Path to first frame: {frame_path}")

# Calculate true time delta (dt) between frames for accurate kinematics
# This is especially important for VFR (Variable Frame Rate) videos.
dt = loader.get_dt(1)
print(f"Time delta between frame 0 and 1: {dt} seconds")

# Cleanup the temporary extracted frames directory when done
loader.release()
```

### 2. Getting Video Metadata (VideoUtils)

`VideoUtils` uses FFprobe to extract accurate metadata from the video without loading any frames.

```python
from custom_ffmpeg import VideoUtils

video_path = "sample_video.mp4"
stats = VideoUtils.get_video_stats(video_path)

if stats:
    print(f"Resolution: {stats['width']}x{stats['height']}")
    print(f"FPS: {stats['fps']}")
    print(f"Total Frames: {stats['frame_count']}")
    print(f"Rotation: {stats['rotation']} degrees")
```

## Publishing to PyPI

If you want to publish this package to the public Python Package Index (PyPI) or a private repository, follow these steps:

1. **Install Build Tools:**
   Ensure you have `build` and `twine` installed in your environment.
   ```bash
   pip install build twine
   ```

2. **Build the Package:**
   Run the following command from the same directory as `pyproject.toml`. It will create a `dist/` folder containing a `.tar.gz` source archive and a `.whl` built distribution.
   ```bash
   python -m build
   ```

3. **Test the Build Locally (Optional but Recommended):**
   Before uploading, it is a good idea to verify the built package locally.
   
   First, check if the package description will render correctly on PyPI:
   ```bash
   twine check dist/*
   ```
   
   Next, you can test installing the compiled `.whl` file in a fresh virtual environment to ensure it works exactly as the end-user will experience it:
   ```bash
   # Create a test virtual environment
   python -m venv test_env
   source test_env/bin/activate
   
   # Install the built wheel file
   pip install dist/custom_ffmpeg-0.1.0-py3-none-any.whl
   
   # Verify the import works
   python -c "import custom_ffmpeg; print('Success!')"
   
   # Clean up and exit
   deactivate
   rm -rf test_env
   ```

4. **Upload to PyPI:**
   Use twine to upload the generated archives. You will be prompted for your PyPI API token (username is `__token__`).
   ```bash
   python -m twine upload dist/*
   ```
   *(To test the upload safely without publishing to the real PyPI, use TestPyPI: `python -m twine upload --repository testpypi dist/*`)*
