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 --source test.avi --logging True --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] [-ep ENABLEPICAMERA] [-S STABILIZE]
            [-cn CAMERA_NUM] [-yt stream_mode] [-b BACKEND] [-cs COLORSPACE]
            [-r RESOLUTION] [-f FRAMERATE] [-td TIME_DELAY]
            [-ip IPADDRESS] [-pt PORT] [-l LOGGING] [-op OPTIONS]

Runs WebGear/WebGear_RTC Video Server through terminal.

optional arguments:
  -h, --help            show this help message and exit
  -m {mjpeg,webrtc}, --mode {mjpeg,webrtc}
                        Whether to use "MJPEG" or "WebRTC" mode for streaming.
  -s SOURCE, --source SOURCE
                        Path to input source for CamGear API.
  -ep ENABLEPICAMERA, --enablePiCamera ENABLEPICAMERA
                        Sets the flag to access PiGear(if True) or otherwise
                        CamGear API respectively.
  -S STABILIZE, --stabilize STABILIZE
                        Enables/disables real-time video stabilization.
  -cn CAMERA_NUM, --camera_num CAMERA_NUM
                        Sets the camera module index that will be used by
                        PiGear API.
  -yt STREAM_MODE, --stream_mode STREAM_MODE
                        Enables YouTube Mode in CamGear API.
  -b BACKEND, --backend BACKEND
                        Sets the backend of the video source in CamGear API.
  -cs COLORSPACE, --colorspace COLORSPACE
                        Sets the colorspace of the output video stream.
  -r RESOLUTION, --resolution RESOLUTION
                        Sets the resolution (width,height) for camera module
                        in PiGear API.
  -f FRAMERATE, --framerate FRAMERATE
                        Sets the framerate for camera module in PiGear API.
  -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, --logging 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, But make sure to
                        wrap your dict value in single or double quotes.