…d using pip.

✨ This update brings official support for the new Picamera2 API, unlocking powerful features for Raspberry Pi Camera Modules and limited USB camera support.

Key improvements:
- 🚸 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.
- ⚡️ 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 if Picamera2 is unavailable.
- 🧑‍💻 Standalone functionalities: Separates functionalities for both legacy and newer APIs for clarity.
- ⚡️ Automatic configuration management: Handles common configuration parameters and non-standard settings for various camera types.
- New internal parameters:
  - 🚩 auto_align_output_config: Optimizes output frame configuration for the camera sensor.
  - 🚩 enable_verbose_logs: Enables more detailed logging through Picamera2.
- Unified `format` parameter:
  - 🥅 Defaults to RGB888 (24-bit BGR) for Raspberry Pi cameras.
  - 🦺 Validates formats for USB cameras before handling.
  - 🥅 Requires explicit `colorspace` definition if `format` is not MPEG (USB cameras) or for specific formats in Raspberry Pi cameras.
- Raspberry Pi camera exclusive parameters:
  - 🚩 Currently Supports `"controls," "queue," "transform," "bit_depth," "buffer_count," "sensor," and "stride"` with type checks.
- ⚡️ Framerate handling: Tailored framerate handling based on camera type.
- 🦺 Logging optimization: Added a warning advising users to disable common libcamera messages when logging is disabled.

Additional Changes:
- 💥 Dropped legacy `picamera` dependency in `Setup.py`.
- 💡 Improved code efficiency with short-circuiting and formatting.
- 🔊 Updated logging practices.

CI:
- 🏗️ Temporarily removed PiGear API from code coverage due to hardware limitations.

- 💡 Updated code comments.

- 🧑‍💻 Replaced legacy Picamera library installation instructions with Picamera2 python library.
- 📝 Added two methods of Picamera2 installation: using `apt`(recommended) and using `pip`.
- 🚸 Added information admonition about Picamera2 comes pre-installed on images downloaded from Raspberry Pi.
- 🚸 Added warning admonition Picamera2 is only supported on Raspberry Pi OS Bullseye (or later) images.
- 🚸 Moved legacy Picamera library optional installation instructions to a Admonition.
- 🔇 Added `unrecognized_links: ignore` to mkdocs.yml for validations to minimize logging.
- 📝 Updated vidgear library binaries version.

… while using an API.

- 📝 Added new `navigation.tabs.sticky`, `navigation.tracking`, `navigation.instant`, and `navigation.instant.progress` features.
- 📱 Replaced docs font `Muli` with `Source Sans 3`.
- 💄 Added custom admonition icons to `mkdocs.yml`.
- 🚩 Added `enable_creation_date:true` and `fallback_to_build_date: true` to `git-revision-date-localized` plugin.
- 🚚 Migrated to new Google Analytics 4 in mkdocs.yml.
- ✨ Added new `git-authors` plugin in `mkdocs.yml`.
- ✨ Added new `tables` markdown extension.
- 🚩 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 complete Picamera2 library installation instructions for pip and source.
  - 🚚 Moved legacy picamera python library installation instructions to admonition.
- ➕ Added new mkdocs feature dependency `mkdocs-git-authors-plugin`.
- 👥 Added missing version contributors to changelog.md
- 🧑‍💻 Added new icons to make headings more readable.
- 🗑️ Replace depreciated `materialx` with supported `extensions` emoji extension.
- 🩹 Fixed titles and indentations in various admonitions.
- 📝 Replaced permalink icon with default one.
- 🩹 Replaced wrong unsupported admonitions with supported ones.
- 🔥 Removed all custom admonition icons and color CSS from `custom.css`.
- 🙈 Added `.cache` directory to `.gitignore`.
- 🔥 Removed Twitter section from help and site metadata.
- 🩹 Fixed Ko-fi sponsorship heart hover effect in footer.
- 💄 Replace twemoji `heart` with `heart-pulse` fontawesome SVG.
- 🔥 Removed Gitter community chat sidecard js.
- 💄 Redefined spacing between sections.
- ✏️ Fixed small typos and hyperlinks.

- 🚩 Moved `sensor` optional parameter to common supported picamera2 config parameters.
- 🔥 Removed unsupported `bit_depth`, `buffer_count`, `queue` optional parameter from picamera2 config parameters.
- 🥅 Added sanity checks for `sensor` optional parameter, only `output_size`, `bit_depth` config parameters are supported.
- 🥅 Added sanity checks for `controls` optional parameter, only camera sensor specific config parameters extracted using `camera.camera_controls` are supported.
- 💡 Added comments related to `controls`, `transform` and `stride` not supported with USB cameras.
- 🔊 Updated logs to be more developer friendly.

- 📝 Added a concise tagline of the PiGear API. Emphasize its seamless wrapper around Picamera2, compatibility with various camera modules, and robust resource management through the Threaded Internal Timer feature.
- 🧑‍💻 Update the PiGear API introduction in the documentation to provide a more concise and intuitive summary. Highlight the key features, such as seamless Picamera2 integration, enhanced camera control, USB camera support, and automatic configuration management.
- ♿️ Reflected these updated changes in `README.md` and `index.md`, and PiGear source code comments.
- 🩹 Fixed colorspace typo bug in PiGear API.
- 💡 Fixed minor code comments.

…ation

- **Overview**
    - 📝 Updated the description for the camera module and added limited USB camera support with the `Picamera2` backend.
    - 🧑‍💻  Added backward compatibility information for seamless legacy `Picamera` switching.
- **Parameters**
    - 🚸 Clarified the `camera_num` parameter to allow multiple cameras.
    - 📝 Updated the `options` parameter with new sections:
        - Configurational Camera Parameters (provided by the backend library).
        - User-defined Parameters (e.g., `enforce_legacy_picamera`, `enable_verbose_logs`).
    - 🧑‍💻 Updated admonitions, examples, and text for each parameter.
- **Usage Examples**
    - 📝 Updated examples for Picamera2 configuration, user-defined parameters, and legacy Picamera usage.
    - ✨ Added new admonitions on:
        - Picamera2 configurational parameters (with table) and library installation.
        - Enabling verbose logs for the Picamera2 backend.
        - Limited USB camera support with the Picamera2 backend.
        - Prioritization of the Picamera2 backend and enforcing the legacy backend.
        - Disabling common `libcamera` messages in silent mode.
    - 📝 Updated the usage example to include examples for both the `picamera2` and legacy `picamera` backends when using the PiGear API.
- **Bonus Examples**
    - ✨ Added examples for changing the output pixel format and accessing multiple cameras (Picamera2 backend).
    - ✨ Added new example for dynamically adjusting Raspberry Pi Camera Parameters at Runtime in the PiGear API for both the `picamera2` and legacy `picamera` backends.
- **FAQ**
    - 📝 Updated answers to refer to the "Switching from OpenCV" guide and API documentation.
    - ✨ Added new questions and answers related to PiGear API features.
- 📝 Updated the PiGear description to include support for camera modules and limited USB cameras on Raspberry Pis.
- ✨ Added a note about enforcing the legacy Picamera API backend using the `enforce_legacy_picamera` parameter in various documents concerning the PiGear API.
- 🚸Updated formatting and readability in various documentation files.
- 🧑‍💻 Updated the warning message about enabling Raspberry Pi camera hardware-specific settings.
- 💄Added `content.footnote.tooltips` feature in `mkdocs.yml`.

- 🏗️Moved logging enablement before version logging for consistency.
- 🔥Removed redundant boolean assignment for `self.__logging`.
- 🧑‍💻 Simplified conditional statements and assignments using short-circuiting, Boolean operations, and ternary operators.
- ♻️ In `netgear_async.py`: Refactored return data handling in `recv_generator`.
- ♻️ vidgear code has been refactored to improve readability, maintainability, and performance.

- 🧑‍💻 Renamed references from 'PiCamera2' to 'picamera2' for consistency
- 🚩 Added option to enforce legacy picamera API with 'enforce_legacy_picamera' optional boolean parameter.
- ⚡️Improved logging and warning messages for unsupported/custom formats.
- ✨ Added `buffer_count` and `queue` configuration parameter options for picamera2 API.
- 🏗️ Renamed `auto_align_output_config` to `auto_align_output_size`.
- 🔊 Included `buffer_count` and `queue` in `picamera2` parameter logging.
- ✏️ Fixed a typo in the error message for Camera Module API failure.
- 💡 Clarified comments for thread joining during `stop()`.
- 🚸 Minor code formatting and comment updates.

…ignment

…ted_demuxers` method.

Docs:
- 📝 Updated the PiGear API's example to new Picamera2 backend in README.md.
- 🚀 Applied new Picamera2 backend integration documentation changes to StreamGear, plus VideoGear and its dependent WebGear, WebGear_RTC, and NetGear_Async API's Parameters, Usage and Bonus examples.
- ✏️ Fixed typos typos and context in documentation.

- ✏️ Fixed typos in hyperlink URLs.

🚀 This massive update brings official support for the new Picamera2 API, unlocking powerful features for Raspberry Pi Camera Modules and limited USB camera support. 

### ✨Key PiGear Enhancements include:
- **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.
- **Document Overhaul:** * 
- **Advanced optional parameters handling:** Handles camera configurational parameters and user-defined settings for various camera types.
	- **New optional configurationalparameters:** 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.
- **Additional changes:**
	* 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 
	* Fixed colorspace typo bug
	* Fixed UnboundLocalError bug for 'picamera2' variable assigment.
	* Fixed UnboundLocalError bug for 'queue' variable assignment.

### 📝 Documentation updates:
* Added a warning advising users to disable common `libcamera` messages when logging is disabled.
* Updated Zenodo badge and BibTeX entry
* Added complete Picamera2 library installation instructions for `pip` and from source as a dependency. 
* 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 in PiGear.
* Overhauled mkdocs theme.
  * Added `unrecognized_links: ignore` to `mkdocs.yml` for validations.
  * Added new `features` to mkdocs.yml 
	* Added custom admonition icons to mkdocs.yml 
	* Migrated to new Google Analytics 4 in mkdocs.yml 
	* Added new `git-authors` plugin in mkdocs.yml 
	* Added new tables markdown extension 
	* 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
	* Replaced depreciated `materialx `with supported emoji extension.
	* Replaced permalink icon with default one 
* 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
* 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.
* Removed Gitter community chat sidecard JS file.
* Redefined spacing between sections 
* Fixed various typos, code comments, and hyperlinks URLs. 

### 🧑‍💻 Maintenance Updates:
* 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 return data handling in netgear_async.py
* Refactored vidgear code to improve readability, maintainability, and performance
* Added `.cache` directory to `.gitignore` 
* Updated vidgear library version to `v0.3.3`
* Dropped legacy picamera dependency in Setup.py 
* Improved code efficiency with short-circuiting and formatting
* Updated logging practices to be more developer-friendly
* Updated code highlighting in NetGear_Async Docs
* Added patch for substring index bug in `get_supported_demuxers` helper method.
* Updated code comments 

### 👷CI Updates:
* Temporarily removed PiGear API from code coverage due to hardware limitations 
* Fixed `pip install` hash bug in Azure Pipelines CI.

…edirect

- 💚 Change mike deploy commands in `deploy_docs.yml` to use `--alias-type=copy`
  instead of `--no-redirect` for release, stable, and dev deployments
- 💬 Update `main.html` announcement text with minor wording changes
- ♿️ Set default version in `mkdocs.yml` to 'latest'

…o attribute 'is_capturing'' error on Windows.

- 💄 Added new `screengear_error11.png` asset.

- 🏗️ Replaced deprecated Starlette's `on_shutdown` parameter with an async context manager `lifespan` in WebGear and WebGear_RTC APIs.
- 🚚 Moved shutdown logic for VideoGear and peer RTC connections to this new `lifespan` context manager.
- 📦️ Added new `contextlib` import for using `asynccontextmanager`.

Docs:
- 📝 Update README.md with changes to JPEG compression options
  - ✏️ Replaces 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.

- 👷 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.
- 🗑️ Deprecated custom `event_loop` fixture overrides in WebGear_RTC and NetGear_Async tests.
- 🔥 Removed redundant `pytest.mark.asyncio` decorators from several test functions.

- ⚡️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.
  - 💬 Background: 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`.
- 💡 Updated code comments.

- 🐛 Replaced buggy kofi widget with a button image in index.md
- 🏗️ Remove script tags from main.html and use a custom hook for adding JS
- 🔥 Remove site.webmanifest file
- 💄 Update mkdocs.yml with new configuration settings:
    - 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 JS hook for adding scripts on certain pages
- ♻️ Other minor tweaks and cleanups

- 👷 Add a new event_loop_policy fixture for pytest to override the event loop policy
- 🔊 Log the event loop being used for debugging
- 🔧 Mark the new fixture in relevant test functions with pytest.mark.asyncio(scope="module")
- ♻️ Remove unused imports and code cleanup

NetGear_Async:
- ⚡️ Move event loop setup and policy assignment to the beginning of `__init__` before zmq Context creation.

- 🧑‍💻 Refactored all APIs and bonus examples to use linenums and hl_lines
    - Makes it easier to highlight specific lines in code blocks
- 📝 Updated remaining code examples for picamera2 and legacy picamera backends
- 🐛 Replaced buggy kofi widget with a button image in  `help.md`
- 💄 Update announcement icon in `main.html`
- 💄 Change system mode toggle icon and name in `mkdocs.yml`

…ra=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.

Docs:
- 📝 Add failure warning in various docs about `picamera` incompatibility on 64-bit OS

- 🏗️ Replaced deprecated Starlette's `on_shutdown` parameter with an async context manager `lifespan` in WebGear and WebGear_RTC APIs.
- 🚚 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:
- 🩹 Fixed event loop handling 
    - ⚡️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.
- 🚑️  Fix event loop initialization on Windows platforms 
    - ⚡️ 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.
      - 💬 Background: 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`.
    - 💡 Updated code comments.
- ⚡️ Move event loop setup and policy assignment to the beginning of `__init__` before zmq Context creation.

### PiGear API: 
- 🚑️ 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.

### Docs: 
- 📝 Added workaround for 'AttributeError: 'DXCamera' object has no attribute 'is_capturing'' error on Windows.
- 💄 Added new `screengear_error11.png` asset.
- 📝 Update README.md with changes to JPEG compression options
  - ✏️ Replaces 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.
- 🐛 Replaced buggy kofi widget with a button image in index.md
- 🏗️ Remove script tags from main.html and use a custom hook for adding JS
- 🔥 Remove site.webmanifest file
- 💄 Update mkdocs.yml with new configuration settings:
    - 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 JS hook for adding scripts on certain pages
- ♻️ Other minor tweaks and cleanups
- 🧑‍💻 Refactored all APIs and bonus examples to use linenums and hl_lines
    - Makes it easier to highlight specific lines in code blocks
- 📝 Updated remaining code examples for picamera2 and legacy picamera backends
- 🐛 Replaced buggy kofi widget with a button image in  `help.md`
- 💄 Update announcement icon in `main.html`
- 💄 Change system mode toggle icon and name in `mkdocs.yml`
- 📝 Add failure warning in various docs about `picamera` incompatibility on 64-bit OS

### CI: 
- 💚 Deprecated event_loop fixture overrides. 
    - 👷 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.
    - 🗑️ Deprecated custom `event_loop` fixture overrides in WebGear_RTC and NetGear_Async tests.
    - 🔥 Removed redundant `pytest.mark.asyncio` decorators from several test functions.
- 💚 Refactor event loop handling 
    - 👷 Add a new event_loop_policy fixture for pytest to override the event loop policy
    - 🔊 Log the event loop being used for debugging
    - 🔧 Mark the new fixture in relevant test functions with pytest.mark.asyncio(scope="module")
    - ♻️ Remove unused imports and code cleanup

💬 When the output codec is set to "copy" (stream copy mode), certain video
processing parameters like "-vf" (video filters) and "-aspect" (aspect ratio)
are not supported and can lead to errors and invalid output files.

♻️ This commit refactors the internal `PreProcess` method in StreamGear API to handle
the stream copy mode correctly:

- 🥅 Moved the existing code for setting "-vf" and "-aspect" inside conditional block that checks if
  the output stream codec is not "copy".
- 🔊 Added an else block to log warnings and discard "-vf" and "-aspect" in stream copy mode.

- 🧑‍💻 Update the StreamGear usage examples for streaming live audio from an external device
  - Fixed typo in source, code comments and filename in usage example code.
  - Updated usage example for device video source.
- ✏️ Fixed minor typo in `js_hook.py.`

StreamGear:
- 💡 Fix minor typos and formatting issues in code comments for better clarity

Helper:
- 🩹Update `extract_time` helper function regex to handle milliseconds.

♻️ 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.

- 📌 Pinned `typing_extensions` dependency to `>=4.7.1` for using the `@deprecated` decorator. See issue fastapi/fastapi#9808
- 🗑️ Deprecate the `terminate()` method in StreamGear and added backward compatibility.
- ⚡️ Introduce a new `close()` method to safely terminate StreamGear processes
- 📝 Minor formatting and docstring updates

…#399)

- 💬 pyzmq version `24.0.1` has a bug with Cython, and it breaks the installation process. See issue [cython/cython#5238](cython/cython#5238).

💬 The updates aim to provide a better understanding of the StreamGear API's functionality, modes of operation, and usage scenarios. The documentation now includes more detailed explanations, practical examples, and best practices for working with StreamGear in various situations.

- 📝 Improve the overview section's description and wording.
- 🧑‍💻 Update usage examples for both Single-Source Mode and Real-time Frames Mode.
- ♻️ Refactored sections for Live Streaming and RGB Mode usage.
- ♿️ Clarify warnings, alerts, and important information.
- 🎨 Fix markdown formatting and code highlighting issues.
- 🗑️ Addressed deprecation of the `terminate()` method in favor of new `close()` method.
- 🚸 Enhance overall clarity and readability of the documentation.

WriteGear:
- ⚡️ Simplified the logic for formatting output parameters.

CI:
- 👷 Updated Streamgear tests to use new `close()` method instead of deprecated `terminate()`.

- ⚡️ Implemented a custom `deprecated` decorator function
  - This decorator can be used to mark functions or parameters as deprecated
  - It displays a warning message when a deprecated function or parameter is used

StreamGear:
- ⚡️ Updated the `stream` method to use the new custom `deprecated` decorator
- 🗑️ Marked the `rgb_mode` parameter as deprecated with a relevant warning message
  - This parameter will be removed in a future version, and only BGR format frames will be supported
- 🚩 Added a new `-enable_force_termination` attribute, similar to WriteGear API.
  - When set to True, this parameter will force the termination of the FFmpeg process
  - This option can be useful in cases where the FFmpeg process needs to be terminated immediately
- 🔊 Enhanced logging messages for better clarity and readability
- 🧑‍💻 Improved parameter validation and added more descriptive warning/error messages
- 🎨 Refactored some conditions and error handling for better code maintainability
- 💡 Updated docstrings and comments to better reflect the current functionality
- 📝 Improved code documentation for better understanding and easier maintenance
- 🩹 Fixed `libx264rgb` encoder not compatible with `-profile:v` FFmpeg parameter.

Setup
- ⏪️ Removed the `typing_extensions` package as core dependency
  - This package was previously required for the `deprecated` decorator.
  - With the introduction of the custom `deprecated` decorator in helper.py, this dependency is no longer needed.

- ♻️ Refactored the logic for terminating the FFmpeg process in the `close` method
  - Instead of directly terminating the process, the code now sends a CTRL_BREAK_EVENT signal
  - This allows for a more graceful termination and avoids potential issues with abrupt termination
  - If the forced termination option is enabled, the process is directly terminated
- ✏️ Fixed a typo in an error message related to stream initiation
- 🎨 Refactored and simplified some logging statements using Python's ternary operator

🍻 WriteGear: Mirrored logic for terminating the FFmpeg process in the `close` method

- 🔥 Removed the obsolete usage example for deprecation RGB mode with StreamGear.
- 🗑️ Added a deprecation warning admonition for the `rgb_mode` parameter in the `stream()` method.
- 💡 Updated the docstring for the `stream()` method and `transcode_source()` method.
- 🚩 Added documentation and usage of the new `-enable_force_termination` parameter.
- 📝 Updated the documentation for the `-disable_force_termination` parameter in WriteGear API.
- 💬 Added a new FAQ entry about deprecated `rgb_mode` parameter.
- 🎨 Minor formatting and wording improvements in the documentation.

- 🏗️ Removed the `-aspect` parameter from the default FFmpeg pipeline
  - Previously, StreamGear would enforce a simplified aspect ratio using this parameter, which forces FFmpeg to use non-square pixels, leading to unwanted distortion on the output.
- 🎨 Updated warning messages for better clarity.

- 🔊 Updated the StreamGear docs file to clarify the purpose and potential side effects of the `-enable_force_termination` parameter.

StreamGear API:
- 🧑‍💻 Modified the warning message to mention that forced termination can cause corrupted output in certain scenarios.
- 🔊 Changed the log message in StreamGear to print a warning instead of an info message when forced termination is enabled.

…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.

- 🏗️ Disabled live streaming if `-video_source` is provided (Single-Source Mode)
- 🔊 Log an error message when live streaming is attempted in Single-Source Mode, otherwise log normally in Real-time Frames Mode.

Docs:
- 📝 Refine description of `-streams` attribute of StreamGear API for better clarity in params.
  - Clarify primary stream generation and user-defined secondary streams.
  - Improve formatting and language for better readability.
- ♻️ Replace usage of "tip" admonition with "example" for usage examples.
- 🚸 Add warning for unsupported `-livestream` parameter in Single-Source Mode.
- 📝 Updated respective notices for deprecate `terminate()` method and `rgb_mode` parameter.
- 🔥 Remove unsupported live-streaming usage examples in Single-Source Mode.

…hance clarity and readability

- 🧑‍💻 Simplified and clarified descriptions for `output`, `format`, `custom_ffmpeg`, and `stream_params` parameters.
- 📝 Improved examples for defining output paths, filenames, and URLs.
- 🚸 Enhanced warnings, tips, and information admonitions for better user guidance.
- 🎨 Reformatted code examples to provide clearer usage patterns.
- ✏️ Updated formatting and grammar for consistency and precision.

- 🔥 Removed unused imports.

💬 The `close()` methods in StreamGear and WriteGear were sending the
`CTRL_BREAK_EVENT` signal to terminate the underlying process, which only
works on Windows systems. This commit modifies the code to send the
appropriate signal based on the operating system:

- For Windows, it sends the `CTRL_BREAK_EVENT` signal
- For non-Windows systems, it sends the `SIGINT` signal

…ate_dash_stream` method.

- 🔊 Updated logging message format in `evaluate_streams` method of for consistency.

WriteGear:
- 🐛 Fixed dictionary comprehension logic to strip only string values.

CI:
- 💚 Fixed expected duration value in parameterized test case from `8` to `8.44` since `test_extract_time` function now supports floating point values.

… Mode

🚑️ This commit addresses an bug where the `-vcodec copy` parameter was
incorrectly defined when using the Real-time Frames Mode in StreamGear.
Stream copy is not compatible with this mode since it requires encoding
the frames before streaming. Additionally, If the Real-time Frames Mode
is active and `-vcodec copy` is specified, a warning log message is printed
to notify the user that the stream copy parameter is being discarded.

- 🐛 Updated logic to use `zmq.Context()` instead of `zmq.Context.instance()` to isolate contexts in order to fix `zmq.error.ZMQError: Address in use (addr='inproc://zeromq.zap.01')` bug.
- ♻️ Refactored code.

CI:
- 💚 Fixed typos in NetGear Tests method names.

- ⏪️ Reverted Isolated contexts for Secure Modes

…4.0.1` on Windows.

- 🧑‍💻 Added warnings about Secure Mode issues with PyZMQ versions > 24.0.1 on Windows in NetGear API:
    - 💬 Secure Mode functionality is broken on Windows with PyZMQ versions > 24.0.1 due to changes in `zmq.auth` module.
    - 💬 Users should downgrade to PyZMQ version <= 24.0.1 to use Secure Mode on Windows.
- 🧑‍💻 Added warnings about Stream copy (`-vcodec copy`) is not compatible with Real-time Frames Mode as this mode requires re-encoding of incoming frames in StreamGear API.
    - 💡 Refined warning message for stream copy compatibility for clarity.

CI:
- 👷 Added a skip condition in `test_netgear.py` for Windows platform when PyZMQ version > 24.0.1:
    - Ensured relevant tests are skipped on incompatible PyZMQ versions to prevent test failures.

NetGear:
- ⏪️ Reverted Handle graceful termination of ZMQ Context.

- 👷 CI: Applied short-circuiting to simplify code in NetGear Tests.

…dio streams only.

WriteGear:
- ⏪️ Reverted terminating the FFmpeg process in the `close` method, handled by `terminate()`

⚡️ StreamGear: Discarded invalid audio stream.

…xts.

- 🚑️ Fix an issue where the secure mode failed to work due to conflicting ZMQ contexts, when Server and Client run on same thread.
  - Moved ZMQ Authenticator and Certificates handling code together, independent of mode activated in API.
  - Handle Authenticator and Certification errors more gracefully, by handling the "Address in use" error, and disable secure mode if errors occur.
  - Logged Authenticator start/stop events.
- 🥅 Handle socket session expiration more gracefully in the `recv_handler` internal method.
- Fixed `msg_json` undefined when terminating context in the `recv_handler` internal method forcefully.
- 🩹 Ensure proper termination of the ZMQ context and socket when closing the NetGear instance.
- ⚡️ Set the `WindowsSelectorEventLoopPolicy` for Python `3.8` and above on Windows to ensure compatibility with ZMQ event loop.
- ♻️ Simplify and refactor conditional statements and variable assignments with short-circuiting and formatting.
- 🔊 Improve logging for various events, such as Authenticator termination, thread termination, and secure mode activation.
- 🚩 Added new imports.

Docs:
- 🔥 Removed warning for Secure Mode issues with PyZMQ `versions > 24.0.1` on Windows.
- 📝 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 `"127.0.0.1"` address to allow common endpoint for connection.
- 👷 Added `"jpeg_compression":False` to disable frame compression, allowing frame to be same while assertion.
- ⏪️ Reverted skip condition for Windows platform when PyZMQ version `> 24.0.1`.
- ☂️ Improved code coverage.

📝 Docs: Fixed typos in admonitions.

…PI [#401]

💬 This commit includes significant refactoring, documentation updates, and enhancements across StreamGear, 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.

- 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.

- ⚡️ Only close peer connections that are not already in the "closed" state.
- 🎨 Logged the ICE connection state change only when it's not in the "failed" state, reducing unnecessary logging.

- 👷 Added a pytest fixture `event_loop_policy` to set the WindowsSelectorEventLoopPolicy on Windows platforms.
- ⚡️Replace the use of `async_asgi_testclient` with `httpx.AsyncClient` and `httpx.ASGITransport` for testing the ASGI application.
- 🥅 Update the test cases to use the `httpx.AsyncClient` correctly:
   - Use the `content` parameter instead of `data` when sending POST requests with JSON payloads.
   - Use the `post` method instead of `get` when sending WebRTC offers, as `get` do not support `content` parameter.
- 🔥 Remove the `pytest.mark.skipif` conditions related to Python version 3.11 and above, as the compatibility issues have been addressed.
- 🗑️ Add the `pytest.mark.asyncio(scope="module")` marker to the test functions to ensure proper handling of asynchronous tests.

…ixes #396)

- ♻️ Ignore the stream copy parameter if Real-time Frames Mode or Custom Streams are enabled, and log appropriate warnings.
- ⚡️Updated the handling of the `-acodec` parameter:
     - Use the default `aac` codec for Custom Streams.
     - Use stream copy (`-acodec copy`) for the input video's audio stream if Custom Streams are not enabled.
- ♻️ Refactor the handling of the `-livestream` parameter to ensure it is only enabled for the Real-time Frames Mode.
- ♻️ Refactor the video and audio bitrate assignment to skip the assignment when stream copy is enabled.
- 🔊 Updated log message for `-clear_prev_assets` parameter.
- ✏️ Fix a typo in comments.

Docs:
- 📝 Add a new tip box explaining the benefits of using stream copy (`-vcodec copy`) in the Single Source Mode for faster transcoding of HLS/DASH streams.
- 💬 Highlight the limitations of stream copy, such as incompatibility with Real-time Frames Mode and Custom Streams, which require re-encoding of frames.
- 💬 Clarify that the audio stream copy (`-acodec copy`) is automatically applied when using the input video's audio stream.
- 🎨 Fixed various issues like typos, formatting errors, code highlighting issues, and grammar inconsistencies.

- ⚡️ Instead of raising an exception, log a warning message and discard the invalid colorspace value.
- 🎨 Consolidate the colorspace logging statement to a single line using a ternary operation.

CamGear API
- 🔥 Remove the check for GStreamer support, as it is not being used currently (marked as a TODO).
- 🔊 Improve the readability of the livestream warning log.

Maintenance
- 🎨 Applied short-circuiting to simplify code across various APIs.
- 🎨 Remove unnecessary parentheses and unnecessary type checks.
- 🔧 Removed unused imports

- 🎨 Instead of raising a generic `ValueError` exception, the method now raises a `ValueError` with a more descriptive error message when encountering a `BrokenPipeError` or `IOError`.
- 🥅 The error handling has been updated to follow the recommendations of PEP 409 - Suppressing exception context. This ensures that the original exception context is preserved when re-raising the `ValueError`.
- ⚡️ If logging is enabled (`self.__logging` is True), the `ValueError` is raised with the suppressed context (`from None`), effectively discarding the original exception context.
- ⚡️ If logging is disabled, the `ValueError` is raised with the original exception context (`from e`), where `e` is the original `OSError` or `IOError` exception.

- 🥅 Added a warning message in the `NetGear` class to log potential issues when `flag=1` (NOBLOCK) is set, which may cause NetGear to not terminate gracefully.
- 🔊 Included an informational log message indicating that the `track` option will be ignored when `copy=True` is defined.
- 📝 Changed the default value of the `copy` option from `False` to `True` across various documentation files for NetGear.

👷 CI: Updated unit tests to reflect the new default value for the `copy` option.

✏️ Docs: Fixed few typos.

…treamGear' object has no attribute '_StreamGear__format' bug.

…x.x` versions.

- 📌 Pinned `numpy<2.0.0` in all CI envs.
- ⏪️ Reverted testing simplejpeg import

- ⚡️ 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.

.
- ⚡️ Included various test cases to validate different scenarios and error handling in `import_dependency_safe`.
- ☔ Ensured coverage for `raise`, `log`, `silent`, and unknown error types.

#### 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.

#### StreamGear:
- Enhanced stream copy support in Single Source mode (Fixes #396)
  - 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.
- Moved handle streaming format to beginning to fix 'StreamGear' object has no attribute '_StreamGear__format' bug.

#### CamGear:
- Removed GStreamer support check.
- Improved readability of livestream warning logs.

#### WriterGear:
- 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.

#### NetGear: Updated parameters and documentation (Fixes #390)
- Added warning log for potential issues with `flag=1` (NOBLOCK).
- Noted that `track` option is ignored when `copy=True`.

### Core: 
- Improved exception handling for module imports. 
  - Updated `import_dependency_safe` in `helper.py`:
    - dded 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.

#### Maintenance:
- Refactored 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.
- Simplified code using short-circuiting.
- Corrected a typo in comments.
- Removed unnecessary parentheses and type checks.
- Removed unused imports.

#### Docs:
- Enhanced StreamGear documentation:
  - 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.
- Changed default value of `copy` to `True` in NetGear API documentation.
- Fixed typos, formatting, code highlighting, and grammar issues.

#### CI:
- Enhanced WebGear RTC tests
- Updated NetGear unit tests to reflect the new default for `copy`.
- Fixed simplejpeg and opencv not compatible with `numpy==2.x.x` versions.
  - Pinned `numpy<2.0.0` in all CI envs.
- Added test cases for import_dependency_safe function to validate different scenarios and error handling in `import_dependency_safe`.
  - Ensured coverage for `raise`, `log`, `silent`, and unknown error types.
- Fixed invalid escape sequence in testcase string.
- Fixed python environment bugs in `appveyor.yml`.
- Removed pinned `cryptography==38.0.4` dependency.

- 🔊 Updated `no_warnings` parameter in `CamGear` to be `False` when logging is enabled and `True` otherwise.

#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.

📝 Docs: Fixed minor code highlighting

#### CamGear: 
- Fixed logging condition for yt-dlp (Fixes #394) 
  - Updated `no_warnings` parameter in `CamGear` to be `False` when logging is enabled and `True` otherwise.

#### WebGear: 
- Enhanced error messages for WebGear auto-generation workflow (Fixes #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.

#### CI: 
- Rearranged the dependencies 

#### Docs: 
- Minor updates to reference page titles.
- Fixed minor code highlighting

… version.

- 📌 Pinned `simplejpeg>=1.7.3` to support python-3.8 legacies.

 #410)

- ⚡️ Enhanced `is_valid_url` in `helper.py` to recognize and support both `rtsp` and `rtsps` protocols. (Suggested by @jonra1993)
- 💬 SRTP/RTSPS extends RTSP/RTP to encrypt video and audio data using the same ciphers as HTTPS, typically AES with a 128-bit key length.