ffmpeg-python-helper 0.1.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

ffmpeg_python_helper/__init__.py

@@ -1,9 +1,67 @@
+"""
+FFMPEG Python Helper - A Python wrapper for FFMPEG video processing.
+
+This package provides a simple, intuitive API for common video processing tasks
+including format conversion, GIF creation, video trimming, audio extraction,
+in-memory processing, and data pipeline utilities.
+
+Example:
+    >>> from ffmpeg_python_helper import FFMPEG, Pipe
+    >>> ffmpeg = FFMPEG()
+    >>> ffmpeg.reformat("input.mp4", "output.avi")
+    >>> ffmpeg.gif("video.mp4", "animation.gif", fps=15, scale=480)
+    >>> ffmpeg.trim("video.mp4", "short_clip.mp4", start=10.5, duration=5.0)
+    >>> ffmpeg.extract_audio("video.mp4", "audio.m4a")
+    >>> 
+    >>> # In-memory processing
+    >>> with open("video.mp4", "rb") as f:
+    ...     video_data = f.read()
+    >>> gif_data = ffmpeg.gifs(video_data, fps=15, scale=480)
+    >>> trimmed_data = ffmpeg.trims(video_data, start=0, duration=30)
+    >>> audio_data = ffmpeg.extract_audios(video_data, output_format="m4a")
+    >>> 
+    >>> # Pipeline processing
+    >>> def process_video(data: bytes) -> bytes:
+    ...     return ffmpeg.trims(data, start=0, duration=30)
+    >>> 
+    >>> def convert_to_gif(data: bytes) -> bytes:
+    ...     return ffmpeg.gifs(data, fps=15, scale=480)
+    >>> 
+    >>> processed_data = Pipe.pipe_bytes(video_data, process_video, convert_to_gif)
+
+For detailed API documentation, see:
+    - FFMPEG class documentation
+    - Pipe class documentation
+    - README.md for usage examples and tutorials
+"""
+
 from .ffmpeg_api import FFMPEG
+from .pipe_helper import Pipe
 
 __all__ = [
-    'FFMPEG'
+    'FFMPEG',
+    'Pipe'
 ]
 
-def main():
+__version__ = "0.1.0"
+__author__ = "marjon <marjongodito@gmanmi.com>"
+
+
+def main() -> None:
+    """
+    Command-line entry point for the FFMPEG Python Helper.
+
+    This function is called when the package is executed as a script.
+    It demonstrates basic functionality by:
+        1. Creating an FFMPEG instance
+        2. Printing the path to the FFMPEG executable
+
+    Example:
+        $ python -m ffmpeg_python_helper
+        FFMPEG executable found at: /usr/bin/ffmpeg
+
+    Raises:
+        FileNotFoundError: If FFMPEG is not found in PATH.
+    """
     ffmpeg = FFMPEG()
-    print(ffmpeg.executable)
+    print(f"FFMPEG executable found at: {ffmpeg.executable}")

ffmpeg_python_helper/ffmpeg_api.py

@@ -1,8 +1,52 @@
 import subprocess
 from pathlib import Path
 
+
 class FFMPEG:
+    """
+    A Python wrapper for FFMPEG that provides a simple, intuitive API for
+    common video processing tasks.
+
+    This class automatically detects FFMPEG installation in the system PATH
+    and provides methods for video conversion, GIF creation, video trimming,
+    and audio extraction. It supports both file-based operations and 
+    in-memory data processing.
+
+    Example:
+        >>> from ffmpeg_python_helper import FFMPEG
+        >>> ffmpeg = FFMPEG()
+        >>> ffmpeg.reformat("input.mp4", "output.avi")
+        >>> ffmpeg.gif("video.mp4", "animation.gif", fps=15, scale=480)
+        >>> ffmpeg.trim("video.mp4", "short_clip.mp4", start=10.5, duration=5.0)
+        >>> ffmpeg.extract_audio("video.mp4", "audio.m4a")
+        >>> 
+        >>> # In-memory processing
+        >>> with open("video.mp4", "rb") as f:
+        ...     video_data = f.read()
+        >>> gif_data = ffmpeg.gifs(video_data, fps=15, scale=480)
+        >>> trimmed_data = ffmpeg.trims(video_data, start=0, duration=30)
+        >>> audio_data = ffmpeg.extract_audios(video_data, output_format="m4a")
+
+    Attributes:
+        executable (str): The path to the FFMPEG executable found in the system PATH.
+    """
+
     def __init__(self) -> None:
+        """
+        Initialize a new FFMPEG instance.
+
+        Automatically searches for FFMPEG in the system PATH.
+
+        Raises:
+            FileNotFoundError: If FFMPEG is not found in the system PATH.
+
+        Example:
+            >>> try:
+            ...     ffmpeg = FFMPEG()
+            ...     print(f"FFMPEG found at: {ffmpeg.executable}")
+            ... except FileNotFoundError as e:
+            ...     print(f"FFMPEG not found: {e}")
+        """
         import shutil
         self.executable = shutil.which('ffmpeg')
 
@@ -14,13 +58,71 @@ in your system PATH.
 """)
 
     @classmethod
-    def api(cls):
+    def api(cls) -> "FFMPEG":
+        """
+        Factory method that returns a new FFMPEG instance.
+
+        Returns:
+            FFMPEG: A new instance of the FFMPEG class.
+
+        Example:
+            >>> ffmpeg = FFMPEG.api()
+            >>> ffmpeg.execute("-version")
+        """
         return cls()
 
-    def execute(self, *args : str):
+    def execute(self, *args: str, input_data: bytes | None = None) -> tuple[bytes, bytes]:
+        """
+        Execute raw FFMPEG commands with the given arguments.
+
+        This method allows you to run any FFMPEG command directly,
+        providing maximum flexibility for operations not covered
+        by the built-in methods.
+
+        Args:
+            *args: FFMPEG command-line arguments as strings.
+            input_data: Optional bytes to send to FFMPEG's stdin. Useful for
+                       piping data directly to FFMPEG without intermediate files.
+
+        Returns:
+            tuple[bytes, bytes]: A tuple containing (stdout, stderr) from FFMPEG
+                                 as bytes objects.
+
+        Raises:
+            FileNotFoundError: If FFMPEG executable is not found.
+            RuntimeError: If FFMPEG command returns a non-zero exit code.
+
+        Example:
+            >>> stdout, stderr = ffmpeg.execute("-version")
+            >>> print(stdout.decode())
+
+            >>> # Extract audio from video
+            >>> ffmpeg.execute("-i", "video.mp4", "-q:a", "0", "-map", "a", "audio.mp3")
+
+            >>> # Add watermark to video
+            >>> ffmpeg.execute("-i", "video.mp4", "-i", "watermark.png",
+            ...                "-filter_complex", "overlay=10:10", "output.mp4")
+
+            >>> # Process data from memory
+            >>> video_data = b"...video bytes..."
+            >>> stdout, stderr = ffmpeg.execute("-i", "pipe:0", "-f", "null", "-",
+            ...                                 input_data=video_data)
+        """
         if self.executable:
-            result = subprocess.run([self.executable, *args], capture_output=True, text=True)
-            return result.stdout.strip(), result.stderr.strip()
+            result = subprocess.run(
+                [self.executable, *args], 
+                input=input_data,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                check=False
+                )
+
+            if result.returncode != 0:
+                raise RuntimeError(
+                    result.stderr.decode(errors="replace")
+                )
+            
+            return result.stdout, result.stderr
 
         raise FileNotFoundError("""
         No ffmpeg executable found.
@@ -28,7 +130,30 @@ in your system PATH.
         Please Install ffmpeg first.
         """)
 
-    def reformat(self, input_file : str, output_file : str):
+    def reformat(self, input_file: str, output_file: str) -> bytes:
+        """
+        Convert a video file from one format to another.
+
+        This method performs a simple format conversion without
+        modifying video quality or other parameters.
+
+        Args:
+            input_file: Path to the input video file.
+            output_file: Path for the output video file.
+
+        Returns:
+            bytes: FFMPEG output (stdout or stderr) as bytes.
+
+        Raises:
+            FileNotFoundError: If input file doesn't exist.
+
+        Example:
+            >>> output = ffmpeg.reformat("input.mov", "output.mp4")
+            >>> print(output.decode())
+            >>> 
+            >>> output = ffmpeg.reformat("video.avi", "video.mkv")
+            >>> print(output.decode())
+        """
         if not Path(input_file).exists():
             raise FileNotFoundError(f"""
                     Input file {input_file} did not found .
@@ -39,16 +164,103 @@ in your system PATH.
         stdout, stderr = self.execute("-i", input_file, output_file)
 
         if stdout:
-            print(stdout)
+            return stdout
         else:
-            print(stderr)
-
-    def gif(self, 
-            input_file : str, 
-            output_file : str,
-            fps = 10,
-            scale = 320
-            ):
+            return stderr
+
+    def gifs(self,
+            input_bytes: bytes,
+            fps: int = 10,
+            scale: int = 320) -> bytes:
+        """
+        Convert video data from bytes to an optimized GIF.
+
+        Creates a high-quality GIF from in-memory video data using FFMPEG's
+        palette optimization. This method is useful when you have video data
+        in memory and want to avoid writing temporary files.
+
+        Args:
+            input_byte: Video data as bytes to convert to GIF.
+            fps: Frames per second for the GIF. Defaults to 10.
+            scale: Width of the GIF in pixels. Height is auto-scaled
+                   to maintain aspect ratio. Defaults to 320.
+
+        Returns:
+            bytes: The generated GIF data as bytes.
+
+        Raises:
+            RuntimeError: If GIF conversion fails.
+
+        Example:
+            >>> # Read video data from a file
+            >>> with open("video.mp4", "rb") as f:
+            ...     video_data = f.read()
+            >>> 
+            >>> # Convert to GIF in memory
+            >>> gif_data = ffmpeg.gifs(video_data, fps=15, scale=480)
+            >>> 
+            >>> # Save the GIF
+            >>> with open("output.gif", "wb") as f:
+            ...     f.write(gif_data)
+
+            >>> # Process video from network or database
+            >>> # video_bytes = download_video_from_url(url)
+            >>> # gif_bytes = ffmpeg.gifs(video_bytes, scale=320)
+        """
+        filter_graph: str = (
+            f"fps={fps},"
+            f"scale={scale}:-1:flags=lanczos,"
+            "split[s0][s1];"
+            "[s0]palettegen[p];"
+            "[s1][p]paletteuse"
+        )
+
+        stdout, stderr = self.execute(
+            "-y",
+            "-i", "pipe:0",
+            "-vf", filter_graph,
+            "-f", "gif",
+            "pipe:1",
+            input_data=input_bytes
+        )
+
+        return stdout
+
+    def gif(self,
+            input_file: str,
+            output_file: str,
+            fps: int = 10,
+            scale: int = 320
+            ) -> None:
+        """
+        Convert a video file to an optimized GIF.
+
+        Creates a high-quality GIF using FFMPEG's palette optimization
+        for better color reproduction and smaller file sizes.
+
+        Args:
+            input_file: Path to the input video file.
+            output_file: Path for the output GIF file.
+            fps: Frames per second for the GIF. Defaults to 10.
+            scale: Width of the GIF in pixels. Height is auto-scaled
+                   to maintain aspect ratio. Defaults to 320.
+
+        Raises:
+            FileNotFoundError: If input file doesn't exist.
+            RuntimeError: If GIF file was not created successfully.
+
+        Example:
+            >>> # Create a standard GIF
+            >>> ffmpeg.gif("video.mp4", "output.gif")
+
+            >>> # Create a higher quality GIF with custom settings
+            >>> ffmpeg.gif("video.mp4", "output.gif",
+            ...            fps=15, scale=640)
+
+            >>> # Create a small thumbnail GIF
+            >>> ffmpeg.gif("video.mp4", "thumbnail.gif",
+            ...            fps=5, scale=160)
+        """
         input_path = Path(input_file)
         output_path = Path(output_file)
 
@@ -57,7 +269,7 @@ in your system PATH.
                 f"Input file {input_file} was not found."
             )
 
-        filter_graph : str = (
+        filter_graph: str = (
             f"fps={fps},"
             f"scale={scale}:-1:flags=lanczos,"
             "split[s0][s1];"
@@ -65,7 +277,7 @@ in your system PATH.
             "[s1][p]paletteuse"
         )
 
-        stdout, stderr = self.execute(
+        self.execute(
             "-y",
             "-i", str(input_path),
             "-vf", filter_graph,
@@ -77,15 +289,48 @@ in your system PATH.
                 f"GIF was not created: {output_file}"
             )
 
-        return stdout, stderr
-
     def trim(
         self,
         input_file: str,
         output_file: str,
         start: float = 0,
         duration: float | None = None,
-    ):
+    ) -> None:
+        """
+        Trim a video file.
+
+        Extracts a segment from a video file starting at a specified time
+        and optionally ending after a specified duration.
+
+        Args:
+            input_file: Path to the input video file.
+            output_file: Path for the output trimmed video.
+            start: Start time in seconds. Defaults to 0.
+            duration: Duration in seconds, or None for remaining video.
+                      Defaults to None.
+
+        Raises:
+            FileNotFoundError: If input file doesn't exist.
+            ValueError: If start is negative or duration is non-positive.
+            RuntimeError: If trimmed video was not created successfully.
+
+        Example:
+            >>> # Trim from 5 seconds to 10 seconds (5-second clip)
+            >>> ffmpeg.trim("video.mp4", "clip.mp4",
+            ...             start=5, duration=5)
+
+            >>> # Trim from 10 seconds to the end of video
+            >>> ffmpeg.trim("video.mp4", "ending.mp4",
+            ...             start=10)
+
+            >>> # Trim first 30 seconds of video
+            >>> ffmpeg.trim("video.mp4", "intro.mp4",
+            ...             start=0, duration=30)
+
+            >>> # Trim with floating point precision
+            >>> ffmpeg.trim("video.mp4", "precise.mp4",
+            ...             start=2.5, duration=3.75)
+        """
         input_path = Path(input_file)
         output_path = Path(output_file)
 
@@ -118,4 +363,164 @@ in your system PATH.
                 f"Trimmed video was not created: {output_file}"
             )
 
-        return stdout, stderr
+    def trims(self, input_bytes: bytes,
+            start: float = 0,
+            duration: float | None = None,
+            format_type: str = "mp4") -> bytes:
+        """
+        Trim video data from bytes (in-memory processing).
+
+        Extracts a segment from in-memory video data starting at a specified time
+        and optionally ending after a specified duration. This method is useful
+        when you have video data in memory and want to avoid writing temporary files.
+
+        Note: For MP4 format, this method uses libx264 video codec and AAC audio codec
+        with fragmented MP4 output for better streaming compatibility.
+
+        Args:
+            input_bytes: Video data as bytes to trim.
+            start: Start time in seconds. Defaults to 0.
+            duration: Duration in seconds, or None for remaining video.
+                      Defaults to None.
+            format_type: Output format (e.g., 'mp4', 'avi', 'mov'). Defaults to 'mp4'.
+
+        Returns:
+            bytes: The trimmed video data as bytes.
+
+        Raises:
+            RuntimeError: If video trimming fails.
+
+        Example:
+            >>> # Read video data from a file
+            >>> with open("video.mp4", "rb") as f:
+            ...     video_data = f.read()
+            >>> 
+            >>> # Trim first 30 seconds in memory
+            >>> trimmed_data = ffmpeg.trims(video_data, start=0, duration=30)
+            >>> 
+            >>> # Save the trimmed video
+            >>> with open("intro.mp4", "wb") as f:
+            ...     f.write(trimmed_data)
+            >>> 
+            >>> # Trim with different format
+            >>> webm_data = ffmpeg.trims(video_data, start=10, duration=5, format_type="webm")
+            >>> with open("clip.webm", "wb") as f:
+            ...     f.write(webm_data)
+            >>> 
+            >>> # Trim with specific codec settings
+            >>> # For non-MP4 formats, FFMPEG will use default codecs
+            >>> avi_data = ffmpeg.trims(video_data, start=5, duration=10, format_type="avi")
+        """
+        args = [
+            "-y",
+            "-i", "pipe:0",
+            "-ss", str(start)
+        ]
+
+        if duration is not None:
+            args.extend(["-t", str(duration)])
+
+        if format_type == 'mp4':
+            args.extend([
+                "-c:v", "libx264",
+                "-pix_fmt", "yuv420p",
+                "-c:a", "aac",
+                "-movflags", "frag_keyframe+empty_moov"
+            ])
+
+        args.extend([
+            "-f", format_type,
+            "pipe:1"
+        ])
+
+        stdout, stderr = self.execute(*args, input_data=input_bytes)
+
+        return stdout
+
+    def extract_audio(self, input_file: str, output_file: str) -> None:
+        """
+        Extract audio from a video file.
+
+        Extracts the audio track from a video file without re-encoding,
+        preserving the original audio quality. The output file extension
+        should match the audio codec (e.g., .m4a for AAC, .mp3 for MP3,
+        .ogg for Vorbis).
+
+        Args:
+            input_file: Path to the input video file.
+            output_file: Path for the output audio file.
+
+        Raises:
+            FileNotFoundError: If input file doesn't exist.
+            RuntimeError: If audio extraction fails.
+
+        Example:
+            >>> # Extract audio from MP4 video
+            >>> ffmpeg.extract_audio("video.mp4", "audio.m4a")
+            >>> 
+            >>> # Extract audio and convert to MP3
+            >>> ffmpeg.execute("-i", "video.mp4", "-q:a", "0", "-map", "a", "audio.mp3")
+            >>> 
+            >>> # Extract audio from multiple formats
+            >>> ffmpeg.extract_audio("movie.mkv", "audio.m4a")
+            >>> ffmpeg.extract_audio("clip.avi", "audio.mp3")
+        """
+        input_path = Path(input_file)
+        output_path = Path(output_file)
+
+        if not input_path.exists():
+            raise FileNotFoundError(
+                f"Input file {input_file} was not found."
+            )
+
+        self.execute(
+            "-i", str(input_path),  # Specifies the input video file.
+            "-vn",  # Disables the video stream (drops the visual data).
+            "-c:a", "copy",  # Copies the audio track as-is without re-encoding.
+            str(output_path)  # Output file. Extension should match audio codec.
+        )
+
+    def extract_audios(self, input_bytes: bytes, output_format: str = "m4a") -> bytes:
+        """
+        Extract audio from video data (in-memory processing).
+
+        Extracts the audio track from in-memory video data without re-encoding,
+        preserving the original audio quality. This method is useful when you
+        have video data in memory and want to avoid writing temporary files.
+
+        Args:
+            input_bytes: Video data as bytes to extract audio from.
+            output_format: Audio output format (e.g., 'm4a', 'mp3', 'ogg', 'wav').
+                          Defaults to 'm4a'.
+
+        Returns:
+            bytes: The extracted audio data as bytes.
+
+        Raises:
+            RuntimeError: If audio extraction fails.
+
+        Example:
+            >>> # Read video data from a file
+            >>> with open("video.mp4", "rb") as f:
+            ...     video_data = f.read()
+            >>> 
+            >>> # Extract audio in memory
+            >>> audio_data = ffmpeg.extract_audios(video_data, output_format="m4a")
+            >>> 
+            >>> # Save the extracted audio
+            >>> with open("audio.m4a", "wb") as f:
+            ...     f.write(audio_data)
+            >>> 
+            >>> # Extract audio in different formats
+            >>> mp3_data = ffmpeg.extract_audios(video_data, output_format="mp3")
+            >>> ogg_data = ffmpeg.extract_audios(video_data, output_format="ogg")
+        """
+        args = [
+            "-i", "pipe:0",
+            "-vn",
+            "-c:a", "copy",
+            "-f", output_format,
+            "pipe:1"
+        ]
+
+        return self.execute(*args, input_data=input_bytes)[0]

ffmpeg_python_helper/pipe_helper.py

@@ -0,0 +1,114 @@
+from typing import Callable
+
+
+class Pipe:
+    """
+    A utility class for piping bytes through multiple processing functions.
+
+    This class provides a convenient way to chain multiple byte-processing
+    operations together, creating a pipeline that transforms data step by step.
+
+    Example:
+        >>> from ffmpeg_python_helper import FFMPEG, Pipe
+        >>> ffmpeg = FFMPEG()
+        >>> 
+        >>> # Define processing functions
+        >>> def trim_first_30s(data: bytes) -> bytes:
+        ...     return ffmpeg.trims(data, start=0, duration=30)
+        >>> 
+        >>> def convert_to_gif(data: bytes) -> bytes:
+        ...     return ffmpeg.gifs(data, fps=15, scale=480)
+        >>> 
+        >>> def extract_audio(data: bytes) -> bytes:
+        ...     return ffmpeg.extract_audios(data, output_format="m4a")
+        >>> 
+        >>> # Read video data
+        >>> with open("video.mp4", "rb") as f:
+        ...     video_data = f.read()
+        >>> 
+        >>> # Create a processing pipeline
+        >>> # Trim → Convert to GIF → Extract audio
+        >>> result = Pipe.pipe_bytes(
+        ...     video_data,
+        ...     trim_first_30s,
+        ...     convert_to_gif,
+        ...     extract_audio
+        ... )
+        >>> 
+        >>> # Save the final result (audio from trimmed GIF-converted video)
+        >>> with open("processed_audio.m4a", "wb") as f:
+        ...     f.write(result)
+    """
+
+    @staticmethod
+    def pipe_bytes(initial_value: bytes, *fn: Callable[[bytes], bytes]) -> bytes:
+        """
+        Pipe bytes through multiple processing functions.
+
+        This method takes an initial bytes value and passes it through
+        a series of functions, using the output of each function as the
+        input to the next function in the chain.
+
+        Args:
+            initial_value: The initial bytes to start the pipeline with.
+            *fn: One or more callable functions that take bytes as input
+                 and return bytes as output. Functions are applied in
+                 the order they are provided.
+
+        Returns:
+            bytes: The final result after passing through all functions.
+
+        Raises:
+            TypeError: If any function is not callable or doesn't accept bytes.
+            RuntimeError: If any function in the pipeline fails.
+
+        Example:
+            >>> # Simple pipeline: read, process, save
+            >>> def add_header(data: bytes) -> bytes:
+            ...     return b"HEADER" + data
+            >>> 
+            >>> def add_footer(data: bytes) -> bytes:
+            ...     return data + b"FOOTER"
+            >>> 
+            >>> def uppercase_data(data: bytes) -> bytes:
+            ...     return data.upper()
+            >>> 
+            >>> # Create pipeline
+            >>> result = Pipe.pipe_bytes(
+            ...     b"hello world",
+            ...     add_header,
+            ...     uppercase_data,
+            ...     add_footer
+            ... )
+            >>> 
+            >>> print(result)
+            b'HEADERHELLO WORLD FOOTER'
+
+            >>> # FFMPEG processing pipeline
+            >>> from ffmpeg_python_helper import FFMPEG
+            >>> ffmpeg = FFMPEG()
+            >>> 
+            >>> def trim_video(data: bytes) -> bytes:
+            ...     return ffmpeg.trims(data, start=10, duration=5)
+            >>> 
+            >>> def convert_to_webm(data: bytes) -> bytes:
+            ...     return ffmpeg.trims(data, format_type="webm")  # Re-encode as webm
+            >>> 
+            >>> # Process video through pipeline
+            >>> with open("input.mp4", "rb") as f:
+            ...     video_data = f.read()
+            >>> 
+            >>> processed_data = Pipe.pipe_bytes(
+            ...     video_data,
+            ...     trim_video,
+            ...     convert_to_webm
+            ... )
+            >>> 
+            >>> with open("output.webm", "wb") as f:
+            ...     f.write(processed_data)
+        """
+        current: bytes = initial_value
+        for callable in fn:
+            current = callable(current)
+
+        return current

ffmpeg_python_helper-3.0.0.dist-info/METADATA

@@ -0,0 +1,358 @@
+Metadata-Version: 2.3
+Name: ffmpeg-python-helper
+Version: 3.0.0
+Summary: A Python wrapper for FFMPEG that provides a simple, intuitive API for common video processing tasks including format conversion, GIF creation, and video trimming.
+Author: marjon
+Author-email: marjon <marjongodito@gmanmi.com>
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# FFMPEG Python Helper
+
+A Python wrapper for FFMPEG that provides a simple, intuitive API for common video processing tasks.
+
+## Features
+
+- 🔧 **Easy FFMPEG Integration** - Automatically detects FFMPEG installation
+- 🎥 **Video Processing** - Reformat videos between formats
+- 🎞️ **GIF Creation** - Convert videos to optimized GIFs with customizable settings
+- 🎵 **Audio Extraction** - Extract audio tracks from videos without re-encoding
+- 🧠 **In-Memory Processing** - Process video/audio data directly from bytes without temporary files
+- ✂️ **Video Trimming** - Trim videos with precise start time and duration control
+- 🐍 **Pythonic API** - Clean, object-oriented interface with proper error handling
+- 📁 **File Validation** - Automatic input file existence checking
+
+## Installation
+
+### Prerequisites
+- Python 3.14 or higher
+- FFMPEG installed and available in your system PATH
+
+### Install FFMPEG Python Helper
+
+```bash
+pip install ffmpeg-python-helper
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/yourusername/ffmpeg-python-helper.git
+cd ffmpeg-python-helper
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from ffmpeg_python_helper import FFMPEG
+
+# Initialize the FFMPEG wrapper
+ffmpeg = FFMPEG()
+
+# Check if FFMPEG is available
+print(f"FFMPEG executable found at: {ffmpeg.executable}")
+
+# Convert a video file
+output = ffmpeg.reformat("input.mp4", "output.avi")
+print(output.decode())
+
+# Create a GIF from video
+ffmpeg.gif("video.mp4", "animation.gif", fps=15, scale=480)
+
+# Trim a video
+ffmpeg.trim("video.mp4", "short_clip.mp4", start=10.5, duration=5.0)
+
+# Extract audio from video
+ffmpeg.extract_audio("video.mp4", "audio.m4a")
+
+# Create GIF from in-memory video data
+with open("video.mp4", "rb") as f:
+    video_data = f.read()
+gif_data = ffmpeg.gifs(video_data, fps=15, scale=480)
+with open("memory.gif", "wb") as f:
+    f.write(gif_data)
+
+# Trim video in memory
+trimmed_data = ffmpeg.trims(video_data, start=0, duration=30)
+with open("trimmed.mp4", "wb") as f:
+    f.write(trimmed_data)
+
+# Extract audio in memory
+audio_data = ffmpeg.extract_audios(video_data, output_format="m4a")
+with open("audio.m4a", "wb") as f:
+    f.write(audio_data)
+```
+
+## API Reference
+
+### `FFMPEG` Class
+
+The main class that wraps FFMPEG functionality.
+
+#### Constructor
+```python
+FFMPEG()
+```
+Creates a new FFMPEG instance. Automatically searches for FFMPEG in the system PATH.
+- **Raises**: `FileNotFoundError` if FFMPEG is not found in PATH
+
+#### Properties
+- `executable` (str): The path to the FFMPEG executable found in the system
+
+#### Class Methods
+```python
+@classmethod
+def api(cls) -> "FFMPEG"
+```
+Factory method that returns a new FFMPEG instance.
+- **Returns**: `FFMPEG` instance
+
+#### Instance Methods
+
+##### `execute(*args: str, input_data: bytes | None = None) -> tuple[bytes, bytes]`
+Execute raw FFMPEG commands with the given arguments.
+
+**Parameters:**
+- `*args` (str): FFMPEG command-line arguments
+- `input_data` (bytes | None, optional): Optional bytes to send to FFMPEG's stdin
+
+**Returns:**
+- `tuple[bytes, bytes]`: A tuple containing (stdout, stderr) as bytes
+
+**Raises:**
+- `FileNotFoundError`: If FFMPEG executable is not found
+- `RuntimeError`: If FFMPEG command returns a non-zero exit code
+
+**Example:**
+```python
+stdout, stderr = ffmpeg.execute("-version")
+print(stdout.decode())
+
+# Process data from memory
+video_data = b"...video bytes..."
+stdout, stderr = ffmpeg.execute("-i", "pipe:0", "-f", "null", "-", input_data=video_data)
+```
+
+##### `reformat(input_file: str, output_file: str) -> bytes`
+Convert a video file from one format to another.
+
+**Parameters:**
+- `input_file` (str): Path to the input video file
+- `output_file` (str): Path for the output video file
+
+**Returns:**
+- `bytes`: FFMPEG output (stdout or stderr) as bytes
+
+**Raises:**
+- `FileNotFoundError`: If input file doesn't exist
+
+**Example:**
+```python
+output = ffmpeg.reformat("input.mov", "output.mp4")
+print(output.decode())
+```
+
+##### `gif(input_file: str, output_file: str, fps: int = 10, scale: int = 320) -> bytes`
+Convert a video file to an optimized GIF.
+
+**Parameters:**
+- `input_file` (str): Path to the input video file
+- `output_file` (str): Path for the output GIF file
+- `fps` (int, optional): Frames per second for the GIF (default: 10)
+- `scale` (int, optional): Width of the GIF in pixels, height is auto-scaled (default: 320)
+
+**Returns:**
+- `bytes`: FFMPEG output (stdout or stderr) as bytes
+
+**Raises:**
+- `FileNotFoundError`: If input file doesn't exist
+- `RuntimeError`: If GIF file was not created successfully
+
+**Example:**
+```python
+output = ffmpeg.gif("video.mp4", "output.gif", fps=15, scale=640)
+print(output.decode())
+```
+
+##### `gifs(input_byte: bytes, fps: int = 10, scale: int = 320) -> bytes`
+Convert video data from bytes to an optimized GIF (in-memory processing).
+
+**Parameters:**
+- `input_byte` (bytes): Video data as bytes to convert to GIF
+- `fps` (int, optional): Frames per second for the GIF (default: 10)
+- `scale` (int, optional): Width of the GIF in pixels, height is auto-scaled (default: 320)
+
+**Returns:**
+- `bytes`: The generated GIF data as bytes
+
+**Raises:**
+- `RuntimeError`: If GIF conversion fails
+
+**Example:**
+```python
+# Read video data from a file
+with open("video.mp4", "rb") as f:
+    video_data = f.read()
+
+# Convert to GIF in memory
+gif_data = ffmpeg.gifs(video_data, fps=15, scale=480)
+
+# Save the GIF
+with open("output.gif", "wb") as f:
+    f.write(gif_data)
+```
+
+##### `trim(input_file: str, output_file: str, start: float = 0, duration: float | None = None) -> bytes`
+Trim a video file.
+
+**Parameters:**
+- `input_file` (str): Path to the input video file
+- `output_file` (str): Path for the output trimmed video
+- `start` (float, optional): Start time in seconds (default: 0)
+- `duration` (float | None, optional): Duration in seconds, or None for remaining video (default: None)
+
+**Returns:**
+- `bytes`: FFMPEG output (stdout or stderr) as bytes
+
+**Raises:**
+- `FileNotFoundError`: If input file doesn't exist
+- `ValueError`: If start is negative or duration is non-positive
+- `RuntimeError`: If trimmed video was not created successfully
+
+**Example:**
+```python
+# Trim from 5 seconds to 10 seconds (5-second clip)
+output = ffmpeg.trim("video.mp4", "clip.mp4", start=5, duration=5)
+print(output.decode())
+
+# Trim from 10 seconds to the end of video
+output = ffmpeg.trim("video.mp4", "ending.mp4", start=10)
+print(output.decode())
+```
+
+## Advanced Usage
+
+### Custom FFMPEG Commands
+For operations not covered by the built-in methods, use the `execute` method:
+
+```python
+# Extract audio from video
+ffmpeg.execute("-i", "video.mp4", "-q:a", "0", "-map", "a", "audio.mp3")
+
+# Add watermark to video
+ffmpeg.execute("-i", "video.mp4", "-i", "watermark.png", 
+               "-filter_complex", "overlay=10:10", "output.mp4")
+
+# Change video bitrate
+ffmpeg.execute("-i", "input.mp4", "-b:v", "1M", "output.mp4")
+```
+
+### Error Handling
+```python
+from ffmpeg_python_helper import FFMPEG
+import sys
+
+try:
+    ffmpeg = FFMPEG()
+    ffmpeg.gif("video.mp4", "output.gif")
+except FileNotFoundError as e:
+    print(f"FFMPEG not found: {e}", file=sys.stderr)
+    sys.exit(1)
+except RuntimeError as e:
+    print(f"Processing failed: {e}", file=sys.stderr)
+    sys.exit(1)
+```
+
+## Common Use Cases
+
+### Batch Processing
+```python
+import os
+from ffmpeg_python_helper import FFMPEG
+
+ffmpeg = FFMPEG()
+videos = ["video1.mp4", "video2.mp4", "video3.mp4"]
+
+for video in videos:
+    if os.path.exists(video):
+        base_name = os.path.splitext(video)[0]
+        ffmpeg.gif(video, f"{base_name}.gif", fps=12, scale=400)
+```
+
+### Video Compilation
+```python
+from ffmpeg_python_helper import FFMPEG
+
+ffmpeg = FFMPEG()
+
+# Trim interesting parts
+ffmpeg.trim("concert.mp4", "intro.mp4", start=0, duration=30)
+ffmpeg.trim("concert.mp4", "chorus.mp4", start=120, duration=45)
+ffmpeg.trim("concert.mp4", "finale.mp4", start=300, duration=60)
+
+# Later, use FFMPEG to concatenate trimmed parts
+ffmpeg.execute("-f", "concat", "-safe", "0", "-i", "parts.txt", "highlight_reel.mp4")
+```
+
+## Troubleshooting
+
+### FFMPEG Not Found
+If you get `FileNotFoundError` when creating an FFMPEG instance:
+
+1. **Install FFMPEG**:
+   - **Windows**: Download from [ffmpeg.org](https://ffmpeg.org/download.html)
+   - **macOS**: `brew install ffmpeg`
+   - **Linux**: `sudo apt install ffmpeg` (Ubuntu/Debian) or `sudo yum install ffmpeg` (Fedora/RHEL)
+
+2. **Add to PATH**:
+   - Ensure FFMPEG is in your system PATH
+   - Test with `ffmpeg -version` in your terminal
+
+### File Not Found Errors
+- Ensure input file paths are correct and files exist
+- Use absolute paths if working with files in different directories
+- Check file permissions
+
+### GIF Creation Issues
+- Lower FPS or scale if GIF file is too large
+- Ensure input video has sufficient quality
+- Check available disk space
+
+## Development
+
+### Running Tests
+```bash
+python -m pytest tests/
+```
+
+### Building Documentation
+```bash
+# Install documentation dependencies
+pip install pdoc3
+
+# Generate API documentation
+pdoc --html ffmpeg_python_helper --output-dir docs
+```
+
+### Contributing
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for your changes
+4. Ensure all tests pass
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/yourusername/ffmpeg-python-helper/issues)
+- **Documentation**: [ReadTheDocs](https://ffmpeg-python-helper.readthedocs.io)
+- **Email**: marjongodito@gmanmi.com
+
+## Acknowledgments
+
+- FFMPEG team for the amazing multimedia framework
+- Python community for excellent tooling and libraries

ffmpeg_python_helper-3.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+ffmpeg_python_helper/__init__.py,sha256=aPK2SEFdtbeRyoCz_FOn0ZF35cpPhHBSFUsqd2T7DVk,2200
+ffmpeg_python_helper/ffmpeg_api.py,sha256=UTDZ8JdizWjLdU0xfFhwiwDbUBiZ7H9a5vA7aydFoOs,18513
+ffmpeg_python_helper/pipe_helper.py,sha256=fmEQwKNWuRU78bdTuS2-UIYWF8YcXjdHuR--FR8EDNw,4202
+ffmpeg_python_helper-3.0.0.dist-info/WHEEL,sha256=y6e-a5KI2W-qDAJKfh9Xr81bin8NgUdfWgz3VSXXpe4,80
+ffmpeg_python_helper-3.0.0.dist-info/entry_points.txt,sha256=M9t-tNA-GePbZIBMosX7vgLqg88pjImAYzSQ_fErZzA,68
+ffmpeg_python_helper-3.0.0.dist-info/METADATA,sha256=2JO6yyaV-D2d152tFRE5IHd2hdR7gu2BmeELUy3e93s,10007
+ffmpeg_python_helper-3.0.0.dist-info/RECORD,,

ffmpeg_python_helper/_bundled/ffmpeg.exe

@@ -1,4 +0,0 @@
-[diffend] Oversized file quarantined before diffing.
-name: ffmpeg_python_helper/_bundled/ffmpeg.exe
-size: 105674240 bytes
-sha256: f1dd57a9afb2893250fe3ea227899eb4779cbe8c2a2d0915761f2318a09140ca

ffmpeg_python_helper-0.1.0.dist-info/METADATA

@@ -1,9 +0,0 @@
-Metadata-Version: 2.3
-Name: ffmpeg-python-helper
-Version: 0.1.0
-Summary: Add your description here
-Author: marjon
-Author-email: marjon <marjongodito@gmanmi.com>
-Requires-Python: >=3.14
-Description-Content-Type: text/markdown
-

ffmpeg_python_helper-0.1.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-ffmpeg_python_helper/__init__.py,sha256=_8jV2YNFzNWRGPEeiXCPrNqgW6w1sdJ9XWoPjK5h33Q,123
-ffmpeg_python_helper/_bundled/ffmpeg.exe,sha256=8d1Xqa-yiTJQ_j6iJ4metHecvowqLQkVdh8jGKCRQMo,105674240
-ffmpeg_python_helper/ffmpeg_api.py,sha256=BbOzeaAepWrGvi--YmFJkQedsSMJ-NT4XRYRp2JRMxY,3317
-ffmpeg_python_helper-0.1.0.dist-info/WHEEL,sha256=y6e-a5KI2W-qDAJKfh9Xr81bin8NgUdfWgz3VSXXpe4,80
-ffmpeg_python_helper-0.1.0.dist-info/entry_points.txt,sha256=M9t-tNA-GePbZIBMosX7vgLqg88pjImAYzSQ_fErZzA,68
-ffmpeg_python_helper-0.1.0.dist-info/METADATA,sha256=A9Yu67-lbGGrN8Fj8O8nKv5O2ODInjKhETTvbU7P_bw,226
-ffmpeg_python_helper-0.1.0.dist-info/RECORD,,