ffmpeg-python-helper 2.0.0__tar.gz → 3.0.0__tar.gz

{ffmpeg_python_helper-2.0.0 → ffmpeg_python_helper-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ffmpeg-python-helper
-Version: 2.0.0
+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>
@@ -16,7 +16,8 @@ A Python wrapper for FFMPEG that provides a simple, intuitive API for common vid
 - 🔧 **Easy FFMPEG Integration** - Automatically detects FFMPEG installation
 - 🎥 **Video Processing** - Reformat videos between formats
 - 🎞️ **GIF Creation** - Convert videos to optimized GIFs with customizable settings
-- 🧠 **In-Memory Processing** - Process video data directly from bytes without temporary files
+- 🎵 **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
@@ -57,12 +58,13 @@ output = ffmpeg.reformat("input.mp4", "output.avi")
 print(output.decode())
 
 # Create a GIF from video
-output = ffmpeg.gif("video.mp4", "animation.gif", fps=15, scale=480)
-print(output.decode())
+ffmpeg.gif("video.mp4", "animation.gif", fps=15, scale=480)
 
 # Trim a video
-output = ffmpeg.trim("video.mp4", "short_clip.mp4", start=10.5, duration=5.0)
-print(output.decode())
+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:
@@ -70,6 +72,16 @@ with open("video.mp4", "rb") as f:
 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_python_helper-2.0.0 → ffmpeg_python_helper-3.0.0}/README.md

@@ -7,7 +7,8 @@ A Python wrapper for FFMPEG that provides a simple, intuitive API for common vid
 - 🔧 **Easy FFMPEG Integration** - Automatically detects FFMPEG installation
 - 🎥 **Video Processing** - Reformat videos between formats
 - 🎞️ **GIF Creation** - Convert videos to optimized GIFs with customizable settings
-- 🧠 **In-Memory Processing** - Process video data directly from bytes without temporary files
+- 🎵 **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
@@ -48,12 +49,13 @@ output = ffmpeg.reformat("input.mp4", "output.avi")
 print(output.decode())
 
 # Create a GIF from video
-output = ffmpeg.gif("video.mp4", "animation.gif", fps=15, scale=480)
-print(output.decode())
+ffmpeg.gif("video.mp4", "animation.gif", fps=15, scale=480)
 
 # Trim a video
-output = ffmpeg.trim("video.mp4", "short_clip.mp4", start=10.5, duration=5.0)
-print(output.decode())
+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:
@@ -61,6 +63,16 @@ with open("video.mp4", "rb") as f:
 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_python_helper-2.0.0 → ffmpeg_python_helper-3.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ffmpeg-python-helper"
-version = "2.0.0"
+version = "3.0.0"
 description = "A Python wrapper for FFMPEG that provides a simple, intuitive API for common video processing tasks including format conversion, GIF creation, and video trimming."
 readme = "README.md"
 requires-python = ">=3.14"

{ffmpeg_python_helper-2.0.0 → ffmpeg_python_helper-3.0.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ffmpeg-python-helper"
-version = "2.0.0"
+version = "3.0.0"
 description = "A Python wrapper for FFMPEG that provides a simple, intuitive API for common video processing tasks including format conversion, GIF creation, and video trimming."
 readme = "README.md"
 authors = [

{ffmpeg_python_helper-2.0.0 → ffmpeg_python_helper-3.0.0}/src/ffmpeg_python_helper/__init__.py

@@ -2,29 +2,45 @@
 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, and in-memory processing.
+including format conversion, GIF creation, video trimming, audio extraction,
+in-memory processing, and data pipeline utilities.
 
 Example:
-    >>> from ffmpeg_python_helper import FFMPEG
+    >>> 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'
 ]
 
 __version__ = "0.1.0"

{ffmpeg_python_helper-2.0.0 → ffmpeg_python_helper-3.0.0}/src/ffmpeg_python_helper/ffmpeg_api.py

@@ -8,8 +8,9 @@ class FFMPEG:
     common video processing tasks.
 
     This class automatically detects FFMPEG installation in the system PATH
-    and provides methods for video conversion, GIF creation, and video trimming.
-    It supports both file-based operations and in-memory data processing.
+    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
@@ -17,11 +18,14 @@ class 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.
@@ -165,7 +169,7 @@ in your system PATH.
             return stderr
 
     def gifs(self,
-            input_byte: bytes,
+            input_bytes: bytes,
             fps: int = 10,
             scale: int = 320) -> bytes:
         """
@@ -217,7 +221,7 @@ in your system PATH.
             "-vf", filter_graph,
             "-f", "gif",
             "pipe:1",
-            input_data=input_byte
+            input_data=input_bytes
         )
 
         return stdout
@@ -227,7 +231,7 @@ in your system PATH.
             output_file: str,
             fps: int = 10,
             scale: int = 320
-            ) -> bytes:
+            ) -> None:
         """
         Convert a video file to an optimized GIF.
 
@@ -241,27 +245,21 @@ in your system PATH.
             scale: Width of the GIF in pixels. Height is auto-scaled
                    to maintain aspect ratio. Defaults to 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:
             >>> # Create a standard GIF
-            >>> output = ffmpeg.gif("video.mp4", "output.gif")
-            >>> print(output.decode())
+            >>> ffmpeg.gif("video.mp4", "output.gif")
 
             >>> # Create a higher quality GIF with custom settings
-            >>> output = ffmpeg.gif("video.mp4", "output.gif",
-            ...                     fps=15, scale=640)
-            >>> print(output.decode())
+            >>> ffmpeg.gif("video.mp4", "output.gif",
+            ...            fps=15, scale=640)
 
             >>> # Create a small thumbnail GIF
-            >>> output = ffmpeg.gif("video.mp4", "thumbnail.gif",
-            ...                     fps=5, scale=160)
-            >>> print(output.decode())
+            >>> ffmpeg.gif("video.mp4", "thumbnail.gif",
+            ...            fps=5, scale=160)
         """
         input_path = Path(input_file)
         output_path = Path(output_file)
@@ -279,7 +277,7 @@ in your system PATH.
             "[s1][p]paletteuse"
         )
 
-        stdout, stderr = self.execute(
+        self.execute(
             "-y",
             "-i", str(input_path),
             "-vf", filter_graph,
@@ -291,18 +289,13 @@ in your system PATH.
                 f"GIF was not created: {output_file}"
             )
 
-        if stderr:
-            return stderr
-
-        return stdout
-
     def trim(
         self,
         input_file: str,
         output_file: str,
         start: float = 0,
         duration: float | None = None,
-    ) -> bytes:
+    ) -> None:
         """
         Trim a video file.
 
@@ -316,9 +309,6 @@ in your system PATH.
             duration: Duration in seconds, or None for remaining video.
                       Defaults to 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.
@@ -326,24 +316,20 @@ in your system PATH.
 
         Example:
             >>> # Trim from 5 seconds to 10 seconds (5-second clip)
-            >>> output = ffmpeg.trim("video.mp4", "clip.mp4",
-            ...                      start=5, duration=5)
-            >>> print(output.decode())
+            >>> ffmpeg.trim("video.mp4", "clip.mp4",
+            ...             start=5, duration=5)
 
             >>> # Trim from 10 seconds to the end of video
-            >>> output = ffmpeg.trim("video.mp4", "ending.mp4",
-            ...                      start=10)
-            >>> print(output.decode())
+            >>> ffmpeg.trim("video.mp4", "ending.mp4",
+            ...             start=10)
 
             >>> # Trim first 30 seconds of video
-            >>> output = ffmpeg.trim("video.mp4", "intro.mp4",
-            ...                      start=0, duration=30)
-            >>> print(output.decode())
+            >>> ffmpeg.trim("video.mp4", "intro.mp4",
+            ...             start=0, duration=30)
 
             >>> # Trim with floating point precision
-            >>> output = ffmpeg.trim("video.mp4", "precise.mp4",
-            ...                      start=2.5, duration=3.75)
-            >>> print(output.decode())
+            >>> ffmpeg.trim("video.mp4", "precise.mp4",
+            ...             start=2.5, duration=3.75)
         """
         input_path = Path(input_file)
         output_path = Path(output_file)
@@ -377,4 +363,164 @@ in your system PATH.
                 f"Trimmed video was not created: {output_file}"
             )
 
-        return stdout if stdout else 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-3.0.0/src/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