🎉 Release VidGear Stable v0.3.3

[abhiTronix]

Brief Description

This pull request introduces Vidgear version 0.3.3, which includes a significant update featuring new functionalities, improvements, and crucial bug fixes across various components of the library.

Key PR Changes:

New Features ✨

• PiGear:
  • Official Support for Picamera2 API (Fixes [Proposal]: Support Picamera2 #342)
    • This massive update brings official support for the new Picamera2 API, unlocking powerful features for Raspberry Pi Camera Modules and limited USB camera support.
    • Seamless Python wrapper: A robust wrapper around Picamera2 API library simplifies integration with minimal code changes for existing PiGear users.
    • Enhanced camera control: Leverages libcamera API under the hood for Raspberry Pi Camera Modules.
    • Existing compatibility: Maintains compatibility with PiGear's existing super-charged multi-threaded and colorspace manipulation framework.
    • Proper Resource management: Ensures proper resource release during PiGear termination.
    • USB camera support (limited): Provides basic functionality for USB webcams. PiGear could accurately differentiates between USB and Raspberry Pi cameras using metadata.
    • Backward compatibility: Seamlessly switches to the legacy Picamera library backend if Picamera2 is unavailable.
    • Standalone functionalities: Standalone functionalities for both legacy picamera and newer picamera2 backends for clarity.
    • Advanced optional parameters handling: Handles camera configurational parameters and user-defined settings for various camera types.
      • New optional configurational parameters: Currently Supports "sensor", "format", "controls", "transform", "stride", "buffer_count", and "queue" with sanity checks. Seperated Raspberry Pi camera module exclusive and Unified USB cameras supported optional parameters.
      • New user-defined optional parameters: Such as auto_align_output_config, enable_verbose_logs, and more.
• StreamGear:
  • Introduced new -enable_force_termination attribute for immediate FFmpeg process termination.
• Helper:
  • Added a custom deprecated decorator to mark deprecated functions and parameters.
    • It displays a warning message when a deprecated function or parameter is used.
• Docs:
  • Overhauled mkdocs theme.
    • Added unrecognized_links: ignore to mkdocs.yml for validations.
    • Added custom admonition icons to mkdocs.yml
    • Added new git-authors plugin in mkdocs.yml
    • Added new tables markdown extension in mkdocs.yml
    • Added custom fences to pymdownx.superfences markdown extension.
    • Added line_spans: __span and pygments_lang_class: true parameters to pymdownx.highlight markdown extension.
    • Added normalize_issue_symbols: true to pymdownx.magiclink markdown extension.
    • Added new mkdocs feature dependency mkdocs-git-authors-plugin.
  • Added the use of new -enable_force_termination parameter.
  • Added a new FAQ entry about the deprecated rgb_mode parameter.
  • Added new screengear_error11.png asset.
• CI:
  • Added test cases for import_dependency_safe function to validate different scenarios and error handling in import_dependency_safe.

Updates/Improvements ⚡️

• Core:
  • Improved exception handling for module imports.
    • Updated import_dependency_safe in helper.py:
      • Added specific handling for ModuleNotFoundError.
      • Included original exception in ImportError for better error tracing.
      • Enhanced logging to include exception traceback when error is set to "log".
    • Enhanced import_core_dependency in __init__.py:
      • Added specific handling for ModuleNotFoundError.
      • Included original exception in ImportError for better error tracing.
  • Improved colorspace handling in videocapture gears
    • Logged a warning and discarded invalid colorspace values instead of raising an exception.
    • Consolidated colorspace logging into a single line using a ternary operation.
• Asyncio:
  • Replaced deprecated Starlette's on_shutdown parameter with an async context manager lifespan in WebGear and WebGear_RTC APIs. (Fixes [Proposal]: Deprecate on_startup and on_shutdown in favor of lifespan #397)
    • Moved shutdown logic for VideoGear and peer RTC connections to this new lifespan context manager.
    • Added new contextlib import for using asynccontextmanager.
• NetGear_Async API:
  • Modified __init__ method to handle event loop more robustly:
    • Try to get the running event loop using asyncio.get_running_loop()
    • If no running event loop found, create a new one with asyncio.new_event_loop()
    • Log if creating a new event loop
  • Changed launch method to use self.loop.create_task() instead of asyncio.ensure_future()
    • Ensures the task is created using the correct event loop instance.
  • Moved the event loop initialization code to an earlier point before setting event loop policy to ensure it is set up correctly before selecting WindowsSelectorEventLoop policy.
    • On Windows, vidgear requires the WindowsSelectorEventLoop, but Python 3.8 and above defaults to the ProactorEventLoop which is not compatible.
  • Removed redundant python version check to set WindowsSelectorEventLoop policy, as minimum supported version is already 3.8.
  • Move event loop setup and policy assignment to the beginning of __init__ before zmq Context creation.
  • Refactored return data handling.
• StreamGear:
  • Updated close() methods for handling gracefully signal interruptions based on different operating systems with device audio streams.
  • Deprecated terminate() method, introducing close() for safer process termination.
  • Enhanced stream copy support in Single Source mode (Fixes [Proposal]: -vcodec copy HLS #396).
    • Moved settings for "-vf" and "-aspect" inside conditional blocks.
    • Added warnings and discarded these parameters in stream copy mode.
    • Ignored stream copy parameter in Real-time Frames Mode or Custom Streams with appropriate warnings.
    • Updated -acodec handling:
      • Default to aac for Custom Streams.
      • Use stream copy (-acodec copy) for input video’s audio when Custom Streams are disabled.
    • Refined -livestream parameter usage to Real-time Frames Mode only.
    • Adjusted video and audio bitrate assignment to skip when stream copy is enabled.
    • Improved log message for -clear_prev_assets parameter.
  • Restricted -livestream parameter to Real-time Frames Mode only.
    • Disabled live streaming for video files and updated relevant logging.
  • Enhanced warning messages and clarified description.
• PiGear:
  • Logging optimization with warning for common libcamera messages.
  • Lowered framerate minimum value to 0.0.
  • Moved sensor optional parameter to commonly supported picamera2 configurational parameters.
  • Removed unsupported bit_depth optional parameters.
  • Updated PiGear API tagline and introduction.
• NetGear:
  • Enhanced logging and error handling for secure mode.
  • Logged Authenticator start/stop events.
  • Handled socket session expiration more gracefully in recv_handler.
  • Ensured proper termination of the ZMQ context and socket when closing the NetGear instance.
• WebGear:
  • Enhanced error messages for WebGear auto-generation workflow (Fixes [Bug]: WebGear throws error 500: context must include a "request" key #403)
    • Updated homepage, not_found, and server_error methods to include more detailed JSON error messages.
    • Added specific error and message prefixes to improve clarity.
• WebGear_RTC:
  • Optimized peer connection closure to avoid redundant closures.
  • Reduced unnecessary logging by only logging ICE connection state changes when they are not in a "failed" state.
• WriteGear:
  • Simplified the logic for formatting output parameters.
  • Improved error handling in execute_ffmpeg_cmd method:
    • Raised ValueError with descriptive messages for BrokenPipeError or IOError.
    • Updated error handling per PEP 409 to preserve original exception context or suppress it based on logging settings.
• CamGear:
  • Removed GStreamer support check.
  • Improved readability of livestream warning logs.
• Setup.py:
  • Dropped legacy picamera dependency in setup.py.
  • Updated setup.py to use the latest pyzmq version to address installation issues (Fixes [Bug]: update pyzmq version #399).
• Helper:
  • Added patch for substring index bug in get_supported_demuxers helper method.
  • Updated extract_time helper function regex to handle milliseconds.
• Docs:
  • Update StreamGear documentation:
    • Updated documentation to deprecated terminate() method, and introducing close() for safer process termination.
    • 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.
    • Added a tip box on benefits of using stream copy (-vcodec copy) for faster HLS/DASH transcoding.
      • Highlighted limitations of stream copy, including incompatibility with Real-time Frames Mode and Custom Streams.
      • Clarified automatic audio stream copy (-acodec copy) usage with input video’s audio stream.
    • 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 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.
  • Update PiGear documentation:
    • Added a warning advising users to disable common libcamera messages when logging is disabled.
    • Updated Picamera2 installation instructions (including apt, pip, pre-installation on Raspberry Pi images, and compatibility warnings)
    • Moved legacy Picamera library installation instructions to an admonition.
    • Removed Importing section from overview to avoid confusion.
  • Update NetGear documentation:
    • 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.
    • Added warning log for potential issues with flag=1 (NOBLOCK). (Fixes Exception in thread NetGear, zmq.error.Again: Resource temporarily unavailable #390)
      • Changed default value of copy to True in NetGear API documentation.
    • Noted that track option is ignored when copy=True.
  • Update WriteGear documentationL
    • Updated the documentation for the -disable_force_termination parameter.
  • Update README.md:
    • Replaced deprecated options (frame_jpeg_quality, frame_jpeg_optimize, frame_jpeg_progressive) with their newer equivalents (jpeg_compression_quality, jpeg_compression_fastdct, jpeg_compression_fastupsample) in WebGear usage example.
  • Update mkdocs.yml:
    • Set edit_uri for GitHub edit links
    • Add new theme features like content actions, tooltips, etc.
    • Update palette settings for light/dark mode
    • Enable new markdown extensions
    • Add custom javascript hook support.
    • Migrated to new Google Analytics 4 in mkdocs.yml
    • Replaced depreciated materialx with supported emoji extension.
    • Replaced permalink icon with default one.
  • Improved overall documentation quality, including enhancing clarity, readability, consistency, and precision.
  • Added detailed explanations, practical examples, best practices, and clearer usage patterns.
  • Updated sections, code examples, admonitions, and comments for better clarity and accuracy.
  • Added missing version contributors to changelog.md
  • Added new icons to make headings more readable
  • Replaced unsupported admonitions with supported ones
  • Removed all custom admonition icons and color CSS from custom.css
  • Removed Twitter section from help and docs site metadata
  • Updated Zenodo badge and BibTeX entry
  • Added workaround for 'AttributeError: 'DXCamera' object has no attribute 'is_capturing'' error on Windows.
  • Remove script tags from main.html and use a custom hook for adding javascripts on certain pages.
  • Refactored all APIs and bonus examples to use linenums and hl_lines which makes it easier to highlight specific lines in code blocks.
  • Removed Gitter community chat sidecard JS file.
  • Redefined spacing between sections.
  • Change system mode toggle icon and name in mkdocs.yml.
  • Add failure warning in various docs about picamera incompatibility on 64-bit OS.
  • Update announcement icon in main.html.
  • Remove site.webmanifest file.
• Maintenance:
  • Applied short-circuiting to simplify code across various APIs and tests.
  • Improved logging, parameter validation, and added descriptive dialogs across various APIs.
  • Moved logging enablement before version logging for consistency in vidgear APIs.
  • Removed redundant boolean assignment for various APIs internal logging.
  • Simplified conditional statements and assignments using short-circuiting, Boolean operations, and ternary operators.
  • Refactored vidgear code to improve readability, maintainability, and performance,
  • Added .cache directory to .gitignore,
  • Updated vidgear library version to v0.3.3.
  • Improved code efficiency with short-circuiting and formatting.
  • Updated logging practices to be more developer-friendly.
  • Updated code highlighting.
  • Corrected a typo in comments.
  • Simplified code using short-circuiting.
  • Removed unnecessary parentheses and type checks.
  • Removed unused imports.
  • Updated code comments.
• CI:
  • Temporarily removed PiGear API from code coverage due to hardware limitations.
  • Deprecated custom event_loop fixture overrides in WebGear_RTC and NetGear_Async tests
    • Removed redundant pytest.mark.asyncio decorators from several test functions.
  • Add a new event_loop_policy fixture for pytest to override the event loop policy:
    • Added new recommended approach of using pytest.mark.asyncio(scope="module") to mark all WebGear_RTC and NetGear_Async tests as asynchronous and utilize the same event loop throughout the module.
    • Log the event loop being used for debugging.
  • Updated NetGear unit tests to reflect the new default for copy.
  • Ensured coverage for raise, log, silent, and unknown error types.
  • Improved parameterized test cases to support floating point values.
  • 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.
  • Removed pinned cryptography==38.0.4 dependency.
  • Remove unused imports and code cleanup.
  • Rearranged the dependencies.

Breaking Updates/Changes 💥

• StreamGear:
  • Deprecated terminate() method and introduce close() method.
    • The terminate() method in StreamGear is now deprecated and will be removed in a future release. Developers should use the new close() method instead, which provides a more descriptive name like in WriteGear API for terminating StreamGear processes safely.
  • Deprecated rgb_mode parameter in stream() method.
    • This parameter will be removed in a future version, and only BGR format frames will be supported.
  • Restricted -livestream parameter to Real-time Frames Mode only.
    • Live streaming is intended for low-latency streaming of real-time frames, where chunks contain only the most recent frames. It doesn't make sense when streaming from a video file, as the entire file can be streamed normally without the need for live streaming.

Bug-fixes 🐛

• PiGear:
  • Modify PiGear class behavior when enforce_legacy_picamera=True on unsupported system
    • Instead of silently disabling picamera2 API directly, PiGear now raises an error if picamera is unavailable or unsupported
    • Prevented incorrect initialization of PiGear class on unsupported 64-bit OS systems.
  • Fixed UnboundLocalError bug for 'picamera2' variable assigment.
  • Fixed UnboundLocalError bug for 'queue' variable assignment.
  • Fixed colorspace typo bug.
• StreamGear:
  • Fixed incompatibility of stream copy with Real-time Frames Mode.
    • Added warnings and discarded -vcodec copy when using this mode.
  • Removed non-essential aspect ratio parameter to prevent unwanted distortions (Fixes [Bug]: Stream gear imposes simplified aspect ratios, which does not seem necessary #385).
  • Moved handle streaming format to beginning to fix 'StreamGear' object has no attribute '_StreamGear__format' bug.
• NetGear:
  • 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.
  • Fixed msg_json undefined when terminating context in the recv_handler method.
• CamGear:
  • Fixed logging condition for yt-dlp (Fixes [Bug]: Logging issue with yt-dlp #394)
    • Updated no_warnings parameter in CamGear to be False when logging is enabled and True otherwise.
• Docs:
  • Replaced buggy kofi widget with a button image in index.md.
  • Fixed Ko-fi sponsorship heart hover effect in footer
    • Replaced twemoji heart emoji with heart-pulse fontawesome SVG
  • Fixed titles and indentations in various admonitions.
  • Fixed various code comments, and hyperlinks URLs.
  • Fixed various issues like typos, formatting errors, code highlighting issues, and grammar inconsistencies.
  • Fixed typos, formatting, code highlighting, and grammar issues.
  • Fixed minor typo in js_hook.py.
• CI:
  • Fixed simplejpeg and opencv not compatible with numpy==2.x.x versions.
    • Pinned numpy<2.0.0 in all CI envs.
  • 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.
  • Fixed pip install hash bug in Azure Pipelines CI.
  • Fixed various typos and code issues in tests.
  • Fixed invalid escape sequence in testcase string.
  • Fixed python environment bugs in appveyor.yml.

Requirements / Checklist

• I have read the PR Guidelines.
• I have read the Documentation.
• I have updated the documentation accordingly(if required).

Related Issue

#410
#394
#403
#390
#396
#385
#399
#397
#342

Context

This update significantly enhances Vidgear's capabilities, ensuring better performance, broader compatibility, and improved user experience. The introduction of the Picamera2 API support, enhanced error handling, and detailed documentation updates are pivotal in making Vidgear more robust and user-friendly.

Types of changes

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

Screenshots (if available):