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.

Bare-Minimum Usage with Default MJPEG Mode ¶

By default (streaming_mode="mjpeg"), WebGear only streams JPEG-encoded frames over HTTP at /video endpoint, with no FFmpeg dependency. See Modes of Operation ➶ for its pros and cons.

MJPEG Performance Enhancing Attributes

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

Following JPEG Performance Enhancing Attributes only work in MJPEG Mode (and in H.264 Mode's MJPEG fallback stream), and have no effect on H.264 encoding, except frame_size_reduction.

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 25, and must be lower than 90 (higher values are faster, with max compression and barely visible frame-size) and no lower than 0 (slowest, no compression, Original frame-size). Its recommended value is between 40~60. This attribute downsizes frames in H.264 Mode too. Its usage is as follows:
```
options={"frame_size_reduction": 50} #frame-size will be reduced by 50%
```
Various Encoding Parameters:

In MJPEG Mode, 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}
```

Let's implement our Bare-Minimum usage example in MJPEG Mode with these Performance Enhancing Attributes ➶ for speeding up the output, 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

# MJPEG mode with 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", streaming_mode="mjpeg", 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/.

Bare-Minimum Usage with Low-Latency H.264 Streaming ¶

New in v0.3.7

Low-Latency H.264 Streaming was added in v0.3.7.

When streaming_mode="h264", WebGear encodes frames with FFmpeg (libx264 -preset ultrafast -tune zerolatency) and pushes each complete H.264 frame as a binary WebSocket message at /ws/video. WebGear's Default Theme decodes them with the browser's hardware-accelerated WebCodecs VideoDecoder inside a Web Worker and paints them on a <canvas>, while a telemetry HUD shows live FPS, bandwidth and decode latency.

Higher Server CPU usage

Every connected viewer starts its own FFmpeg encoder process in this mode, so server CPU usage grows with the number of viewers. Use MJPEG Mode for many simultaneous viewers on a low-power server. See Modes of Operation ➶ for more details.

Critical Requirements

Server: FFmpeg with libx264 encoder must be installed (or set via custom_ffmpeg). On Windows , WebGear looks for FFmpeg on startup, and may download a static FFmpeg build if none is found.
Browser: WebCodecs support (Chrome/Edge 94+, Safari 16.4+, Firefox 130+) inside a Secure Context, i.e. https:// or http://localhost.

Automatic MJPEG Fallback

The /video MJPEG endpoint stays available, and the Default Theme automatically falls back to it whenever WebCodecs is unavailable (including plain http:// on non-localhost hosts) or WebSocket stream fails. MJPEG Performance Enhancing Attributes therefore still apply to the fallback stream.

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

# H.264 mode, tweak encoder, and keep frames at original size
options = {
    "h264_options": {"-crf": 23},  # optional encoder tweaks
    "frame_size_reduction": 0,
}

# initialize WebGear app
web = WebGear(source="foo.mp4", streaming_mode="h264", 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 WebCodecs-capable browser on your machine at http://localhost:8000/.