WebGear API Usage Examples:¶

Requirements¶

Installation with Asyncio Support¶

WebGear API is the part of asyncio package of VidGear, thereby you need to install VidGear with asyncio support as follows:

pip install vidgear[asyncio]

ASGI Server¶

You'll also need to install an ASGI Server to run following WebGear usage examples, and by default WebGear ships the state-of-the-art uvicorn Server. But you can also use other ASGI server such as daphne, or hypercorn with it.

Performance Enhancements ¶

WebGear provides certain performance enhancing attributes for its options dictionary parameter to cope with performance-throttling.

Performance Enhancing Attributes

frame_size_reduction: (int/float) This attribute controls the size reduction(in percentage) of the frame to be streamed on Server. Its value has the most significant effect on WebGear performance: More its value, smaller will be frame size and faster will be live streaming. The value defaults to 20, and must be no higher than 90 (fastest, max compression, Barely Visible frame-size) and no lower than 0 (slowest, no compression, Original frame-size). Its recommended value is between 40~60. Its usage is as follows:
```
options={"frame_size_reduction": 50} #frame-size will be reduced by 50%
```
Various Encoding Parameters:

In WebGear API, the input video frames are first encoded into Motion JPEG (M-JPEG or MJPEG) compression format, in which each video frame or interlaced field of a digital video sequence is compressed separately as a JPEG image using simplejpeg library, before sending onto a server. Therefore, WebGear API provides various attributes to have full control over JPEG encoding performance and quality, which are as follows:
- jpeg_compression_quality: (int/float) This attribute controls the JPEG quantization factor. Its value varies from 10 to 100 (the higher is the better quality but performance will be lower). Its default value is 90. Its usage is as follows:
```
# activate jpeg encoding and set quality 95%
options = {"jpeg_compression_quality": 95}
```
- jpeg_compression_fastdct: (bool) This attribute if True, WebGear API uses fastest DCT method that speeds up decoding by 4-5% for a minor loss in quality. Its default value is also True, and its usage is as follows:
```
# activate jpeg encoding and enable fast dct
options = {"jpeg_compression_fastdct": True}
```
- jpeg_compression_fastupsample: (bool) This attribute if True, WebGear API use fastest color upsampling method. Its default value is False, and its usage is as follows:
```
# activate jpeg encoding and enable fast upsampling
options = {"jpeg_compression_fastupsample": True}
```

Bare-Minimum Usage with Performance Enhancements¶

Let's implement our Bare-Minimum usage example with these Performance Enhancing Attributes ➶ for speeding up the output.

Running Programmatically ¶

You can access and run WebGear VideoStreamer Server programmatically in your python script in just a few lines of code, as follows:

For accessing WebGear 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 ➶

# import required libraries
import uvicorn
from vidgear.gears.asyncio import WebGear

# various performance tweaks
options = {
    "frame_size_reduction": 40,
    "jpeg_compression_quality": 80,
    "jpeg_compression_fastdct": True,
    "jpeg_compression_fastupsample": False,
}

# initialize WebGear app
web = WebGear(source="foo.mp4", logging=True, **options)

# run this app on Uvicorn server at address http://localhost:8000/
uvicorn.run(web(), host="localhost", port=8000)

# close app safely
web.shutdown()

which can be accessed on any browser on your machine at http://localhost:8000/.

Running from Terminal ¶

You can also access and run WebGear Server directly from the terminal commandline. The following command will run a WebGear VideoStreamer server at http://localhost:8000/:

Make sure your PYTHON_PATH is set to python 3.7+ versions only.

If you're using --options/-op flag, then kindly wrap your dictionary value in single '' quotes.

python3 -m vidgear.gears.asyncio --mode mjpeg --source test.avi --logging --options '{"frame_size_reduction": 50, "jpeg_compression_quality": 80, "jpeg_compression_fastdct": True, "jpeg_compression_fastupsample": False}'

which can also be accessed on any browser on the network at http://localhost:8000/.

Advanced Usage from Terminal

You can run python3 -m vidgear.gears.asyncio -h help command to see all the advanced settings, as follows:

usage: python -m vidgear.gears.asyncio [-h] [-m MODE] [-s SOURCE] [-a API] [-S] [-b BACKEND]
                [-cs COLORSPACE] [-cn CAMERA_NUM] [-r RESOLUTION] [-f FRAMERATE]
                [-yt] [-sd SOURCE_DEMUXER] [-ff FRAME_FORMAT] [-cf CUSTOM_FFMPEG]
                [-td TIME_DELAY] [-ip IPADDRESS] [-pt PORT] [-l] [-op OPTIONS]

Runs WebGear/WebGear_RTC Video Server through terminal.

options:
-h, --help            show this help message and exit
-m {mjpeg,webrtc}, --mode {mjpeg,webrtc}
                        Whether to use "MJPEG" or "WebRTC" mode for streaming.
-a {camgear,pigear,ffgear}, --api {camgear,pigear,ffgear}
                        Selects the capture backend for VideoGear. Choices: camgear, pigear, ffgear. Default: camgear.
-ep, --enablePiCamera
                        [DEPRECATED] Use `--api pigear` instead. Sets the flag to access PiGear API.
-S, --stabilize       Enables real-time video stabilization.
-s SOURCE, --source SOURCE
                        Path to input source (device index, filepath, URL, or glob pattern).
-yt, --stream_mode    Enables YouTube/yt_dlp Stream Mode in CamGear/FFGear API.
-b BACKEND, --backend BACKEND
                        Sets the backend of the video source in CamGear API (e.g. cv2.CAP_DSHOW).
-sd SOURCE_DEMUXER, --source_demuxer SOURCE_DEMUXER
                        [FFGear only] FFmpeg demuxer for the source (e.g. "v4l2", "dshow"). Default: auto-detect.
-ff FRAME_FORMAT, --frame_format FRAME_FORMAT
                        [FFGear only] Pixel format for decoded frames (e.g. "bgr24", "gray"). Default: bgr24.
-cf CUSTOM_FFMPEG, --custom_ffmpeg CUSTOM_FFMPEG
                        [FFGear only] Path to a custom FFmpeg executable. Default: use PATH.
-cn CAMERA_NUM, --camera_num CAMERA_NUM
                        [PiGear only] Sets the camera module index.
-r RESOLUTION, --resolution RESOLUTION
                        [PiGear only] Sets the resolution (width,height) for the camera module.
-f FRAMERATE, --framerate FRAMERATE
                        [PiGear only] Sets the framerate for the camera module.
-cs COLORSPACE, --colorspace COLORSPACE
                        Sets the colorspace of the output video stream.
-td TIME_DELAY, --time_delay TIME_DELAY
                        Sets the time delay (in seconds) before start reading the frames.
-ip IPADDRESS, --ipaddress IPADDRESS
                        Uvicorn binds the socket to this ipaddress.
-pt PORT, --port PORT
                        Uvicorn binds the socket to this port.
-l, --logging         Enables/disables error logging, essential for debugging.
-op OPTIONS, --options OPTIONS
                        Sets the parameters supported by APIs (whichever being accessed) to the input videostream. Wrap your dict value in
                        single or double quotes.