WebGear_RTC API Parameters¶
WebGear_RTC provides a special internal wrapper around VideoGear, which itself provides internal access to both CamGear and PiGear APIs and their parameters.
enablePiCamera
¶
This parameter provide direct access to PiGear or CamGear APIs respectively in WebGear_RTC. This means the if enablePiCamera
flag is True
, the PiGear API will be accessed, and if False
, the CamGear API will be accessed.
Data-Type: Boolean
Default Value: Its default value is False
.
Usage:
Its complete usage example is given here ➶.
options
¶
This parameter can be used to pass user-defined parameter to WebGear_RTC API by formatting them as this parameter's attribute.
Data-Type: Dictionary
Default Value: Its default value is {}
WebGear_RTC Specific attributes¶
-
custom_stream
(class) : Can be used to easily define your own Custom Streaming Class with suitable custom source(such as OpenCV) that you want to use to transform your frames before sending them onto the browser.Make sure your Custom Streaming Class at-least implements
read()
andstop()
methods, otherwise WebGear_RTC will throw ValueError!New in v0.2.4
This attribute was added in
v0.2.4
.Using Vidgear's VideoCapture APIs instead of OpenCV
You can directly replace Custom Streaming Class with any VideoCapture APIs. These APIs implements
read()
andstop()
methods by-default, so they're also supported out-of-the-box.See this example ➶ for more information.
Its complete usage example is given here ➶.
-
custom_data_location
(string) : Can be used to change/alter default location path to somewhere else. Its usage is as follows: -
overwrite_default_files
(boolean) : Can be used to force trigger the Auto-generation process to overwrite existing data-files. Its usage is as follows:Remember only downloaded files will be overwritten in this process, and any other file/folder will NOT be affected/overwritten.
-
frame_size_reduction
(int/float) : This attribute controls the size reduction (in percentage) of the frame to be streamed on Server and it has the most significant effect on performance. The value defaults to20
, and must be no higher than90
(fastest, max compression, Barely Visible frame-size) and no lower than0
(slowest, no compression, Original frame-size). Its recommended value is between40-60
. Its usage is as follows: -
enable_live_broadcast
(boolean) : WebGear_RTC by default only supports one-to-one peer connection with a single consumer/client, Hence this boolean attribute can be used to enable live broadcast to multiple peer consumers/clients at same time. Its default value isFalse
. Its usage is as follows:enable_infinite_frames
is enforced by default when this attribute is enabled(True
).For accessing WebGear_RTC on different Client Devices on the network, use
"0.0.0.0"
as host value instead of"localhost"
on Host Machine. More information can be found here ➶New in v0.2.2
enable_live_broadcast
attribute was added inv0.2.2
.# enable live boadcast to multiple consumers. options = {"enable_live_broadcast": True} # assign it WebGear_RTC(logging=True, **options)
Its complete usage example is given here ➶.
-
enable_infinite_frames
(boolean) : Can be used to continue streaming (instead of terminating immediately) with emulated blank frames with text "No Input", whenever the input source disconnects. Its default value isFalse
. Its usage is as follows:enable_infinite_frames
is disabled whenenable_live_broadcast
attribute is enabled(True
).New in v0.2.1
enable_infinite_frames
attribute was added inv0.2.1
.
Parameters for Stabilizer Backend¶
Enable this backend with stabilize=True
in WebGear_RTC. Default is also False
.
stabilize
¶
This parameter enable access to Stabilizer Class for stabilizing frames, i.e. can be set to True
(to enable) or unset to False
(to disable).
Data-Type: Boolean
Default Value: Its default value is False
.
Usage:
Its complete usage example is given here ➶.
options
¶
This parameter can be used in addition, to pass user-defined parameters supported by Stabilizer Class. These parameters can be formatted as this parameter's attribute.
Supported dictionary attributes for Stabilizer Class are:
-
SMOOTHING_RADIUS
(integer) : This attribute can be used to alter averaging window size. It basically handles the quality of stabilization at the expense of latency and sudden panning. Larger its value, less will be panning, more will be latency and vice-versa. Its default value is25
. You can easily pass this attribute as follows: -
BORDER_SIZE
(integer) : This attribute enables the feature to extend border size that compensates for stabilized output video frames motions. Its default value is0
(no borders). You can easily pass this attribute as follows: -
CROP_N_ZOOM
(boolean): This attribute enables the feature where it crops and zooms frames(to original size) to reduce the black borders from stabilization being too noticeable (similar to the Stabilized, cropped and Auto-Scaled feature available in Adobe AfterEffects). It simply works in conjunction with theBORDER_SIZE
attribute, i.e. when this attribute is enabled,BORDER_SIZE
will be used for cropping border instead of extending them. Its default value isFalse
. You can easily pass this attribute as follows: -
BORDER_TYPE
(string) : This attribute can be used to change the extended border style. Valid border types are'black'
,'reflect'
,'reflect_101'
,'replicate'
and'wrap'
, learn more about it here. Its default value is'black'
. You can easily pass this attribute as follows:Altering
BORDER_TYPE
attribute is Disabled whileCROP_N_ZOOM
is enabled.
Parameters for CamGear backend¶
Enable this backend with enablePiCamera=False
in WebGear_RTC.
source
¶
WebGear_RTC API will throw RuntimeError
if source
provided is invalid.
This parameter defines the source for the input stream.
Data-Type: Based on input.
Default Value: Its default value is 0
.
Its valid input can be one of the following:
-
Index (integer): Valid index of the connected video device, for e.g
0
, or1
, or2
etc. as follows: -
Filepath (string): Valid path of the video file, for e.g
"/home/foo.mp4"
as follows: -
Streaming Services URL Address (string): Valid Video URL as input when Stream Mode is enabled(i.e.
stream_mode=True
)CamGear internally implements
yt_dlp
backend class for pipelining live video-frames and metadata from various streaming services. For example Twitch URL can be used as follows:Supported Streaming Websites
The complete list of all supported Streaming Websites URLs can be found here ➶
-
Network Address (string): Valid (
http(s)
,rtp
,rtsp
,rtmp
,mms
, etc.) incoming network stream address such as'rtsp://192.168.31.163:554/'
as input: -
GStreamer Pipeline:
CamGear API also supports GStreamer Pipeline.
Requirements for GStreamer Pipelining
Successful GStreamer Pipelining needs your OpenCV to be built with GStreamer support. Checkout this FAQ for compiling OpenCV with GStreamer support.
Thereby, You can easily check GStreamer support by running
print(cv2.getBuildInformation())
python command and see if output contains something similar as follows:Be sure convert video output into BGR colorspace before pipelining as follows:
stream_mode
¶
This parameter controls the Stream Mode, .i.e if enabled(stream_mode=True
), the CamGear API will interpret the given source
input as YouTube URL address.
Due to a FFmpeg bug that causes video to freeze frequently in OpenCV, It is advised to always use GStreamer backend for any livestream videos. Checkout this FAQ for compiling OpenCV with GStreamer support.
Data-Type: Boolean
Default Value: Its default value is False
.
Usage:
Supported Streaming Websites
The complete list of all supported Streaming Websites URLs can be found here ➶
Its complete usage example is given here ➶.
backend
¶
This parameter manually selects the backend for OpenCV's VideoCapture class (only if specified).
Data-Type: Integer
Default Value: Its default value is 0
Usage:
All supported backends are listed here ➶
Its value can be for e.g. backend = cv2.CAP_DSHOW
for selecting Direct Show as backend:
options
¶
This parameter provides the ability to alter various Source Tweak Parameters available within OpenCV's VideoCapture API properties.
Data-Type: Dictionary
Default Value: Its default value is {}
Usage:
All supported parameters are listed here ➶
The desired parameters can be passed to WebGear_RTC API by formatting them as this parameter's attributes, as follows:
# formatting parameters as dictionary attributes
options = {"CAP_PROP_FRAME_WIDTH":320, "CAP_PROP_FRAME_HEIGHT":240, "CAP_PROP_FPS":60}
# assigning it
WebGear_RTC(source=0, **options)
Parameters for PiGear backend¶
Enable this backend with enablePiCamera=True
in WebGear_RTC.
camera_num
¶
This parameter selects the camera index to be used as the source, allowing you to drive these multiple cameras simultaneously from within a single Python session. Its value can only be zero or greater, otherwise, WebGear_RTC API will throw ValueError
for any negative value.
Data-Type: Integer
Default Value: Its default value is 0
.
Usage:
The complete usage example demonstrating the usage of the camera_num
parameter is available here ➶.
resolution
¶
This parameter controls the resolution - a tuple (i.e. (width,height)
) of two values giving the width and height of the output frames.
Make sure both width and height values should be at least 64
.
When using the Picamera2 backend, the resolution
parameter will be OVERRIDDEN, if the user explicitly defines the output_size
property of the sensor
configurational parameter.
Data-Type: Tuple
Default Value: Its default value is (640,480)
.
Usage:
framerate
¶
This parameter controls the framerate of the source.
Data-Type: integer/float
Default Value: Its default value is 30
.
Usage:
options
¶
This dictionary parameter in the internal PiGear API backend allows you to control various camera settings for both the picamera2
and legacy picamera
backends and some internal API tasks. These settings include:
A. Configurational Camera Parameters¶
- These parameters are provided by the underlying backend library (depending upon backend in use), and must be applied to the camera system before the camera can be started.
- These parameter include: Brightness, Contrast, Saturation, Exposure, Colour Temperature, Colour Gains, etc.
- All supported parameters are listed in this Usage example ➶
B. User-defined Parameters¶
- These user-defined parameters control specific internal behaviors of the API and perform certain tasks on the camera objects.
- All supported User-defined Parameters are listed here ➶
Data-Type: Dictionary
Default Value: Its default value is {}
Usage:
The complete usage example demonstrating the usage of the options
parameter is available here ➶.
You can format these user-defined and configurational parameters as attributes of this options
dictionary parameter as follows:
# formulate various Picamera2 API parameters
options = {
"queue": True,
"buffer_count": 4,
"controls": {"Brightness": 0.5, "ExposureValue": 2.0},
"exposure_compensation": 15,
"sensor": {"output_size": (480, 320)}, # !!! will override `resolution` !!!
}
# open pi video stream with defined parameters
stream = WebGear_RTC(enablePiCamera=True, resolution=(640, 480), framerate=60, logging=True, **options).start()
# formulate various Picamera API parameters
options = {
"hflip": True,
"exposure_mode": "auto",
"iso": 800,
"exposure_compensation": 15,
"awb_mode": "horizon",
"sensor_mode": 0,
}
# open pi video stream with defined parameters
stream = WebGear_RTC(enablePiCamera=True, resolution=(640, 480), framerate=60, logging=True, **options).start()
Common Parameters¶
These are common parameters that works with every backend in WebGear_RTC.
colorspace
¶
This parameter selects the colorspace of the source stream.
Data-Type: String
Default Value: Its default value is None
.
Usage:
All supported colorspace
values are given here ➶
Its complete usage example is given here ➶
logging
¶
This parameter enables logging (if True
), essential for debugging.
Data-Type: Boolean
Default Value: Its default value is False
.
Usage:
time_delay
¶
This parameter set the time delay (in seconds) before the WebGear_RTC API start reading the frames. This delay is only required if the source required some warm-up delay before starting up.
Data-Type: Integer
Default Value: Its default value is 0
.
Usage: