From c8d9620b28995fbef575cc15de73e31a779072e7 Mon Sep 17 00:00:00 2001
From: Asia <2736300+humpydonkey@users.noreply.github.com>
Date: Wed, 27 Mar 2024 09:49:49 -0700
Subject: [PATCH] Add frame extraction tool for video processing (#26)

* Add frame extraction tool for video processing

* Update ExtractFrames tool

* minor updates

* Update docs

* Attempt to support py 3.9

* Update pyproject.toml

* Test 3.9 and 3.11 in CI

---------

Co-authored-by: Yazhou Cao <yazhou.cao@landing.ai>
---
 .github/workflows/ci_cd.yml |   2 +-
 README.md                   |   1 +
 docs/api/tools.md           |   4 +-
 docs/index.md               |   1 +
 poetry.lock                 | 126 +++++++++++++++++++++++++-
 pyproject.toml              |   5 +-
 tests/data/video/test.mp4   | Bin 0 -> 17317 bytes
 tests/tools/test_video.py   |   8 ++
 vision_agent/tools/tools.py |  43 +++++++++
 vision_agent/tools/video.py | 176 ++++++++++++++++++++++++++++++++++++
 10 files changed, 361 insertions(+), 5 deletions(-)
 create mode 100644 tests/data/video/test.mp4
 create mode 100644 tests/tools/test_video.py
 create mode 100644 vision_agent/tools/video.py

diff --git a/.github/workflows/ci_cd.yml b/.github/workflows/ci_cd.yml
index d21d703b..56c31d19 100644
--- a/.github/workflows/ci_cd.yml
+++ b/.github/workflows/ci_cd.yml
@@ -9,7 +9,7 @@ jobs:
   Test:
     strategy:
       matrix:
-        python-version: [3.10.11]
+        python-version: [3.9, 3.11]
         os: [ ubuntu-22.04, windows-2022, macos-12 ]
     runs-on: ${{ matrix.os }}
     steps:
diff --git a/README.md b/README.md
index 5687dd43..6879e734 100644
--- a/README.md
+++ b/README.md
@@ -104,6 +104,7 @@ you. For example:
 | Crop | Crop crops an image given a bounding box and returns a file name of the cropped image. |
 | BboxArea | BboxArea returns the area of the bounding box in pixels normalized to 2 decimal places. |
 | SegArea | SegArea returns the area of the segmentation mask in pixels normalized to 2 decimal places. |
+| ExtractFrames | ExtractFrames extracts image frames from the input video. |
 
 
 It also has a basic set of calculate tools such as add, subtract, multiply and divide.
diff --git a/docs/api/tools.md b/docs/api/tools.md
index fa3fba93..71935d46 100644
--- a/docs/api/tools.md
+++ b/docs/api/tools.md
@@ -2,4 +2,6 @@
 
 ::: vision_agent.tools.prompts
 
-::: vision_agent.tools.tools
\ No newline at end of file
+::: vision_agent.tools.tools
+
+::: vision_agent.tools.video
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index 2a83bef7..e0033dfa 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -90,6 +90,7 @@ you. For example:
 | Crop | Crop crops an image given a bounding box and returns a file name of the cropped image. |
 | BboxArea | BboxArea returns the area of the bounding box in pixels normalized to 2 decimal places. |
 | SegArea | SegArea returns the area of the segmentation mask in pixels normalized to 2 decimal places. |
+| ExtractFrames | ExtractFrames extracts image frames from the input video. |
 
 
 It also has a basic set of calculate tools such as add, subtract, multiply and divide.
diff --git a/poetry.lock b/poetry.lock
index 3f479663..e50ff090 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -257,6 +257,17 @@ files = [
 [package.extras]
 dev = ["black", "flake8", "flake8-pyi", "matplotlib", "mypy (==0.770)", "numpy", "pandas", "pytest"]
 
+[[package]]
+name = "decorator"
+version = "4.4.2"
+description = "Decorators for Humans"
+optional = false
+python-versions = ">=2.6, !=3.0.*, !=3.1.*"
+files = [
+    {file = "decorator-4.4.2-py2.py3-none-any.whl", hash = "sha256:41fa54c2a0cc4ba648be4fd43cff00aedf5b9465c9bf18d64325bc225f08f760"},
+    {file = "decorator-4.4.2.tar.gz", hash = "sha256:e3a62f0520172440ca0dcc823749319382e377f37f140a0b99ef45fecb84bfe7"},
+]
+
 [[package]]
 name = "distro"
 version = "1.9.0"
@@ -518,6 +529,56 @@ files = [
     {file = "idna-3.6.tar.gz", hash = "sha256:9ecdbbd083b06798ae1e86adcbfe8ab1479cf864e4ee30fe4e46a003d12491ca"},
 ]
 
+[[package]]
+name = "imageio"
+version = "2.34.0"
+description = "Library for reading and writing a wide range of image, video, scientific, and volumetric data formats."
+optional = false
+python-versions = ">=3.8"
+files = [
+    {file = "imageio-2.34.0-py3-none-any.whl", hash = "sha256:08082bf47ccb54843d9c73fe9fc8f3a88c72452ab676b58aca74f36167e8ccba"},
+    {file = "imageio-2.34.0.tar.gz", hash = "sha256:ae9732e10acf807a22c389aef193f42215718e16bd06eed0c5bb57e1034a4d53"},
+]
+
+[package.dependencies]
+numpy = "*"
+pillow = ">=8.3.2"
+
+[package.extras]
+all-plugins = ["astropy", "av", "imageio-ffmpeg", "pillow-heif", "psutil", "tifffile"]
+all-plugins-pypy = ["av", "imageio-ffmpeg", "pillow-heif", "psutil", "tifffile"]
+build = ["wheel"]
+dev = ["black", "flake8", "fsspec[github]", "pytest", "pytest-cov"]
+docs = ["numpydoc", "pydata-sphinx-theme", "sphinx (<6)"]
+ffmpeg = ["imageio-ffmpeg", "psutil"]
+fits = ["astropy"]
+full = ["astropy", "av", "black", "flake8", "fsspec[github]", "gdal", "imageio-ffmpeg", "itk", "numpydoc", "pillow-heif", "psutil", "pydata-sphinx-theme", "pytest", "pytest-cov", "sphinx (<6)", "tifffile", "wheel"]
+gdal = ["gdal"]
+itk = ["itk"]
+linting = ["black", "flake8"]
+pillow-heif = ["pillow-heif"]
+pyav = ["av"]
+test = ["fsspec[github]", "pytest", "pytest-cov"]
+tifffile = ["tifffile"]
+
+[[package]]
+name = "imageio-ffmpeg"
+version = "0.4.9"
+description = "FFMPEG wrapper for Python"
+optional = false
+python-versions = ">=3.5"
+files = [
+    {file = "imageio-ffmpeg-0.4.9.tar.gz", hash = "sha256:39bcd1660118ef360fa4047456501071364661aa9d9021d3d26c58f1ee2081f5"},
+    {file = "imageio_ffmpeg-0.4.9-py3-none-macosx_10_9_intel.macosx_10_9_x86_64.macosx_10_10_intel.macosx_10_10_x86_64.whl", hash = "sha256:24095e882a126a0d217197b86265f821b4bb3cf9004104f67c1384a2b4b49168"},
+    {file = "imageio_ffmpeg-0.4.9-py3-none-manylinux2010_x86_64.whl", hash = "sha256:2996c64af3e5489227096580269317719ea1a8121d207f2e28d6c24ebc4a253e"},
+    {file = "imageio_ffmpeg-0.4.9-py3-none-manylinux2014_aarch64.whl", hash = "sha256:7eead662d2f46d748c0ab446b68f423eb63d2b54d0a8ef96f80607245540866d"},
+    {file = "imageio_ffmpeg-0.4.9-py3-none-win32.whl", hash = "sha256:b6de1e18911687c538d5585d8287ab1a23624ca9dc2044fcc4607de667bcf11e"},
+    {file = "imageio_ffmpeg-0.4.9-py3-none-win_amd64.whl", hash = "sha256:7e900c695c6541b1cb17feb1baacd4009b30a53a45b81c23d53a67ab13ffb766"},
+]
+
+[package.dependencies]
+setuptools = "*"
+
 [[package]]
 name = "iniconfig"
 version = "2.0.0"
@@ -803,6 +864,30 @@ files = [
 griffe = ">=0.37"
 mkdocstrings = ">=0.20"
 
+[[package]]
+name = "moviepy"
+version = "1.0.3"
+description = "Video editing with Python"
+optional = false
+python-versions = "*"
+files = [
+    {file = "moviepy-1.0.3.tar.gz", hash = "sha256:2884e35d1788077db3ff89e763c5ba7bfddbd7ae9108c9bc809e7ba58fa433f5"},
+]
+
+[package.dependencies]
+decorator = ">=4.0.2,<5.0"
+imageio = {version = ">=2.5,<3.0", markers = "python_version >= \"3.4\""}
+imageio_ffmpeg = {version = ">=0.2.0", markers = "python_version >= \"3.4\""}
+numpy = {version = ">=1.17.3", markers = "python_version > \"2.7\""}
+proglog = "<=1.0.0"
+requests = ">=2.8.1,<3.0"
+tqdm = ">=4.11.2,<5.0"
+
+[package.extras]
+doc = ["Sphinx (>=1.5.2,<2.0)", "numpydoc (>=0.6.0,<1.0)", "pygame (>=1.9.3,<2.0)", "sphinx_rtd_theme (>=0.1.10b0,<1.0)"]
+optional = ["matplotlib (>=2.0.0,<3.0)", "opencv-python (>=3.0,<4.0)", "scikit-image (>=0.13.0,<1.0)", "scikit-learn", "scipy (>=0.19.0,<1.5)", "youtube_dl"]
+test = ["coverage (<5.0)", "coveralls (>=1.1,<2.0)", "pytest (>=3.0.0,<4.0)", "pytest-cov (>=2.5.1,<3.0)", "requests (>=2.8.1,<3.0)"]
+
 [[package]]
 name = "mpmath"
 version = "1.3.0"
@@ -1106,6 +1191,29 @@ typing-extensions = ">=4.7,<5"
 [package.extras]
 datalib = ["numpy (>=1)", "pandas (>=1.2.3)", "pandas-stubs (>=1.1.0.11)"]
 
+[[package]]
+name = "opencv-python-headless"
+version = "4.9.0.80"
+description = "Wrapper package for OpenCV python bindings."
+optional = false
+python-versions = ">=3.6"
+files = [
+    {file = "opencv-python-headless-4.9.0.80.tar.gz", hash = "sha256:71a4cd8cf7c37122901d8e81295db7fb188730e33a0e40039a4e59c1030b0958"},
+    {file = "opencv_python_headless-4.9.0.80-cp37-abi3-macosx_10_16_x86_64.whl", hash = "sha256:2ea8a2edc4db87841991b2fbab55fc07b97ecb602e0f47d5d485bd75cee17c1a"},
+    {file = "opencv_python_headless-4.9.0.80-cp37-abi3-macosx_11_0_arm64.whl", hash = "sha256:e0ee54e27be493e8f7850847edae3128e18b540dac1d7b2e4001b8944e11e1c6"},
+    {file = "opencv_python_headless-4.9.0.80-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:57ce2865e8fec431c6f97a81e9faaf23fa5be61011d0a75ccf47a3c0d65fa73d"},
+    {file = "opencv_python_headless-4.9.0.80-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:976656362d68d9f40a5c66f83901430538002465f7db59142784f3893918f3df"},
+    {file = "opencv_python_headless-4.9.0.80-cp37-abi3-win32.whl", hash = "sha256:11e3849d83e6651d4e7699aadda9ec7ed7c38957cbbcb99db074f2a2d2de9670"},
+    {file = "opencv_python_headless-4.9.0.80-cp37-abi3-win_amd64.whl", hash = "sha256:a8056c2cb37cd65dfcdf4153ca16f7362afcf3a50d600d6bb69c660fc61ee29c"},
+]
+
+[package.dependencies]
+numpy = [
+    {version = ">=1.23.5", markers = "python_version >= \"3.11\""},
+    {version = ">=1.21.4", markers = "python_version >= \"3.10\" and platform_system == \"Darwin\" and python_version < \"3.11\""},
+    {version = ">=1.21.2", markers = "platform_system != \"Darwin\" and python_version >= \"3.10\" and python_version < \"3.11\""},
+]
+
 [[package]]
 name = "packaging"
 version = "24.0"
@@ -1167,8 +1275,8 @@ files = [
 
 [package.dependencies]
 numpy = [
-    {version = ">=1.22.4,<2", markers = "python_version < \"3.11\""},
     {version = ">=1.23.2,<2", markers = "python_version == \"3.11\""},
+    {version = ">=1.22.4,<2", markers = "python_version < \"3.11\""},
 ]
 python-dateutil = ">=2.8.2"
 pytz = ">=2020.1"
@@ -1325,6 +1433,20 @@ files = [
 dev = ["pre-commit", "tox"]
 testing = ["pytest", "pytest-benchmark"]
 
+[[package]]
+name = "proglog"
+version = "0.1.10"
+description = "Log and progress bar manager for console, notebooks, web..."
+optional = false
+python-versions = "*"
+files = [
+    {file = "proglog-0.1.10-py3-none-any.whl", hash = "sha256:19d5da037e8c813da480b741e3fa71fb1ac0a5b02bf21c41577c7f327485ec50"},
+    {file = "proglog-0.1.10.tar.gz", hash = "sha256:658c28c9c82e4caeb2f25f488fff9ceace22f8d69b15d0c1c86d64275e4ddab4"},
+]
+
+[package.dependencies]
+tqdm = "*"
+
 [[package]]
 name = "pycodestyle"
 version = "2.9.1"
@@ -2488,4 +2610,4 @@ watchmedo = ["PyYAML (>=3.10)"]
 [metadata]
 lock-version = "2.0"
 python-versions = ">=3.10,<3.12"
-content-hash = "dbb1f3241c006408ab8056349c63d7f947450c01fd518a758af66e2e5c000916"
+content-hash = "93a4e362ddaf2a1e65a6457c212896853b1c4409e0456f9209f33b795b5ec748"
diff --git a/pyproject.toml b/pyproject.toml
index 9630a9b5..3c0569df 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -16,7 +16,7 @@ packages = [{include = "vision_agent"}]
 "documentation" = "https://github.com/landing-ai/vision-agent"
 
 [tool.poetry.dependencies]  # main dependency group
-python = ">=3.10,<3.12"
+python = ">=3.9,<3.12"
 
 numpy = ">=1.21.0,<2.0.0"
 pillow = "10.*"
@@ -28,6 +28,8 @@ torch = "2.1.*"  # 2.2 causes sentence-transformers to seg fault
 sentence-transformers = "2.*"
 openai = "1.*"
 typing_extensions = "4.*"
+moviepy = "1.*"
+opencv-python-headless = "4.*"
 
 [tool.poetry.group.dev.dependencies]
 autoflake = "1.*"
@@ -84,4 +86,5 @@ module = [
     "faiss.*",
     "openai.*",
     "sentence_transformers.*",
+    "moviepy.*",
 ]
diff --git a/tests/data/video/test.mp4 b/tests/data/video/test.mp4
new file mode 100644
index 0000000000000000000000000000000000000000..596eea389407ac08915148bbd2212567a1382b4a
GIT binary patch
literal 17317
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

literal 0
HcmV?d00001

diff --git a/tests/tools/test_video.py b/tests/tools/test_video.py
new file mode 100644
index 00000000..a19b529f
--- /dev/null
+++ b/tests/tools/test_video.py
@@ -0,0 +1,8 @@
+from vision_agent.tools.video import extract_frames_from_video
+
+
+def test_extract_frames_from_video():
+    # TODO: consider generating a video on the fly instead
+    video_path = "tests/data/video/test.mp4"
+    res = extract_frames_from_video(video_path)
+    assert len(res) == 1
diff --git a/vision_agent/tools/tools.py b/vision_agent/tools/tools.py
index c5f50e98..6e55f210 100644
--- a/vision_agent/tools/tools.py
+++ b/vision_agent/tools/tools.py
@@ -11,6 +11,7 @@
 from PIL.Image import Image as ImageType
 
 from vision_agent.image_utils import convert_to_b64, get_image_size
+from vision_agent.tools.video import extract_frames_from_video
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -505,6 +506,47 @@ def __call__(self, input: List[int]) -> float:
         return round(input[0] / input[1], 2)
 
 
+class ExtractFrames(Tool):
+    r"""Extract frames from a video."""
+
+    name = "extract_frames_"
+    description = "'extract_frames_' extract image frames from the input video, return a list of tuple (frame, timestamp), where the timestamp is the relative time in seconds of the frame occurred in the video, the frame is a local image file path that stores the frame."
+    usage = {
+        "required_parameters": [{"name": "video_uri", "type": "str"}],
+        "examples": [
+            {
+                "scenario": "Can you extract the frames from this video? Video: www.foobar.com/video?name=test.mp4",
+                "parameters": {"video_uri": "www.foobar.com/video?name=test.mp4"},
+            },
+            {
+                "scenario": "Can you extract the images from this video file? Video path: tests/data/test.mp4",
+                "parameters": {"video_uri": "tests/data/test.mp4"},
+            },
+        ],
+    }
+
+    def __call__(self, video_uri: str) -> list[tuple[str, float]]:
+        """Extract frames from a video.
+
+
+        Parameters:
+            video_uri: the path to the video file or a url points to the video data
+
+        Returns:
+            a list of tuples containing the extracted frame and the timestamp in seconds. E.g. [(path_to_frame1, 0.0), (path_to_frame2, 0.5), ...]. The timestamp is the time in seconds from the start of the video. E.g. 12.125 means 12.125 seconds from the start of the video. The frames are sorted by the timestamp in ascending order.
+        """
+        frames = extract_frames_from_video(video_uri)
+        result = []
+        _LOGGER.info(
+            f"Extracted {len(frames)} frames from video {video_uri}. Temporarily saving them as images to disk for downstream tasks."
+        )
+        for frame, ts in frames:
+            with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as tmp:
+                Image.fromarray(frame).save(tmp)
+            result.append((tmp.name, ts))
+        return result
+
+
 TOOLS = {
     i: {"name": c.name, "description": c.description, "usage": c.usage, "class": c}
     for i, c in enumerate(
@@ -520,6 +562,7 @@ def __call__(self, input: List[int]) -> float:
             Subtract,
             Multiply,
             Divide,
+            ExtractFrames,
         ]
     )
     if (hasattr(c, "name") and hasattr(c, "description") and hasattr(c, "usage"))
diff --git a/vision_agent/tools/video.py b/vision_agent/tools/video.py
new file mode 100644
index 00000000..606166ed
--- /dev/null
+++ b/vision_agent/tools/video.py
@@ -0,0 +1,176 @@
+import logging
+import math
+import os
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from typing import List, Tuple, cast
+
+import cv2
+import numpy as np
+from moviepy.video.io.VideoFileClip import VideoFileClip
+from tqdm import tqdm
+
+_LOGGER = logging.getLogger(__name__)
+# The maximum length of the clip to extract frames from, in seconds
+_CLIP_LENGTH = 30.0
+
+
+def extract_frames_from_video(
+    video_uri: str, fps: int = 2, motion_detection_threshold: float = 0.06
+) -> List[Tuple[np.ndarray, float]]:
+    """Extract frames from a video
+
+    Parameters:
+        video_uri: the path to the video file or a video file url
+        fps: the frame rate per second to extract the frames
+        motion_detection_threshold: The threshold to detect motion between changes/frames.
+            A value between 0-1, which represents the percentage change required for the frames to be considered in motion.
+            For example, a lower value means more frames will be extracted.
+
+    Returns:
+        a list of tuples containing the extracted frame and the timestamp in seconds. E.g. [(frame1, 0.0), (frame2, 0.5), ...]. The timestamp is the time in seconds from the start of the video. E.g. 12.125 means 12.125 seconds from the start of the video. The frames are sorted by the timestamp in ascending order.
+    """
+    with VideoFileClip(video_uri) as video:
+        video_duration: float = video.duration
+        num_workers = os.cpu_count()
+        clip_length: float = min(video_duration, _CLIP_LENGTH)
+        start_times = list(range(0, math.ceil(video_duration), math.ceil(clip_length)))
+        assert start_times, f"No frames to extract from the input video: {video_uri}"
+        segment_args = [
+            {
+                "video_uri": video_uri,
+                "start": start,
+                "end": (
+                    start + clip_length if i < len(start_times) - 1 else video_duration
+                ),
+                "fps": fps,
+                "motion_detection_threshold": motion_detection_threshold,
+            }
+            for i, start in enumerate(start_times)
+        ]
+        if (
+            cast(float, segment_args[-1]["end"])
+            - cast(float, segment_args[-1]["start"])
+            < 1
+        ):
+            # If the last segment is less than 1s, merge it with the previous segment
+            # This is to avoid the failure of the last segment extraction
+            assert (
+                len(segment_args) > 1
+            ), "Development bug - Expect at least 2 segments."
+            segment_args[-2]["end"] = video_duration
+            segment_args.pop(-1)
+        _LOGGER.info(
+            f"""Created {len(segment_args)} segments from the input video  {video_uri} of length {video.duration}s, with clip size: {clip_length}s and {num_workers} workers.
+            Segments: {segment_args}
+            """
+        )
+        frames = []
+        with tqdm(total=len(segment_args)) as pbar:
+            with ProcessPoolExecutor(max_workers=num_workers) as executor:
+                futures = [
+                    executor.submit(_extract_frames_by_clip, **kwargs)  # type: ignore
+                    for kwargs in segment_args
+                ]
+                for future in as_completed(futures):
+                    result = future.result()
+                    frames.extend(result)
+                    pbar.update(1)
+        frames.sort(key=lambda x: x[1])
+        _LOGGER.info(f"Extracted {len(frames)} frames from video {video_uri}")
+        return frames
+
+
+def _extract_frames_by_clip(
+    video_uri: str,
+    start: int = 0,
+    end: float = -1,
+    fps: int = 2,
+    motion_detection_threshold: float = 0.06,
+) -> List[Tuple[np.ndarray, float]]:
+    """Extract frames from a video clip with start and end time in seconds.
+
+    Parameters:
+        video_uri: the path to the video file or a video file url
+        start: the start time (in seconds) of the clip to extract
+        end: the end time (in seconds, up to millisecond level precision) of the clip to extract, if -1, extract the whole video
+        fps: the frame rate to extract the frames
+        motion_detection_threshold: the threshold to detect the motion between frames
+    """
+    with VideoFileClip(video_uri) as video:
+        source_fps = video.fps
+        if end <= 0:
+            end = video.duration
+        _LOGGER.info(
+            f"Extracting frames from video {video_uri} ({video.duration}s) with start={start}s and end={end}s"
+        )
+        clip = video.subclip(start, end)
+        processable_frames = int(clip.duration * fps)
+        _LOGGER.info(
+            f"Extracting frames from video clip of length {clip.duration}s with FPS={fps} and start_time={start}s. Total number of frames in clip: {processable_frames}"
+        )
+        frames = []
+        total_count, skipped_count = 0, 0
+        prev_processed_frame = None
+        pbar = tqdm(
+            total=processable_frames, desc=f"Extracting frames from clip {start}-{end}"
+        )
+        for i, frame in enumerate(clip.iter_frames(fps=fps, dtype="uint8")):
+            curr_processed_frame = _preprocess_frame(frame)
+            total_count += 1
+            pbar.update(1)
+            # Skip the frame if it is similar to the previous one
+            if prev_processed_frame is not None and _similar_frame(
+                prev_processed_frame,
+                curr_processed_frame,
+                threshold=motion_detection_threshold,
+            ):
+                skipped_count += 1
+                continue
+            prev_processed_frame = curr_processed_frame
+            ts = round(clip.reader.pos / source_fps, 3)
+            frames.append((frame, ts))
+
+        _LOGGER.info(
+            f"""Finished!
+                Frames extracted: {len(frames)}
+                Extracted frame timestamp: {[f[1] for f in frames]}
+                Total processed frames: {total_count}
+                Skipped frames:  {skipped_count}
+                Scan FPS: {fps}
+                Clip start time: {start}s, {clip.pos}
+                Clip end time: {end}s
+                Clip duration: {clip.duration}s
+                Clip total frames: {clip.duration * source_fps}
+                Video duration: {video.duration}s
+                Video FPS: {video.fps}
+                Video total frames: {video.reader.nframes}"""
+        )
+        return frames
+
+
+def _preprocess_frame(frame: np.ndarray) -> np.ndarray:
+    # Convert to grayscale
+    frame = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+    frame = cv2.GaussianBlur(src=frame, ksize=(5, 5), sigmaX=0)
+    return frame
+
+
+def _similar_frame(
+    prev_frame: np.ndarray, curr_frame: np.ndarray, threshold: float
+) -> bool:
+    """Detect two frames are similar or not
+
+    Parameters:
+        threshold: similarity threshold, a value between 0-1, the percentage change that is considered a different frame.
+    """
+    # calculate difference and update previous frame TODO: don't assume the processed image is cached
+    diff_frame = cv2.absdiff(src1=prev_frame, src2=curr_frame)
+    # Only take different areas that are different enough (>20 / 255)
+    thresh_frame = cv2.threshold(
+        src=diff_frame, thresh=20, maxval=255, type=cv2.THRESH_BINARY
+    )[1]
+    change_percentage = cv2.countNonZero(thresh_frame) / (
+        curr_frame.shape[0] * curr_frame.shape[1]
+    )
+    _LOGGER.debug(f"Image diff: {change_percentage}")
+    return change_percentage < threshold