vpdq 0.2.1__tar.gz → 0.2.2__tar.gz

{vpdq-0.2.1/python/vpdq.egg-info → vpdq-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: vpdq
-Version: 0.2.1
+Version: 0.2.2
 Summary: Python bindings for Facebook VPDQ hash
 Author-email: Meta <threatexchange@meta.com>
 License: Copyright (c) 2017- Facebook

{vpdq-0.2.1 → vpdq-0.2.2}/README.md

@@ -1,15 +1,22 @@
 # Summary
+
 vPDQ (Video PDQ) is a video-similarity-detection algorithm, which uses the PDQ image similarity algorithm on video frames to measure the similarity of videos.
 Full details of PDQ are located in the [hashing.pdf](https://github.com/facebook/ThreatExchange/blob/main/hashing/hashing.pdf) document.
 It allows for matching individual frames against known bad images, as well as which segments of a video are matching.
+
+See [CPP implementation](#cpp-implementation) for how to install and use vpdq.
+
 ## Compared to TMK+PDQF
+
 Compared to TMK+PDQF (TMK), which also relies on the PDQ image hashing algorithm:
 TMK optimizes for identical videos (same length), vPDQ can match subsequences or clips within videos.
 TMK has a fixed-length hash, which simplifies matching lookup, and can be near constant time with the help of FAISS. vPDQ produces a variable length hash, and requires a linear comparison of candidates. This requires either an O(n*F<sub>c</sub>*F<sub>q</sub>) lookup where n is the number of videos being compared, and F<sub>c</sub> is the average number of frames per compared video and F<sub>q</sub> is the number of frames in the source video, or an initial filtering pass to reduce the candidates, which can potentially discard matching videos.
 Both TMK and vPDQ are backed by PDQ, and so inherit both PDQ’s strengths and weaknesses.
 
-# Description of Algorithm
-## Producing a Hash
+## Description of Algorithm
+
+### Producing a Hash
+
 The algorithm for producing the “hash” is simple: given a video, convert it into a sequence of frame images at some interval (for example, 1 frame/second). For each frame image, use the PDQ hashing algorithm on each.
 
 We can annotate these hashes with their frame number, quality(0-100 which measures gradients/features,from least featureful to most featureful) and timestamp(sec). So for a 5 minute video at 1 frame/sec, we might have:
@@ -26,26 +33,28 @@ We can annotate these hashes with their frame number, quality(0-100 which measur
 For the matching algorithm, the frame numbers are not used, but they can still be useful for identifying matching segments when comparing videos.
 
 ### Pruning Frames
+
 Often, many frames are repeated in a video, or frames are very close to each other in PDQ distance. It is possible to reduce the number of frames in a hash by omitting subsequent frames that are within a distance D<sub>prune</sub> of the last retained frame.
 
 In the previous example, with D<sub>prune</sub> of 2 we might instead end up with:
 | Frame | PDQ Hash | Distance from last retained frame| Result |
 | ------------- | ------------- | ------------- |------------- |
-| 1  | face000...  | N/A | Retain
-| 2  | face000...  | 0 | Prune
-| 3  | face011...  | 2 | Prune
-| 4  | face111...  | 3 | Retain
-| 5  | face111...  | 0 | Prune
+| 1  | face000...  | N/A | Retain |
+| 2  | face000...  | 0 | Prune |
+| 3  | face011...  | 2 | Prune |
+| 4  | face111...  | 3 | Retain |
+| 5  | face111...  | 0 | Prune |
 | ... | ...  | ... | ... |
 
 Afterwards, what is left is:
-| Frame | PDQ Hash
+| Frame | PDQ Hash |
 | ------------- | ------------- |
 | 1  | face000...  |
 | 4  | face111...  |
 | ... | ...  |
 
-## Comparison (Matching) Algorithm
+### Comparison (Matching) Algorithm
+
 There are four inputs to the comparison algorithm, which determines if two videos are considered similar by vPDQ:
 
 1. The query video’s frame PDQ hashes Q
@@ -62,7 +71,8 @@ There are four inputs to the comparison algorithm, which determines if two video
     - Using P<sub>c</sub> = 100% and P<sub>q</sub> = 100% will attempt to find only videos with the exact same frame content
 
 Here is the algorithm, in pseudocode:
-```
+
+```python
 q_unique_frames  = set(Q)
 c_unique_frames  = set(C)
 q_unique_frames_matched_count = 0
@@ -89,11 +99,11 @@ is_match = c_pct_matched >= P_c and q_pct_matched >= P_q
 
 > **Note**: The frame number and the timestamp is not used at all in this comparison. The frames are treated as an unordered “bag of hashes”. The frame number and timestamp are included in each feature in the reference implementation in case of future expansion.
 
-
 ### Pruning Candidates
+
 When the number of potential candidates is high, the n*F<sub>c</sub>*F<sub>q</sub> algorithm might be too expensive to run. One potential solution for filtering is indexing frames from candidate videos into an index like FAISS, keyed to the video to compare. Our lookup algorithm then becomes:
 
-```
+```python
 candidate_video_ids = set()
 
 for q_frame in Q:
@@ -112,22 +122,42 @@ for c_id in candidate_video_ids:
 
 Beyond pruning frames from candidates, it may be desirable to further prune to just sampled or key frames in candidate videos to control index size, but this may result in videos being incorrectly pruned.
 
-# CPP Implementation
-This implementation does not have Pruning Frames and Pruning Candidates.
+## CPP Implementation
+
+The reference implementation for vpdq is written in C++. In addition, there are [Python bindings](#python-binding) to allow the use of vpdq from Python.
+
+> **Note**: This implementation does not have Pruning Frames and Pruning Candidates.
+
+The C++ implementation requires some external libraries to build.
+
+ Follow the [manual installation guide](#manual-installation) below for how to build vpdq. Alternatively, a [Dockerfile](../Dockerfile.vpdq) and devcontainer config are provided for convience.
+
+## Docker Development
+
+Docker can be used for development, preferably using a devcontainer with VSCode.
+
+Build the Docker image:
+
+```sh
+# ThreatExchage/
+docker build -t vpdq . -f Dockerfile.vpdq
+```
+
+After building the image, you can easily connect to it using the VSCode devcontainer extension. See [the VSCode devcontainer tutorial](https://code.visualstudio.com/docs/devcontainers/containers#_quick-start-open-an-existing-folder-in-a-container) for more information.
 
-## Build Dependencies
+Once you are in the container proceed to [**Building**](#building).
 
-* C++14
-* CMake
-* make
-* FFmpeg and libav* libraries
+## Manual Installation
 
-#### MacOS on Apple M1
+### Dependencies
 
-* Currently the builtin Apple clang g++ does not work for building this implementation
-* Installing GCC and updating the `CMake`s CXX to use that version of g++ instead is recommended
+- C++14
+- CMake
+- pkg-config
+- make
+- FFmpeg and libav* libraries
 
-## Install FFmpeg
+### Install FFmpeg
 
 [FFmpeg](https://ffmpeg.org/) and its [libav* libraries](https://trac.ffmpeg.org/wiki/Using%20libav*) must be installed before building.
 
@@ -140,6 +170,7 @@ macOS: `brew install ffmpeg`
 Windows MinGW/MSYS2: `pacman -S mingw-w64-x86_64-ffmpeg`
 
 To check if it's installed:
+
 ```sh
 $ ffmpeg
 ffmpeg version 4.4.2 Copyright (c) 2000-2023 the FFmpeg developers
@@ -148,21 +179,19 @@ ffmpeg version 4.4.2 Copyright (c) 2000-2023 the FFmpeg developers
 
 > **Note**: The actual version information displayed here may vary from one system to another; but if a message such as `ffmpeg: command not found` appears instead of the version information, FFmpeg is not properly installed.
 
+### Install libav*
 
-## Install libav*
-
-Some package managers will install the libav* libraries bundled with FFmpeg.
-
-If they don't you will need to install them separately.
+Some package managers will install the libav* libraries bundled with FFmpeg. But if yours does not then you will need to install them manually.
 
 Required:
- - libavdevice
- - libavfilter
- - libavformat
- - libavcodec
- - libswresample
- - libswscale
- - libavutil
+
+- libavdevice
+- libavfilter
+- libavformat
+- libavcodec
+- libswresample
+- libswscale
+- libavutil
 
 Debian/Ubuntu:
 
@@ -170,36 +199,57 @@ Debian/Ubuntu:
 sudo apt-get install -y libavdevice-dev libavfilter-dev libavformat-dev libavcodec-dev libswresample-dev libswscale-dev libavutil-dev
 ```
 
+All dependencies should now be installed. Proceed to [**Building**](#building).
+
 ## Building
 
-In vpdq/cpp:
+Build using the usual CMake commands:
+
 ```sh
-mkdir build
-cd build
-cmake ..
-make
+# vpdq/cpp
+# Generate CMake project
+cmake -S . -B build
+# Build
+cmake --build build -j
 ```
 
-This will produce 3 executable programs:
- - vpdq-hash-video
- - match-hashes-byline
- - match-hashes-brute 
- 
-Run the executables with `-h` or see below for usage information.
+> **Note:** The CMake files will respect your `-DCMAKE_BUILD_TYPE` option.
+>
+> For example, to build with optimizations pass `-DCMAKE_BUILD_TYPE=Release` to the generator command (the first one above).
+>
+> To build with optimizations and debug info, pass `-DCMAKE_BUILD_TYPE=RelWithDebInfo`.
+>
+> There is also a custom `Asan` and `Tsan` build type to compile with address/thread sanitizers (Linux only).
+>
+> See [CMAKE_BUILD_TYPE documentation](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html) for more information.
+
+This will build both the library and 3 CLI programs:
+
+- vpdq-hash-video
+- match-hashes-byline
+- match-hashes-brute
+
+The CLI programs will be found in `build/apps`.
+
+The vpdq library will be located at `build/vpdq/libvpdqlib.a`.
+
+Run the CLI programs with `-h` to see their usage information.
 
 ## Usage
 
+Some Python scripts are used for testing the C++ implementation, but they do not require the Python binding to be installed. These scripts are located in the [cpp](./cpp) folder.
+
 This demo shows how to use `vpdq_match.py` to compare one target hash with all the queried hashes in the `sample-hashes`.
 
 The target hash must be generated with vpdq-hash-video before running.
 
-#### Brute-force matching
+### Brute-force matching
 
-In vpdq/cpp:
 ```sh
+# vpdq/cpp
 python vpdq_match.py -f sample-hashes -i output-hashes/chair-19-sd-bar.txt
-
 ```
+
 Sample Output:
 
 ```sh
@@ -220,12 +270,13 @@ Matching Target ../ThreatExchange/vpdq/cpp/sampletest/chair-19-sd-bar.txt with .
 ---
 
 #### Regression Test
+
 An additional Python script, `regtest.py` can be used to test for changes in output during development.
 
 It hashes the provided sample videos and compares them with known good hashes from `sample-hashes` line by line.
 
-In vpdq/cpp:
 ```sh
+# vpdq/cpp
 python regtest.py
 
 Matching File pattern-sd-with-small-logo-bar.txt
@@ -244,23 +295,25 @@ Matching File chair-22-with-small-logo-bar.txt
 100.000000 Percentage  matches
 ```
 
-## vPDQ Python Binding
-A Cython binding is available to the CPP library for linux and Mac users. All of the dependencies from the CPP implementation are required to build the binding.
+### Python Binding
 
-See [README.md in `python/`](./python/README.md) for more information.
+A Cython binding is available to that using the C++ library for Linux and macos.
+
+All of the dependencies from the C++ implementation are required to build the binding.
 
 ```sh
 pip install vpdq
 ```
 
+See [README.md in `python/`](./python/README.md) for more information.
 
 ## FAISS
+
 [FAISS](https://github.com/facebookresearch/faiss) has been successfully integrated with vPDQ in the [python-threatexchange](../python-threatexchange/threatexchange/extensions/vpdq) library. See the [README](../python-threatexchange/threatexchange/extensions/vpdq/README.md) for more information.
 
 ## Contact
 
-threatexchange@fb.com
-
+threatexchange@meta.com
 
 ---
 

vpdq-0.2.2/cpp/CMakeLists.txt

@@ -0,0 +1,99 @@
+# Top level CMake for vpdq
+# This will build vpdq, pdq, and the vpdq CLI programs.
+
+cmake_minimum_required(VERSION 3.17)
+
+project(vpdq LANGUAGES CXX)
+set(CMAKE_CXX_STANDARD 14)
+
+# Sanitizer build type options.
+# This allows you to build with address/thread sanitizer by using
+# -DCMAKE_BUILD_TYPE=Asan or Tsan on the generator.
+# From https://stackoverflow.com/a/64294837
+if(NOT MSVC)
+get_property(isMultiConfig GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
+
+if(isMultiConfig)
+    if(NOT "Asan" IN_LIST CMAKE_CONFIGURATION_TYPES)
+        list(APPEND CMAKE_CONFIGURATION_TYPES Asan)
+    endif()
+    if(NOT "Tsan" IN_LIST CMAKE_CONFIGURATION_TYPES)
+        list(APPEND CMAKE_CONFIGURATION_TYPES Tsan)
+    endif()
+else()
+    set(allowedBuildTypes Asan Tsan Debug Release RelWithDebInfo MinSizeRel)
+    set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "${allowedBuildTypes}")
+
+    if(CMAKE_BUILD_TYPE AND NOT CMAKE_BUILD_TYPE IN_LIST allowedBuildTypes)
+        message(FATAL_ERROR "Invalid build type: ${CMAKE_BUILD_TYPE}")
+    endif()
+endif()
+
+# Asan
+set(CMAKE_C_FLAGS_ASAN
+    "${CMAKE_C_FLAGS_DEBUG} -fsanitize=address,leak,undefined -fno-omit-frame-pointer" CACHE STRING
+    "Flags used by the C compiler for Asan build type or configuration." FORCE)
+
+set(CMAKE_CXX_FLAGS_ASAN
+    "${CMAKE_CXX_FLAGS_DEBUG} -fsanitize=address,leak,undefined -fno-omit-frame-pointer" CACHE STRING
+    "Flags used by the C++ compiler for Asan build type or configuration." FORCE)
+
+set(CMAKE_EXE_LINKER_FLAGS_ASAN
+    "${CMAKE_EXE_LINKER_FLAGS_DEBUG} -fsanitize=address,leak,undefined" CACHE STRING
+    "Linker flags to be used to create executables for Asan build type." FORCE)
+
+set(CMAKE_SHARED_LINKER_FLAGS_ASAN
+    "${CMAKE_SHARED_LINKER_FLAGS_DEBUG} -fsanitize=address,leak,undefined" CACHE STRING
+    "Linker lags to be used to create shared libraries for Asan build type." FORCE)
+
+# Tsan
+set(CMAKE_C_FLAGS_TSAN
+    "${CMAKE_C_FLAGS_DEBUG} -fsanitize=thread,undefined -fno-omit-frame-pointer" CACHE STRING
+    "Flags used by the C compiler for Asan build type or configuration." FORCE)
+
+set(CMAKE_CXX_FLAGS_TSAN
+    "${CMAKE_CXX_FLAGS_DEBUG} -fsanitize=thread,undefined -fno-omit-frame-pointer" CACHE STRING
+    "Flags used by the C++ compiler for Asan build type or configuration." FORCE)
+
+set(CMAKE_EXE_LINKER_FLAGS_TSAN
+    "${CMAKE_EXE_LINKER_FLAGS_DEBUG} -fsanitize=thread,undefined" CACHE STRING
+    "Linker flags to be used to create executables for Tsan build type." FORCE)
+
+set(CMAKE_SHARED_LINKER_FLAGS_TSAN
+    "${CMAKE_SHARED_LINKER_FLAGS_DEBUG} -fsanitize=thread,undefined" CACHE STRING
+    "Linker lags to be used to create shared libraries for Tsan build type." FORCE)
+endif()
+
+
+# Find Threads for C++ multithreading
+set(CMAKE_THREAD_PREFER_PTHREAD TRUE)
+set(THREADS_PREFER_PTHREAD_FLAG ON)
+find_package(Threads REQUIRED)
+
+# Find libav* FFmpeg libraries using pkg-config
+find_package(PkgConfig REQUIRED)
+pkg_check_modules(LIBAV REQUIRED IMPORTED_TARGET
+    libavdevice
+    libavfilter
+    libavformat
+    libavcodec
+    libswresample
+    libswscale
+    libavutil
+)
+
+# pdq library
+add_subdirectory(pdq)
+
+# vpdq library
+add_subdirectory(vpdq)
+
+# CLI programs
+# TODO: Make this a custom command/option. This isn't necessary to just build the library.
+add_subdirectory(apps)
+
+# Write the libav* library dirs to a new-line delimited file for Cython to be able to locate LIBAV files
+# TODO: Make this a custom command or something. This isn't necessary on every run.
+string(REPLACE ";" "\n" LIBRARY_DIRS "${LIBAV_STATIC_LIBRARY_DIRS}")
+set(LIBRARY_DIRS_FILE "libraries-dirs.txt")
+file(WRITE ${LIBRARY_DIRS_FILE} "${LIBRARY_DIRS}")

vpdq-0.2.2/cpp/apps/CMakeLists.txt

@@ -0,0 +1,9 @@
+# vpdq CLI programs
+
+add_executable(match-hashes-brute match-hashes-brute.cpp)
+add_executable(match-hashes-byline match-hashes-byline.cpp)
+add_executable(vpdq-hash-video vpdq-hash-video.cpp)
+
+target_link_libraries(match-hashes-brute PRIVATE vpdqlib)
+target_link_libraries(match-hashes-byline PRIVATE vpdqlib)
+target_link_libraries(vpdq-hash-video PRIVATE vpdqlib)

vpdq-0.2.2/cpp/pdq/CMakeLists.txt

@@ -0,0 +1,37 @@
+# PDQ library
+# This will produce one library file: libpdqlib
+
+set(PDQSOURCES
+    cpp/common/pdqhashtypes.cpp
+    cpp/hashing/pdqhashing.cpp
+    cpp/common/pdqhamming.cpp
+    cpp/io/hashio.cpp
+    cpp/downscaling/downscaling.cpp
+    cpp/hashing/torben.cpp
+)
+
+set(PDQHEADERS
+    cpp/common/pdqhashtypes.h
+    cpp/common/pdqbasetypes.h
+    cpp/common/pdqhamming.h
+    cpp/hashing/pdqhashing.h
+    cpp/io/hashio.h
+    cpp/downscaling/downscaling.h
+    cpp/hashing/torben.h
+)
+
+# Note: Including header files here helps IDEs, but is not required.
+add_library(pdqlib ${PDQHEADERS} ${PDQSOURCES})
+
+# We need this directory, and users of the library will need it too.
+target_include_directories(pdqlib PUBLIC
+    # We go up a directory so that the source files can include the
+    # whole path, e.g. <pdq/cpp/common/pdqbasetypes.h>
+    ${CMAKE_CURRENT_SOURCE_DIR}/..
+)
+
+# Turn on -fPIC
+set_target_properties(pdqlib PROPERTIES POSITION_INDEPENDENT_CODE ON)
+
+# All users of this library will need at least C++11
+target_compile_features(pdqlib PUBLIC cxx_std_11)

{vpdq-0.2.1 → vpdq-0.2.2}/cpp/pdq/cpp/hashing/torben.cpp

@@ -1,13 +1,15 @@
 // ================================================================
-// The following code is public domain.
-// Algorithm by Torben Mogensen, implementation by N. Devillard.
-// This code in public domain.
+// Copyright (c) Meta Platforms, Inc. and affiliates.
 // ================================================================
 
 namespace facebook {
 namespace pdq {
 namespace hashing {
 
+/**
+ * The following code is public domain.
+ * Algorithm by Torben Mogensen, implementation by N. Devillard.
+ */
 float torben(float m[], int n) {
   int i, less, greater, equal;
   float min, max, guess, maxltguess, mingtguess;

{vpdq-0.2.1 → vpdq-0.2.2}/cpp/pdq/cpp/hashing/torben.h

@@ -1,20 +1,18 @@
 // ================================================================
-// The following code is public domain.
-// Algorithm by Torben Mogensen, implementation by N. Devillard.
-// This code in public domain.
+// Copyright (c) Meta Platforms, Inc. and affiliates.
 // ================================================================
 
 #ifndef TORBEN_H
 #define TORBEN_H
-/*
- * The following code is public domain.
- * Algorithm by Torben Mogensen, implementation by N. Devillard.
- * This code in public domain.
- */
 
 namespace facebook {
 namespace pdq {
 namespace hashing {
+
+/**
+ * The following code is public domain.
+ * Algorithm by Torben Mogensen, implementation by N. Devillard.
+ */
 float torben(float m[], int n);
 } // namespace hashing
 } // namespace pdq

{vpdq-0.2.1 → vpdq-0.2.2}/cpp/regtest.py

@@ -1,5 +1,6 @@
 # Copyright (c) Meta Platforms, Inc. and affiliates.
 
+import os
 import subprocess
 import sys
 import argparse
@@ -14,7 +15,7 @@ import csv
 DIR = Path(__file__).parent
 VPDQ_DIR = DIR.parent
 SAMPLE_HASHES_DIR = VPDQ_DIR / "sample-hashes"
-EXEC_DIR = VPDQ_DIR / "cpp/build"
+EXEC_DIR = VPDQ_DIR / "cpp/build/apps"
 
 
 def get_os() -> str:
@@ -130,7 +131,11 @@ def main():
 
     # Run the hashing and matching tests for single and multithreaded
     for thread_count in range(0, 2):
-        print(f"Threads: {thread_count}")
+        if thread_count == 0:
+            num_cpu_cores = os.cpu_count()
+            print(f"Number of hashing threads: auto. Probably {num_cpu_cores} threads.")
+        else:
+            print(f"Number of hashing threads: {thread_count}")
         with TemporaryDirectory() as tempOutputHashFolder:
             tempOutputHashFolder = Path(tempOutputHashFolder)
 

vpdq-0.2.2/cpp/vpdq/CMakeLists.txt

@@ -0,0 +1,52 @@
+# VPDQ library
+# This will produce one library file: libvpdqlib
+
+set(VPDQSOURCES
+    cpp/hashing/bufferhasher.cpp
+    cpp/hashing/filehasher.cpp
+    cpp/hashing/ffmpegutils.cpp
+    cpp/hashing/ffmpegwrapper.cpp
+    cpp/hashing/matchTwoHash.cpp
+    cpp/io/vpdqio.cpp
+)
+
+set(VPDQHEADERS
+    cpp/hashing/bufferhasher.h
+    cpp/hashing/filehasher.h
+    cpp/hashing/ffmpegutils.h
+    cpp/hashing/ffmpegwrapper.h
+    cpp/hashing/hasher.h
+    cpp/hashing/vpdqHashType.h
+    cpp/hashing/matchTwoHash.h
+    cpp/io/vpdqio.h
+)
+
+# Make an automatic library - will be static or dynamic based on user setting.
+# Note: Including header files here helps IDEs, but is not required.
+add_library(vpdqlib ${VPDQSOURCES} ${VPDQHEADERS})
+
+# We need this directory, and users of the library will need it too.
+target_include_directories(vpdqlib PUBLIC
+    # We go up a directory so that the source files can include the
+    # whole path, e.g. <vpdq/cpp/hashing/vpdqHashType.h>
+    ${CMAKE_CURRENT_SOURCE_DIR}/..
+)
+
+target_link_libraries(vpdqlib PUBLIC PkgConfig::LIBAV Threads::Threads pdqlib)
+
+# All users of this library will need at least C++14
+target_compile_features(vpdqlib PUBLIC cxx_std_14)
+
+# Turn on -fPIC
+set_target_properties(vpdqlib PROPERTIES POSITION_INDEPENDENT_CODE ON)
+
+if(NOT MSVC)
+    set(VPDQ_WARNING_FLAGS
+        -Wall
+        -Wextra
+        -Wpedantic
+        -Werror
+        -Wno-error=deprecated-declarations # Avoid compile error if something gets deprecated. Warning will still show up.
+    )
+    target_compile_options(vpdqlib PRIVATE ${VPDQ_WARNING_FLAGS})
+endif()

vpdq-0.2.2/cpp/vpdq/cpp/hashing/ffmpegutils.cpp

@@ -0,0 +1,68 @@
+// ================================================================
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// ================================================================
+
+#include <algorithm>
+#include <cstdio>
+#include <fstream>
+#include <iostream>
+#include <memory>
+#include <string>
+
+#include <vpdq/cpp/hashing/ffmpegutils.h>
+#include <vpdq/cpp/hashing/ffmpegwrapper.h>
+
+extern "C" {
+#include <libavcodec/avcodec.h>
+#include <libavformat/avformat.h>
+#include <libavutil/frame.h>
+#include <libavutil/imgutils.h>
+#include <libavutil/log.h>
+#include <libavutil/mem.h>
+#include <libswscale/swscale.h>
+}
+
+namespace facebook {
+namespace vpdq {
+namespace hashing {
+namespace ffmpeg {
+
+void saveFrameToFile(AVFramePtr frame, const std::string& filename) {
+  if (!frame) {
+    throw std::invalid_argument("Cannot save frame to file. Frame is null.");
+  }
+
+  std::ofstream outfile(filename, std::ios::out | std::ios::binary);
+  if (!outfile) {
+    throw std::runtime_error("Cannot save frame to file " + filename);
+  }
+
+  for (int y = 0; y < frame->height; y++) {
+    outfile.write(
+        reinterpret_cast<const char*>(frame->data[0] + y * frame->linesize[0]),
+        frame->width * 3);
+  }
+  outfile.close();
+}
+
+AVFramePtr createRGB24Frame(size_t const width, size_t const height) {
+  AVFramePtr frame(av_frame_alloc());
+  if (frame.get() == nullptr) {
+    throw std::bad_alloc();
+  }
+
+  frame->format = PIXEL_FORMAT;
+  frame->width = width;
+  frame->height = height;
+
+  if (av_image_alloc(
+          frame->data, frame->linesize, width, height, PIXEL_FORMAT, 1) < 0) {
+    throw std::bad_alloc();
+  }
+  return frame;
+}
+
+} // namespace ffmpeg
+} // namespace hashing
+} // namespace vpdq
+} // namespace facebook