Skip to content

WebGear API

WebGear in action!
WebGear API's Video Server running at http://localhost:8000/ address.

Overview

WebGear is a powerful ASGI Video-Broadcaster API ideal for transmitting Motion-JPEG-frames from a single source to multiple recipients via the browser.

WebGear API works on Starlette's ASGI application and provides a highly extensible and flexible async wrapper around its complete framework. WebGear can flexibly interact with Starlette's ecosystem of shared middleware, mountable applications, Response classes, Routing tables, Static Files, Templating engine(with Jinja2), etc.

WebGear API uses an intraframe-only compression scheme under the hood where the sequence of video-frames are first encoded as JPEG-DIB (JPEG with Device-Independent Bit compression) and then streamed over HTTP using Starlette's Multipart Streaming Response and a Uvicorn ASGI Server. This method imposes lower processing and memory requirements, but the quality is not the best, since JPEG compression is not very efficient for motion video.

In layman's terms, WebGear acts as a powerful Video Broadcaster that transmits live video-frames to any web-browser in the network. Additionally, WebGear API also provides internal wrapper around VideoGear, which itself provides internal access to both CamGear and PiGear APIs, thereby granting it exclusive power for transferring frames incoming from any source to the network.

Data-Files Auto-Generation WorkFlow for WebGear

Disabling Auto-Generation process in WebGear

Starting with vidgear v0.3.0, you can now completely disable Auto-Generation process in WebGear API using skip_generate_webdata optional boolean attribute. When {skip_generate_webdata:True}, no default data files will be downloaded or validated during initialization.

Only /video route is available when {skip_generate_webdata:True} in WebGear API. All other default routes will be JSONResponses with 404/500 status codes.

Customizing default video endpoint path

Starting with vidgear v0.3.1, you can change default /video video endpoint path to any alphanumeric string value, using custom_video_endpoint optional string attribute. For example:

Only alphanumeric string with no space in between are allowed as custom_video_endpoint value. Any other value will be discarded.

WebGear's Default Theme which expects only default /video video endpoint path, will fail to work, if it is customized to any other value using this custom_video_endpoint attribute.

# custom alphanumeric video endpoint string
options = {"custom_video_endpoint": "xyz"}

# initialize WebGear app
web = WebGear(source="foo.mp4", logging=True, **options)
Hence, default video endpoint will now be available at /xyz path.

On initializing WebGear API, it automatically checks for three critical data files(i.e index.html, 404.html & 500.html) inside the templates folder of the webgear directory at the default location which gives rise to the following two possible scenario:

  • If data-files found: it will proceed normally for instantiating the Starlette application.
  • If data-files not found: it will trigger the Auto-Generation process

Default Location

  • A default location is the path of the directory where data files/folders are downloaded/generated/saved.
  • By default, the .vidgear the folder at the home directory of your machine (for e.g /home/foo/.vidgear on Linux ) serves as the default location.
  • But you can also use WebGear's custom_data_location dictionary attribute to change/alter default location path to somewhere else.

Identifying Default location

You can set logging=True during initialization, for easily identifying the selected default location, which will be something like this on a Linux machine:

WebGear :: DEBUG :: `/home/foo/.vidgear` is the default location for saving WebGear data-files.

Auto-Generation process

Info

  • You can also force trigger the Auto-generation process to overwrite existing data-files using overwrite_default_files dictionary attribute. Remember, only downloaded default data files(given above) will be overwritten in this process but any other file/folder will NOT be affected.

  • It is advised to enable logging(logging=True) on the first run for easily identifying any runtime errors.

  • On triggering this process, WebGear API creates webgear directory, and templates and static folders inside along with js, css, img sub-folders at the assigned default location.
  • Thereby at this default location, the necessary default data files will be downloaded from a dedicated Github Server inside respective folders in the following order:

    .vidgear
    └── webgear
        ├── static
        │   ├── css
        │   │   └── custom.css
        │   ├── img
        │   │   └── favicon-32x32.png
        │   └── js
        │       └── custom.js
        └── templates
            ├── 404.html
            ├── 500.html
            ├── base.html
            └── index.html
    6 directories, 7 files
    
  • Finally these downloaded files thereby are verified for errors and API proceeds for instantiating the Starlette application normally.

WebGear's Default Template

New in v0.2.1

New Standalone WebGear's Default Theme was added in v0.2.1.

The WebGear API by default uses simple & elegant WebGear's Default Theme which looks like something as follows:

Index.html

Can be accessed by visiting WebGear app server, running at http://localhost:8000/:

WebGear default Index page

404.html

Appears when respective URL is not found, for example http://localhost:8000/ok:

WebGear default 404 page

500.html

Appears when an API Error is encountered:

If logging is enabled and an error occurs, then instead of displaying this 500 handler, WebGear will respond with a traceback response.

WebGear default 500 page

Usage Examples

After going through WebGear Usage Examples, Checkout more bonus examples here ➶

Parameters

References

FAQs