Package: vidcontrol
vidcontrol⚠️ This package is still under development and is not yet ready for production use. ⚠️vidcontrol is a Python package for managing multi-webcam video capture. It is designed to be cross-platform and easy to use. Under the hood, we useimageiofor video capture, which itself usesffmpeg. This package offers various utility functions for listing and selecting available webcams, and for capturing video from multiple webcams simultaneously. We also provide an easy-to-use interface for resolving image resolutions and frame rates.This package has been developed in conjunction withctrlabilitytogether with thePrototype Fund.PlatformStatusMacOSFull supportTested and verified on macOS 12.0+LinuxNot yet, but plannedWindowsFull supportTested and verified on Windows 11Getting StartedPrerequisitesThis package requires Python 3.8 or higher. We recommend using a virtual environment for development. You can create a virtual environment usingvenvorconda.Additionally, you will need to installffmpegon your system. On macOS, you can install ffmpeg usingHomebrew:brewinstallffmpegInstallationYou can install the latest version of the package directly from this repository:pipinstallgit+https://github.com/inmotion-health/vidcontrol.gitOr install from source:gitclonehttps://github.com/inmotion-health/vidcontrol.gitcdvidcontrol
pipinstall.Basic UsageGenerally, this package is constructed around two main classes:VideoManagerandVideoSource. TheVideoManageris used to manage all available webcams and to create newVideoSourceinstances. TheVideoSourceis used to capture video from a single webcam. The following example shows how to use these classes to capture video from a single webcam:fromvidcontrolimportVideoManagermanager=VideoManager()# List available webcamsmanager.list_available_cameras()# Set the height of the video capturemanager.set_preferred_height(480)# Get a video source and start capturingsource=manager.get_video_source(0)forframeinsource:# Do something with the framepassTo capture video from a webcam, you first need to request aVideoSourcefrom theVideoManager. You can do this by callingget_video_sourceand passing the index of the webcam you want to use. The index is the same as the index returned bylist_available_cameras. You can also pass apreferred_heightandpreferred_fpstoget_video_sourceto set the height and frame rate of the video capture. If you do not pass these parameters, the VideoManager will use the default values.The VideoManager will then try to find a webcam that supports the requested height and frame rate. If it cannot find a webcam that supports the requested height and frame rate, it will use the next best resolution and frame rate. By default, this fallback is disabled, but you can enable it by settingnext_besttoTruewhen configuring the VideoManager.If the VideoSource for a webcam is requested multiple times, the VideoManager will return the same VideoSource instance. This means that you can use the same VideoSource instance in multiple places in your code. This is useful if you want to capture video from a single webcam multiple times.For more detailed examples, please see theexamplesfolder.Configurationvidcontrol supports various options for configuring the video capture. You can set these options either when creating a newVideoManageror when creating a newVideoSource. The following table lists all available options:ParameterDescriptionDefault ValueVideoManagerpreferred_heightThe preferred height of the video capture.480preferred_fpsThe preferred frame rate of the video capture.30next_bestWhether to use the next best resolution if the preferred resolution fails.FalseVideoSourcecolor_formatThe color format of the video capture.rgbOther options:bgrmirror_frameWhether to mirror the frame vertically.Trueflip_frame_horizontalWhether to flip the frame horizontally.FalseThese options are either passed as a dictionary to theVideoManagerorVideoSourceset_config, or via their respective functions in the form ofset_<option>. See thebasic usageorpass configexample to see how to use some of these options.Contributing and IssuesWe welcome contributions and feedback. Please use GitHub issues to report bugs, discuss features, or ask questions. If you would like to contribute to the project, feel free to open a pull request. Please make sure to follow thePEP8style guide.Things we especially would appreciate help with:Testing on different platforms and versionsTesting with different webcamsWhen contributing, please make sure to use conventional commits for your commit messages. This makes it easier to automatically generate a changelog. You can find more information about conventional commitshere.LicenseThis project is licensed under the MIT License - see theLICENSE.mdfile for details.