Skip to content

Commit

Permalink
🎉 Released VidGear Stable v0.3.2 [#379]
Browse files Browse the repository at this point in the history
### New Features ✨
- **NetGear:** 
    * Added new `kill` parameter to `close()` method to forcefully kill ZMQ context instead of graceful exit only in the `receive` mode.
    * Added new `subscriber_timeout` integer optional parameter to support timeout with `pattern=2` _(or Publisher-Subscriber)_ pattern.
        + Receiver will exit safely if timeout defined(any value(in milliseconds) > 0), and timeout occurs in Receiver Mode with `pattern=2`.
        + 💬 Note: Default behavior still is to block the thread till infinite time.
- **WriteGear:** 
    * Added new `-disable_ffmpeg_window` optional Boolean flag to enable patch that prevents FFmpeg creation window from opening when building `.exe` files on Windows OS. _(PR by @ibtsam3301)_
        + 💬 Note: `-disable_ffmpeg_window` optional Boolean flag is only available on Windows OS with logging disabled(`logging=False`) in compression mode.
        + Use Case: This flag can be useful while creating an `.exe` file for a python script that uses WriteGear API. On windows even after creating the `.exe` file in windowed mode or no-console mode, the `ffmpeg.exe` command line window would pop up while its being used by WriteGear API.
- **Setup.py**
    * Added official support for python `3.11.x` legacies.
    * Bumped version to `0.3.1`. 
- **Docs**
    * Added doc for `subscriber_timeout` optional Integer parameter in NetGear.
    * Added doc for `disable_ffmpeg_window` optional Boolean parameter in WriteGear.
    * Added new asset `screengear_region.png`.
- **CI**
    * Added python 3.11 legacy support for MacOS, Windows and Linux environments.
    * Added kill argument to close() method in various NetGear tests.

### Updates/Improvements ⚡️
- Asyncio: 
    * Formatted TemplateResponse class parameters w.r.t new changes in backend Starlette API.
- Setup.py:
    * Readded latest patch to `uvicorn`, `starlette`, `pyzmq` dependencies.
    * Removed `3.7` legacy from Programming Language metadata.
- Maintenance: 
    * Added GitHub sponsors and dropped liberapay from `Funding.yml`.
    * Removed redundant code.
- Docs:
    * Updated information related to Supported Dimensional Attributes in ScreenGear docs.
    * Updated minimum python to version `3.8` while installing vidgear in docs.
    * Updated API-specific dependencies in docs.
    * Updated changelog.md
- CI:
    * Updated Azure Pipeline workflow. 
    * Updated Appveyor Pipeline workflow.
    * Updated GitHub Actions Pipeline workflow.
    * Migrated python version to `3.9` in `deploy_docs.yml` workflow.
    * Removed deprecated python `3.7` legacy support.
    * Increased code coverage by updating tests.
    * Updated tests for `subscriber_timeout` optional Integer parameter in NetGear.
    * Updated tests for `disable_ffmpeg_window` optional Boolean parameter in WriteGear.

### Breaking Updates/Changes 💥
- [ ] Setup.py:
    * Removed support for python-3.7 legacies 
        + Raised `python_requires` to `>=3.8`. Thereby python `3.7` and any before legacy are no longer supported.

### Bug-fixes 🐛
- ScreenGear:
    * Fixed swapped region dimensions bug with dxcam backend.
    * Fixed "mss" backend disabled when `monitor` parameter is not defined.
- Docs:
    * Fixed missing `compression_mode` flags in WriteGear API docs.
    * Fixed missing hyperlinks.
    * Fixed typos and context.
- CI:
    * Temporary fix for AST constructor depth mismatch in pytest on python `3.11.x`, More information: pytest-dev/pytest#10874
        + Made temporary fix platform independent. 
        + Extended fix to all Webgear_RTC tests.
    * Fixed NetGear tests bugs.
    * Fixed condition logic bug.
  • Loading branch information
abhiTronix authored Sep 10, 2023
2 parents 7d6a817 + 5087055 commit be6f3f0
Show file tree
Hide file tree
Showing 32 changed files with 363 additions and 151 deletions.
2 changes: 1 addition & 1 deletion .github/FUNDING.yml
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
ko_fi: abhitronix
liberapay: abhiTronix
github: abhiTronix
2 changes: 1 addition & 1 deletion .github/workflows/ci_linux.yml
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ jobs:
runs-on: ubuntu-20.04
strategy:
matrix:
python-version: ["3.7", "3.8", "3.9", "3.10"]
python-version: ["3.8", "3.9", "3.10", "3.11"]
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
Expand Down
5 changes: 2 additions & 3 deletions .github/workflows/deploy_docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ on:
types: [published]

env:
PYTHON_VERSION: 3.7
PYTHON_VERSION: 3.9
GIT_TOKEN: ${{ secrets.GIT_TOKEN }}
GIT_NAME: ${{ secrets.GIT_NAME }}
GIT_EMAIL: ${{ secrets.GIT_EMAIL }}
Expand Down Expand Up @@ -65,7 +65,7 @@ jobs:
- name: mike deploy docs release
run: |
echo "${{ env.NAME_RELEASE }}"
mike deploy --push --update-aliases --no-redirect ${{ env.NAME_RELEASE }} ${{ env.RELEASE_NAME }} --title=${{ env.RELEASE_NAME }}
mike deploy --push --update-aliases --no-redirect ${{ env.NAME_RELEASE }} ${{ env.RELEASE_NAME }} --title=${{ env.RELEASE_NAME }}
env:
NAME_RELEASE: "v${{ env.RELEASE_NAME }}-release"
if: success()
Expand Down Expand Up @@ -112,7 +112,6 @@ jobs:
NAME_STABLE: "v${{ env.RELEASE_NAME }}-stable"
if: success()


deploy-docs-dev:
name: Deploy Development Docs
if: github.event_name == 'push' && github.ref == 'refs/heads/testing'
Expand Down
12 changes: 6 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -650,7 +650,7 @@ It is something I am doing with my own free time. But so much more needs to be d

Here is a Bibtex entry you can use to cite this project in a publication:

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7571405.svg)](https://doi.org/10.5281/zenodo.7571405)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8174694.svg)](https://doi.org/10.5281/zenodo.8174694)

```BibTeX
@software{vidgear,
Expand All @@ -665,13 +665,13 @@ Here is a Bibtex entry you can use to cite this project in a publication:
Benjamin Lowe and
Mickaël Schoentgen and
Renaud Bouckenooghe},
title = {abhiTronix/vidgear: VidGear v0.3.0},
month = jan,
title = {abhiTronix/vidgear: VidGear v0.3.1},
month = jul,
year = 2023,
publisher = {Zenodo},
version = {vidgear-0.3.0},
doi = {10.5281/zenodo.7571405},
url = {https://doi.org/10.5281/zenodo.7571405}
version = {vidgear-0.3.1},
doi = {10.5281/zenodo.8174694},
url = {https://doi.org/10.5281/zenodo.8174694}
}
```

Expand Down
11 changes: 5 additions & 6 deletions appveyor.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,6 @@ image: Visual Studio 2019

environment:
matrix:
- PYTHON: "C:\\Python37-x64"
PYTHON_VERSION: "3.7.x"
PYTHON_ARCH: "64"

- PYTHON: "C:\\Python38-x64"
PYTHON_VERSION: "3.8.x"
PYTHON_ARCH: "64"
Expand All @@ -32,6 +28,10 @@ environment:
PYTHON_VERSION: "3.10.x"
PYTHON_ARCH: "64"

- PYTHON: "C:\\Python311-x64"
PYTHON_VERSION: "3.11.x"
PYTHON_ARCH: "64"

build: off

version: "{branch}-{build}"
Expand Down Expand Up @@ -70,6 +70,5 @@ install:
test_script:
- cmd: python -m pytest --verbose --capture=no --cov-report term-missing --cov=vidgear vidgear/tests/


after_test:
- cmd: python -m codecov
- cmd: python -m codecov
4 changes: 2 additions & 2 deletions azure-pipelines.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,14 +35,14 @@ pool:

strategy:
matrix:
Python37:
python.version: "3.7"
Python38:
python.version: "3.8"
Python39:
python.version: "3.9"
Python310:
python.version: "3.10"
Python311:
python.version: "3.11"

steps:
- task: UsePythonVersion@0
Expand Down
76 changes: 76 additions & 0 deletions docs/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,82 @@ limitations under the License.

# Release Notes

## v0.3.2 (2023-09-10)

???+ tip "New Features"
- [x] **NetGear:**
* Added new `kill` parameter to `close()` method to forcefully kill ZMQ context instead of graceful exit only in the `receive` mode.
* Added new `subscriber_timeout` integer optional parameter to support timeout with `pattern=2` _(or Publisher-Subscriber)_ pattern.
+ Receiver will exit safely if timeout defined(any value(in milliseconds) > 0), and timeout occurs in Receiver Mode with `pattern=2`.
+ 💬 Note: Default behavior still is to block the thread till infinite time.
- [x] **WriteGear:**
* Added new `-disable_ffmpeg_window` optional Boolean flag to enable patch that prevents FFmpeg creation window from opening when building `.exe` files on Windows OS. _(PR by @ibtsam3301)_
+ 💬 Note: `-disable_ffmpeg_window` optional Boolean flag is only available on Windows OS with logging disabled(`logging=False`) in compression mode.
+ Use Case: This flag can be useful while creating an `.exe` file for a python script that uses WriteGear API. On windows even after creating the `.exe` file in windowed mode or no-console mode, the `ffmpeg.exe` command line window would pop up while its being used by WriteGear API.
- [x] **Setup.py**
* Added official support for python `3.11.x` legacies.
* Bumped version to `0.3.1`.
- [x] **Docs**
* Added doc for `subscriber_timeout` optional Integer parameter in NetGear.
* Added doc for `disable_ffmpeg_window` optional Boolean parameter in WriteGear.
* Added new asset `screengear_region.png`.
- [x] **CI**
* Added python 3.11 legacy support for MacOS, Windows and Linux environments.
* Added kill argument to close() method in various NetGear tests.

??? success "Updates/Improvements"
- [x] Asyncio:
* Formatted TemplateResponse class parameters w.r.t new changes in backend Starlette API.
- [x] Setup.py:
* Readded latest patch to `uvicorn`, `starlette`, `pyzmq` dependencies.
* Removed `3.7` legacy from Programming Language metadata.
- [x] Maintenance:
* Added GitHub sponsors and dropped liberapay from `Funding.yml`.
* Removed redundant code.
- [x] Docs:
* Updated information related to Supported Dimensional Attributes in ScreenGear docs.
* Updated minimum python to version `3.8` while installing vidgear in docs.
* Updated API-specific dependencies in docs.
* Updated changelog.md
- [x] CI:
* Updated Azure Pipeline workflow.
* Updated Appveyor Pipeline workflow.
* Updated GitHub Actions Pipeline workflow.
* Migrated python version to `3.9` in `deploy_docs.yml` workflow.
* Removed deprecated python `3.7` legacy support.
* Increased code coverage by updating tests.
* Updated tests for `subscriber_timeout` optional Integer parameter in NetGear.
* Updated tests for `disable_ffmpeg_window` optional Boolean parameter in WriteGear.

??? danger "Breaking Updates/Changes"
- [ ] Setup.py:
* Removed support for python-3.7 legacies
+ Raised `python_requires` to `>=3.8`. Thereby python `3.7` and any before legacy are no longer supported.

??? bug "Bug-fixes"
- [x] ScreenGear:
* Fixed swapped region dimensions bug with dxcam backend.
* Fixed "mss" backend disabled when `monitor` parameter is not defined.
- [x] Docs:
* Fixed missing `compression_mode` flags in WriteGear API docs.
* Fixed missing hyperlinks.
* Fixed typos and context.
- [x] CI:
* Temporary fix for AST constructor depth mismatch in pytest on python `3.11.x`, More information: pytest-dev/pytest#10874
+ Made temporary fix platform independent.
+ Extended fix to all Webgear_RTC tests.
* Fixed NetGear tests bugs.
* Fixed condition logic bug.

??? question "Pull Requests"
* PR #378
* PR #375
* PR #370

 

 

## v0.3.1 (2023-07-22)

??? tip "New Features"
Expand Down
4 changes: 3 additions & 1 deletion docs/gears/netgear/params.md
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,9 @@ This parameter provides the flexibility to alter various NetGear API's internal

* **`max_retries`**(_integer_): This internal attribute controls the maximum retries before Server/Client exit itself, if it's unable to get any response/reply from the socket before a certain amount of time, when synchronous messaging patterns like (`zmq.PAIR` & `zmq.REQ/zmq.REP`) are being used. It's value can anything greater than `0`, and its default value is `3`.

* **`request_timeout`**(_integer_): This internal attribute controls the timeout value _(in seconds)_, after which the Server/Client exit itself if it's unable to get any response/reply from the socket, when synchronous messaging patterns like (`zmq.PAIR` & `zmq.REQ/zmq.REP`) are being used. It's value can anything greater than `0`, and its default value is `10` seconds.
* **`request_timeout`**(_integer_): This internal attribute controls the timeout value _(in seconds)_, after which the Server/Client exit itself with `Nonetype` value if it's unable to get any response/reply from the socket, when synchronous messaging patterns like (`zmq.PAIR` & `zmq.REQ/zmq.REP`) are being used. It's value can anything greater than `0`, and its default value is `10` seconds.

* **`subscriber_timeout`**(_integer_): Similar to `request_timeout`, this internal attribute also controls the timeout value _(in seconds)_ but for non-synchronous `zmq.PUB/zmq.SUB` pattern in compression mode, after which the Client(Subscriber) exit itself with `Nonetype` value if it's unable to get any response from the socket. It's value can anything greater than `0`, and its disabled by default _(meaning the client will wait forever for response)_.

* **`flag`**(_integer_): This PyZMQ attribute value can be either `0` or `zmq.NOBLOCK`_( i.e. 1)_. More information can be found [here ➶](https://pyzmq.readthedocs.io/en/latest/api/zmq.html).

Expand Down
23 changes: 11 additions & 12 deletions docs/gears/screengear/params.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,33 +131,32 @@ ScreenGear(colorspace="COLOR_BGR2HSV")

This parameter provides the flexibility to manually set the dimensions of capture screen area.

!!! info "Supported Dimensional Parameters"
!!! info "Supported Dimensional Attributes"

Supported Dimensional Parameters are as follows:
ScreenGear API takes `left`, `top`, `width`, `height` coordinates of the bounding box of capture screen area(ROI), similar to [PIL.ImageGrab.grab](https://pillow.readthedocs.io/en/stable/reference/ImageGrab.html), defined below:

<h2 align="center">
<img src="../../../assets/images/screengear_region.png" loading="lazy" alt="ScreenGear ROI region" width="80%"/>
</h2>

* **`left`:** the x-coordinate of the upper-left corner of the region
* **`top`:** the y-coordinate of the upper-left corner of the region
* **`width`:** the width of the region
* **`height`:** the height of the region

!!! note "Additional Exclusive Attribute such as [`THREAD_TIMEOUT`](../../camgear/advanced/source_params/#exclusive-camgear-parameters) is also supported for this parameter."

* **`width`:** the width of the complete region from left to the bottom-right corner of the region.
* **`height`:** the height of the complete region from top to the bottom-right corner of the region.

**Data-Type:** Dictionary

**Default Value:** Its default value is `{}`

**Usage:**

The desired dimensional parameters can be passed to ScreenGear API by formatting them as attributes, as follows:

!!! tip "More information about screen dimensioning can be found [here ➶](https://python-mss.readthedocs.io/api.html#mss.tools.mss.base.MSSMixin.monitors)"
The desired dimensional coordinates parameters can be passed to ScreenGear API by formatting them as attributes, as follows:

```python
# formatting dimensional parameters as dictionary attributes
options = {'top': 40, 'left': 0, 'width': 100, 'height': 100}
# assigning it w.r.t monitor=1
ScreenGear(monitor=1, **options)
# assigning it
ScreenGear(**options)
```

&nbsp;
Expand Down
14 changes: 14 additions & 0 deletions docs/gears/screengear/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,20 @@ stream.stop()

ScreenGear API provides us the flexibility to directly set the dimensions of capturing-area of the screen. These dimensions can be easily applied to ScreenGear API through its [`options`](../params/#options) dictionary parameter by formatting them as its attributes.


??? info "Supported Dimensional Attributes"

ScreenGear API takes `left`, `top`, `width`, `height` coordinates of the bounding box of capture screen area(ROI), similar to [PIL.ImageGrab.grab](https://pillow.readthedocs.io/en/stable/reference/ImageGrab.html), defined below:

<h2 align="center">
<img src="../../../assets/images/screengear_region.png" loading="lazy" alt="ScreenGear ROI region" width="80%"/>
</h2>

* **`left`:** the x-coordinate of the upper-left corner of the region
* **`top`:** the y-coordinate of the upper-left corner of the region
* **`width`:** the width of the complete region from left to the bottom-right corner of the region.
* **`height`:** the height of the complete region from top to the bottom-right corner of the region.

The complete usage example is as follows:


Expand Down
11 changes: 11 additions & 0 deletions docs/gears/writegear/compression/params.md
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,17 @@ This parameter allows us to exploit almost all FFmpeg supported parameters effor
"-ffpreheaders": ["-re"], # executes as `ffmpeg -re <rest of command>`
}
```

* **`-disable_ffmpeg_window`** _(bool)_: sets a special flag to enable detached subprocess creation on Windows OS, and can be useful while creating an `.exe` file for a python script that uses WriteGear API. On Windows, in certain cases, even after creating the `.exe` file in windowed mode or no-console mode, the FFmpeg commandline window would pop up while its being used by WriteGear API. Its usage is as follows:

??? new "New in v0.3.2"
This feature was added in `v0.3.2`.

!!! warning "`-disable_ffmpeg_window` is only available on Windows OS with logging disabled(`logging=False`) in compression mode."

```python
output_params = {"-disable_ffmpeg_window": True} # disables FFmpeg creation window
```

* **`-disable_force_termination`** _(bool)_: sets a special flag to manually disable the default forced-termination behaviour in WriteGear API when `-i` FFmpeg parameter is used _(For more details, see issue: #149)_. Its usage is as follows:

Expand Down
6 changes: 3 additions & 3 deletions docs/gears/writegear/non_compression/params.md
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,7 @@ To assign desired parameters in Non-Compression Mode, you can format it as dicti
# format parameter as dictionary attribute
output_params = {"-fps":30}
# and then, assign it
WriteGear(output = 'output.mp4', **output_params)
WriteGear(output = 'output.mp4', compression_mode=False, **output_params)
```

!!! example "Its usage example can be found [here ➶](../usage/#using-non-compression-mode-with-videocapture-gears)."
Expand All @@ -170,7 +170,7 @@ To select desired FOURCC codec in Non-Compression Mode, you can format it as dic
# format codec as dictionary attribute
output_params = {"-fourcc":"MJPG"}
# and then, assign it
WriteGear(output = 'output.mp4', **output_params)
WriteGear(output = 'output.mp4', compression_mode=False, **output_params)
```

!!! example "Its usage example can be found [here ➶](../usage/#using-non-compression-mode-with-videocapture-gears)."
Expand All @@ -188,7 +188,7 @@ This parameter enables logging _(if `True`)_, essential for debugging.
**Usage:**

```python
WriteGear(output = 'output.mp4', logging=True)
WriteGear(output = 'output.mp4', compression_mode=False, logging=True)
```

&nbsp;
12 changes: 6 additions & 6 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ It is something I am doing with my own free time. But so much more needs to be d

Here is a Bibtex entry you can use to cite this project in a publication:

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7571405.svg)](https://doi.org/10.5281/zenodo.7571405)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8174694.svg)](https://doi.org/10.5281/zenodo.8174694)

```BibTeX
@software{vidgear,
Expand All @@ -142,13 +142,13 @@ Here is a Bibtex entry you can use to cite this project in a publication:
Benjamin Lowe and
Mickaël Schoentgen and
Renaud Bouckenooghe},
title = {abhiTronix/vidgear: VidGear v0.3.0},
month = jan,
title = {abhiTronix/vidgear: VidGear v0.3.1},
month = jul,
year = 2023,
publisher = {Zenodo},
version = {vidgear-0.3.0},
doi = {10.5281/zenodo.7571405},
url = {https://doi.org/10.5281/zenodo.7571405}
version = {vidgear-0.3.1},
doi = {10.5281/zenodo.8174694},
url = {https://doi.org/10.5281/zenodo.8174694}
}
```

Expand Down
6 changes: 3 additions & 3 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ limitations under the License.

## Supported Systems

VidGear is well-tested and supported on the following systems(but not limited to), with [python 3.7+](https://www.python.org/downloads/) and [pip](https://pip.pypa.io/en/stable/installing/#do-i-need-to-install-pip) installed:
VidGear is well-tested and supported on the following systems(but not limited to), with [python 3.8+](https://www.python.org/downloads/) and [pip](https://pip.pypa.io/en/stable/installing/#do-i-need-to-install-pip) installed:

* Any :material-linux: Linux distro released in 2016 or later
* :fontawesome-brands-windows: Windows 7 or later
Expand All @@ -41,9 +41,9 @@ VidGear is well-tested and supported on the following systems(but not limited to

!!! warning "Depreciation Notice"

Python-3.6 legacies support has been dropped from Vidgear.
Python-3.7 legacies support has been dropped from Vidgear.

:fontawesome-brands-python: [**Python 3.7+**](https://www.python.org/downloads/) are only supported legacies for installing Vidgear v0.2.5 and above.
:fontawesome-brands-python: [**Python 3.8+**](https://www.python.org/downloads/) are only supported legacies for installing Vidgear `v0.3.1` and above.

&thinsp;

Expand Down
6 changes: 3 additions & 3 deletions docs/installation/pip_install.md
Original file line number Diff line number Diff line change
Expand Up @@ -262,7 +262,7 @@ When installing VidGear with [pip](https://pip.pypa.io/en/stable/installing/), y
| CamGear | `pafy`, `yt_dlp`, `streamlink` |
| PiGear | `picamera` |
| VideoGear | *Based on CamGear or PiGear backend in use* |
| ScreenGear | `dxcam`, `mss`, `pyscreenshot`, `Pillow` |
| ScreenGear | `mss`, `pyscreenshot`, `Pillow` |
| WriteGear | **FFmpeg:** See [this doc ➶](../../gears/writegear/compression/advanced/ffmpeg_install/#ffmpeg-installation-instructions) |
| StreamGear | **FFmpeg:** See [this doc ➶](../../gears/streamgear/ffmpeg_install/#ffmpeg-installation-instructions) |
| NetGear | `pyzmq`, `simplejpeg` |
Expand Down Expand Up @@ -329,10 +329,10 @@ pip install git+git://github.com/abhiTronix/vidgear@master#egg=vidgear[asyncio]
```sh
# Install latest stable release with all Core dependencies
pip install vidgear-0.3.1-py3-none-any.whl[core]
pip install vidgear-0.3.2-py3-none-any.whl[core]
# Or Install latest stable release with all Core & Asyncio dependencies
pip install vidgear-0.3.1-py3-none-any.whl[asyncio]
pip install vidgear-0.3.2-py3-none-any.whl[asyncio]
```
&nbsp;
Expand Down
Loading

0 comments on commit be6f3f0

Please sign in to comment.