WebGear API¶
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)
/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:
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, andtemplates
andstatic
folders inside along withjs
,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/:
404.html¶
Appears when respective URL is not found, for example http://localhost:8000/ok:
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.
Usage Examples¶
After going through WebGear Usage Examples, Checkout more bonus examples here ➶
Parameters¶
References¶
FAQs¶