Brief Description

This PR includes significant refactoring, documentation updates, and significant enhancements to the StreamGear, along with minor improvements to WriteGear, and NetGear APIs. It introduces safer process termination methods, improved parameter handling, and enhanced documentation for better user guidance. Additionally, it addresses several bugs and improves the overall maintainability and clarity of the codebase.

Key Changes

StreamGear API:

Refactored stream copy handling to address errors with unsupported parameters (Fixes #396).
- Moved settings for "-vf" and "-aspect" inside conditional blocks.
- Added warnings and discarded these parameters in stream copy mode.
- Fixed incompatibility of stream copy with Real-time Frames Mode.
- Added warnings and discarded -vcodec copy when using this mode.
Deprecated terminate() method, introducing close() for safer process termination.
- Updated documentation and tests to reflect these changes.
Introduced new -enable_force_termination attribute for immediate FFmpeg process termination.
Restricted -livestream parameter to Real-time Frames Mode only.
- Disabled live streaming for video files and updated relevant logging.
Removed non-essential aspect ratio parameter to prevent unwanted distortions (Fixes #385).
- Enhanced warning messages and clarified documentation.
Updated close() methods for handling gracefully signal interruptions on different systems with device audio streams.
- Adjusted signals for graceful termination based on the operating system.

WriteGear API:

Simplified the logic for formatting output parameters.

NetGear API:

Fixed Secure Mode failing to work on conflicting ZMQ Contexts:
- Handled "Address in use" error more gracefully and disabled secure mode if errors occur.
- Improved handling of ZMQ Authenticator and Certificates.
Enhanced logging and error handling for secure mode.
- Logged Authenticator start/stop events.
Handled socket session expiration more gracefully in recv_handler.
Fixed msg_json undefined when terminating context in the recv_handler method.
Ensured proper termination of the ZMQ context and socket when closing the NetGear instance.
Added Admonition for warning users about the Client's end must run before the Server's end to establish a secure connection in Secure Mode.

Helper Class:

Added a custom deprecated decorator to mark deprecated functions and parameters.
- It displays a warning message when a deprecated function or parameter is used.
Updated extract_time helper function regex to handle milliseconds.

Setup

Updated setup.py to use the latest pyzmq version to address installation issues (Fixes #399).

Documentation:

StreamGear Updates:
- Improved the overview section's description and wording.
- Updated usage examples for both Single-Source Mode and Real-time Frames Mode.
- Updated StreamGear usage examples for device audio input.
- Refactored sections for Live Streaming usage.
  - Added warning for unsupported -livestream parameter in Single-Source Mode.
- Updated usage example for device video source.
- Addressed deprecation of the terminate() method in favor of the new close() method.
- Updated respective notices for the deprecated terminate() method and rgb_mode parameter.
- Added the use of new -enable_force_termination parameter.
- Added a new FAQ entry about the deprecated rgb_mode parameter.
- Added a deprecation warning admonition for the rgb_mode parameter in the stream() method.
- Removed the obsolete usage example for deprecation RGB mode with StreamGear.
- Added documentation and usage of the new -enable_force_termination parameter.
- Modified the warning message to mention that forced termination can cause corrupted output in certain scenarios.
- Updated the docstring for the stream() method and transcode_source() method.
- Refactored the StreamGear API Parameters documentation to enhance clarity and readability.
- Refined the description of the -streams attribute of the StreamGear API.
Updated the documentation for the -disable_force_termination parameter in WriteGear API.
Improved overall documentation quality, including enhancing clarity, readability, consistency, and precision.
Added detailed explanations, practical examples, best practices, and clearer usage patterns.
Fixed various issues like typos, formatting errors, code highlighting issues, and grammar inconsistencies.
Updated sections, code examples, admonitions, and comments for better clarity and accuracy.
Fixed minor typo in js_hook.py.

CI

Improved parameterized test cases to support floating point values.
Fixed various typos and code issues in tests.
Updated StreamGear tests to use the new close() method instead of the deprecated terminate() method.
Updated tests of various APIs for better coverage and reliability.
Enabled kill=True in close() in NetGear Tests.
Fixed expected duration value in parameterized test case from 8 to 8.44 since test_extract_time function now supports floating point values.
Fixed test_secure_mode NetGear test:
- Added "127.0.0.1" address to allow common endpoint for connection.
- Added "jpeg_compression":False to disable frame compression, allowing frame to be the same while assertion.

Maintenance:

Applied short-circuiting to simplify code across various APIs and tests.
Improved logging, parameter validation, and added descriptive dialogs across various APIs.

Requirements / Checklist

[x] I have read the PR Guidelines.
[x] I have read the Documentation.
[x] I have updated the documentation accordingly(if required).

Related Issue

385

396

399

Context

This Pull Request aims to introduce various improvements, refactoring efforts, and maintenance updates to the StreamGear API. The changes encompass bug fixes, documentation updates, feature enhancements, and code quality improvements, along with minor improvements to WriteGear, and NetGear APIs. It introduces safer process termination methods, improved parameter handling, and enhanced documentation for better user guidance. Additionally, it addresses several bugs and improves the overall maintainability and clarity of the codebase.

Types of changes

[ ] Bug fix (non-breaking change which fixes an issue)
[ ] New feature (non-breaking change which adds functionality)
[x] Breaking change (fix or feature that would cause existing functionality to change)

Files	Patch %	Lines
vidgear/gears/netgear.py	88.52%	7 Missing :warning:
vidgear/gears/streamgear.py	98.05%	3 Missing :warning:
vidgear/gears/helper.py	92.30%	1 Missing :warning:

abhiTronix / vidgear

⚡️ Enhancements, Refactoring, and Maintenance Updates for StreamGear API #401