<div align="center">
<img src="https://raw.githubusercontent.com/demmenie/videohash2/main/assets/logo/logo-optimized.svg"><br>
</div>
<h2 align="center"> The Python package for near duplicate video detection </h2>
<p align="center">
<a href="https://github.com/demmenie/videohash2/actions?query=workflow%3AUbuntu"><img alt="Build Status" src="https://github.com/demmenie/videohash2/workflows/Ubuntu/badge.svg"></a>
<a href="https://github.com/demmenie/videohash2/actions?query=workflow%3AWindows"><img alt="Build Status" src="https://github.com/demmenie/videohash2/workflows/Windows/badge.svg"></a>
<a href="https://github.com/demmenie/videohash2/actions?query=workflow%3AmacOS"><img alt="Build Status" src="https://github.com/demmenie/videohash2/workflows/macOS/badge.svg"></a>
<a href="https://pypi.org/project/videohash2/"><img alt="pypi" src="https://img.shields.io/pypi/v/videohash2.svg"></a>
<a href="https://pepy.tech/project/videohash2?versions=1*&versions=2*&versions=3*"><img alt="Downloads" src="https://pepy.tech/badge/videohash2"></a>
<a href="https://github.com/demmenie/videohash2/commits/main"><img alt="GitHub lastest commit" src="https://img.shields.io/github/last-commit/demmenie/videohash2?color=blue&style=flat-square"></a>
<a href="#"><img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/videohash2?style=flat-square"></a>
</p>
--------------------------------------------------------------------------
# <img src="https://github.githubassets.com/images/icons/emoji/unicode/2b50.png" width="30"></img> Introduction
Videohash2 is a [Python package](https://www.udacity.com/blog/2021/01/what-is-a-python-package.html) for **detecting near-duplicate videos (Perceptual Video Hashing)**.
It can take any input video and generate a 64-bit equivalent hash value. Videohash is way faster than comparing the imagehash values of individual [frames](https://en.wikipedia.org/wiki/Film_frame) of the video and more reliable than hashing [keyframes](https://en.wikipedia.org/wiki/Key_frame).
The video-hash-values for identical or near-duplicate videos are the same or similar, implying that if the video is resized (upscaled/downscaled), [transcoded](https://medium.com/videocoin/what-is-video-transcoding-and-why-do-you-do-it-348a2610cefc), [watermark](https://en.wikipedia.org/wiki/Digital_watermarking) added/removed, [stabilized](https://link.springer.com/referenceworkentry/10.1007%2F978-0-387-78414-4_76), [color changed](https://en.wikipedia.org/wiki/Chrominance), [frame rate](https://www.techsmith.com/blog/frame-rate-beginners-guide/) changed, changed [aspect ratio](https://en.wikipedia.org/wiki/Aspect_ratio_(image)), [cropped](https://www.avs4you.com/blog/trim-cut-crop-avs4you/), [black-bars](https://en.wikipedia.org/wiki/Letterboxing_(filming)) added or removed, the hash-value should remain unchanged or not vary substantially.
### How the hash values are calculated
> - Every one second, a frame from the input video is extracted, the frames are shrunk to a 144x144 pixel square, a collage is constructed that contains all of the resized frames(square-shaped), the collage's [wavelet hash](https://fullstackml.com/wavelet-image-hash-in-python-3504fdd282b5)'s bit-list is the first bit-list that we use. The frames extracted are now stitched horizontally to each other, and finally divided into 64 equal sized images, the dominant color of these 64 images are detected and compared with a pre-defined pattern of dominant colours, if they match the bit is set else unset. So now we have two bitlists, finally we bitwise XOR these two bitlists. The XOR'ed output is used to generate the final 64 bit hash-value for the video. The bits are joined to form the 64 bit hash-value of the input value.
### When not to use Videohash
> - Videohash cannot be used to verify whether one video is part of another (video fingerprinting). If the video is reversed or rotated by a substantial angle (greater than 10 degrees), Videohash will not provide the same or similar hash result, but you can always reverse the video manually and generate the hash value for reversed video.
### How to compare the video hash values stored in a database
> - Read [Hamming Distance / Similarity searches in a database - Stack Overflow](https://stackoverflow.com/questions/9606492/hamming-distance-similarity-searches-in-a-database) [(Archive link)](https://web.archive.org/web/20211015120052/https://stackoverflow.com/questions/9606492/hamming-distance-similarity-searches-in-a-database)
--------------------------------------------------------------------------
## <img src="https://github.githubassets.com/images/icons/emoji/unicode/1f3d7.png" width="20"></img> Installation
To use this software, you must have [FFmpeg](https://ffmpeg.org/) installed. Please read [how to install FFmpeg](https://github.com/demmenie/videohash2/wiki/Install-FFmpeg,-but-how%3F) if you don't already know how.
#### Install videohash2
Upgrade pip
```bash
python3 -m pip install --upgrade pip
```
If you do not want to upgrade pip and the installation fails try appending `--prefer-binary` to the following installation command(s).
**Install from the [PyPi](https://pypi.org/) (recommended)**:
```bash
pip install videohash2
```
**Install directly from [the](https://github.com/demmenie/videohash2) GitHub repository (NOT recommended)**:
```bash
pip install git+https://github.com/demmenie/videohash2.git
```
--------------------------------------------------------------------------
### Features
- Generate videohash of a video directly from its URL(uses [yt-dlp](https://github.com/yt-dlp/yt-dlp)) or its path.
- Can be used as the core of a scalable Near Duplicate Video Retrieval (NDVR) system.
- The end-user can access the image representation(the collage) of the video.
- A videohash instance can be compared to a 64-bit stored hash, its hex representation, bitlist, and other videohash instances.
--------------------------------------------------------------------------
## <img src="https://github.githubassets.com/images/icons/emoji/unicode/1f680.png" width="20"></img> Usage
In the following usage example the first two and the fourth instance of VideoHash class are computing the hash for the same video(not same as in checksum) and the third one is a different video.
- videohash1 is the VideoHash object for the video at <https://user-images.githubusercontent.com/64683866/168872267-7c6682f8-7294-4d9a-8a68-8c6f44c06df6.mp4>.
- videohash2 video (link : <https://user-images.githubusercontent.com/64683866/168869109-1f77c839-6912-4e24-8738-42cb15f3ab47.mp4>) is upscaled, FPS changed and a text overlay added version of the first video, url1 at <https://user-images.githubusercontent.com/64683866/168872267-7c6682f8-7294-4d9a-8a68-8c6f44c06df6.mp4>.
- videohash3 video is a completely different video, at <https://user-images.githubusercontent.com/64683866/148960165-a210f2d2-6c41-4349-bd8d-a4cb673bc0af.mp4>.
- videohash4 video is a local copy of url1, <https://user-images.githubusercontent.com/64683866/168872267-7c6682f8-7294-4d9a-8a68-8c6f44c06df6.mp4>.
```python
>>> from videohash2 import VideoHash
>>> url1 = "https://user-images.githubusercontent.com/64683866/168872267-7c6682f8-7294-4d9a-8a68-8c6f44c06df6.mp4"
>>> videohash1 = VideoHash(url=url1)
>>>
>>> url2 = "https://user-images.githubusercontent.com/64683866/168869109-1f77c839-6912-4e24-8738-42cb15f3ab47.mp4"
>>> videohash2 = VideoHash(url=url2)
>>> videohash2 - videohash1
2
>>> videohash2.is_similar(videohash1)
True
>>>
>>> url3 = "https://user-images.githubusercontent.com/64683866/148960165-a210f2d2-6c41-4349-bd8d-a4cb673bc0af.mp4"
>>> videohash3 = VideoHash(url=url3)
>>> videohash3.is_similar(videohash1)
False
>>> videohash3.is_diffrent(videohash2)
True
>>> videohash3-videohash1
34
>>> videohash3-videohash2
34
>>> path4 = "/home/demmenie/Downloads/168872267-7c6682f8-7294-4d9a-8a68-8c6f44c06df6.mp4"
>>> videohash4 = VideoHash(path=path4)
>>> videohash4 == videohash1
True
>>> videohash4 - videohash1
0
>>> videohash4.is_similar(videohash2)
True
>>> videohash4.is_similar(videohash4)
True
>>> videohash4.is_similar(videohash3)
False
>>>
```
**Extended Usage** : <https://github.com/demmenie/videohash2/wiki/Extended-Usage>
**API Reference** : <https://github.com/demmenie/videohash2/wiki/API-Reference>
--------------------------------------------------------------------------
### Credits
- [JohannesBuchner](https://github.com/JohannesBuchner) and [bunchesofdonald](https://github.com/bunchesofdonald) for [imagehash](https://github.com/JohannesBuchner/imagehash).
- [Dmitry Petrov](https://medium.com/@fullstackml) for [implementing](https://fullstackml.com/wavelet-image-hash-in-python-3504fdd282b5) [discrete wavelet transform](https://en.wikipedia.org/wiki/Discrete_wavelet_transform) (DWT) based image hashing in Python.
- [FFmpeg developers](https://ffmpeg.org/consulting.html).
- [Sam Dobson](https://github.com/samdobson) for [image_slicer](https://github.com/samdobson/image_slicer), videohash incorporates some code from image_slicer.
- [Eddievin](https://github.com/Eddievin) for README design.
- [iconolocode](https://github.com/iconolocode) for the videohash logo.
- [Demmenie](https://github.com/demmenie) for forking and maintaining videohash2.
--------------------------------------------------------------------------
### License
[](https://github.com/demmenie/videohash2/blob/main/LICENSE)
Copyright (c) 2024 Akash Mahanty. See
[license](https://github.com/demmenie/videohash2/blob/main/LICENSE) for details.
The VideoHash logo was created by [iconolocode](https://github.com/iconolocode). See [license](https://github.com/demmenie/videohash2/blob/main/assets/logo/LICENSE-LOGO) for details.
Videos are from NASA and are in the public domain.
> NASA copyright policy states that "NASA material is not protected by copyright unless noted".
Raw data
{
"_id": null,
"home_page": "https://demmenie.github.io/videohash2/",
"name": "videohash2",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "videohash2, near duplicate video detection, NDVD, perceptual video hashing, video hashing, near duplicate video, compare videos, video, video diff",
"author": "Akash Mahanty and Chico Demmenie",
"author_email": "cdemmenie@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/2e/d3/472dfee3e0397ad5b9ab4e54dfab01ca89bdd32ff4f99fd9a1ea68b68e3c/videohash2-3.2.2.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n<img src=\"https://raw.githubusercontent.com/demmenie/videohash2/main/assets/logo/logo-optimized.svg\"><br>\n</div>\n\n<h2 align=\"center\"> The Python package for near duplicate video detection </h2>\n\n<p align=\"center\">\n<a href=\"https://github.com/demmenie/videohash2/actions?query=workflow%3AUbuntu\"><img alt=\"Build Status\" src=\"https://github.com/demmenie/videohash2/workflows/Ubuntu/badge.svg\"></a>\n<a href=\"https://github.com/demmenie/videohash2/actions?query=workflow%3AWindows\"><img alt=\"Build Status\" src=\"https://github.com/demmenie/videohash2/workflows/Windows/badge.svg\"></a>\n<a href=\"https://github.com/demmenie/videohash2/actions?query=workflow%3AmacOS\"><img alt=\"Build Status\" src=\"https://github.com/demmenie/videohash2/workflows/macOS/badge.svg\"></a>\n<a href=\"https://pypi.org/project/videohash2/\"><img alt=\"pypi\" src=\"https://img.shields.io/pypi/v/videohash2.svg\"></a>\n<a href=\"https://pepy.tech/project/videohash2?versions=1*&versions=2*&versions=3*\"><img alt=\"Downloads\" src=\"https://pepy.tech/badge/videohash2\"></a>\n<a href=\"https://github.com/demmenie/videohash2/commits/main\"><img alt=\"GitHub lastest commit\" src=\"https://img.shields.io/github/last-commit/demmenie/videohash2?color=blue&style=flat-square\"></a>\n<a href=\"#\"><img alt=\"PyPI - Python Version\" src=\"https://img.shields.io/pypi/pyversions/videohash2?style=flat-square\"></a>\n</p>\n\n--------------------------------------------------------------------------\n\n# <img src=\"https://github.githubassets.com/images/icons/emoji/unicode/2b50.png\" width=\"30\"></img> Introduction\n\nVideohash2 is a [Python package](https://www.udacity.com/blog/2021/01/what-is-a-python-package.html) for **detecting near-duplicate videos (Perceptual Video Hashing)**.\nIt can take any input video and generate a 64-bit equivalent hash value. Videohash is way faster than comparing the imagehash values of individual [frames](https://en.wikipedia.org/wiki/Film_frame) of the video and more reliable than hashing [keyframes](https://en.wikipedia.org/wiki/Key_frame).\n\nThe video-hash-values for identical or near-duplicate videos are the same or similar, implying that if the video is resized (upscaled/downscaled), [transcoded](https://medium.com/videocoin/what-is-video-transcoding-and-why-do-you-do-it-348a2610cefc), [watermark](https://en.wikipedia.org/wiki/Digital_watermarking) added/removed, [stabilized](https://link.springer.com/referenceworkentry/10.1007%2F978-0-387-78414-4_76), [color changed](https://en.wikipedia.org/wiki/Chrominance), [frame rate](https://www.techsmith.com/blog/frame-rate-beginners-guide/) changed, changed [aspect ratio](https://en.wikipedia.org/wiki/Aspect_ratio_(image)), [cropped](https://www.avs4you.com/blog/trim-cut-crop-avs4you/), [black-bars](https://en.wikipedia.org/wiki/Letterboxing_(filming)) added or removed, the hash-value should remain unchanged or not vary substantially.\n\n### How the hash values are calculated\n\n> - Every one second, a frame from the input video is extracted, the frames are shrunk to a 144x144 pixel square, a collage is constructed that contains all of the resized frames(square-shaped), the collage's [wavelet hash](https://fullstackml.com/wavelet-image-hash-in-python-3504fdd282b5)'s bit-list is the first bit-list that we use. The frames extracted are now stitched horizontally to each other, and finally divided into 64 equal sized images, the dominant color of these 64 images are detected and compared with a pre-defined pattern of dominant colours, if they match the bit is set else unset. So now we have two bitlists, finally we bitwise XOR these two bitlists. The XOR'ed output is used to generate the final 64 bit hash-value for the video. The bits are joined to form the 64 bit hash-value of the input value.\n\n### When not to use Videohash\n\n> - Videohash cannot be used to verify whether one video is part of another (video fingerprinting). If the video is reversed or rotated by a substantial angle (greater than 10 degrees), Videohash will not provide the same or similar hash result, but you can always reverse the video manually and generate the hash value for reversed video.\n\n### How to compare the video hash values stored in a database\n\n> - Read [Hamming Distance / Similarity searches in a database - Stack Overflow](https://stackoverflow.com/questions/9606492/hamming-distance-similarity-searches-in-a-database) [(Archive link)](https://web.archive.org/web/20211015120052/https://stackoverflow.com/questions/9606492/hamming-distance-similarity-searches-in-a-database)\n\n--------------------------------------------------------------------------\n\n## <img src=\"https://github.githubassets.com/images/icons/emoji/unicode/1f3d7.png\" width=\"20\"></img> Installation\n\nTo use this software, you must have [FFmpeg](https://ffmpeg.org/) installed. Please read [how to install FFmpeg](https://github.com/demmenie/videohash2/wiki/Install-FFmpeg,-but-how%3F) if you don't already know how.\n\n#### Install videohash2\n\nUpgrade pip\n```bash\npython3 -m pip install --upgrade pip\n```\nIf you do not want to upgrade pip and the installation fails try appending `--prefer-binary` to the following installation command(s).\n\n**Install from the [PyPi](https://pypi.org/) (recommended)**:\n\n```bash\npip install videohash2\n```\n\n**Install directly from [the](https://github.com/demmenie/videohash2) GitHub repository (NOT recommended)**:\n\n```bash\npip install git+https://github.com/demmenie/videohash2.git\n```\n\n--------------------------------------------------------------------------\n\n### Features\n\n- Generate videohash of a video directly from its URL(uses [yt-dlp](https://github.com/yt-dlp/yt-dlp)) or its path.\n- Can be used as the core of a scalable Near Duplicate Video Retrieval (NDVR) system.\n- The end-user can access the image representation(the collage) of the video.\n- A videohash instance can be compared to a 64-bit stored hash, its hex representation, bitlist, and other videohash instances.\n\n--------------------------------------------------------------------------\n\n## <img src=\"https://github.githubassets.com/images/icons/emoji/unicode/1f680.png\" width=\"20\"></img> Usage\n\nIn the following usage example the first two and the fourth instance of VideoHash class are computing the hash for the same video(not same as in checksum) and the third one is a different video.\n\n- videohash1 is the VideoHash object for the video at <https://user-images.githubusercontent.com/64683866/168872267-7c6682f8-7294-4d9a-8a68-8c6f44c06df6.mp4>.\n\n- videohash2 video (link : <https://user-images.githubusercontent.com/64683866/168869109-1f77c839-6912-4e24-8738-42cb15f3ab47.mp4>) is upscaled, FPS changed and a text overlay added version of the first video, url1 at <https://user-images.githubusercontent.com/64683866/168872267-7c6682f8-7294-4d9a-8a68-8c6f44c06df6.mp4>.\n\n- videohash3 video is a completely different video, at <https://user-images.githubusercontent.com/64683866/148960165-a210f2d2-6c41-4349-bd8d-a4cb673bc0af.mp4>.\n\n- videohash4 video is a local copy of url1, <https://user-images.githubusercontent.com/64683866/168872267-7c6682f8-7294-4d9a-8a68-8c6f44c06df6.mp4>.\n\n```python\n>>> from videohash2 import VideoHash\n>>> url1 = \"https://user-images.githubusercontent.com/64683866/168872267-7c6682f8-7294-4d9a-8a68-8c6f44c06df6.mp4\"\n>>> videohash1 = VideoHash(url=url1)\n>>> \n>>> url2 = \"https://user-images.githubusercontent.com/64683866/168869109-1f77c839-6912-4e24-8738-42cb15f3ab47.mp4\"\n>>> videohash2 = VideoHash(url=url2)\n>>> videohash2 - videohash1\n2\n>>> videohash2.is_similar(videohash1)\nTrue\n>>> \n>>> url3 = \"https://user-images.githubusercontent.com/64683866/148960165-a210f2d2-6c41-4349-bd8d-a4cb673bc0af.mp4\"\n>>> videohash3 = VideoHash(url=url3)\n>>> videohash3.is_similar(videohash1)\nFalse\n>>> videohash3.is_diffrent(videohash2)\nTrue\n>>> videohash3-videohash1\n34\n>>> videohash3-videohash2\n34\n>>> path4 = \"/home/demmenie/Downloads/168872267-7c6682f8-7294-4d9a-8a68-8c6f44c06df6.mp4\"\n>>> videohash4 = VideoHash(path=path4)\n>>> videohash4 == videohash1\nTrue\n>>> videohash4 - videohash1\n0\n>>> videohash4.is_similar(videohash2)\nTrue\n>>> videohash4.is_similar(videohash4)\nTrue\n>>> videohash4.is_similar(videohash3)\nFalse\n>>> \n```\n\n**Extended Usage** : <https://github.com/demmenie/videohash2/wiki/Extended-Usage>\n\n**API Reference** : <https://github.com/demmenie/videohash2/wiki/API-Reference>\n\n--------------------------------------------------------------------------\n\n\n### Credits\n\n - [JohannesBuchner](https://github.com/JohannesBuchner) and [bunchesofdonald](https://github.com/bunchesofdonald) for [imagehash](https://github.com/JohannesBuchner/imagehash).\n - [Dmitry Petrov](https://medium.com/@fullstackml) for [implementing](https://fullstackml.com/wavelet-image-hash-in-python-3504fdd282b5) [discrete wavelet transform](https://en.wikipedia.org/wiki/Discrete_wavelet_transform) (DWT) based image hashing in Python.\n - [FFmpeg developers](https://ffmpeg.org/consulting.html).\n - [Sam Dobson](https://github.com/samdobson) for [image_slicer](https://github.com/samdobson/image_slicer), videohash incorporates some code from image_slicer.\n - [Eddievin](https://github.com/Eddievin) for README design.\n - [iconolocode](https://github.com/iconolocode) for the videohash logo.\n - [Demmenie](https://github.com/demmenie) for forking and maintaining videohash2.\n \n--------------------------------------------------------------------------\n \n### License\n\n[](https://github.com/demmenie/videohash2/blob/main/LICENSE)\n\nCopyright (c) 2024 Akash Mahanty. See\n[license](https://github.com/demmenie/videohash2/blob/main/LICENSE) for details.\n\nThe VideoHash logo was created by [iconolocode](https://github.com/iconolocode). See [license](https://github.com/demmenie/videohash2/blob/main/assets/logo/LICENSE-LOGO) for details.\n\nVideos are from NASA and are in the public domain.\n> NASA copyright policy states that \"NASA material is not protected by copyright unless noted\".\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python package for Near Duplicate Video Detection (Perceptual Video Hashing) - Get a 64-bit comparable hash-value for any video.",
"version": "3.2.2",
"project_urls": {
"Documentation": "https://github.com/demmenie/videohash2/wiki",
"Download": "https://github.com/demmenie/videohash2/archive/3.2.2.tar.gz",
"Homepage": "https://demmenie.github.io/videohash2/",
"Source": "https://github.com/demmenie/videohash2",
"Tracker": "https://github.com/demmenie/videohash2/issues"
},
"split_keywords": [
"videohash2",
" near duplicate video detection",
" ndvd",
" perceptual video hashing",
" video hashing",
" near duplicate video",
" compare videos",
" video",
" video diff"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "88d5716d977f0474293925f9937d1b2b58c722ea114ecdf4d2b057286db6414e",
"md5": "8b827f551b5a8dec688223cec1b95b36",
"sha256": "650fa6049d9ac197be724c14f40a8b2e061fc95aeeb41dc7cc5d4433237eee0f"
},
"downloads": -1,
"filename": "videohash2-3.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b827f551b5a8dec688223cec1b95b36",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 24932,
"upload_time": "2024-07-14T22:21:28",
"upload_time_iso_8601": "2024-07-14T22:21:28.777861Z",
"url": "https://files.pythonhosted.org/packages/88/d5/716d977f0474293925f9937d1b2b58c722ea114ecdf4d2b057286db6414e/videohash2-3.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2ed3472dfee3e0397ad5b9ab4e54dfab01ca89bdd32ff4f99fd9a1ea68b68e3c",
"md5": "a21590f9d45b244f5cf7e9548c75acb7",
"sha256": "f7f4219cab9b570c6b8f54d30b85fc58901fae9e989d46a5bdf6670930d739c6"
},
"downloads": -1,
"filename": "videohash2-3.2.2.tar.gz",
"has_sig": false,
"md5_digest": "a21590f9d45b244f5cf7e9548c75acb7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 24820,
"upload_time": "2024-07-14T22:21:31",
"upload_time_iso_8601": "2024-07-14T22:21:31.831804Z",
"url": "https://files.pythonhosted.org/packages/2e/d3/472dfee3e0397ad5b9ab4e54dfab01ca89bdd32ff4f99fd9a1ea68b68e3c/videohash2-3.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-14 22:21:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "demmenie",
"github_project": "videohash2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "videohash2"
}
JSON
