custom-ffmpeg-v 0.1.0

A custom FFmpeg and FFprobe wrapper for precise frame extraction and video metadata

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:

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:

# 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:

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.

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.

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.

   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.

   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:

   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:

   # 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__).

   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/*)