WebGear API¶

Overview¶

WebGear is a powerful ASGI Video-Broadcaster API ideal for transmitting Motion-JPEG-frames (or low-latency H.264 video) 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 can stream video in two modes: classic Motion-JPEG over HTTP (default), or low-latency H.264 over WebSockets, both served by a Uvicorn ASGI Server. See Modes of Operation ➶ for their differences.

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 CamGear, PiGear, and FFGear APIs, thereby granting it exclusive power for transferring frames incoming from any source to the network.

Modes of Operation¶

WebGear primarily operates in following modes, selectable with its streaming_mode parameter:

Data-Files Auto-Generation WorkFlow for WebGear¶

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

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

On initializing WebGear API, it automatically checks for three critical data files(i.e index.html, 404.html & 500.html) inside the templates folder, and two script files(i.e custom.js & videoFrameDecoderWorker.js) inside the static/js 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.

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

Auto-Generation process¶

• 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
      │       └── videoFrameDecoderWorker.js
      └── templates
          ├── 404.html
          ├── 500.html
          ├── base.html
          └── index.html
  6 directories, 8 files
  

• Finally these downloaded files thereby are verified for errors and API proceeds for instantiating the Starlette application normally.

WebGear's Default Template¶

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/:

404.html¶

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

500.html¶

Appears when an API Error is encountered:

Usage Examples¶

Parameters¶

References¶

FAQs¶