![videogestalt-logo][6]
# Video Gestalt
[![PyPI-Status][1]][2] [![PyPI-Versions][3]][2] [![PyPi-License][4]][2] [![PyPI-Downloads][5]][2]
[![Build-Status][7]][8] [![Coverage-Status][9]][10]
One-Glance Overview of Any Video
[![Example video gestalt: Vespa-Scooter-Commercial][11]][12]
Video Gestalt displays a video in a summary form that shows the entire video at once as an array of moving video thumbnails.
## Description
Video Gestalt presents a condensed video array, showing the entire video at once as moving video thumbnails.
The above is an example of the Video Gestalt for a 50-second commercial for Vesta scooters. (Click the Video Gestalt to see the original video.)
As you can see, it is a looping video with moving thumbnails of the original video. In one second, you can see every frame of the original video at a glance, without any discontinuities as it loops. This is done by arranging that each thumbnail slides over exactly its width in one loop so that the next thumbnail takes over seamlessly.
Hence, the video gestalts can be read in two ways: 1- an overall quick glance shows all the scenes of the entire video, 2- by focusing on one animated thumbnail, we can watch the entire video, by starting in the upper left corner, and following to the right, then descending one block lower and moving from right to left, then descending one block and moving left to right again, etc.
A longer explanation is available in [this blog post](https://eamonn.org/video-gestalt-one-glance-overview-of-a-video).
## Installation
So far this has been tested on Linux, Chrome OS and Windows, but it will likely work on MacOS too.
To install, simply use `pip`:
```bash
pip install --upgrade videogestalt
```
This will also install [MoviePy](https://zulko.github.io/moviepy/), which will automatically install [FFmpeg](https://ffmpeg.org/) if necessary.
If they are not already installed, you will need to install `python3` and the corresponding Python package manager `pip` beforehand.
On Linux and friends you might be able to do this like so:
```bash
sudo apt-get install python3 python3-pip
```
If you get an error, please ensure you are using the latest `pip` version, as older versions may not support PEP517 Python packages:
```bash
pip install --upgrade pip
```
## Usage
An executable binary `videogestalt` is automatically installed in the local environment.
To generate a video file:
```bash
videogestalt -i countdown.mp4 -o countdown-gestalt --video
```
To generate an animated GIF (warning, output can be large):
```bash
videogestalt -i countdown.mp4 -o countdown-gestalt --gif
```
The application can also be used as a Python module:
```python
>>> from videogestalt import videogestalt as vg
>>> vg.main('-i countdown.mp4 -o countdown-gestalt --gif')
```
Note: if the repository is cloned, there is an example `countdown.mp4` video in `tests/examples`.
## Building
The module can be built with PEP517 standard tools, such as `pypa/build`:
```bash
python -sBm build .
```
It can also be installed in development/editable mode after cloning this git repository:
```bash
pip install --upgrade -e .
```
## Known issues
There are a few known issues, due to the fact that moviepy, the library that we use to process videos, is [currently not actively maintained as of August 2023 since at least December 2022](https://github.com/Zulko/moviepy/issues/1874). Here is a list of downstream issues:
* PILLOW 10.0.0 introduced a breaking change with moviepy, and although [a fix](https://github.com/Zulko/moviepy/pull/2003) was merged upstream into moviepy, there is no pypi release. Two solutions: cap PILLOW below 10, or install moviepy from github. Since the future of moviepy is uncertain, we chose to cap PILLOW, to ensure this tool continues to work in venvs.
* On Windows, after saving the output, the following exception may arise:
```
Exception ignored in: <function FFMPEG_VideoReader.__del__ at 0x00000253011BF920>
Traceback (most recent call last):
File "C:\Users\33632\miniconda3\Lib\site-packages\moviepy\video\io\ffmpeg_reader.py", line 199, in __del__
self.close()
File "C:\Users\33632\miniconda3\Lib\site-packages\moviepy\video\io\ffmpeg_reader.py", line 190, in close
self.proc.terminate()
File "C:\Users\33632\miniconda3\Lib\subprocess.py", line 1671, in terminate
_winapi.TerminateProcess(self._handle, 1)
OSError: [WinError 6] Descripteur non valide
```
Again this was [fixed](https://github.com/Zulko/moviepy/pull/1296) on github but not in the latest pypi release of MoviePy. This remain unfixed, it does not prevent usage of the tool, it is just inelegant.
## License
Created by Eamonn O'Brien-Strain.
Licensed under the Mozilla Public License 2.0
[1]: https://img.shields.io/pypi/v/videogestalt.svg
[2]: https://pypi.org/project/videogestalt
[3]: https://img.shields.io/pypi/pyversions/videogestalt.svg?logo=python&logoColor=white
[4]: https://img.shields.io/pypi/l/videogestalt.svg
[5]: https://img.shields.io/pypi/dm/videogestalt.svg?label=pypi%20downloads&logo=python&logoColor=white
[6]: https://raw.githubusercontent.com/eobrain/videogestalt/main/resources/videogestalt_logo.png
[7]: https://github.com/eobrain/videogestalt/actions/workflows/ci-build.yml/badge.svg?event=push
[8]: https://github.com/eobrain/videogestalt/actions/workflows/ci-build.yml
[9]: https://codecov.io/github/eobrain/videogestalt/coverage.svg?branch=master
[10]: https://codecov.io/github/eobrain/videogestalt?branch=master
[11]: https://raw.githubusercontent.com/eobrain/videogestalt/main/resources/vespa-commercial-gestalt.gif
[12]: https://ia904607.us.archive.org/11/items/vespa-scooter-commercial/Vespa%20Scooter%20Commercial.mp4
Raw data
{
"_id": null,
"home_page": "",
"name": "videogestalt",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Stephen Karl Larroque <lrq3000@gmail.com>",
"keywords": "video,gestalt,movie,summary,summarization,thumbnails",
"author": "",
"author_email": "Eamonn O'Brien-Strain <eobrain@proton.me>",
"download_url": "https://files.pythonhosted.org/packages/ad/0f/d5cb2e85a150c30f36a168770aa1ac26e8d927339feb3a9f786a62a26179/videogestalt-0.2.10.tar.gz",
"platform": null,
"description": "![videogestalt-logo][6]\r\n# Video Gestalt\r\n\r\n[![PyPI-Status][1]][2] [![PyPI-Versions][3]][2] [![PyPi-License][4]][2] [![PyPI-Downloads][5]][2]\r\n\r\n[![Build-Status][7]][8] [![Coverage-Status][9]][10]\r\n\r\nOne-Glance Overview of Any Video\r\n\r\n[![Example video gestalt: Vespa-Scooter-Commercial][11]][12]\r\n\r\nVideo Gestalt displays a video in a summary form that shows the entire video at once as an array of moving video thumbnails.\r\n\r\n## Description\r\n\r\nVideo Gestalt presents a condensed video array, showing the entire video at once as moving video thumbnails.\r\n\r\nThe above is an example of the Video Gestalt for a 50-second commercial for Vesta scooters. (Click the Video Gestalt to see the original video.)\r\n\r\nAs you can see, it is a looping video with moving thumbnails of the original video. In one second, you can see every frame of the original video at a glance, without any discontinuities as it loops. This is done by arranging that each thumbnail slides over exactly its width in one loop so that the next thumbnail takes over seamlessly.\r\n\r\nHence, the video gestalts can be read in two ways: 1- an overall quick glance shows all the scenes of the entire video, 2- by focusing on one animated thumbnail, we can watch the entire video, by starting in the upper left corner, and following to the right, then descending one block lower and moving from right to left, then descending one block and moving left to right again, etc.\r\n\r\nA longer explanation is available in [this blog post](https://eamonn.org/video-gestalt-one-glance-overview-of-a-video).\r\n\r\n## Installation\r\n\r\nSo far this has been tested on Linux, Chrome OS and Windows, but it will likely work on MacOS too.\r\n\r\nTo install, simply use `pip`:\r\n\r\n```bash\r\npip install --upgrade videogestalt\r\n```\r\n\r\nThis will also install [MoviePy](https://zulko.github.io/moviepy/), which will automatically install [FFmpeg](https://ffmpeg.org/) if necessary.\r\n\r\nIf they are not already installed, you will need to install `python3` and the corresponding Python package manager `pip` beforehand.\r\n\r\nOn Linux and friends you might be able to do this like so:\r\n```bash\r\nsudo apt-get install python3 python3-pip\r\n```\r\n\r\nIf you get an error, please ensure you are using the latest `pip` version, as older versions may not support PEP517 Python packages:\r\n\r\n```bash\r\npip install --upgrade pip\r\n```\r\n\r\n## Usage\r\n\r\nAn executable binary `videogestalt` is automatically installed in the local environment.\r\n\r\nTo generate a video file:\r\n\r\n```bash\r\nvideogestalt -i countdown.mp4 -o countdown-gestalt --video\r\n```\r\n\r\nTo generate an animated GIF (warning, output can be large):\r\n\r\n```bash\r\nvideogestalt -i countdown.mp4 -o countdown-gestalt --gif\r\n```\r\n\r\nThe application can also be used as a Python module:\r\n\r\n```python\r\n>>> from videogestalt import videogestalt as vg\r\n>>> vg.main('-i countdown.mp4 -o countdown-gestalt --gif')\r\n```\r\n\r\nNote: if the repository is cloned, there is an example `countdown.mp4` video in `tests/examples`.\r\n\r\n## Building\r\n\r\nThe module can be built with PEP517 standard tools, such as `pypa/build`:\r\n\r\n```bash\r\npython -sBm build .\r\n```\r\n\r\nIt can also be installed in development/editable mode after cloning this git repository:\r\n\r\n```bash\r\npip install --upgrade -e .\r\n```\r\n\r\n## Known issues\r\n\r\nThere are a few known issues, due to the fact that moviepy, the library that we use to process videos, is [currently not actively maintained as of August 2023 since at least December 2022](https://github.com/Zulko/moviepy/issues/1874). Here is a list of downstream issues:\r\n* PILLOW 10.0.0 introduced a breaking change with moviepy, and although [a fix](https://github.com/Zulko/moviepy/pull/2003) was merged upstream into moviepy, there is no pypi release. Two solutions: cap PILLOW below 10, or install moviepy from github. Since the future of moviepy is uncertain, we chose to cap PILLOW, to ensure this tool continues to work in venvs.\r\n* On Windows, after saving the output, the following exception may arise:\r\n```\r\nException ignored in: <function FFMPEG_VideoReader.__del__ at 0x00000253011BF920>\r\nTraceback (most recent call last):\r\n File \"C:\\Users\\33632\\miniconda3\\Lib\\site-packages\\moviepy\\video\\io\\ffmpeg_reader.py\", line 199, in __del__\r\n self.close()\r\n File \"C:\\Users\\33632\\miniconda3\\Lib\\site-packages\\moviepy\\video\\io\\ffmpeg_reader.py\", line 190, in close\r\n self.proc.terminate()\r\n File \"C:\\Users\\33632\\miniconda3\\Lib\\subprocess.py\", line 1671, in terminate\r\n _winapi.TerminateProcess(self._handle, 1)\r\nOSError: [WinError 6] Descripteur non valide\r\n```\r\nAgain this was [fixed](https://github.com/Zulko/moviepy/pull/1296) on github but not in the latest pypi release of MoviePy. This remain unfixed, it does not prevent usage of the tool, it is just inelegant.\r\n\r\n## License\r\n\r\nCreated by Eamonn O'Brien-Strain.\r\n\r\nLicensed under the Mozilla Public License 2.0\r\n\r\n[1]: https://img.shields.io/pypi/v/videogestalt.svg\r\n[2]: https://pypi.org/project/videogestalt\r\n[3]: https://img.shields.io/pypi/pyversions/videogestalt.svg?logo=python&logoColor=white\r\n[4]: https://img.shields.io/pypi/l/videogestalt.svg\r\n[5]: https://img.shields.io/pypi/dm/videogestalt.svg?label=pypi%20downloads&logo=python&logoColor=white\r\n[6]: https://raw.githubusercontent.com/eobrain/videogestalt/main/resources/videogestalt_logo.png\r\n[7]: https://github.com/eobrain/videogestalt/actions/workflows/ci-build.yml/badge.svg?event=push\r\n[8]: https://github.com/eobrain/videogestalt/actions/workflows/ci-build.yml\r\n[9]: https://codecov.io/github/eobrain/videogestalt/coverage.svg?branch=master\r\n[10]: https://codecov.io/github/eobrain/videogestalt?branch=master\r\n[11]: https://raw.githubusercontent.com/eobrain/videogestalt/main/resources/vespa-commercial-gestalt.gif\r\n[12]: https://ia904607.us.archive.org/11/items/vespa-scooter-commercial/Vespa%20Scooter%20Commercial.mp4\r\n",
"bugtrack_url": null,
"license": "Mozilla Public License 2.0",
"summary": "One-Glance Overview of Any Video",
"version": "0.2.10",
"project_urls": {
"Documentation": "https://github.com/eobrain/videogestalt/blob/master/README.md",
"Download": "https://github.com/eobrain/videogestalt/releases",
"Homepage": "https://github.com/eobrain/videogestalt",
"Source": "https://github.com/eobrain/videogestalt",
"Tracker": "https://github.com/eobrain/videogestalt/issues"
},
"split_keywords": [
"video",
"gestalt",
"movie",
"summary",
"summarization",
"thumbnails"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "37af96f9c47a1e8a5500c88a0ac701011c8d987a7f77d495bd47230667b99ecc",
"md5": "9da673871de6c8e712b4fbf22f4c5a0d",
"sha256": "5cf30af7a9b96f9911cdd981f18de0ae10d2960310e1a6952a43eaf713d14054"
},
"downloads": -1,
"filename": "videogestalt-0.2.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9da673871de6c8e712b4fbf22f4c5a0d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 12448,
"upload_time": "2023-08-21T20:26:48",
"upload_time_iso_8601": "2023-08-21T20:26:48.124175Z",
"url": "https://files.pythonhosted.org/packages/37/af/96f9c47a1e8a5500c88a0ac701011c8d987a7f77d495bd47230667b99ecc/videogestalt-0.2.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ad0fd5cb2e85a150c30f36a168770aa1ac26e8d927339feb3a9f786a62a26179",
"md5": "429c44b43ea3795e311453c917a6c396",
"sha256": "892fcde57e18809d5542b46d0a574ce7b22a4e018afc9deda4a614cf0ec20075"
},
"downloads": -1,
"filename": "videogestalt-0.2.10.tar.gz",
"has_sig": false,
"md5_digest": "429c44b43ea3795e311453c917a6c396",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 16234,
"upload_time": "2023-08-21T20:26:49",
"upload_time_iso_8601": "2023-08-21T20:26:49.240504Z",
"url": "https://files.pythonhosted.org/packages/ad/0f/d5cb2e85a150c30f36a168770aa1ac26e8d927339feb3a9f786a62a26179/videogestalt-0.2.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-21 20:26:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eobrain",
"github_project": "videogestalt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "videogestalt"
}
JSON
