Deffcode

???+ new "New Features"
- [x] **FFdecoder:**
* Introduced a new optional `-disable_ffmpeg_window` boolean parameter.
* 💬 Prevents the FFmpeg command line window from appearing by applying the `DETACHED_PROCESS` flag to the subprocess FFmpeg pipeline when building `.exe` files on Windows in silent (`verbose=False`) mode.
- [x] **Sourcer:**
* Added new parameters to metadata to accurately display video orientation.
* Added `source_video_orientation` parameter (default `0.0`).
* Added `output_orientation` parameter (default `0.0`).
- [x] **FFHelper:**
* Added support for SRTP/RTSPS in `is_valid_url` function.
* Enhanced `is_valid_url` method to support both RTP/RTSP and SRTP/RTSPS protocols.
* 💬 SRTP/RTSPS extends RTSP/RTP to encrypt video/audio data using ciphers like AES with a 128-bit key.
- [x] **Core:**
* Added official support for Python `3.11.x` legacies.
* Added Python-3.11 support across CI/CD configurations.
* Added Python-3.11 to setup.py metadata.
- [x] **Docs:**
* Added context and detailed instructions for Input and Output Seeking methods.
* Introduced `Input Seeking` and `Output Seeking` sections with pros, cons, and usage examples.
* Added warning about using output seeking with filters for accuracy.
* Added new `tables` markdown extension for improved table formatting.
* Added documentation for the new optional `-disable_ffmpeg_window` boolean parameter.
* Added `unrecognized_links: ignore` to `mkdocs.yml` to minimize logging during validation.
* Added new features to `mkdocs.yml` related to `navigation`, `content`, and `toc`.

??? success "Updates/Improvements"
- [x] FFdecoder:
* Changed process termination from `kill()` to `terminate()` if the process is still running, to ensure graceful shutdown.
* 💬 The `terminate()` method sends the `SIGTERM` signal to a process, which typically allows for a graceful shutdown. On Unix, this uses the `SIGTERM` signal, while on Windows, it uses `TerminateProcess()`.
- [x] FFhelper:
* Improved regex pattern in `get_supported_demuxers` method.
* Simplified regex search for demuxers and handled multi-line output correctly.
* Improved output extraction logic to handle commas within demuxer names.
- [x] Sourcer:
* Updated `extract_resolution_framerate` method to also return video orientation.
* Added new regex pattern and filter for accurate video orientation extraction.
- [x] Setup:
* Updated patch for `long_description`.
* Bumped version to `0.2.6`.
- [x] Maintenance:
* Refactored logging messages and code comments for better readability and maintainability.
* Simplified conditional check using short-circuiting.
- [x] Docs:
* Updated `mkdocs.yml` to improve overall documents structure and readability
* Set the default version of the documentation to 'latest'.
* Set `edit_uri` for GitHub edit links to facilitate easier contributions.
* Replaced deprecated `materialx` with supported `extensions` emoji generator.
* Enhanced the active tab fonts with `font-weight: bold` in `custom.css`.
* Updated LinkedIn URL.
* Removed Twitter section from help and site metadata.
* Migrated to Google Analytics 4.
* Enabled `line_spans: __span` and `pygments_lang_class: true` parameters in `pymdownx.highlight` markdown extension.
* Enabled `normalize_issue_symbols: true` in `pymdownx.magiclink` markdown extension.
* Updated the Zenodo badges and the BibTeX entry to reflect recent changes.
* Included GitHub sponsors in `FUNDING.yml`.
* Removed deprecated Gitter community chat sidecard.
- [x] CI:
* Updated paths to ignore additional files and types in CI/CD Pipelines and Codecov:
* Included `*.html`, `*.js`, `*.css`, `mkdocs.yml`, `README.md` to ignore list.
* Changed runner from `ubuntu-latest` to `ubuntu-20.04` in GitHub Actions.
* Updated dependencies in `docs_deployer.yml` for better readability.
* Modified Mike deploy commands to use `--alias-type=copy` instead of deprecated `--no-redirect`.
* Removed unsupported darwin platform from `test_FFdecoder_params` test.

??? danger "Breaking Updates/Changes"
* **Core:**
- [x] :skull_crossbones: Ended support for Python `3.7.x` legacies.
* Increased `python_requires` to `3.8` and above in setup.py.
* Removed Python `3.7` from setup.py metadata.
* Removed Python `3.7` support from CI/CD pipelines.

??? bug "Bug-fixes"
- [x] FFdecoder API:
* Fixed regex expression bugs in `get_supported_demuxers` method.
- [x] CI:
* Fixed Assertion error with WriteGear API.

??? question "Pull Requests"
* PR 53
* PR 52
* PR 51
* PR 49

 

 

??? new "New Features"
- [x] **FFdecoder:**
* Added OpenCV compatibility patch for YUV pixel-formats.
* Implemented new patch for handling YUV pixel-formats(such as `YUV420p`, `yuv444p`, `NV12`, `NV21` etc.) for exclusive compatibility with OpenCV APIs.
* **Note:** Only YUV pixel-formats starting with `YUV` and `NV` are currently supported.
* Added new `-enforce_cv_patch` boolean attribute for enabling OpenCV compatibility patch.
- [x] **Sourcer:**
* Added Looping Video support.
* Now raw-frame numbers revert to null(`None`) whenever any looping is defined through filter(such as `-filter_complex "loop=loop=3:size=75:start=25"`) or prefix(`"-ffprefixes":["-stream_loop", "3"]`).
- [x] **Docs:**
* Added YUV frames example code for `Capturing and Previewing BGR frames from a video file` recipe.
* Added YUV frames example code for `Transcoding video using OpenCV VideoWriter API recipe.
* Added YUV frames example code for `Transcoding lossless video using WriteGear API recipe.
* Added new CUVID-accelerated Hardware-based Video Decoding and Previewing recipe.
* Added new CUDA-accelerated Hardware-based Video Decoding and Previewing recipe.
* Added new CUDA-accelerated Video Transcoding with OpenCV`s VideoWriter API recipe.
* Added new CUDA-NVENC-accelerated Video Transcoding with WriteGear API recipe both for consuming BGR and NV12 frames.
* Added new CUDA-NVENC-accelerated End-to-end Lossless Video Transcoding with WriteGear API recipe which is still WIP(💬confirmed with a GIF from tenor).
* Added new Capturing and Previewing frames from a Looping Video recipe using `-stream_loop` option and `loop` filter.
* Added docs for `-enforce_cv_patch` boolean attribute in `ffparam` dictionary parameter.
* Added new python dependency block for recipes.
* Reflected new OpenCV compatibility patch for YUV pixel-formats in code.
* Added new `content.code.copy` and `content.code.link` features.

??? success "Updates/Improvements"
- [x] FFhelper:
* Replaced depreciating `Retry` API from `requests.packages` with `requests.adapters`.
- [x] Maintenance:
* Replaced `raw.github.com` links with GitLab and GH links.
* Removed unused code.
* Updated log message.
- [x] CI:
* Updated `test_FFdecoder_params` unittest to include `with` statement access method.
* Updated `test_frame_format` test to include `-enforce_cv_patch` boolean attribute.
* Updated `test_source` to test looping video support.
- [x] Setup:
* Removed unused imports and patches.
* Bumped version to `0.2.5`.
- [x] Docs:
* Updated Limitation: Bottleneck in Hardware-Accelerated Video Transcoding performance with Real-time Frame processing passage.
* Updated and corrected docs hyperlinks in index.md and ReadMe.md
* Update Zenodo Badge and BibTex entry.
* Updated `Readme.md` banner image URLs.
* Updated md-typeset text font size to `.75rem`.
* Updated text and admonitions.
* Updated recipe assumptions.
* Updated `Readme.md` GIF URLs.
* Updated abstract text in recipes.
* Updated `changelog.md`.
* Updated recipe code.
* Removed old recipes.

??? bug "Bug-fixes"
- [x] FFdecoder API:
* Fixed Zero division bug while calculating `raw_bit_per_component`.
- [x] FFhelper:
* Fixed response.headers returning `content-length` as Nonetype since it may not necessarily have the Content-Length header set.
* **Reason:** The response from gitlab.com contains a Transfer-Encoding field as `'Transfer-Encoding': 'chunked'`, which means data is sent in a series of chunks, so the Content-Length header is emitted. More info: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Transfer-Encoding#Directives
- [x] Docs:
* Fixed https://github.com/badges/shields/issues/8671 badge issue in README.md
* Removed depreciated text.
* Fixed several typos in docs.
- [x] CI:
* Added fix for codecov upload bug (https://github.com/codecov/codecov-action/issues/598).
* Updated `codecov-action` workflow to `v3.
* Added new `CODECOV_TOKEN` GitHub secret.

??? question "Pull Requests"
* PR 37

 

 

??? new "New Features"
- [x] **FFdecoder API:**
* Implemented new comprehensive support for both discarding key default FFmpeg parameters from Decoding pipeline simply by assigning them `null` string values, and concurrently using values extracted from Output Stream metadata properties _(available only when FFmpeg filters are defined)_ for formulating pipelines.
* Added `null` string value support to `-framerate` and `-custom_resolution` attributes, as well as `frame_format` parameter for easily discarding them.
* Re-Implemented calculation of rawframe pixel-format.
* Reconfigured default rawframe pixel-format, Now rawframe pixel-format will always default to `source_video_pixfmt` with `frame_format="null"`.
* Now with `frame_format` parameter value either "null" or invalid or undefined, rawframe pixel-format value is taken from `output_frames_pixfmt` metadata property extracted from Output Stream (available only when filters are defined). If valid `output_video_resolution` metadata property is found then it defaults to default pixel-format(calculated variably).
* With `frame_format="null"`, `-pix_fmt` FFmpeg parameter will not be added to Decoding pipeline.
* Re-Implemented calculation of rawframe resolution value.
* Now with `-custom_resolution` dictionary attribute value either "null" or invalid or undefined, rawframe resolution value is first taken from `output_video_resolution` metadata property extracted from Output Stream (available only when filters are defined), next from `source_video_resolution` metadata property(extracted from Input Source Stream). If neither `output_video_resolution` nor `source_video_resolution` valid metadata properties are found then `RuntimeError` is raised.
* With `-custom_resolution` dictionary attribute value "null", `-s/-size` FFmpeg parameter will not be added to Decoding pipeline.
* Re-Implemented calculation of output framerate value.
* Now with `-framerate` dictionary attribute either null or invalid or undefined, output framerate value is first taken from `output_video_framerate` metadata property extracted from Output Stream (available only when filters are defined), next from `source_video_framerate` metadata property(extracted from Input Source Stream). If neither `output_video_resolution` nor `source_video_framerate` valid metadata properties are found then `RuntimeError` is raised.
* With `-framerate` dictionary attribute value "null", `-r/-framerate` FFmpeg parameter will not be added to Decoding pipeline.
* Implemented passing of simple `-vf` filters, complex `-filter_complex` filters, and pre-headers(via `-ffprefixes`) directly to Sourcer API's `sourcer_params` parameter for probing Output Stream metadata and filter values.
- [x] **Sourcer API:**
* Implemented new comprehensive approach to handle `source_demuxer` parameter w.r.t different `source` parameter values.
* The `source_demuxer` parameter now accepts "auto" as its value for enabling Index based Camera Device Capture feature in Sourcer API.
* Sourcer API auto-enforces `source_demuxer="auto"` by default, whenever a valid device index (uses `validate_device_index` method for validation) is provided as its `source` parameter value.
* ⚠️ Sourcer API will throw `Assertion` error if `source_demuxer="auto"` is provided explicitly without a valid device index at its `source` parameter.
* Source API now accepts all +ve and -ve device indexes (e.g. `-1,0,1,2` etc.) to its `source` parameter, both as in integer and string of integer types as source in Index based Camera Device Capture feature.
* Sourcer API imports and utilizes `extract_device_n_demuxer()` method for discovering and extracting all Video-Capture device(s) name/path/index present on system.
* ⚠️ Sourcer API will throw `RuntimeError` on failure to identify any device.
* Sourcer API auto verifies that the specified source device index is in range of the devices discovered.
* ⚠️ Sourcer API will raise `ValueError` if value goes out of valid range.
* Sourcer API also automatically handle -ve indexes if specified within the valid range.
* Implemented patch to auto-add `video=` suffix to selected device name before using it as video source on Windows OSes.
* Added patch for handling dictionary of devices paths(with devices names as values) and log messages on Linux Oses.
* Added `copy` import for shallow copying various class parameters.
* Implemented new Support for additional FFmpeg parameters and Output metadata.
* Added three new metadata properties: `output_video_resolution`, `output_video_framerate`, `output_frames_pixfmt` for handling extracted Output Stream values, whenever additional FFmpeg parameters(such as FFmpeg filters) are defined.
* Added support for auto-handling additional FFmpeg parameters defined by `sourcer_params` dictionary parameters.
* Implement new separate pipeline for parsing Output Stream metadata by decoding video source using `null` muxer for few microseconds whenever additional FFmpeg parameters(such as `-vf` filters) are defined by the user.
* Included new `metadata_output` internal parameter for holding Output Stream metadata splitted from original Sourcer Metadata extracted from new pipeline.
* Included new `output_video_resolution`, `output_video_framerate`, `output_frames_pixfmt` internal parameters for metadata properties, whenever Output Stream Metadata available.
* Added new `extract_output` boolean parameter to `extract_video_pixfmt` and `extract_resolution_framerate` internal methods for extracting output `pixel-format`, `framerate` and `resolution` using Output Stream metadata instead of Sourcer Metadata, whenever available.
* Added `tuple` datatype to `sourcer_params` exception.
* Added `dict2Args` import.
* Added `enumerate_devices` property object to enumerate all probed Camera Devices connected to a system names along with their respective "device indexes" or "camera indexes" as python dictionary.
* Added new `force_retrieve_missing` parameter to `retrieve_metadata()` method for returning metadata missing in current Pipeline as `(metadata, metadata_missing)` tuple value instead of just `metadata`, when `force_retrieve_missing=True`.
* Added various output stream metadata properties that are only available when additional FFmpeg parameters(such as filters) are defined manually, by assigning them counterpart source stream metadata property values
- [x] **FFhelper:**
* Implemented new `extract_device_n_demuxer()` method for discovering and extracting all Video-Capture device(s) name/path/index present on system and supported by valid OS specific FFmpeg demuxer.
* Added support for three OS specific FFmpeg demuxers: namely `dshow` for Windows, `v4l2` for Linux, and `avfoundation` for Darwin/Mac OSes.
* Implemented separate code for parsing outputs of python `subprocess` module outputs provided with different commands for discovering all Video-Capture devices present on system.
* Processed `dshow` _(on Windows)_ and `avfoundation` _(on Darwin)_ demuxers in FFmpeg commands with `-list_devices true` parameters using `subprocess` module and applied various brute-force pattern matching on its output for discovering and extracting all devices names/indexes.
* Used `v4l2-ctl` submodule command on Linux machines for listing all Video-Capture devices using `subprocess` module and applied various brute-force pattern matching on its output for discovering and extracting all devices names and true system `/dev/video` paths.
* Added patch for a single device with multiple `/dev/video` paths _(each for metadata, video, controls)_, where it iterates on each path to find the exact path that contains valid video stream.
* Added elaborated checks for catching all possible system errors that can occur while running `v4l2-ctl` submodule command.
* The method will return discovered devices as list of dictionaries with device paths(`/dev/video`) as keys and respective device name as the values, instead of default list of device names.
* Added patch for handling Linux specific log messages.
* Added various logging messages to notify users about all discover devices names/paths w.r.t indexes.
* ⚠️ The `extract_device_n_demuxer` method will raise `RuntimeError` if it fails to identify any device.
* Added various checks to assert invalid input parameters and unsupported OSes.
* Added `machine_OS` parameter to specify OS running on the system, must be value of `platform.system()` module. If invalid the method will raise ValueError.
- [x] **Utilities:**
* Added new `new validate_device_index()` method to verify if given device index is valid or not?
* Only Integers or String of integers are valid indexes.
* Returns a boolean value, confirming whether valid(If `true`), or not(If `False`).
* Added checks to support all +ve and -ve integers, both as integer and string types.
- [x] **Docs:**
* Added `new validate_device_index()` method and its parameters description.
* Added `new extract_device_n_demuxer()` method and its parameters description.
* Added Decoding Camera Devices using Indexes support docs.
* Added `decode-camera-devices.md` doc for Decoding Camera Devices using Indexes.
* Added `Enumerating all Camera Devices with Indexes` example doc with code.
* Added `Capturing and Previewing frames from a Camera using Indexes` example doc with code.
* Added Camera Device Index support docs to FFdecoder and Sourcer API params.
- [x] **CI:**
* Added check exception for `mandelbrot` virtual source in Sourcer API's `test_probe_stream_n_retrieve_metadata` unittest.
* Added new `test_discard_n_filter_params` unittest for test recently added supported for both discarded parameters and filter values.

??? success "Updates/Improvements"
- [x] FFdecoder API:
* Extended range of supported output frame pixel-formats.
* Added new pixel-formats to supported group by extending raw bits-per-component range.
* Simplified raw frame dtype calculation based on selected pixel-format.
* `output_frames_pixfmt` metadata property(if available) will be overridden to `rgb24`.
* Replaced `continue` with `break` in `generateFrame()` method.
* Improved handling of `frame_format` parameter.
- [x] Sourcer API:
* Simplified JSON formatting and returning values logic.
* Updated logging messages text and position.
* Removed redundant variable definitions.
* Changed related internal variable names w.r.t metadata property names.
* Replaced `os_windows` internal parameter with `machine_OS`, and changed its input from `os.name` to more flexible `platform.system()`.
* Removed `source_extension` internal parameter and assigned values directly.
- [x] FFhelper:
* Implemented more robust pattern matching for Linux machines.
* Updated logs in `check_sp_output()` method for improving error output message.
* Implemented "Cannot open device" v4l2-ctl command Error logs.
- [x] Maintenance:
* Bumped version to `0.2.4`.
* Updated code comments.
- [x] CI:
* Updated FFdecoder API's `test_camera_capture` unittest to test new Index based Camera Device Capturing on different platforms.
* Added various parametrize `source` and `source_demuxer` parameter data to attain maximum coverage.
* Added `result` field to `fail` and `xfail` unittest according to parametrize data provided on different platforms.
* Removed `pytest.mark.skipif` to support all platforms.
* Added and updated various parametrize test data to attain maximum coverage.
* Limited range of extracted frames, for finishing tests faster.
* Updated unittests to reflect recent name changes.
* Disabled capturing of stdout/stderr with `-s` flag in pytest.
- [x] Setup:
* Updated description metadata.
- [x] Bash Script:
* Created undeleteable `undelete.txt` file for testing on Linux envs.
* Updated `undelete.txt` file path.
* Made FFmpeg output less verbose.
- [x] Docs:
* Updated FFdecoder API params docs w.r.t recent changes and supported for both discarded parameters and filter values.
* Added new admonitions to explain handling of "null" and (special-case), undefined, or invalid type values in various parameters/attributes.
* Added new footer reference explaining the handling of Default pixel-format for `frame_format` parameter.
* Added missing docs for `-default_stream_indexes` ffparams attribute.
* Added docs for recently added additional FFmpeg parameter in Sourcer API's `sourcer_params` parameter.
* Removed unsupported `-custom_resolution` sourcer_params attributes from `sourcer_params` parameter docs.
* Removed redundant `-vcodec` and `-framerate` attributes from `sourcer_params` parameter docs.
* Updated both basic and advanced project Index hyperlinks.
* Moved `decoding-live-feed-devices.md` doc from basic to advanced directory.
* Updated page navigation in `mkdocs.yml`.
* Update announcement bar to feature Index based Camera Device Capture support.
* Updated Project description and Key features of DeFFcode.
* Updated README.md with latest information.
* Updated `source` and `source_demuxer` param doc.
* Updated Hardware-Acceleration docs.
* Updated Hardware-Accelerated Video Decoding and Transcoding docs to inform users about DeFFcode generated YUV frames not yet supported by OpenCV and its APIs.
* Updated recipes docs to reflect recent changes in APIs.
* Updated parameter docs to reflect recent name changes.
* Updated parameters/attributes introductory descriptions.
* Updated various parametrize data to attain maximum coverage.
* Updated Zenodo badge and the BibTeX entry.
* Updated method description texts and logging messages.
* Update title headings, icons and admonition messages.
* Updated code comments.
* Updated `changelog.md`.


??? danger "Breaking Updates/Changes"
* **API:**
- [x] :skull_crossbones: Implemented new Index based Camera Device Capture feature (Similar to OpenCV), where the user just have to assign device index as integer _(`-n` to `n-1`)_ in source parameter of DeFFcode APIs to directly access the given input device in few seconds.
* **FFdecoder API**
- [x] :skull_crossbones: Unsupported dtype pixel-format always defaults to `rgb24`.
* **Sourcer API:**
- [x] :skull_crossbones: Renamed `output_video_resolution` metadata property to `output_frames_resolution`.
- [x] :skull_crossbones: Renamed `output_video_framerate` metadata property to `output_framerate`.

??? bug "Bug-fixes"
- [x] FFdecoder API:
* Removed redundant dummy value for `output_frames_pixfmt` metadata property.
* Fixed critical KeyError bug arises due to missing output metadata properties.
* Enforced `force_retrieve_missing` parameter in Sourcer API's `retrieve_metadata()` method for returning metadata missing in current Pipeline as `(metadata, metadata_missing)` tuple value instead of just `metadata`.
* Added new `missing_prop` internal class variable for handling metadata properties missing, received from Sourcer API.
* Moved `ffdecoder_operational_mode` to missing metadata properties that cannot be updated but are read only.
* Added missing metadata properties to metadata class property object for easy printing along with other metadata information.
* Implemented missing metadata properties updation via. overridden metadata class property object.
* Added `counterpart_prop` dict to handle all counterpart source properties for each missing output properties.
* Implemented missing output properties auto-updation w.r.t counterpart source property.
* Added separate case for handling only missing metadata properties and notifying user about counterpart source properties.
* Fixed source metadata properties update bug causing non-existential missing metadata properties to be added to source metadata properties dictionary along with source metadata property.
* Replaced `update()` calling on `value` dict directly with explicitly assigning values to source metadata properties dictionary.
* Simplified `missing_prop` validation.
* Removed unwanted `continue` in middle of loop.
* Remove unusable exclusive `yuv` frames patch.
* Fixed `KeyError` bug arises due to wrong variable placement.
* Fixed `approx_video_nframes` metadata property check.
* Fixed `av_interleaved_write_frame(): broken pipe` warning bug by switching `process.terminate()` with `process.kill()`.
* Fixed `AttributeError` bug caused due to typo in logger.
- [x] FFhelper:
* Fixed `check_sp_output()` method returning Standard Error (stderr) even when Nonetype.
* Fixed logger requiring `utf-8` decoding.
* Fixed missing `force_retrieve_stderr` argument to `check_sp_output` in `extract_device_n_demuxer` method on Linux platforms.
* Fixed logger message bug.
- [x] Utils:
* Fixed logger name typo.
- [x] Maintenance:
* Fixed hyperlinks to new GitHub's form schemas.
* Fixed typos in logs messages.
* Removed redundant code.
* Updated code comments.
- [x] Setup:
* Rearranged `long_description` patches to address unused patch bug.
- [x] Bash Script:
* Fixed `chattr: No such file or directory` bug.
- [x] CI:
* Fixed missing `lavfi` demuxer for `mandelbrot` virtual source in Sourcer API's `test_probe_stream_n_retrieve_metadata` unittest.
* Fixed missing `ffparams` parameter bug in `test_discard_n_filter_params()` unittest.
* Fixed `test_camera_capture` test.
* Removed redundant similar `ValueError` checks.
* Fixed typo in pytest arguments.
* Fixed missing arguments.
- [x] Docs:
* Fixed invalid hyperlinks in ReadMe.md
* Fixed bad formatting and context.
* Fixed typos in code comments.
* Fixed several typos in docs.

??? question "Pull Requests"
* PR 29
* PR 32

 

 

??? new "New Features"
- [x] **Docs:**
* Added Zenodo Bibtex entry and badge in docs for easy citation.
* Added new `<div>` tag bounding-box style to the Static FFmpeg binary download links in FFmpeg Installation Doc for better accessibility.
- [x] **Maintenance:**
* Switched to new Issue GitHub's form schema using YAML:
* Added new `bug_report.yaml` Issue GitHub's form schema for Bug Reports.
* Added new `idea.yaml` Issue GitHub's form schema for new Ideas.
* Added new `question.yaml` Issue GitHub's form schema for Questions.
* Deleted old depreciated markdown(`.md`) files.
* Polished forms.

??? success "Updates/Improvements"
- [x] Maintenance:
* Added new patterns to `.gitignore` to ignore vim files.
- [x] CI:
* Updated `test_FFdecoder_params` unittest to include `with` statement access method.
- [x] Setup:
* Added new patches for using README.md text as `long_description` metadata.
* Implemented new patch to remove GitHub README UI specific text.
* Simplified multiple `str.replace` to chained `str.replace` of better readability.
* Bumped version to `0.2.3`.
- [x] Docs:
* Updated recipes to include `with` statement access method.
* Updated existing recipes to include `with` statement access method in FFdecoder APIs.
* Included new example code of accessing RGB frames using `with` statement access method.
* Updated Recipe title to "Accessing RGB frames from a video file" across docs.
* Included warning admonition for advising users to always use `trim` with `reverse` filter.
* Updated docs text font to `Libre Franklin`.
* Updated method description texts and logging messages.
* Update icons and admonition messages.
* Updated code comments.
* Updated `changelog.md`.

??? bug "Bug-fixes"
- [x] FFdecoder API:
* Fixed Context Manager methods.
* Fixed `__enter__` method returning class instance instead of formulating pipeline.
* Fixed `__exit__` method calling wrong non-existent method.
- [x] Setup:
* Fixed missing `comma(,)` in keywords metadata.
* Fixed bug in patch string.
- [x] Docs:
* Fixed typos in code comments.
* Fixed several typos in docs.

??? question "Pull Requests"
* PR 26

&nbsp;

&nbsp;

??? new "New Features"
- [x] **Sourcer API:**
* Added support for `-ffprefixes` attribute through Sourcer API's `sourcer_param` dictionary parameter _(similar to FFdecoder API)_.
- [x] **FFdecoder API:**
* Added new `output_frames_pixfmt` metadata property to preview and handle output frames pixel-format.
- [x] **Docs:**
* Added separate "Basic" and "Advanced" Recipes markdowns files with self-explanatory text, related usage code, asset _(such as images, diagrams, GIFs, etc.)_, and UI upgrades for bringing standard quality to visual design.
* Added separate `index.md` for Basic and Advanced Recipes with introductory text and curated hyperlinks for quick references to various recipes _(separated with sub-categories "Decoding", "Transcoding", and "Extracting Video Metadata")_.
* Added related admonitions to specify python dependencies as well as other requirements and relevant information required for each of these recipes.
* Added new Basic Decoding Recipes:
* Added Decoding Video files with various pixel formats recipes.
* Added Decoding Live Feed Devices recipes with `source_demuxer` FFdecoder API parameter.
* Added Decoding Image sequences recipes supporting Sequential, Glob pattern , Single (looping) image.
* Added Decoding Network Streams recipes.
* Added new Basic Transcoding Recipes:
* Added Transcoding Live frames recipes with OpenCV and WriteGear.
* Added Transcoding Live Simple Filtergraphs recipes with OpenCV.
* Added Saving Key-frames as Image recipes with different image processing libraries.
* Added new Basic Extracting Video Metadata Recipes:
* Added Extracting Video Metadata recipes with FFdecoder and Sourcer APIs.
* Added new Advanced Decoding Recipes:
* Added Hardware-Accelerated Video Decoding recipe using NVIDIA's H.264 CUVID Video-decoder(`h264_cuvid`).
* Added Decoding Live Virtual Sources recipes with many test patterns using `lavfi` input virtual device.
* Added new Advanced Decoding Recipes:
* Added lossless Hardware-Accelerated Video Transcoding recipe with WriteGear API.
* Added Transcoding Live Complex Filtergraphs recipes with WriteGear API.
* Added Transcoding Video Art with Filtergraphs recipes with WriteGear API for creating real-time artistic generative video art using simple and complex filtergraphs.
* Added new Advanced Updating Video Metadata Recipes:
* Added Updating Video Metadata recipes with user-defined as well as source metadata in FFdecoder API.
* Added new dark and light theme logo support.
* Added new recipes GIF assets to `gifs` folder.
* Added new dark logo `deffcode-dark.png` asset to `images` folder.
* Added new `ffdecoder.png` and `sourcer.png` Image assets to `images` folder.
* Added new `navigation.tabs` feature.
* Added Material Announcement-Bar notifying recent changes.

??? success "Updates/Improvements"
- [x] Sourcer API:
* Implemented new validation checks to ensure given `source` has usable video stream available by checking availability of either `video bitrate` or both `frame-size` and `framerate`_ properties in the source metadata.
* Improved `extract_resolution_framerate` method for making framerate extraction more robust by falling back to extracting `TBR` value when no framerate value available in the source metadata.
- [x] FFdecoder API:
* Updated `metadata` property object to validate and override source metadata properties directly by overloading same property object before formulating Frames Decoder Pipeline:
* Implemented validation checks to verify each validate manually assigned source metadata property against specific datatype before overriding.
* Updated logging to notify invalid datatype values when assigned through `metadata` property object.
* Added support for overriding `source_video_resolution` source metadata property to control frame-size directly through metadata.
* Added support for overriding `output_frames_pixfmt` metadata attribute to be used as default pixel-format, when `frame_format` parameter value is None-type.
* Improved handling of source metadata keys in metadata property object.
* Updated `metadata` property object to handle and assign User-defined metadata directly by overloading the same property object:
* Added new internal `user_metadata` class variable to handle all User-defined metadata information separately.
* FFdecoder API's `metadata` property object now returns User-defined metadata information merged with Source Video metadata.
* Added `tuple` value warning log to notify users `json` module converts Python `tuples` to JSON `lists`.
* Improved logic to test validity of `-custom_resolution` attribute value through `ffparams` dictionary parameter.
* Improved handling of FFmpeg pipeline framerate with both user-defined and metadata defined values.
* Added `tuple` to exception in datatype check for `ffparams` dictionary parameter.
* Added datatype validation check for `frame_format` parameter.
* Improved handling of `-framerate` parameter.
- [x] Maintenance:
* Reformatted all Core class and methods text descriptions:
* Rewritten introductory each API class description.
* Moved reference block from `index.md` to class description.
* Fixed missing class and methods parameter description.
* Fixed typos and context in texts.
* Reformatted code comments.
* Simplified `for` loop with `if` condition checking in metadata property object.
* Updated logging comments.
- [x] Setup:
* Updated project description in metadata.
* Bumped version to `0.2.2`.
- [x] Docs:
* Updated Introduction doc:
* Added new text sections such as "Getting Started", "Installation Notes", "Recipes a.k.a Examples" and "API in a nutshell".
* Rewritten Introduction(`index.md`) with recent Information, redefined context, UI changes, updated recipe codes, curated hyperlinks to various recipes(separated with categories), and relatable GIFs.
* Updated spacing in `index.md` using `spacer` class within `<div>` tag and `&nbsp;`.
* Reformatted and centered DeFFcode Introductory description.
* Reformatted FFmpeg Installation doc and Issue & PR guidelines.
* Updated static FFmpeg binaries download URLs in FFmpeg Installation doc.
* Refashioned text contexts, icons, and recipes codes.
* Updated Key Features section with reflecting new features.
* Updated README.md:
* Updated README.md w.r.t recent changes in Introduction(`index.md`) doc.
* Simplified and Reformatted text sections similar to Introduction doc.
* Imported new "Contributions" and "Donations" sections from VidGear docs.
* Added collapsible text and output section using `<summary>` and `<detail>` tags.
* Added experimental note GitHub blockquote to simulate admonition in README.md.
* Removed tag-line from README.md and related image asset.
* Simplified and Grouped README URL hyperlinks.
* Removed Roadmap section.
* Updated Recipes docs:
* Revamped DeFFcode Introduction `index.md` with new Information, Context and UI changes, Updated example codes and hyperlinks.
* Updated Announcement Bar to fix `announcement_link` variable and text.
* Updated footer note to notify users regarding `tuple` value warning in FFdecoder API.
* Rewritten recipes w.r.t breaking changes in APIs.
* Updated Reference docs:
* Completely revamped API's parameter reference docs.
* Added new Functional Block Diagrams to FFdecoder and Sourcer API References.
* Rewritten and Reformatted FFdecoder and Sourcer API's parameter reference docs with new information w.r.t recent changes.
* Implemented new admonitions explaining new changes, related warnings/errors, usage examples etc.
* Removed redundant `advanced.md` and `basic.md` docs.
* Added new abstracts to FFhelper and Utils docs.
* Updated docs site navigation and titles:
* Reformatted `index.md` and `installation/index.md`.
* Renamed `help/index.md` to `help/help.md`.
* Moved basic and advanced recipes from `example` to `recipes` folder.
* Imported "Donations" sections from VidGear docs to `help.md`.
* Added updated page-title and navigation hyperlinks in `mkdocs.yml` to new markdown files incorporated recently.
* Updated internal navigation hyperlinks in docs and removed old redundant file links.
* Updated docs UI:
* Added custom `spacer` class in CSS for custom vertical spacing.
* Imported new "New", "Advance", "Alert", "Danger" and "Bug" admonitions custom CSS UI patches from vidgear.
* Updated all admonitions icons with new custom icon SVG+XML URLs.
* Reformatted `custom.css` and added missing comments.
* Updated docs fonts:
* Updated text font to `Heebo`.
* Updated code font to `JetBrains Mono`.
* Updated primary and accent colors:
* Updated primary light color to `light green`.
* Updated primary dark color to `amber`.
* Updated accent light color to `green`.
* Updated accent dark color to `lime`.
* Replaced admonitions with appropriate ones.
* Changed Color palette toggle icons.
* Updated icons in title headings.
* Updated admonitions messages.
* Updated `changelog.md`.
- [x] CI:
* Pinned `jinja2` version to `<3.1.0`, since `jinja2>=3.1.0` breaks mkdocs (mkdocs/mkdocs2799).
* Updated unittests w.r.t recent changes in APIs:
* Updated `test_frame_format` unittest to include manually assign output pixel-format via `metadata` property object.
* Updated `test_metadata` unittest to include new `checks` parameter to decide whether to perform Assertion test on assigned `metadata` properties in FFdecoder API.
* Added new parametrize attributes in `test_metadata` and `test_seek_n_save` unittests to cover every use-cases.
* Replaced `IOError` with `ValueError` in Sourcer API unittests.
* Updated `test_metadata` unittest to verify `tuple` value warning.
* Updated unittests to increase code coverage significantly.


??? danger "Breaking Updates/Changes"
* **Sourcer API:**
- [x] :skull_crossbones: Sourcer API's `retrieve_metadata()` method now returns parsed metadata either as JSON string or dictionary type.
* Added new `pretty_json` boolean parameter to `retrieve_metadata()`, that is when `True`, returns metadata formatted as JSON string instead of default python dictionary.
- [x] :skull_crossbones: Changed `IOError` to `ValueError` in Sourcer API, raised when source with no decodable audio or video stream is provided.
* **FFdecoder API:**
- [x] :skull_crossbones: Rename `extraparams` dictionary parameter to `ffparams` in FFdecoder API.
- [x] :skull_crossbones: The `source` metadata value cannot be altered through `metadata` property object in FFdecoder API.
- [x] :skull_crossbones: Removed `-ffpostfixes` attribute support from `ffparams` dictionary parameter in FFdecoder API, since totally redundant in favor of similar `-ffprefixes` and `-clones` attributes.

??? bug "Bug-fixes"
- [x] FFdecoder API:
* Fixed `metadata` property object unable to process user-defined keys when any source metadata keys are defined.
* Fixed `TypeError` bug with string type `-framerate` parameter values.
- [x] Sourcer API:
* Fixed Sourcer API throws `IOError` for videos containing streams without both source bitrate and framerate defined _(such as from `lavfi` input virtual device)_.
* Fixed `AttributeError` bug due to typo in variable name.
- [x] CI:
* Fixed support for newer mkdocstring version in DeFFcode Docs Deployer workflow.
* Added new `mkdocstrings-python-legacy` dependency.
* Replaced `rendering` variable with `options`.
* Removed pinned `mkdocstrings==0.17.0` version.
* Removed redundant variables.
* Updated `test_metadata` unittest to fix `AssertionError` Bug.
- [x] Docs:
* Fixed some admonitions icons not showing bug using `!important` rule in CSS.
* Fixed `404.html` static page not showing up.
* Fixed invalid internal navigation hyperlinks and asset paths.
* Removed `quote/cite/summary` admonition custom UI patches.
* Removed redundant information texts.
* Fixed typos in code comments.
* Fixed typos in example code.


??? question "Pull Requests"
* PR 23

&nbsp;

&nbsp;

??? new "New Features"
- [x] **Sourcer API:**
* Implemented support for extracting metadata from live input devices/sources.
* Added new `source_demuxer` and `forced_validate` parameters to `validate_source` internal method.
* Implemented logic to validate `source_demuxer` value against FFmpeg supported demuxers.
* Rearranged metadata dict.
* Updated Code comments.
- [x] **FFdecoder API:**
* Implemented functionality to supported live devices by allowing device path and respective demuxer into pipeline.
* Included `-f` FFmpeg parameter into pipeline to specify source device demuxer.
* Added special case for discarding `-framerate` value with Nonetype.
- [x] **CI:**
* Added new unittest `test_camera_capture()` to test support for live Virtual Camera devices.
* Added new `v4l2loopback-dkms`, `v4l2loopback-utils` and kernel related APT dependencies.
- [x] **Bash Script:**
* Added new FFmpeg command to extract image datasets from given video on Linux envs.
* Created live Virtual Camera devices through `v4l2loopback` library on Github Actions Linux envs.
* Added `v4l2loopback` modprobe command to setup Virtual Camera named `VCamera` dynamically at `/dev/video2`.
* Added `v4l2-ctl --list-devices` command for debugging.
* Implemented FFmpeg command through `nohup`(no hangup) to feed video loop input to Virtual Camera in the background.

??? success "Updates/Improvements"
- [x] Sourcer API:
* Only either `source_demuxer` or `source_extension` attribute can be present in metadata.
* Enforced `forced_validate` for live input devices/sources in `validate_source` internal method.
- [x] FFdecoder API:
* Rearranged FFmpeg parameters in pipeline.
* Removed redundant code.
* Updated Code comments.
- [x] FFhelper API:
* Logged error message on metadata extraction failure.
- [x] CI:
* Restricted `test_camera_capture()` unittest to Linux envs only.
* Removed `return_generated_frames_path()` method support for Linux envs.
* Pinned jinja2 `3.1.0` or above breaking mkdocs.
* `jinja2>=3.1.0` breaks mkdocs (mkdocs/mkdocs2799), therefore pinned jinja2 version to `<3.1.0`.
- [x] Bash Script:
* Updated to latest FFmpeg Static Binaries links.
* Updated download links to abhiTronix/ffmpeg-static-builds * hosting latest available versions.
* Updated date/version tag to `12-07-2022`.
* Removed depreciated binaries download links and code.
- [x] Setup:
* Bumped version to `0.2.1`.
- [x] Docs:
* Updated `changelog.md`.

??? danger "Breaking Updates/Changes"
- [x] :skull_crossbones: **Implement support for live input devices/sources.**
* `source` parameter now accepts device name or path.
* Added `source_demuxer` parameter to specify demuxer for live input devices/sources.
* Implemented Automated inserting of `-f` FFmpeg parameter whenever `source_demuxer` is specified by the user.

??? bug "Bug-fixes"
- [x] Sourcer API:
* Fixed Nonetype value bug in `source_demuxer` assertion logic.
* Fixed typos in parameter names.
* Added missing import.
- [x] FFhelper API:
* Logged error message on metadata extraction failure.
* Fixed bug with `get_supported_demuxers` not detecting name patterns with commas.
* Removed redundant logging.
- [x] CI:
* Fixed critical permission bug causing `v4l2loopback` to fail on Github Actions Linux envs.
* Elevated privileges to `root` by adding `sudo` to all commands(including bash scripts and python commands).
* Updated vidgear dependency to pip install from its git `testing` branch with recent bug fixes.
* Replaced relative paths with absolute paths in unit tests.
* Fixed WriteGear API unable to write frames due to permission errors.
* Fixed `test_source_playback()` test failing on Darwin envs with OLD FFmpeg binaries.
* Removed `custom_ffmpeg` value for Darwin envs.
* Fixed various naming typos.
* Fixed missing APT dependencies.

??? question "Pull Requests"
* PR 17

&nbsp;

&nbsp;