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

ffmpeg_python_helper/__init__.py

@@ -37,10 +37,12 @@ For detailed API documentation, see:
 
 from .ffmpeg_api import FFMPEG
 from .pipe_helper import Pipe
+from .ffprobe_api import FFProbe
 
 __all__ = [
     'FFMPEG',
-    'Pipe'
+    'Pipe',
+    'FFProbe'
 ]
 
 __version__ = "0.1.0"

ffmpeg_python_helper/ffmpeg_api.py

@@ -366,7 +366,10 @@ in your system PATH.
     def trims(self, input_bytes: bytes,
             start: float = 0,
             duration: float | None = None,
-            format_type: str = "mp4") -> bytes:
+            format_type: str = "mp4",
+            v_encoder : str = "libx264",
+            a_encoder : str = "aac"
+            ) -> bytes:
         """
         Trim video data from bytes (in-memory processing).
 
@@ -422,9 +425,9 @@ in your system PATH.
 
         if format_type == 'mp4':
             args.extend([
-                "-c:v", "libx264",
+                "-c:v", v_encoder,
                 "-pix_fmt", "yuv420p",
-                "-c:a", "aac",
+                "-c:a", a_encoder,
                 "-movflags", "frag_keyframe+empty_moov"
             ])
 
@@ -523,4 +526,58 @@ in your system PATH.
             "pipe:1"
         ]
 
-        return self.execute(*args, input_data=input_bytes)[0]
+        return self.execute(*args, input_data=input_bytes)[0]
+
+    def compress_file(self, 
+                input_file : str, 
+                output_file : str, 
+                crf: int = 28,
+                v_encoder : str = "libx264",
+                a_encoder : str = "aac" ,
+                px_format : str = "yuv420p"):
+
+            args = [
+                "-i", input_file,
+                "-c:v", v_encoder,
+                "-crf", str(crf),
+                "-pix_fmt", px_format,
+                "-c:a", a_encoder,
+                "-movflags", "faststart",
+                output_file,
+            ]
+
+            self.execute(*args)
+
+    def compress_byte(self, 
+            input_data : bytes,
+            crf: int = 28,
+            v_encoder : str = "libx264",
+            a_encoder : str = "aac" ,
+            px_format : str = "yuv420p"
+            ):
+        args = [
+            "-i", "pipe:0",
+            "-c:v", v_encoder,
+            "-crf", str(crf),
+            "-pix_fmt", px_format,
+            "-c:a", a_encoder,
+            "-movflags", "frag_keyframe+empty_moov",
+            "-f", "mp4",
+            "pipe:1"
+        ]
+
+        return self.execute(*args, input_data=input_data)[0]
+
+    def verify(self, input_file : str) -> tuple[bool, str]:
+        args = [
+            "-v", "error",
+            "-i", input_file,
+            "-f",  "null",
+            "-"
+        ]
+
+        try: 
+            self.execute(*args)
+            return True, ""
+        except RuntimeError as e:
+            return False, str(e)

ffmpeg_python_helper/ffprobe_api.py

@@ -0,0 +1,169 @@
+import subprocess
+from pathlib import Path
+
+
+class FFProbe:
+    """
+    A Python wrapper for FFProbe (FFMPEG's multimedia stream analyzer) that provides
+    video metadata analysis capabilities.
+
+    This class automatically detects FFProbe installation in the system PATH
+    and provides methods for extracting video metadata, analyzing video properties,
+    and checking video characteristics.
+
+    Example:
+        >>> from ffmpeg_python_helper import FFProbe
+        >>> ffprobe = FFProbe()
+        >>> # Check if video is short enough for social media
+        >>> if ffprobe.is_max_length("video.mp4", max_length=5.0):
+        ...     print("Video is perfect for Instagram Reels!")
+        >>> # Get video metadata
+        >>> import json
+        >>> stdout, stderr = ffprobe.execute("-v", "quiet", "-print_format", "json", 
+        ...                                  "-show_format", "-show_streams", "video.mp4")
+        >>> metadata = json.loads(stdout.decode())
+        >>> print(f"Video duration: {metadata['format']['duration']} seconds")
+        >>> print(f"Video dimensions: {metadata['streams'][0]['width']}x{metadata['streams'][0]['height']}")
+
+    Attributes:
+        executable (str): The path to the FFProbe executable found in the system PATH.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initialize a new FFProbe instance.
+
+        Automatically searches for FFProbe in the system PATH.
+
+        Raises:
+            FileNotFoundError: If FFProbe is not found in the system PATH.
+
+        Example:
+            >>> try:
+            ...     ffprobe = FFProbe()
+            ...     print(f"FFProbe found at: {ffprobe.executable}")
+            ... except FileNotFoundError as e:
+            ...     print(f"FFProbe not found: {e}")
+        """
+        import shutil
+        self.executable = shutil.which('ffprobe')
+
+        if self.executable is None:
+            raise FileNotFoundError("""
+FFProbe is not installed or could not be found in PATH.
+Please install FFmpeg and make sure it is available
+in your system PATH.
+""")
+
+    @classmethod
+    def api(cls) -> "FFProbe":
+        """
+        Factory method that returns a new FFProbe instance.
+
+        Returns:
+            FFProbe: A new instance of the FFProbe class.
+
+        Example:
+            >>> ffprobe = FFProbe.api()
+            >>> ffprobe.execute("-version")
+        """
+        return cls()
+
+    def execute(self, *args: str, input_data: bytes | None = None) -> tuple[bytes, bytes]:
+        """
+        Execute raw FFProbe commands with the given arguments.
+
+        This method allows you to run any FFProbe command directly,
+        providing maximum flexibility for metadata analysis operations
+        not covered by the built-in methods.
+
+        Args:
+            *args: FFProbe command-line arguments as strings.
+            input_data: Optional bytes to send to FFProbe's stdin. Useful for
+                       analyzing data directly without intermediate files.
+
+        Returns:
+            tuple[bytes, bytes]: A tuple containing (stdout, stderr) from FFProbe
+                                 as bytes objects.
+
+        Raises:
+            FileNotFoundError: If FFProbe executable is not found.
+            RuntimeError: If FFProbe command returns a non-zero exit code.
+
+        Example:
+            >>> stdout, stderr = ffprobe.execute("-version")
+            >>> print(stdout.decode())
+
+            >>> # Get video metadata in JSON format
+            >>> stdout, stderr = ffprobe.execute("-v", "quiet", "-print_format", "json",
+            ...                                  "-show_format", "-show_streams", "video.mp4")
+            >>> import json
+            >>> metadata = json.loads(stdout.decode())
+            >>> print(f"Video duration: {metadata['format']['duration']} seconds")
+
+            >>> # Get video dimensions
+            >>> stdout, stderr = ffprobe.execute("-v", "error", "-select_streams", "v:0",
+            ...                                  "-show_entries", "stream=width,height",
+            ...                                  "-of", "csv=p=0", "video.mp4")
+            >>> print(f"Video dimensions: {stdout.decode().strip()}")
+        """
+        if self.executable:
+            result = subprocess.run(
+                [self.executable, *args], 
+                input=input_data,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                check=False,
+                text=True
+                )
+
+            if result.returncode != 0:
+                raise RuntimeError(
+                    result.stderr.decode(errors="replace")
+                )
+            
+            return result.stdout, result.stderr
+
+        raise FileNotFoundError("""
+        No ffprobe executable found.
+
+        Please Install FFmpeg (which includes ffprobe) first.
+        """)
+
+    def is_max_length(self, input_file : str, max_length : float = 5.0) -> bool:
+        """
+        Check if a video file's duration is less than or equal to a specified maximum length.
+
+        Args:
+            input_file: Path to the input video file
+            max_length: Maximum allowed duration in seconds (default: 5.0)
+
+        Returns:
+            bool: True if video duration ≤ max_length, False otherwise
+
+        Raises:
+            FileNotFoundError: If input file doesn't exist
+            RuntimeError: If FFProbe command fails
+
+        Example:
+            >>> if ffprobe.is_max_length("video.mp4", max_length=10.0):
+            ...     print("Video is short enough for social media upload")
+            ... else:
+            ...     print("Video is too long, needs trimming")
+        """
+        args = [
+            "-v", "error",
+            "-select_streams", "v:0",
+            "-show_entries", "stream=duration",
+            "-of", "default=noprint_wrappers=1:nokey=1",
+            input_file,
+        ]
+
+        stdout, stderr = self.execute(*args)
+
+        duration = float(stdout.strip())
+
+        return duration <= max_length
+
+
+    

{ffmpeg_python_helper-3.0.0.dist-info → ffmpeg_python_helper-3.2.0.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.3
 Name: ffmpeg-python-helper
-Version: 3.0.0
+Version: 3.2.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>
+Author-email: marjon <petmalu.marjon@gmail.com>
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
 
@@ -19,6 +19,7 @@ A Python wrapper for FFMPEG that provides a simple, intuitive API for common vid
 - 🎵 **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
+- 🔍 **Video Metadata Analysis** - Extract video information and metadata using FFProbe
 - 🐍 **Pythonic API** - Clean, object-oriented interface with proper error handling
 - 📁 **File Validation** - Automatic input file existence checking
 
@@ -82,6 +83,26 @@ with open("trimmed.mp4", "wb") as f:
 audio_data = ffmpeg.extract_audios(video_data, output_format="m4a")
 with open("audio.m4a", "wb") as f:
     f.write(audio_data)
+
+# Analyze video metadata with FFProbe
+from ffmpeg_python_helper import FFProbe
+import json
+
+ffprobe = FFProbe()
+print(f"FFProbe executable found at: {ffprobe.executable}")
+
+# Check if video is short enough for social media
+if ffprobe.is_max_length("video.mp4", max_length=5.0):
+    print("Video is perfect for Instagram Reels!")
+else:
+    print("Video needs trimming for short-form content")
+
+# Get detailed video metadata
+stdout, stderr = ffprobe.execute("-v", "quiet", "-print_format", "json", 
+                                 "-show_format", "-show_streams", "video.mp4")
+metadata = json.loads(stdout.decode())
+print(f"Video duration: {metadata['format']['duration']} seconds")
+print(f"Video dimensions: {metadata['streams'][0]['width']}x{metadata['streams'][0]['height']}")
 ```
 
 ## API Reference
@@ -231,6 +252,100 @@ output = ffmpeg.trim("video.mp4", "ending.mp4", start=10)
 print(output.decode())
 ```
 
+### `FFProbe` Class
+
+A Python wrapper for FFProbe (the FFMPEG multimedia stream analyzer) that provides video metadata analysis capabilities.
+
+#### Constructor
+```python
+FFProbe()
+```
+Creates a new FFProbe instance. Automatically searches for FFProbe in the system PATH.
+- **Raises**: `FileNotFoundError` if FFProbe is not found in PATH
+
+#### Properties
+- `executable` (str): The path to the FFProbe executable found in the system
+
+#### Class Methods
+```python
+@classmethod
+def api(cls) -> "FFProbe"
+```
+Factory method that returns a new FFProbe instance.
+- **Returns**: `FFProbe` instance
+
+**Example:**
+```python
+ffprobe = FFProbe.api()
+print(f"FFProbe executable found at: {ffprobe.executable}")
+```
+
+#### Instance Methods
+
+##### `execute(*args: str, input_data: bytes | None = None) -> tuple[bytes, bytes]`
+Execute raw FFProbe commands with the given arguments.
+
+**Parameters:**
+- `*args` (str): FFProbe command-line arguments as strings
+- `input_data` (bytes | None, optional): Optional bytes to send to FFProbe's stdin
+
+**Returns:**
+- `tuple[bytes, bytes]`: A tuple containing (stdout, stderr) as bytes
+
+**Raises:**
+- `FileNotFoundError`: If FFProbe executable is not found
+- `RuntimeError`: If FFProbe command returns a non-zero exit code
+
+**Example:**
+```python
+# Get FFProbe version
+stdout, stderr = ffprobe.execute("-version")
+print(stdout.decode())
+
+# Get video metadata in JSON format
+stdout, stderr = ffprobe.execute("-v", "quiet", "-print_format", "json", 
+                                 "-show_format", "-show_streams", "video.mp4")
+metadata = json.loads(stdout.decode())
+print(f"Video duration: {metadata['format']['duration']} seconds")
+
+# Get video dimensions
+stdout, stderr = ffprobe.execute("-v", "error", "-select_streams", "v:0",
+                                 "-show_entries", "stream=width,height", 
+                                 "-of", "csv=p=0", "video.mp4")
+print(f"Video dimensions: {stdout.decode().strip()}")
+```
+
+##### `is_max_length(input_file: str, max_length: float = 5.0) -> bool`
+Check if a video file's duration is less than or equal to a specified maximum length.
+
+**Parameters:**
+- `input_file` (str): Path to the input video file
+- `max_length` (float, optional): Maximum allowed duration in seconds (default: 5.0)
+
+**Returns:**
+- `bool`: `True` if video duration ≤ max_length, `False` otherwise
+
+**Raises:**
+- `FileNotFoundError`: If input file doesn't exist
+- `RuntimeError`: If FFProbe command fails
+
+**Example:**
+```python
+# Check if video is shorter than 10 seconds
+if ffprobe.is_max_length("video.mp4", max_length=10.0):
+    print("Video is short enough for social media upload")
+else:
+    print("Video is too long, needs trimming")
+
+# Check multiple videos for length compliance
+videos = ["clip1.mp4", "clip2.mp4", "clip3.mp4"]
+for video in videos:
+    if ffprobe.is_max_length(video, max_length=5.0):
+        print(f"{video}: OK (≤ 5 seconds)")
+    else:
+        print(f"{video}: Too long (> 5 seconds)")
+```
+
 ## Advanced Usage
 
 ### Custom FFMPEG Commands
@@ -248,6 +363,52 @@ ffmpeg.execute("-i", "video.mp4", "-i", "watermark.png",
 ffmpeg.execute("-i", "input.mp4", "-b:v", "1M", "output.mp4")
 ```
 
+### Advanced FFProbe Usage
+FFProbe provides powerful video metadata analysis capabilities:
+
+```python
+from ffmpeg_python_helper import FFProbe
+import json
+
+ffprobe = FFProbe()
+
+# Get multiple video metadata properties at once
+stdout, stderr = ffprobe.execute(
+    "-v", "error",
+    "-select_streams", "v:0",
+    "-show_entries", "stream=width,height,duration,bit_rate,codec_name",
+    "-of", "json",
+    "video.mp4"
+)
+video_info = json.loads(stdout.decode())
+print(f"Video codec: {video_info['streams'][0]['codec_name']}")
+print(f"Video bitrate: {video_info['streams'][0]['bit_rate']} bps")
+
+# Check frame rate
+stdout, stderr = ffprobe.execute(
+    "-v", "error",
+    "-select_streams", "v:0",
+    "-show_entries", "stream=r_frame_rate",
+    "-of", "default=noprint_wrappers=1:nokey=1",
+    "video.mp4"
+)
+print(f"Frame rate: {stdout.decode().strip()}")
+
+# Get audio stream information
+stdout, stderr = ffprobe.execute(
+    "-v", "error",
+    "-select_streams", "a:0",
+    "-show_entries", "stream=codec_name,channels,sample_rate",
+    "-of", "json",
+    "video.mp4"
+)
+audio_info = json.loads(stdout.decode())
+if audio_info['streams']:
+    print(f"Audio codec: {audio_info['streams'][0]['codec_name']}")
+    print(f"Audio channels: {audio_info['streams'][0]['channels']}")
+    print(f"Sample rate: {audio_info['streams'][0]['sample_rate']} Hz")
+```
+
 ### Error Handling
 ```python
 from ffmpeg_python_helper import FFMPEG

ffmpeg_python_helper-3.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+ffmpeg_python_helper/__init__.py,sha256=CUCXwvcuMPz1WzZRSTyKJeEXkSq8YXN7rvOc8jWTWrk,2248
+ffmpeg_python_helper/ffmpeg_api.py,sha256=y4oRbF3piYWD1dgGdni5o27jyBgrGMdFuD4g8VPkJJw,20143
+ffmpeg_python_helper/ffprobe_api.py,sha256=cv3pC7ongB5eMCaYsdKB2mtxklfV3QrxuWUZEoG2kB4,6178
+ffmpeg_python_helper/pipe_helper.py,sha256=fmEQwKNWuRU78bdTuS2-UIYWF8YcXjdHuR--FR8EDNw,4202
+ffmpeg_python_helper-3.2.0.dist-info/WHEEL,sha256=y6e-a5KI2W-qDAJKfh9Xr81bin8NgUdfWgz3VSXXpe4,80
+ffmpeg_python_helper-3.2.0.dist-info/entry_points.txt,sha256=M9t-tNA-GePbZIBMosX7vgLqg88pjImAYzSQ_fErZzA,68
+ffmpeg_python_helper-3.2.0.dist-info/METADATA,sha256=U8BlSYF_8cfuhirdr-C70GuQkJKhgKOWKOuCQpqvgRQ,15196
+ffmpeg_python_helper-3.2.0.dist-info/RECORD,,

ffmpeg_python_helper-3.0.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-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,,