Skip to content

StreamGear API Usage Examples: Single-Source Mode

Important Information

  • 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 executables on your system.

  • By default, StreamGear generates a primary stream of same resolution and framerate1 as the input video (at the index 0).

  • Always use terminate() function at the very end of the main code.

After going through following Usage Examples, Checkout more of its advanced configurations here ➶

Bare-Minimum Usage

Following is the bare-minimum code you need to get started with StreamGear API in Single-Source Mode:

If input video-source (i.e. -video_source) contains any audio stream/channel, then it automatically gets mapped to all generated streams without any extra efforts.

# import required libraries
from vidgear.gears import StreamGear

# activate Single-Source Mode with valid video input
stream_params = {"-video_source": "foo.mp4"}
# describe a suitable manifest-file location/name and assign params
streamer = StreamGear(output="dash_out.mpd", **stream_params)
# trancode source
streamer.transcode_source()
# terminate
streamer.terminate()
# import required libraries
from vidgear.gears import StreamGear

# activate Single-Source Mode with valid video input
stream_params = {"-video_source": "foo.mp4"}
# describe a suitable master playlist location/name and assign params
streamer = StreamGear(output="hls_out.m3u8", format = "hls", **stream_params)
# trancode source
streamer.transcode_source()
# terminate
streamer.terminate()

After running this bare-minimum example, StreamGear will produce a Manifest file (dash.mpd) with streamable chunks that contains information about a Primary Stream of same resolution and framerate as the input.

Bare-Minimum Usage with Live-Streaming

You can easily activate Low-latency Livestreaming in Single-Source Mode, where chunks will contain information for few new frames only and forgets all previous ones), using exclusive -livestream attribute of stream_params dictionary parameter as follows:

If input video-source (i.e. -video_source) contains any audio stream/channel, then it automatically gets mapped to all generated streams without any extra efforts.

Chunk size in DASH

Use -window_size & -extra_window_size FFmpeg parameters for controlling number of frames to be kept in Chunks in DASH stream. Less these value, less will be latency.

After every few chunks (equal to the sum of -window_size & -extra_window_size values), all chunks will be overwritten in Live-Streaming. Thereby, since newer chunks in manifest will contain NO information of any older ones, and therefore resultant DASH stream will play only the most recent frames.

# import required libraries
from vidgear.gears import StreamGear

# activate Single-Source Mode with valid video input and enable livestreaming
stream_params = {"-video_source": 0, "-livestream": True}
# describe a suitable manifest-file location/name and assign params
streamer = StreamGear(output="dash_out.mpd", **stream_params)
# trancode source
streamer.transcode_source()
# terminate
streamer.terminate()

Chunk size in HLS

Use -hls_init_time & -hls_time FFmpeg parameters for controlling number of frames to be kept in Chunks in HLS stream. Less these value, less will be latency.

After every few chunks (equal to the sum of -hls_init_time & -hls_time values), all chunks will be overwritten in Live-Streaming. Thereby, since newer chunks in playlist will contain NO information of any older ones, and therefore resultant HLS stream will play only the most recent frames.

# import required libraries
from vidgear.gears import StreamGear

# activate Single-Source Mode with valid video input and enable livestreaming
stream_params = {"-video_source": 0, "-livestream": True}
# describe a suitable master playlist location/name and assign params
streamer = StreamGear(output="hls_out.m3u8", format = "hls", **stream_params)
# trancode source
streamer.transcode_source()
# terminate
streamer.terminate()

Usage with Additional Streams

In addition to Primary Stream, you can easily generate any number of additional Secondary Streams of variable bitrates or spatial resolutions, using exclusive -streams attribute of stream_params dictionary parameter. You just need to add each resolution and bitrate/framerate as list of dictionaries to this attribute, and rest is done automatically.

A more detailed information on -streams attribute can be found here ➶

The complete example is as follows:

If input video-source contains any audio stream/channel, then it automatically gets assigned to all generated streams without any extra efforts.

Important -streams attribute Information
  • On top of these additional streams, StreamGear by default, generates a primary stream of same resolution and framerate as the input, at the index 0.
  • ⚠ Make sure your System/Machine/Server/Network is able to handle these additional streams, discretion is advised!
  • You MUST need to define -resolution value for your stream, otherwise stream will be discarded!
  • You only need either of -video_bitrate or -framerate for defining a valid stream. Since with -framerate value defined, video-bitrate is calculated automatically.
  • If you define both -video_bitrate and -framerate values at the same time, StreamGear will discard the -framerate value automatically.

Always use -stream attribute to define additional streams safely, any duplicate or incorrect definition can break things!

# import required libraries
from vidgear.gears import StreamGear

# activate Single-Source Mode and also define various streams
stream_params = {
    "-video_source": "foo.mp4",
    "-streams": [
        {"-resolution": "1920x1080", "-video_bitrate": "4000k"},  # Stream1: 1920x1080 at 4000kbs bitrate
        {"-resolution": "1280x720", "-framerate": 30.0},  # Stream2: 1280x720 at 30fps framerate
        {"-resolution": "640x360", "-framerate": 60.0},  # Stream3: 640x360 at 60fps framerate
        {"-resolution": "320x240", "-video_bitrate": "500k"},  # Stream3: 320x240 at 500kbs bitrate
    ],
}
# describe a suitable manifest-file location/name and assign params
streamer = StreamGear(output="dash_out.mpd", **stream_params)
# trancode source
streamer.transcode_source()
# terminate
streamer.terminate()
# import required libraries
from vidgear.gears import StreamGear

# activate Single-Source Mode and also define various streams
stream_params = {
    "-video_source": "foo.mp4",
    "-streams": [
        {"-resolution": "1920x1080", "-video_bitrate": "4000k"},  # Stream1: 1920x1080 at 4000kbs bitrate
        {"-resolution": "1280x720", "-framerate": 30.0},  # Stream2: 1280x720 at 30fps framerate
        {"-resolution": "640x360", "-framerate": 60.0},  # Stream3: 640x360 at 60fps framerate
        {"-resolution": "320x240", "-video_bitrate": "500k"},  # Stream3: 320x240 at 500kbs bitrate
    ],
}
# describe a suitable master playlist location/name and assign params
streamer = StreamGear(output="hls_out.m3u8", format = "hls", **stream_params)
# trancode source
streamer.transcode_source()
# terminate
streamer.terminate()

Usage with Custom Audio

By default, if input video-source (i.e. -video_source) contains any audio, then it gets automatically mapped to all generated streams. But, if you want to add any custom audio, you can easily do it by using exclusive -audio attribute of stream_params dictionary parameter. You just need to input the path of your audio file to this attribute as string, and the API will automatically validate as well as map it to all generated streams.

The complete example is as follows:

Make sure this -audio audio-source it compatible with provided video-source, otherwise you could encounter multiple errors or no output at all.

You can also assign a valid Audio URL as input, rather than filepath. More details can be found here ➶

# import required libraries
from vidgear.gears import StreamGear

# activate Single-Source Mode and various streams, along with custom audio
stream_params = {
    "-video_source": "foo.mp4",
    "-streams": [
        {"-resolution": "1920x1080", "-video_bitrate": "4000k"},  # Stream1: 1920x1080 at 4000kbs bitrate
        {"-resolution": "1280x720", "-framerate": 30.0},  # Stream2: 1280x720 at 30fps
        {"-resolution": "640x360", "-framerate": 60.0},  # Stream3: 640x360 at 60fps
    ],
    "-audio": "/home/foo/foo1.aac" # assigns input audio-source: "/home/foo/foo1.aac"
}
# describe a suitable manifest-file location/name and assign params
streamer = StreamGear(output="dash_out.mpd", **stream_params)
# trancode source
streamer.transcode_source()
# terminate
streamer.terminate()
# import required libraries
from vidgear.gears import StreamGear

# activate Single-Source Mode and various streams, along with custom audio
stream_params = {
    "-video_source": "foo.mp4",
    "-streams": [
        {"-resolution": "1920x1080", "-video_bitrate": "4000k"},  # Stream1: 1920x1080 at 4000kbs bitrate
        {"-resolution": "1280x720", "-framerate": 30.0},  # Stream2: 1280x720 at 30fps
        {"-resolution": "640x360", "-framerate": 60.0},  # Stream3: 640x360 at 60fps
    ],
    "-audio": "/home/foo/foo1.aac" # assigns input audio-source: "/home/foo/foo1.aac"
}
# describe a suitable master playlist location/name and assign params
streamer = StreamGear(output="hls_out.m3u8", format = "hls", **stream_params)
# trancode source
streamer.transcode_source()
# terminate
streamer.terminate()

Usage with Variable FFmpeg Parameters

For seamlessly generating these streaming assets, StreamGear provides a highly extensible and flexible wrapper around FFmpeg and access to almost all of its parameter. Thereby, you can access almost any parameter available with FFmpeg itself as dictionary attributes in stream_params dictionary parameter, and use it to manipulate transcoding as you like.

For this example, let us use our own H.265/HEVC video and AAC audio encoder, and set custom audio bitrate, and various other optimizations:

This example is just conveying the idea on how to use FFmpeg's encoders/parameters with StreamGear API. You can use any FFmpeg parameter in the similar manner.

Kindly read FFmpeg Docs carefully, before passing any FFmpeg values to stream_params parameter. Wrong values may result in undesired errors or no output at all.

Always use -streams attribute to define additional streams safely, any duplicate or incorrect stream definition can break things!

# import required libraries
from vidgear.gears import StreamGear

# activate Single-Source Mode and various other parameters
stream_params = {
    "-video_source": "foo.mp4", # define Video-Source
    "-vcodec": "libx265", # assigns H.265/HEVC video encoder
    "-x265-params": "lossless=1", # enables Lossless encoding
    "-crf": 25, # Constant Rate Factor: 25
    "-bpp": "0.15", # Bits-Per-Pixel(BPP), an Internal StreamGear parameter to ensure good quality of high motion scenes
    "-streams": [
        {"-resolution": "1280x720", "-video_bitrate": "4000k"}, # Stream1: 1280x720 at 4000kbs bitrate
        {"-resolution": "640x360", "-framerate": 60.0},  # Stream2: 640x360 at 60fps
    ],
    "-audio": "/home/foo/foo1.aac",  # define input audio-source: "/home/foo/foo1.aac",
    "-acodec": "libfdk_aac", # assign lossless AAC audio encoder
    "-vbr": 4, # Variable Bit Rate: `4`
}

# describe a suitable manifest-file location/name and assign params
streamer = StreamGear(output="dash_out.mpd", logging=True, **stream_params)
# trancode source
streamer.transcode_source()
# terminate
streamer.terminate()
# import required libraries
from vidgear.gears import StreamGear

# activate Single-Source Mode and various other parameters
stream_params = {
    "-video_source": "foo.mp4", # define Video-Source
    "-vcodec": "libx265", # assigns H.265/HEVC video encoder
    "-x265-params": "lossless=1", # enables Lossless encoding
    "-crf": 25, # Constant Rate Factor: 25
    "-bpp": "0.15", # Bits-Per-Pixel(BPP), an Internal StreamGear parameter to ensure good quality of high motion scenes
    "-streams": [
        {"-resolution": "1280x720", "-video_bitrate": "4000k"}, # Stream1: 1280x720 at 4000kbs bitrate
        {"-resolution": "640x360", "-framerate": 60.0},  # Stream2: 640x360 at 60fps
    ],
    "-audio": "/home/foo/foo1.aac",  # define input audio-source: "/home/foo/foo1.aac",
    "-acodec": "libfdk_aac", # assign lossless AAC audio encoder
    "-vbr": 4, # Variable Bit Rate: `4`
}

# describe a suitable master playlist file location/name and assign params
streamer = StreamGear(output="hls_out.m3u8", format = "hls", logging=True, **stream_params)
# trancode source
streamer.transcode_source()
# terminate
streamer.terminate()

 


  1. 💡 In Real-time Frames Mode, the Primary Stream's framerate defaults to -input_framerate attribute value, if defined, else it will be 25fps. 


Last update: July 5, 2023