vidgear v0.1.9 Release Notes

Release Date: 2020-09-03 // about 1 year ago
  • ๐Ÿ†• New Features

    • StreamGear API:
      • New API that automates transcoding workflow for generating Ultra-Low Latency, High-Quality, Dynamic & Adaptive Streaming Formats.
      • Implemented multi-platform , standalone, highly extensible and flexible wrapper around FFmpeg for generating chunked-encoded media segments of the media, and easily accessing almost all of its parameters.
      • API automatically transcodes videos/audio files & real-time frames into a sequence of multiple smaller chunks/segments and also creates a Manifest file.
      • Added initial support for MPEG-DASH (Dynamic Adaptive Streaming over HTTP, ISO/IEC 23009-1).
      • Constructed default behavior in StreamGear, for auto-creating a Primary Stream of same resolution and framerate as source.
      • Added TQDM progress bar in non-debugged output for visual representation of internal processes.
      • Implemented several internal methods for preprocessing FFmpeg and internal parameters for producing streams.
      • Several standalone internal checks to ensure robust performance.
      • New terminate() function to terminate StremGear Safely.
      • New StreamGear Dual Modes of Operation:
      • Implemented Single-Source and Real-time Frames like independent Transcoding Modes.
      • Linked -video_source attribute for activating these modes
      • Single-Source Mode , transcodes entire video/audio file (as opposed to frames by frame) into a sequence of multiple smaller segments for streaming
      • Real-time Frames Mode , directly transcodes video-frames (as opposed to a entire file), into a sequence of multiple smaller segments for streaming
      • Added separate functions, stream() for Real-time Frame Mode and transcode_source() for Single-Source Mode for easy transcoding.
      • Included auto-colorspace detection and RGB Mode like features (extracted from WriteGear), into StreamGear.
      • New StreamGear Parameters:
      • Developed several new parameters such as:
        • output: handles assets directory
        • formats: handles adaptive HTTP streaming format.
        • custom_ffmpeg: handles custom FFmpeg location.
        • stream_params: handles internal and FFmpeg parameter seamlessly.
        • logging: turns logging on or off.
      • New stream_params parameter allows us to exploit almost all FFmpeg parameters and flexibly change its internal settings, and seamlessly generating high-quality streams with its attributes:
        • -streams (list of dictionaries) for building additional streams with -resolution, -video_bitrate & -framerate like sub-attributes.
        • -audio for specifying external audio.
        • -video_source for specifying Single-Source Mode source.
        • -input_framerate for handling input framerate in Real-time Frames Mode.
        • -bpp attribute for handling bits-per-pixels used to auto-calculate video-bitrate.
        • -gop to manually specify GOP length.
        • -ffmpeg_download_path to handle custom FFmpeg download path on windows.
        • -clear_prev_assets to remove any previous copies of SteamGear Assets.
      • New StreamGear docs, MPEG-DASH demo, and recommended DASH players list:
      • Added new StreamGear docs, usage examples, parameters, references, new FAQs.
      • Added Several StreamGear usage examples w.r.t Mode of Operation.
      • Implemented Clappr based on Shaka-Player, as Demo Player.
      • Added Adaptive-dimensional behavior for Demo-player, purely in css.
      • Hosted StreamGear generated DASH chunks on GitHub and served with raw.githack.com.
      • Introduced variable quality level-selector plugin for Clapper Player.
      • Provide various required javascripts and implemented additional functionality for player in extra.js.
      • Recommended tested Online, Command-line and GUI Adaptive Stream players.
      • Implemented separate FFmpeg installation doc for StreamGear API.
      • Reduced rebufferingGoal for faster response.
      • New StreamGear CI tests:
      • Added IO and API initialization CI tests for its Modes.
      • Added various mode Streaming check CI tests.
    • NetGear_Async API:
      • Added new send_terminate_signal internal method.
      • Added WindowsSelectorEventLoopPolicy() for windows 3.8+ envs.
      • Moved Client auto-termination to separate method.
      • Implemented graceful termination with signal API on UNIX machines.
      • Added new timeout attribute for controlling Timeout in Connections.
      • Added missing termination optimizer (linger=0) flag.
      • Several ZMQ Optimizer Flags added to boost performance.
    • WriteGear API:
      • Added support for adding duplicate FFmpeg parameters to output_params:
      • Added new -clones attribute in output_params parameter for handing this behavior..
      • Support to pass FFmpeg parameters as list, while maintaining the exact order it was specified.
      • Built support for zmq.REQ/zmq.REP and zmq.PUB/zmq.SUB patterns in this mode.
      • Added new CI tests debugging this behavior.
      • Updated docs accordingly.
      • Added support for Networks URLs in Compression Mode:
      • output_filename parameter supports Networks URLs in compression modes only
      • Added automated handling of non path/file Networks URLs as input.
      • Implemented new is_valid_url helper method to easily validate assigned URLs value.
      • Validates whether the given URL value has scheme/protocol supported by assigned/installed ffmpeg or not.
      • WriteGear will throw ValueError if -output_filename is not supported.
      • Added related CI tests and docs.
      • Added disable_force_termination attribute in WriteGear to disable force-termination.
    • NetGear API:
      • Added option to completely disable Native Frame-Compression:
      • Checks if any Incorrect/Invalid value is assigned on compression_format attribute.
      • Completely disables Native Frame-Compression.
      • Updated docs accordingly.
    • CamGear API:
      • Added new and robust regex for identifying YouTube URLs.
      • Moved youtube_url_validator to Helper.
    • ๐Ÿ†• New helper.py methods:
      • Added validate_video function to validate video_source.
      • Added extract_time Extract time from give string value.
      • Added get_video_bitrate to caliculate video birate from resolution, framerate, bits-per-pixels values.
      • Added delete_safe to safely delete files of given extension.
      • Added validate_audio to validate audio source.
      • Added new Helper CI tests.
      • Added new check_valid_mpd function to test MPD files validity.
      • Added mpegdash library to CI requirements.
    • ๐Ÿš€ Deployed New Docs Upgrades:
      • Added new assets like images, gifs, custom scripts, javascripts fonts etc. for achieving better visual graphics in docs.
      • Added clappr.min.js, dash-shaka-playback.js, clappr-level-selector.min.js third-party javascripts locally.
      • Extended Overview docs Hyperlinks to include all major sub-pages (such as Usage Examples, Reference, FAQs etc.).
      • Replaced GIF with interactive MPEG-DASH Video Example in Stabilizer Docs.
      • Added new pymdownx.keys to replace [Ctrl+C]/[โŒ˜+C] formats.
      • Added new custom.css stylescripts variables for fluid animations in docs.
      • Overridden announce bar and added donation button.
      • Lossless WEBP compressed all PNG assets for faster loading.
      • Enabled lazy-loading for GIFS and Images for performance.
      • Reimplemented Admonitions contexts and added new ones.
      • Added StreamGear and its different modes Docs Assets.
      • Added patch for images & unicodes for PiP flavored markdown in setup.py.
    • โž• Added Request Info and Welcome GitHub Apps to automate PR and issue workflow
      • Added new config.yml for customizations.
      • Added various suitable configurations.
    • โž• Added new -clones attribute to handle FFmpeg parameter clones in StreamGear and WriteGear API.
    • โž• Added new Video-only and Audio-Only sources in bash script.
    • โž• Added new paths in bash script for storing StreamGear & WriteGear assets temporarily.

    โšก๏ธ Updates/Improvements

    • ๐Ÿ Added patch for NotImplementedError in NetGear_Async API on Windows 3.8+ envs.
    • Check for valid output file extension according to format selected in StreamGear.
    • Completed migration to travis.com.
    • ๐Ÿฑ Created new temp_write temp directory for WriteGear Assets in bash script.
    • ๐Ÿฑ Deleted old Redundant assets and added new ones.
    • Employed isort library to sort and group imports in Vidgear APIs.
    • ๐Ÿ‘ป Enabled exception for list, tuple, int, float in WriteGear API's output_params dict.
    • ๐Ÿ‘ Enabled missing support for frame-compression in its primary Receive Mode.
    • Enforced pixel formats for streams.
    • Improved check for valid system path detection in WriteGear API.
    • โœ… Overrided pytest-asyncio fixture in NetGear_Async API.
    • Quoted Gear Headline for understanding each gear easily.
    • ๐Ÿ‘ Re-Positioned Gear's banner images in overview for better readability.
    • Reduced redundant try-except blocks in NetGear Async.
    • ๐Ÿ“„ Reformatted and Simplified Docs context.
    • โœ… Reimplemented return_testvideo_path CI function with variable streams.
    • Reimplemented skip_loop in NetGear_Async to fix asyncio.CancelledError.
    • Reimplemented buggy audio handler in StreamGear.
    • Reimplemented images with <figure> and <figurecaption> like tags.
    • ๐Ÿ‘ท Removed Python < 3.8 condition from all CI tests.
    • ๐Ÿšš Removed or Grouped redundant code for increasing codecov.
    • ๐Ÿšš Removed redundant code and simplified algorithmic complexities in Gears.
    • Replaced ;nbsp with ;thinsp and ;emsp.
    • Replaced IOError with more reliable RuntimeError in StreamGear Pipelines.
    • Replaced del with pop in dicts.
    • ๐Ÿ‘ท Replaced all Netgear CI tests with more reliable try-except-final blocks.
    • Replaced simple lists with pymdownx.tasklist.
    • Replaced subprocess call() with run() for better error handling in execute_ffmpeg_cmd function.
    • ๐Ÿ“„ Resized over-sized docs images.
    • Simplified delete_safe Helper function.
    • 0๏ธโƒฃ Simplified default audio-bitrate logic in StreamGear
    • โšก๏ธ Updated CI tests and cleared redundant code from NetGear_Async API.
    • โšก๏ธ Updated CI with new tests and Bumped Codecov.
    • โšก๏ธ Updated Issue and PR templates.
    • โšก๏ธ Updated Licenses for new files and shrink images dimensions.
    • โšก๏ธ Updated Missing Helpful tips and increased logging.
    • โšก๏ธ Updated PR guidelines for more clarity.
    • โšก๏ธ Updated WebGear examples addresses from 0.0.0.0 to localhost.
    • โšก๏ธ Updated WriteGear and StreamGear CI tests for not supporting temp directory.
    • โšก๏ธ Updated README.md and changelog.md with new changes.
    • Updated check_output and added force_retrieve_stderr support to **kwargs to extract stderr output even on FFmpeg error.
    • โšก๏ธ Updated dicts2args to support internal repeated coreX FFmpeg parameters for StreamGear.
    • โšก๏ธ Updated mkdocs.yml, changelog.md and README.md with latest changes.
    • โšก๏ธ Updated validate_audio Helper function will now retrieve audio-bitrate for validation.
    • โšก๏ธ Updated buggy mpegdash dependency with custom dev fork for Windows machines.
    • โšก๏ธ Updated core parameters for audio handling.
    • โšก๏ธ Updated logging for debugging selected eventloops in NetGear_Async API.
    • โšก๏ธ Updated termination linger to zero at Server's end.

    ๐Ÿ’ฅ Breaking Updates/Changes

    • ๐Ÿฑ โš ๏ธ Changed Webgear API default address to localhost for cross-compatibility between different platforms.
    • In Netgear_Async API, source value can now be NoneType for a custom frame-generator at Server-end only.
    • ๐Ÿง Temp (such as /tmp in linux) is now not a valid directory for WriteGear & StreamGear API outputs.
    • ๐Ÿ’… Moved vidgear docs assets (i.e images, gifs, javascripts and stylescripts) to override directory.

    ๐Ÿ› Bug-fixes

    • โ†ช Added workaround for system path not handle correctly.
    • ๐Ÿ›  Fixed Bug: URL Audio format not being handled properly.
    • ๐Ÿš‘ Fixed Critical Bug in NetGear_Async throwing ValueError with None-type Source.
    • ๐Ÿš‘ Fixed Critical StreamGear Bug: FFmpeg pipeline terminating prematurely in Single-Source Mode.
    • ๐Ÿš‘ Fixed Critical external audio handler bug: moved audio-input to input_parameters.
    • ๐Ÿ‘ท Fixed Frozen-threads bug in CI tests.
    • ๐Ÿ›  Fixed Mkdocs only accepting Relative paths.
    • ๐Ÿ›  Fixed OSError in WriteGear's compression mode.
    • ๐Ÿ Fixed StreamGear CI bugs for Windows and CI envs.
    • โœ๏ธ Fixed Typos and Indentation bugs in NetGear API.
    • ๐Ÿ›  Fixed ZMQ throwing error on termination if all max-tries exhausted.
    • ๐Ÿ›  Fixed NameError bug in NetGear API.
    • ๐Ÿ›  Fixed NameError bugs in StreamGear CI.
    • ๐Ÿ‘ท Fixed NameError in CI functions and tests.
    • ๐Ÿ‘ท Fixed TimeoutError bug in NetGear_Async CI tests.
    • Fixed get_valid_ffmpeg_path throwing TypeError with non-string values.
    • ๐Ÿ›  Fixed broken links in docs.
    • ๐Ÿš‘ Fixed critical duplicate logging bug.
    • 0๏ธโƒฃ Fixed default gop value not handle correctly.
    • ๐Ÿ›  Fixed handling of incorrect paths detection.
    • ๐Ÿ›  Fixed incorrect definitions in NetGear_Async.
    • ๐Ÿ›  Fixed left-over attribute bug in WriteGear.
    • ๐Ÿ‘ท Fixed logic and indentation bugs in CI tests.
    • ๐Ÿ›  Fixed logic for handling output parameters in WriteGear API.
    • ๐Ÿ›  Fixed missing definitions and logic bug in StreamGear.
    • ๐Ÿ‘ท Fixed missing import and incorrect CI definitions.
    • ๐Ÿ›  Fixed missing source dimensions from extract_resolutions output in StreamGear API.
    • ๐Ÿ›  Fixed missing support for compression parameters in Multi-Clients Mode.
    • ๐Ÿ›  Fixed round off error in FPS.
    • โšก๏ธ Fixed several CI bugs and updated extract_resolutions method.
    • ๐Ÿ‘ท Fixed several bugs from CI Bidirectional Mode tests.
    • โœ๏ธ Fixed several typos in docs usage examples.
    • ๐Ÿ‘ท Fixed various AttributeError with wrong attribute names and definition in CI Helper functions.
    • ๐Ÿ›  Fixed wrong and missing definitions in docs.
    • ๐Ÿ›  Fixed wrong logic for extracting OpenCV frames.
    • ๐Ÿ›  Fixed wrong type bug in StreamGear API.
    • ๐Ÿ›  Fixed wrong type error bug in WriteGear API.
    • ๐Ÿ›  Fixed wrong variable assignments bug in WriteGear API.
    • โœ… Fixes to CLI tests and missing docs imports.
    • โœ๏ธ Many minor typos and wrong definitions.

    Pull Requests


Previous changes from v0.1.8

  • ๐Ÿ†• New Features

    ๐Ÿ‘ Multiple Clients support in NetGear API:

    • Implemented support for handling any number of Clients simultaneously with a single Server in this mode.
    • Added new multiclient_mode attribute for enabling this mode easily.
    • Built support for zmq.REQ/zmq.REP and zmq.PUB/zmq.SUB patterns in this mode.
    • Implemented ability to receive data from all Client(s) along with frames with zmq.REQ/zmq.REP pattern only.

    - Updated related CI tests

    ๐Ÿ‘Œ Support for robust Lazy Pirate pattern(auto-reconnection) in NetGear API for both server and client ends:

    • Implemented a algorithm where NetGear rather than doing a blocking receive, will now:
      • Poll the socket and receive from it only when it's sure a reply has arrived.
      • Attempt to reconnect, if no reply has arrived within a timeout period.
      • Abandon the connection if there is still no reply after several requests.
    • Implemented its default support for REQ/REP and PAIR messaging patterns internally.
    • Added new max_retries and request_timeout(in seconds) for handling polling.
    • Added DONTWAIT flag for interruption-free data receiving.

    - Both Server and Client can now reconnect even after a premature termination.

    ๐ŸŽ Performance Updates for NetGear API:

    • Added default Frame Compression support for Bidirectional frame transmission in Bidirectional mode.
    • Added support for Reducer() function in Helper.py to aid reducing frame-size on-the-go for more performance.
    • Added small delay in recv() function at client's end to reduce system load.

    - Reworked and Optimized NetGear termination, and also removed/changed redundant definitions and flags.

    ๐Ÿ“„ Docs Migration to Mkdocs:

    • Implemented a beautiful, static documentation site based on MkDocs which will then be hosted on GitHub Pages.
    • Crafted base mkdocs with third-party elegant & simplistic mkdocs-material theme.
    • Implemented new mkdocs.yml for Mkdocs with relevant data.
    • Added new docs folder to handle markdown pages and its assets.
    • Added new Markdown pages(.md) to docs folder, which are carefully crafted documents - based on previous Wiki's docs, and some completely new additions.
    • Added navigation under tabs for easily accessing each document.
    • New Assets:
    • Added Required Plugins and Extensions:
      • Added support for all pymarkdown-extensions.
      • Added support for some important admonition, attr_list, codehilite, def_list, footnotes, meta, and toc like Mkdocs extensions.
      • Enabled search, minify and git-revision-date-localized plugins support.
      • Added various VidGear's social links to yaml.
      • Added support for en (English) language.
    • Auto-Build API Reference with mkdocstrings:
      • Added support for mkdocstrings plugin for auto-building each VidGear's API references.
      • Added python handler for parsing python source-code to mkdocstrings.
    • Auto-Deploy Docs with Github Actions:
      • Implemented Automated Docs Deployment on gh-pages through GitHub Actions workflow.
      • Added new workflow yaml with minimal configuration for automated docs deployment.
      • Added all required python dependencies and environment for this workflow.
      • Added master branch on Ubuntu machine to build matrix.

    โšก๏ธ Updates/Improvements

    • ๐Ÿ‘ Added in-built support for bidirectional frames(NDarray) transfer in Bidirectional mode.
    • ๐Ÿ‘ Added support for User-Defined compression params in Bidirectional frames transfer.
    • โ†ช Added workaround for address already in use bug at client's end.
    • Unified Bidirectional and Multi-Clients mode for client's return data transmission.
    • Replaced ValueError with more suitable RuntimeError.
    • โšก๏ธ Updated logging for better readability.
    • ๐Ÿ‘ท Added CI test for Multi-Clients mode.
    • Reformatted and grouped imports in VidGear.
    • ๐Ÿ‘ท Added Reducer Helper function CI test.
    • โœ… Added Reliability tests for both Server and Client end.
    • Disabled reliable reconnection for Multi-Clients mode.
    • Replaced os.devnull with suprocess's inbuilt function.
    • โšก๏ธ Updated README.md, Issue and PR templates with new information and updates.
    • โšก๏ธ Moved changelog.md to /docs and updated contribution guidelines.
    • ๐Ÿ“„ Improved source-code docs for compatibility with mkdocstrings.
    • ๐Ÿ— Added additional dependency mkdocs-exclude, for excluding files from Mkdocs builds.
    • โšก๏ธ Updated license and compressed images/diagrams.
    • ๐Ÿ‘ท Added new CI tests and Bumped Codecov.
    • ๐Ÿ‘ท Changed YouTube video URL for CI tests to Creative Commons(CC) video.
    • ๐Ÿšš Removed redundant code.

    ๐Ÿ’ฅ Breaking Updates/Changes

    ๐Ÿšš โš ๏ธVidGear Docs moved to GitHub Pages, Now Available at https://abhitronix.github.io/vidgear.

    • ๐Ÿšš Removed filter attribute from options parameter in NetGear API.
    • ๐Ÿšš Removed force_terminate parameter support from NetGear API.
    • Disabled additional data of datatype numpy.ndarray for Server end in Bidirectional Mode.

    ๐Ÿ› Bug-fixes

    • ๐Ÿ›  Fixed 'NoneType' object is not subscriptable bug.
    • ๐Ÿ›  Fixed bugs related to delayed termination in NetGear API.
    • 0๏ธโƒฃ Reduced default request_timeout value to 4 and also lowered cut-off limit for the same.
    • ๐Ÿšš Removed redundant ZMQ context termination and similar variables.
    • Added missing VidGear installation in workflow.
    • ๐Ÿ— Excluded conflicting assets README.md from Mkdocs builds.
    • ๐Ÿ›  Fixed pattern value check bypassed if wrong value is assigned.
    • ๐Ÿ”€ Fixed incorrect handling of additional data transferred in synchronous mode at both Server and Client end.
    • ๐Ÿ‘ท Replaced Netgear CI test with more reliable try-except-final blocks.
    • โšก๏ธ Updated termination linger to zero at Server's end.
    • ๐Ÿ›  Fixed NameError bug in NetGear API.
    • ๐Ÿ›  Fixed missing support for compression parameters in Multi-Clients Mode.
    • ๐Ÿ›  Fixed ZMQ throwing error on termination if all max-tries exhausted.
    • ๐Ÿ‘ Enabled missing support for frame compression in its primary receive mode.
    • ๐Ÿ‘ท Fixed several bugs from CI Bidirectional Mode tests.
    • ๐Ÿšš Removed or Grouped redundant code for increasing codecov.
    • ๐Ÿ›  Fixed Mkdocs only accepting Relative paths.
    • ๐Ÿ›  Fixed broken links in docs.
    • ๐Ÿ›  Fixed round off error in FPS.
    • โœ๏ธ Many small typos and bugs fixes.

    Pull Requests