v0.2.6

Summary: New Parameters, Support for SRTP/RTSPS protocol, and Enhanced Video Orientation Handling and Process Termination 🎉

📓 Complete Release Notes can be found here ↗️

---

DeFFcode is free and open source and will always remain so. ❤️

It is something I am doing with my own free time. But so much more needs to be done, and I need your help to do this. For just the price of a cup of coffee, you can make a difference 🙂

What's Changed

✨ New Features

• 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.
• 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).
• 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.
• Core:
  • Added official support for Python 3.11.x legacies.
• Docs:
  • Added context and detailed instructions for Input and Output Seeking methods.
  • Added documentation for the new optional -disable_ffmpeg_window boolean parameter.

⚡️Updates/Improvements

• 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().
• FFhelper:
  • Improved regex pattern in get_supported_demuxers method.
• Sourcer:
  • Updated extract_resolution_framerate method to also return video orientation.
• Docs:
  • Included GitHub sponsors in FUNDING.yml.
  • Removed deprecated Gitter community chat sidecard.

💥 Breaking Updates/Changes

• Core:
  • ☠️ Ended support for Python 3.7.x legacies.

🐛 Bug-fixes

• FFdecoder API:
  • Fixed regex expression bugs in get_supported_demuxers method.

v0.2.5

📓 Complete Release Notes can be found here ↗️

---

Summary: New patch for handling YUV pixel-formats and Looping Video support 🎉

✨ New Features

• FFdecoder:
  • 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.
• 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"]).
• 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 Capturing and Previewing frames from a Looping Video recipe using -stream_loop option and loop filter.
  • Added new content.code.copy and content.code.link features.

⚡️Updates/Improvements

• FFhelper:
  • Replaced depreciating Retry API from requests.packages with requests.adapters.
• Maintenance:
  • Replaced raw.github.com links with GitLab and GH links.

🐛 Bug-fixes

• FFdecoder API:
  • Fixed Zero division bug while calculating raw_bit_per_component.
• FFhelper:
  • Fixed response.headers returning content-length as Nonetype since it may not necessarily have the Content-Length header set.
  • Docs:
    • Fixed badges/shields#8671 badge issue in README.md

v0.2.4

📓 Complete Release Notes can be found here ↗️

---

Summary: New Index based Camera Device Capturing and Support for Discarded parameters and utilizing Filter values 🎉

✨ New Features

• FFdecoder API:
  • 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.
  • 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.
  • 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.
• 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..
  • 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.
• 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.
    • ⚠️ The extract_device_n_demuxer method will raise RuntimeError if it fails to identify any device.
• Utilities:
  • Added new new validate_device_index() method to verify if given device index is valid or not?

⚡️Updates/Improvements

• FFdecoder API:
  • Added new pixel-formats to supported group by extending raw bits-per-component range.
  • output_frames_pixfmt metadata property(if available) will be overridden to rgb24.
• Sourcer API:
  • 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.
• 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.

💥 Breaking Updates/Changes

• FFdecoder API
  • Unsupported dtype pixel-format always defaults to rgb24.
• Sourcer API:
  • Renamed output_video_resolution metadata property to output_frames_resolution.
  • Renamed output_video_framerate metadata property to output_framerate.

🐛 Bug-fixes

• FFdecoder API:
  • 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.
  • 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.
  • 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.
• 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.
• Utils:
  • Fixed logger name typo.
• Setup:
  • Rearranged long_description patches to address unused patch bug.

v0.2.3

📓 Complete Release Notes can be found here ↗️

---

Summary: Bug Fixes and Maintenance Updates 🎉

✨ New Features

• Docs:
  • Added Zenodo Bibtex entry and badge in docs for easier citation.
• Maintenance:
  • Switched to new Issue GitHub's form schema using YAMLs.

⚡️ Updates/Improvements

• Maintenance:
  • Added new patterns to .gitignore to ignore vim files.
• Setup:
  • Implemented new patch to remove GitHub README UI specific text for using README.md text as long_description metadata.
• Docs:
  • Updated existing recipes to include with statement access method in FFdecoder APIs.
  • Updated docs text font to Libre Franklin.

🐛 Bug-fixes

• FFdecoder API:
  • Fixed Context Manager methods.
    • Fixed __enter__ method returning class instance instead of formulating pipeline.
    • Fixed __exit__ method calling wrong non-existent method.
• Setup:
  • Fixed missing comma(,) in keywords metadata.
  • Fixed bug in patch string.

v0.2.2

📓 Complete Release Notes can be found here ↗️

---

Summary: Major Docs and API Updates. 🎉

✨ New Features

• Sourcer API:
  • Added support for -ffprefixes attribute through Sourcer API's sourcer_param dictionary parameter (similar to FFdecoder API).
• FFdecoder API:
  • Added new output_frames_pixfmt metadata property to preview and handle output frames pixel-format.
• 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 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.

⚡️ Updates/Improvements

• 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.
• 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 metadata property object to handle and assign User-defined metadata directly by overloading the same property object:
    • FFdecoder API's metadata property object now returns User-defined metadata information merged with Source Video metadata.
• Docs:
  • Reformatted all Core class and methods text descriptions:
    • Fixed missing class and methods parameter description.
    • Reformatted code comments.
  • 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.
  • Reformatted and centered DeFFcode Introductory description.
  • Updated Key Features section with reflecting new features.
  • Updated docs site navigation and titles in mkdocs.yml.
  • Added custom spacer class in CSS for custom vertical spacing.
  • Updated all admonitions icons with new custom icon SVG+XML URLs.
  • Updated docs fonts.
  • Updated primary and accent colors.
  • Updated API Reference docs.
  • Changed Color palette toggle icons.
  • Updated icons in title headings.
  • Updated admonition messages.

💥 Updates/Changes

• Sourcer API:
  • 🆕 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.
  • ⚠️ Changed IOError to ValueError in Sourcer API, raised when source with no decodable audio or video stream is provided.
• FFdecoder API:
  • ⚠️Rename extraparams dictionary parameter to ffparams in FFdecoder API.
  • 💀 The source metadata value cannot be altered through metadata property object in FFdecoder API.
  • ⚠️ Removed -ffpostfixes attribute support from ffparams dictionary parameter in FFdecoder API.

🐛 Bug-fixes

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

💡 Pull Requests

• PR #23

v0.2.1

📓 Complete Release Notes can be found here ↗️

---

Summary: Live Input Devices such as Webcams, Screen-capture, Virtual Cameras are now fully supported. 🎉

✨ New Features

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

 

⚡️ Updates/Improvements

• 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.
• FFhelper API:
  • Logged error message on metadata extraction failure.
• CI:
  • Pinned jinja2 version to <3.1.0.
• Bash Script:
  • Updated to latest FFmpeg Static Binaries links.

 

💥 Breaking Updates/Changes

• 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-fixes

• Sourcer API:
  • Fixed Nonetype value bug in source_demuxer assertion logic.
• FFhelper API:
  • Fixed bug with get_supported_demuxers not detecting name patterns with commas.

 

💡 Pull Requests

• PR #17

v0.2.0

📓 Complete Release Notes can be found here ↗️

---

🚀 All available stable python 3.7+ versions are now officially supported by DeFFcode. 🎉

New Features ✨

• Sourcer API:
  • Added a new source_audio_samplerate metadata parameter.
  • Added new -force_validate_source attribute to Sourcer API's sourcer_params dictionary parameter for special cases.
  • Added metadata extraction support:
    • Added retrieve_metadata class method to Sourcer API for extracting source metadata as python dictionary.
• FFdecoder API:
  • Added metadata extraction and updation support:
    • Added metadata property object function to FFdecoder API for retrieving source metadata form Sourcer API as dict and return it as JSON dump for pretty printing.
    • Added metadata property object with setter() method for updating source metadata with user-defined dictionary.
• Tests:
  • Added DeFFcode unit tests with pytest.
• Continuous Integration:
  • Automated CI support for different environments:
    • Implemented auto-handling of dependencies installation, unit testing, and coverage report uploading.
    • Added GitHub Action workflow for Linux envs.
    • Added Appveyor workflow for Windows envs.
    • Added Azure-Pipelines workflow for MacOS envs.
  • Implement new automated Docs Building and Deployment on gh-pages through GitHub Actions workflow.
  • Added new Automated Docs Versioning.
  • Added Skip Duplicate Actions Workflow to DeFFcode Docs Deployer.
• Maintenance:
  • New DeFFcode project issue and PR templates.
  • Added new FUNDING.yml with ko-fi donation link.
  • Added .gitattributes for DeFFcode, that set the default behavior, in case people don't have core.autocrlf set.
  • Imported Codecov config(codecov.yml) from vidgear to modify coverage parameters.
• Docs:
  • Added new comprehensive documentation with mkdocs and mkdocs-material theme.

Updates/Improvements ⚡️

• FFdecoder API:
  • Removed redundant forcing -r FFmpeg parameter for image sequences as source.
  • Removed redundant checks on -vf FFmpeg parameter.
  • FFmpeg parameter -s will be discarded in favor of -custom_resolution attribute.
  • Replaced -constant_framerate with FFmpeg -framerate attribute.
  • Replaced -custom_source_params with correct -custom_sourcer_params attribute.
  • Renamed operational_mode metadata parameter to ffdecoder_operational_mode.
• Sourcer API:
  • Converted all Sourcer API's public variables into private ones.
  • Moved FFmpeg path validation and handling to Sourcer from FFdecoder API.
    • Moved -ffmpeg_download_path dictionary attribute to Sourcer API's sourcer_params parameter.
• Continuous Integration:
  • Excluded dev branch from triggering workflow on any environment.
• Maintenance:
  • Updated LICENSE notice to add vidgear notice.
  • Bumped version to 0.2.0

Breaking Updates/Changes 💥

• ⚠️ Sourcer API will now raises Assertion error if probe_stream() not called before calling retrieve_metadata().
• ⚠️ Only -framerate values greater than 0.0 are now valid.
• ⚠️ Renamed decode_stream to probe_stream in Sourcer API.
• ⚠️ Any of video bitrate or video framerate are sufficient to validate if source contains valid video stream(s).
• ⚠️ Any of audio bitrate or audio samplerate are sufficient to validate if source contains valid audio stream(s).

Bug-fixes 🐛

• APIs:
  • Added missing delete_file_safe function in utils.py
  • Fixed forward slash bugs in regex patterns.
  • Fixed IndexError when no bitrate was discovered in given source.
  • Fixed FFmpeg subprocess pipeline not terminating gracefully in FFdecoder API.
  • Fixed __version__ not defined in DeFFcode's __init__.py that throws AttributeError on any query.

Related PRs 💡

• PR #5
• PR #6
• PR #8
• PR #9
• PR #11
• PR #12
• PR #13
• PR #14

v0.1.0

First Release 🆕

New Features ✨

• 🎉 Open-Sourced DeFFcode under the Apache 2.0 License.
• Added new Classes(APIs):
  • FFdecoder: Performant Real-time Video frames Generator for generating blazingly fast video frames(RGB ndarray by default).
  • Sourcer: Extracts source video metadata (bitrate, resolution, framerate, nframes etc.) using its subprocess FFmpeg output.
• Added new Helper functions:
  • ffhelper: Backend FFmpeg Wrapper that handles all subprocess transactions and gather data.
  • utils: Handles all additional Utilizes required for functioning of Deffcode.
• First PyPi Release:
  • Released Deffcode to Python Package Index (PyPI)
  • Added setup.py and related metadata.
  • Added version.py
• Docs:
  • Added abstract and related information in README.md
  • Added installation instructions.
  • Added preliminary usage examples.
• Maintenance:
  • Added LICENSE.
  • Added .gitignore

Updates/Improvements ⚡️

• Maintenance:
  • Bumped version to 0.1.0
  • Updated LICENSE notice to add vidgear code usage notice.

Breaking Updates/Changes 💥

• Fixed support for Python-3.7 and above legacies only.

Bug-fixes 🐛

• Docs:
  • Fixed hyperlinks in README.
  • Fixed indentation and spacing.
  • Fixed typos and updated context.
  • Removed dead code.