Skip to content

StreamGear API⚓

StreamGear Flow Diagram
StreamGear API's generalized workflow


StreamGear automates transcoding workflow for generating Ultra-Low Latency, High-Quality, Dynamic & Adaptive Streaming Formats (such as MPEG-DASH and Apple HLS) in just few lines of python code.

StreamGear provides a standalone, highly extensible, and flexible wrapper around FFmpeg multimedia framework for generating chunked-encoded media segments of the content.

SteamGear is an out-of-the-box solution for transcoding source videos/audio files & real-time video frames and breaking them into a sequence of multiple smaller chunks/segments of suitable lengths. These segments make it possible to stream videos at different quality levels (different bitrates or spatial resolutions) and can be switched in the middle of a video from one quality level to another – if bandwidth permits – on a per-segment basis. A user can serve these segments on a web server that makes it easier to download them through HTTP standard-compliant GET requests.

SteamGear currently supports MPEG-DASH (Dynamic Adaptive Streaming over HTTP, ISO/IEC 23009-1) and Apple HLS (HTTP Live Streaming).

SteamGear also creates a Manifest file (such as MPD in-case of DASH) or a Master Playlist (such as M3U8 in-case of Apple HLS) besides segments that describe these segment information (timing, URL, media characteristics like video resolution and adaptive bit rates) and is provided to the client before the streaming session.

For streaming with older traditional protocols such as RTMP, RTSP/RTP you could use WriteGear API instead.

New in v0.2.2

Apple HLS support was added in v0.2.2.


  • StreamGear MUST requires FFmpeg executables for its core operations. Follow these dedicated Platform specific Installation Instructions ➶ for its installation.

  • ⚠ StreamGear API will throw RuntimeError, if it fails to detect valid FFmpeg executable on your system.

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

Useful Links

Mode of Operations⚓

StreamGear primarily operates in following independent modes for transcoding:

Real-time Frames Mode is NOT Live-Streaming.

Rather, you can enable live-streaming in Real-time Frames Mode by using the exclusive -livestream attribute of stream_params dictionary parameter in StreamGear API. Checkout this usage example for more information.

  • Single-Source Mode: In this mode, StreamGear transcodes entire video file (as opposed to frame-by-frame) into a sequence of multiple smaller chunks/segments for streaming. This mode works exceptionally well when you're transcoding long-duration lossless videos(with audio) for streaming that required no interruptions. But on the downside, the provided source cannot be flexibly manipulated or transformed before sending onto FFmpeg Pipeline for processing.

  • Real-time Frames Mode: In this mode, StreamGear directly transcodes frame-by-frame (as opposed to a entire video file), into a sequence of multiple smaller chunks/segments for streaming. This mode works exceptionally well when you desire to flexibility manipulate or transform numpy.ndarray frames in real-time before sending them onto FFmpeg Pipeline for processing. But on the downside, audio has to added manually (as separate source) for streams.


You can import StreamGear API in your program as follows:

from vidgear.gears import StreamGear

Watch Demo⚓

Watch StreamGear transcoded MPEG-DASH Stream:

Powered by clappr & shaka-player

This video assets (Manifest and segments) are hosted on GitHub Repository and served with

Watch StreamGear transcoded APPLE HLS Stream:

Powered by clappr & HlsjsPlayback

This video assets (Playlist and segments) are hosted on GitHub Repository and served with

  • MPV Player: (recommended) MPV is a free, open source, and cross-platform media player. It supports a wide variety of media file formats, audio and video codecs, and subtitle types.
  • VLC Player: VLC is a free and open source cross-platform multimedia player and framework that plays most multimedia files as well as DVDs, Audio CDs, VCDs, and various streaming protocols.
  • Parole: (UNIX only) Parole is a modern simple media player based on the GStreamer framework for Unix and Unix-like operating systems.
  • MP4Client: GPAC provides a highly configurable multimedia player called MP4Client. GPAC itself is an open source multimedia framework developed for research and academic purposes, and used in many media production chains.
  • ffplay: FFplay is a very simple and portable media player using the FFmpeg libraries and the SDL library. It is mostly used as a testbed for the various FFmpeg APIs.

To run Online players locally, you'll need a HTTP server. For creating one yourself, See this well-curated list ➶

  • Clapper: Clappr is an extensible media player for the web.
  • Shaka Player: Shaka Player is an open-source JavaScript library for playing adaptive media in a browser.
  • MediaElementPlayer: MediaElementPlayer is a complete HTML/CSS audio/video player.
  • Native MPEG-Dash + HLS Playback(Chrome Extension): Allow the browser to play HLS (m3u8) or MPEG-Dash (mpd) video urls 'natively' on chrome browsers.




Last update: June 27, 2022