prpy 0.2.2__py3-none-any.whl

prpy/__init__.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2024 Philipp Rouast
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.

prpy/constants.py

@@ -0,0 +1,24 @@
+# Copyright (c) 2024 Philipp Rouast
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+NANOS_PER_SECOND = 1000000000.0
+MICROS_PER_SECOND = 1000000.0
+MILLIS_PER_SECOND = 1000.0
+SECONDS_PER_MINUTE = 60.0

prpy/ffmpeg/__init__.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2024 Philipp Rouast
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.

prpy/ffmpeg/probe.py

@@ -0,0 +1,86 @@
+# Copyright (c) 2024 Philipp Rouast
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import ffmpeg
+from fractions import Fraction
+import logging
+from typing import Tuple
+import os
+
+def probe_video(
+    path: str
+  ) -> Tuple[float, int, int, int, str, float, int]:
+  """Probe a video file for metadata.
+
+  Args:
+    path: The path of the video.
+  Returns:
+    fps: The frame rate of the video
+    total_frames: The total number of frames
+    width: The width dimension of the video
+    height: The height dimension of the video
+    codec: The codec of the video
+    bitrate: The bitrate of the video
+    rotation: The rotation of the video
+  """
+  # Check if file exists
+  assert isinstance(path, str)
+  if not os.path.exists(path):
+    raise FileNotFoundError("File {} does not exist".format(path))
+  # ffprobe -show_streams -count_frames -pretty video.mp4
+  try:
+    probe = ffmpeg.probe(filename=path)
+  except Exception as e:
+    # The exception returned by `ffprobe` is in bytes
+    logging.warn("Exception probing video: {}".format(e))
+  else:
+    video_stream = next(
+      (
+        stream
+        for stream in probe["streams"]
+        if stream["codec_type"] == "video"
+      ),
+      None,
+    )
+    try:
+      fps = float(Fraction(video_stream["avg_frame_rate"]))
+    except Exception as e:
+      fps = 0
+    try:
+      total_frames = int(video_stream["nb_frames"])
+    except Exception as e:
+      duration = float(video_stream['duration'])
+      total_frames = int(duration*fps)
+    width = video_stream["width"]
+    height = video_stream["height"]
+    codec = video_stream["codec_name"]
+    try:
+      bitrate = float(video_stream["bit_rate"])/1000.0
+    except Exception as e:
+      bitrate = 0.0
+    rotation = 0
+    if 'tags' in video_stream and 'rotate' in video_stream['tags']:
+      # Regular
+      rotation = int(video_stream['tags']['rotate'])
+    elif 'side_data_list' in video_stream and 'rotation' in video_stream['side_data_list'][0]:
+      # iPhone
+      rotation = int(video_stream['side_data_list'][0]['rotation'])
+    return fps, total_frames, width, height, codec, bitrate, rotation
+  

prpy/ffmpeg/readwrite.py

@@ -0,0 +1,412 @@
+# Copyright (c) 2024 Philipp Rouast
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import ffmpeg
+import logging
+import numpy as np
+import os
+from typing import Tuple, Union
+
+from prpy.ffmpeg.probe import probe_video
+from prpy.ffmpeg.utils import find_factors_near
+
+def _ffmpeg_input_from_path(
+    path: str,
+    fps: Union[float, int],
+    trim: tuple
+  ) -> ffmpeg.nodes.FilterableStream:
+  """Use file as input part of ffmpeg command.
+  
+  Args:
+    path: The path from which video will be read.
+    fps: The framerate of the input video.
+    trim: Frame numbers for temporal trimming (start, end).
+  Returns:
+    stream: ffmpeg input stream from file
+  """
+  assert isinstance(path, str)
+  assert isinstance(fps, (float, int))
+  assert trim is None or (isinstance(trim, tuple) and all(isinstance(i, int) for i in trim))
+  trim_start = 0 if trim is None else trim[0]
+  # Create the stream
+  stream = ffmpeg.input(filename=path, ss=trim_start/fps)
+  # Return
+  return stream
+
+def _ffmpeg_input_from_pipe() -> ffmpeg.nodes.FilterableStream:
+  """Use pipe as input part of ffmpeg command.
+  
+  Returns:
+    stream: ffmpeg input stream from pipe
+  """
+  stream = ffmpeg.input("pipe:")
+  return stream
+
+def _ffmpeg_input_from_numpy(
+    w: int,
+    h: int,
+    fps: Union[float, int],
+    pix_fmt: str
+  ) -> ffmpeg.nodes.FilterableStream:
+  """Use file as input part of ffmpeg command.
+  
+  Args:
+    w: The width dimension of the video data from numpy.
+    h: The height dimension of the video data from numpy.
+    fps: The framerate of the video data from numpy.
+    pix_fmt: The pixel format of the video data from numpy (e.g., `bgr24`).
+  Returns:
+    stream: ffmpeg input stream from pipe (numpy)
+  """
+  assert isinstance(w, int)
+  assert isinstance(h, int)
+  assert isinstance(fps, (float, int))
+  assert isinstance(pix_fmt, str)
+  stream = ffmpeg.input('pipe:', format='rawvideo', pix_fmt=pix_fmt, s='{}x{}'.format(w, h), r=fps)
+  return stream
+
+def _ffmpeg_filtering(
+    stream: ffmpeg.nodes.FilterableStream,
+    fps: Union[float, int],
+    n: int,
+    w: int,
+    h: int,
+    target_fps: Union[float, int, None] = None,
+    crop: Union[tuple, None] = None,
+    scale: Union[Tuple[int, tuple], None] = None,
+    trim: Union[tuple, None] = None,
+    preserve_aspect_ratio: bool = False,
+    scale_algorithm: str = 'bicubic'
+  ) -> Tuple[ffmpeg.nodes.FilterableStream, int, int, int, int]:
+  """Take an ffmpeg stream and optionally add filtering operations.
+  Downsampling, spatial cropping, spatial scaling (applied to result of
+    cropping if specified) and temporal trimming.
+
+  Args:
+    stream: The ffmpeg stream
+    fps: The existing frame rate
+    n: The existing number of frames
+    w: The existing width
+    h: The existing height
+    target_fps: Try to downsample frames to achieve this framerate (optional)
+    crop: Coords and sizes for spatial cropping (x, y, width, height) (optional)
+    scale: Size(s) for spatial scaling. Scalar or (width, height) (optional)
+    trim: Frame numbers for temporal trimming (start, end) (optional)
+    preserve_aspect_ratio: Preserve the aspect ratio if scaling
+    scale_algorithm: The algorithm used for scaling.
+      Supported: bicubic, bilinear, area, lanczos. Default: bicubic
+  Returns:
+    stream: The modified ffmpeg stream
+    target_n: The target number of frames
+    target_w: The target width
+    target_h: The target shape
+    ds_factor: The applied downsampling factor
+  """
+  assert isinstance(stream, ffmpeg.nodes.FilterableStream)
+  assert isinstance(fps, (float, int))
+  assert isinstance(n, int)
+  assert isinstance(w, int)
+  assert isinstance(h, int)
+  assert target_fps is None or isinstance(target_fps, (float, int))
+  assert crop is None or (isinstance(crop, tuple) and len(crop) == 4 and all(isinstance(i, int) for i in crop))
+  assert scale is None or isinstance(scale, int) or (isinstance(scale, tuple) and len(scale) == 2 and all(isinstance(i, int) for i in scale))
+  assert trim is None or (isinstance(trim, tuple) and len(trim) == 2 and all(isinstance(i, int) for i in trim))
+  assert isinstance(preserve_aspect_ratio, bool)
+  assert isinstance(scale_algorithm, str)
+  ds_factor = 1
+  if target_fps is not None and target_fps > fps: logging.warn("target_fps should not be greater than fps. Ignoring.")
+  elif target_fps is not None: ds_factor = int(fps // target_fps)
+  # Target number of frames
+  target_n = trim[1] - trim[0] if trim is not None else n
+  target_n = int(target_n / ds_factor)
+  # Target size after taking into account cropping
+  target_w = crop[2] if crop is not None else w
+  target_h = crop[3] if crop is not None else h
+  # Target size after taking into account scaling
+  if scale not in [None, 0]:
+    if isinstance(scale, int): scale = (scale, scale)
+    if preserve_aspect_ratio:
+      scale_ratio = max(scale) / max(target_w, target_h)
+      target_w = int(target_w * scale_ratio)
+      target_h = int(target_h * scale_ratio)
+    else:
+      target_w, target_h = scale
+  # Trimming
+  if trim is not None:
+    stream = stream.trim(start_frame=0, end_frame=trim[1]-trim[0])
+    stream = stream.setpts('PTS-STARTPTS')
+  # Downsampling
+  if ds_factor > 1:
+    stream = ffmpeg.filter(stream, 'select', 'not(mod(n,{}))'.format(ds_factor))
+  # Cropping
+  if crop is not None:
+    stream = stream.crop(crop[0], crop[1], crop[2], crop[3])
+  # Scaling
+  # http://trac.ffmpeg.org/wiki/Scaling#Specifyingscalingalgorithm
+  if scale not in [None, (0, 0)]:
+    stream = ffmpeg.filter(stream, 'scale', target_w, target_h, scale_algorithm)
+  # Return
+  return stream, target_n, target_w, target_h, ds_factor
+
+def _ffmpeg_output_to_numpy(
+    stream: ffmpeg.nodes.FilterableStream,
+    r: int,
+    fps: Union[float, int, None],
+    n: int,
+    w: int,
+    h: int,
+    scale: Union[tuple, int, None] = None,
+    crf: Union[int, None] = None,
+    pix_fmt: str = 'bgr24',
+    preserve_aspect_ratio: bool = False,
+    scale_algorithm: str = 'bicubic',
+    dim_deltas: tuple = (0, 0, 0)
+  ) -> np.ndarray:
+  """Run the stream and capture the raw video output in a numpy array.
+  
+  Args:
+    stream: The ffmpeg stream
+    r: Rotation present in the video (after applying stream)
+    fps: Framerate attempted to create in stream.
+    n: Number of frames attempted to create in stream.
+    w: Frame width attempted to create in stream.
+    h: Frame height attempted to create in stream.
+    scale: Size(s) for spatial scaling. Scalar or (width, height) (optional)
+    crf: Constant rate factor for H.264 encoding (higher = more compression)
+      If not None, need to run the stream to encode before capturing to np.
+    pix_fmt: Pixel format to read into.
+    preserve_aspect_ratio: Preserve the aspect ratio if scaling
+    scale_algorithm: The algorithm used for scaling.
+      Supported: bicubic, bilinear, area, lanczos. Default: bicubic
+    dim_deltas: Allowed deviation from target (n_frames, height, width)
+  Returns:
+    frames: The video frames in shape (n, h, w, c)
+  """
+  assert isinstance(stream, ffmpeg.nodes.FilterableStream)
+  assert isinstance(r, int)
+  assert fps is None or isinstance(fps, (float, int))
+  assert isinstance(n, int)
+  assert isinstance(w, int)
+  assert isinstance(h, int)
+  assert crf is None or isinstance(crf, int)
+  assert isinstance(pix_fmt, str)
+  assert isinstance(dim_deltas, tuple) and len(dim_deltas) == 3 and all(isinstance(i, int) for i in dim_deltas)
+  if crf is None:
+    # Run stream straight to raw video
+    stream = stream.output("pipe:", vsync=0, format="rawvideo", pix_fmt=pix_fmt)
+    stream = stream.global_args("-loglevel", "panic", "-hide_banner", "-nostdin", "-nostats")
+    out, _ = stream.run(capture_stdout=True, capture_stderr=True)
+  else:
+    # Run stream to encode H264 with crf
+    stream = stream.output("pipe:", vsync=0, format='rawvideo', vcodec='libx264', crf=crf)
+    out, _ = stream.run(capture_stdout=True, capture_stderr=True)
+    # Run stream to decode H264 to raw video
+    stream = _ffmpeg_input_from_pipe()
+    stream, _, w, h, _ = _ffmpeg_filtering(
+      stream, fps=fps, n=n, w=w, h=h, scale=scale,
+      preserve_aspect_ratio=preserve_aspect_ratio, scale_algorithm=scale_algorithm)
+    stream = stream.output("pipe:", vsync=0, format="rawvideo", pix_fmt=pix_fmt)
+    out, _ = stream.run(input=out, capture_stdout=True, capture_stderr=True)
+  # Swap h and w if necessary -> not needed if scaled!
+  if r != 0:
+    if abs(r) == 90:
+      logging.warn("Rotation {} present in video fixed; results in W and H swapped.".format(r))
+      w, h = h, w
+    else:
+      logging.warn("Rotation {} present in video; Fixing is not yet supported.".format(r))
+  # Parse result
+  frames = np.frombuffer(out, np.uint8)
+  adj_n, adh_h, adh_w = find_factors_near(
+    frames.shape[0]//3, n, h, w, dim_deltas[0], dim_deltas[1], dim_deltas[2])
+  assert adj_n * adh_h * adh_w * 3 == frames.shape[0]
+  frames = frames.reshape([adj_n, adh_h, adh_w, 3])
+  # Return
+  return frames
+
+def _ffmpeg_output_to_file(
+    stream: ffmpeg.nodes.FilterableStream,
+    output_dir: str,
+    output_file: str,
+    from_stdin: Union[bytes, None] = None,
+    pix_fmt: str = 'yuv420p',
+    crf: int = 12,
+    overwrite: bool = False
+  ):
+  """Run the stream and encode to file as H264.
+  
+  Args:
+    stream: The ffmpeg stream
+    output_dir: The directory where the video will be written
+    ourput_file: The filename as which the video will be written
+    from_stdin: Byte buffer to pipe data from (optional)
+    pix_fmt: Pixel format to write into
+    crf: Constant rate factor for H.264 encoding (higher = more compression)
+    overwrite: Overwrite if file exists?
+  """
+  assert isinstance(stream, ffmpeg.nodes.FilterableStream)
+  assert isinstance(output_dir, str)
+  assert isinstance(output_file, str)
+  assert from_stdin is None or isinstance(from_stdin, bytes)
+  assert isinstance(pix_fmt, str)
+  assert crf is None or isinstance(crf, int)
+  assert isinstance(overwrite, bool)
+  output_path = os.path.join(output_dir, output_file)
+  stream = ffmpeg.output(stream, output_path, pix_fmt=pix_fmt, crf=crf)
+  if overwrite:
+    stream = stream.global_args("-vsync", "2", "-y")
+  else:
+    stream = stream.global_args("-vsync", "2")
+  if from_stdin is None:
+    stream.run(quiet=True)
+  else:
+    process = stream.run_async(pipe_stdin=True, quiet=True)
+    process.communicate(input=from_stdin)
+
+def read_video_from_path(
+    path: str,
+    target_fps: Union[float, None] = None,
+    crop: Union[tuple, None] = None,
+    scale: Union[int, tuple, None] = None,
+    trim: Union[tuple, None] = None,
+    crf: Union[int, None] = None,
+    pix_fmt: str = 'bgr24',
+    preserve_aspect_ratio: bool = False,
+    scale_algorithm: str = 'bicubic',
+    order: str = 'scale_crf',
+    dim_deltas: tuple = (0, 0, 0)
+  ) -> Tuple[np.ndarray, int]:
+  """Read a video from path into a numpy array.
+  Optionally transformed by downsampling, spatial cropping, spatial scaling
+    (applied to result of cropping if specified), temporal trimming, and
+    intermediate encoding.
+
+  Args:
+    path: The path from which video will be read.
+    target_fps: Try to downsample frames to achieve this framerate.
+    crop: Coords and sizes for spatial cropping (x, y, width, height) (optional).
+    scale: Size(s) for spatial scaling. Scalar or (width, height) (optional).
+    trim: Frame numbers for temporal trimming (start, end) (optional).
+    crf: Constant rate factor for H.264 encoding (higher = more compression)
+      If specified, do intermediate encoding, otherwise ignore.
+    pix_fmt: Pixel format to read into.
+    preserve_aspect_ratio: Preserve the aspect ratio if scaling.
+    scale_algorithm: The algorithm used for scaling.
+      Supported: bicubic, bilinear, area, lanczos. Default: bicubic
+    order: scale_crf or crf_scale - specifies order of application
+    dim_deltas: Allowed deviation from target (n_frames, height, width)
+  Returns:
+    frames: The video frames (n, h, w, 3)
+    ds_factor: The applied downsampling factor
+  """
+  assert isinstance(path, str)
+  # Check if file exists
+  if not os.path.exists(path):
+    raise FileNotFoundError("File {} does not exist".format(path))
+  # Get metadata of original video
+  fps, n, w, h, _, _, r = probe_video(path=path)
+  # Input
+  stream = _ffmpeg_input_from_path(path=path, fps=fps, trim=trim)
+  # Filtering
+  scale_0 = scale if order == 'scale_crf' or crf == None else 0
+  stream, target_n, target_w, target_h, ds_factor = _ffmpeg_filtering(
+    stream=stream, fps=fps, n=n, w=w, h=h, target_fps=target_fps, crop=crop, scale=scale_0,
+    trim=trim, preserve_aspect_ratio=preserve_aspect_ratio, scale_algorithm=scale_algorithm)
+  # Save whether rotation still present
+  if scale not in [None, 0] or crop is not None: r = 0
+  # Output
+  scale_1 = 0 if order == 'scale_crf' or crf == None else scale
+  frames = _ffmpeg_output_to_numpy(
+    stream=stream, r=r, fps=target_fps, n=target_n, w=target_w, h=target_h,
+    scale=scale_1, crf=crf, pix_fmt=pix_fmt, scale_algorithm=scale_algorithm,
+    dim_deltas=dim_deltas)
+  # Return
+  return frames, ds_factor
+
+def write_video_from_path(
+    path: str,
+    output_dir: str,
+    output_file: str,
+    target_fps: Union[float, None] = None,
+    crop: Union[tuple, None] = None,
+    scale: Union[int, tuple, None] = None,
+    trim: Union[tuple, None] = None,
+    pix_fmt: str = 'yuv420p',
+    crf: int = 12,
+    preserve_aspect_ratio: bool = False,
+    scale_algorithm: str = 'bicubic',
+    overwrite: bool = False
+  ):
+  """Read a video from path and write back to a video file.
+  Optionally transformed by downsampling, spatial cropping, spatial scaling
+    (applied to result of cropping if specified), and temporal trimming.
+
+  Args:
+    path: The path from which video will be read.
+    output_dir: The directory where the video will be written.
+    ourput_file: The filename as which the video will be written.
+    target_fps: Try to downsample frames to achieve this framerate (optional).
+    crop: Coords and sizes for spatial cropping (x, y, width, height) (optional).
+    scale: Size(s) for spatial scaling. Scalar or (width, height) (optional).
+    trim: Frame numbers for temporal trimming (start, end) (optional).
+    crf: Constant rate factor for H.264 encoding (higher = more compression).
+    preserve_aspect_ratio: Preserve the aspect ratio if scaling.
+    scale_algorithm: The algorithm used for scaling. Default: bicubic
+  """
+  # Get metadata of original video
+  fps, n, w, h, _, _, r = probe_video(path=path)
+  # Input
+  stream = _ffmpeg_input_from_path(path=path, fps=fps, trim=trim)
+  # Filtering
+  stream, _, _, _, _ = _ffmpeg_filtering(
+      stream=stream, fps=fps, n=n, w=w, h=h, target_fps=target_fps, crop=crop, scale=scale,
+      trim=trim, preserve_aspect_ratio=preserve_aspect_ratio, scale_algorithm=scale_algorithm)
+  # Output
+  _ffmpeg_output_to_file(
+    stream, output_dir=output_dir, output_file=output_file, pix_fmt=pix_fmt, crf=crf, overwrite=overwrite)
+
+def write_video_from_numpy(
+    data: np.ndarray,
+    fps: Union[float, int],
+    pix_fmt: str,
+    output_dir: str,
+    output_file: str,
+    out_pix_fmt: str = 'yuv420p',
+    crf: int = 12,
+    overwrite: bool = False
+  ):
+  """Write data from a numpy array to a video file.
+
+  Args:
+    data: The numpy array with video frames. Shape (n, h, w, 3)
+    fps: The frame rate
+    pix_fmt: The pixel format of `data`
+    output_dir: The directory where the video will be written
+    ourput_file: The filename as which the video will be written
+    pix_fmt: The pixel format for the output video
+    crf: Constant rate factor for H.264 encoding (higher = more compression)
+    overwrite: Overwrite if file exists?
+  """
+  assert isinstance(data, np.ndarray)
+  _, h, w, _ = data.shape
+  stream = _ffmpeg_input_from_numpy(w=w, h=h, fps=fps, pix_fmt=pix_fmt)
+  buffer = data.flatten().tobytes()
+  _ffmpeg_output_to_file(
+    stream, output_dir=output_dir, output_file=output_file, from_stdin=buffer,
+    crf=crf, pix_fmt=out_pix_fmt, overwrite=overwrite)

prpy/ffmpeg/utils.py

@@ -0,0 +1,81 @@
+# Copyright (c) 2024 Philipp Rouast
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import ffmpeg
+import itertools
+import logging
+from typing import Tuple
+
+def find_factors_near(
+    i: int,
+    f1: int,
+    f2: int,
+    f3: int,
+    max_delta_1: int,
+    max_delta_2: int,
+    max_delta_3: int
+  ) -> Tuple[int, int, int]:
+  """Search for factors of a number near provided approximate factors.
+  Used to determine dim of filtered video which can minimally deviate from targets
+
+  Args:
+    i: The number to be factorized
+    f1: The first factor to search nearby
+    f2: The second factor to search nearby
+    f3: The third factor to search nearby
+    max_delta_1: Maximum deviation allowed for f1
+    max_delta_2: Maximum deviation allowed for f2
+    max_delta_3: Maximum deviation allowed for f3
+  Returns:
+    f1: The actual first factor
+    f2: The actual second factor
+    f3: The actual third factor
+  """
+  assert isinstance(i, int)
+  assert isinstance(f1, int)
+  assert isinstance(f2, int)
+  assert isinstance(f3, int)
+  assert isinstance(max_delta_1, int)
+  assert isinstance(max_delta_2, int)
+  assert isinstance(max_delta_3, int)
+  # Iterative deepening
+  for delta in range(max(max_delta_1, max_delta_2, max_delta_3)+1):
+    delta_1 = min(delta, max_delta_1)
+    delta_2 = min(delta, max_delta_2)
+    delta_3 = min(delta, max_delta_3)
+    ts = [(t1, t2, t3) for t1, t2, t3 in list(itertools.product( \
+      range(f1-delta_1, f1+delta_1+1), range(f2-delta_2, f2+delta_2+1), range(f3-delta_3, f3+delta_3+1)))]
+    for t1, t2, t3 in ts:
+      if t1 * t2 * t3 == i:
+        return t1, t2, t3
+  logging.error("Total={}; Failed to find factors near f1={} f2={} f3={} at delta=({}, {}, {})".format(i, f1, f2, f3, max_delta_1, max_delta_2, max_delta_3))
+  raise RuntimeError("Could not find factors near the provided values")
+
+def create_test_video_stream(t: int) -> ffmpeg.nodes.FilterableStream:
+  """Create an ffmpeg video stream for testing.
+  Like `ffmpeg -f lavfi -i testsrc -t 30 -pix_fmt yuv420p testsrc.mp4`
+  
+  Args:
+    t: The test stream time in seconds
+  Returns:
+    stream: The test stream
+  """
+  stream = ffmpeg.input('testsrc', f='lavfi', t=t)
+  return stream

prpy/numpy/__init__.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2024 Philipp Rouast
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.