Skip to content

StreamGear API Parameters

output

This parameter sets the valid filename/path for storing the StreamGear assets (Manifest file (such as MPD in-case of DASH) or a Master Playlist (such as M3U8 in-case of Apple HLS) & Transcoded sequence of segments).

StreamGear API will throw ValueError if output provided is empty or invalid.

Make sure to provide valid filename with valid file-extension for selected format value (such as .mpd in case of MPEG-DASH and .m3u8 in case of APPLE-HLS), otherwise StreamGear will throw AssertionError.

StreamGear generated sequence of multiple chunks/segments are also stored in the same directory.

You can easily delete all previous assets at output location, by using -clear_prev_assets attribute of stream_params dictionary parameter.

Data-Type: String

Usage:

Its valid input can be one of the following:

  • Path to directory: Valid path of the directory. In this case, StreamGear API will automatically assign a unique filename for Manifest file. This can be defined as follows:

    streamer = StreamGear(output = "/home/foo/foo1") # Define streamer with manifest saving directory path 
    
    streamer = StreamGear(output = "/home/foo/foo1", format="hls") # Define streamer with playlist saving directory path 
    
  • Filename (with/without path): Valid filename(with valid extension) of the output Manifest file. In case filename is provided without path, then current working directory will be used.

    streamer = StreamGear(output = "output_foo.mpd") # Define streamer with manifest file name
    
    streamer = StreamGear(output = "output_foo.m3u8", format="hls") # Define streamer with playlist file name
    
  • URL: Valid URL of a network stream with a protocol supported by installed FFmpeg (verify with command ffmpeg -protocols) only. This is useful for directly storing assets to a network server. For example, you can use a http protocol URL as follows:

    streamer = StreamGear(output = "http://195.167.1.101/live/test.mpd") #Define streamer 
    
    streamer = StreamGear(output = "http://195.167.1.101/live/test.m3u8", format="hls") #Define streamer 
    

 

format

This parameter select the adaptive HTTP streaming formats. For now, the supported format are: dash (i.e MPEG-DASH) and hls (i.e Apple HLS).

Any invalid value to format parameter will result in ValueError!

Make sure to provide valid filename with valid file-extension in output for selected format value (such as .mpd in case of MPEG-DASH and .m3u8 in case of APPLE-HLS), otherwise StreamGear will throw AssertionError.

Data-Type: String

Default Value: Its default value is dash

Usage:

StreamGear(output = "output_foo.mpd", format="dash")
StreamGear(output = "output_foo.m3u8", format="hls")

 

custom_ffmpeg

This parameter assigns the custom path/directory where the custom/downloaded FFmpeg executables are located.

Behavior on Windows

If a custom FFmpeg executable's path | directory is not provided through custom_ffmpeg parameter on Windows machine, then StreamGear API will automatically attempt to download and extract suitable Static FFmpeg binaries at suitable location on your windows machine. More information can be found here ➶.

Data-Type: String

Default Value: Its default value is None.

Usage:

# If ffmpeg executables are located at "/foo/foo1/ffmpeg"
StreamGear(output = 'output_foo.mpd', custom_ffmpeg="/foo/foo1/ffmpeg")

 

stream_params

This parameter allows us to exploit almost all FFmpeg supported parameters effortlessly and flexibly change its internal settings for transcoding and seamlessly generating high-quality streams. All supported parameters can formatting as attributes for this dictionary parameter:

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

Data-Type: Dictionary

Default Value: Its default value is {}.

Supported Parameters

A. Exclusive Parameters

StreamGear API provides some exclusive internal parameters to easily generate Streaming Assets and effortlessly tweak its internal properties. These parameters are discussed below:

  • -streams (list of dicts): This important attribute makes it simple and pretty straight-forward to define additional multiple streams as list of dictionaries of different quality levels (i.e. different bitrates or spatial resolutions) for streaming.

    Important -streams attribute facts

    • On top of these additional streams, StreamGear by default, generates a primary stream of same resolution and framerate1 as the input Video, at the index 0.
    • 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 using -bpps and -resolution values.
    • If you define both -video_bitrate and -framerate values at the same time, StreamGear will discard the -framerate value automatically.

    To construct the additional stream dictionaries, you'll will need following sub-attributes:

    • -resolution (string): It is compulsory to define the required resolution/dimension/size for the stream, otherwise given stream will be rejected. Its value can be a "{width}x{height}" as follows:

      "-streams" = [{"-resolution": "1280x720"}] # to produce a 1280x720 resolution/scale 
      
    • -video_bitrate (string): It is an optional (can be ignored if -framerate parameter is defined) sub-attribute that generally determines the bandwidth and quality of stream, i.e. the higher the bitrate, the better the quality and the larger will be bandwidth and more will be strain on network. It value is generally in kbps (kilobits per second) for OBS (Open Broadcasting Softwares). You can easily define this attribute as follows:

      "-streams" : [{"-resolution": "1280x720", "-video_bitrate": "2000k"}] # to produce a 1280x720 resolution and 2000kbps bitrate stream
      
    • -framerate (float/int): It is another optional (can be ignored if -video_bitrate parameter is defined) sub-attribute that defines the assumed framerate for the stream. It's value can be float/integer as follows:

      "-streams" : [{"-resolution": "1280x720", "-framerate": "60.0"}] # to produce a 1280x720 resolution and 60fps framerate stream
      

    Usage: You can easily define any number of streams using -streams attribute as follows:

    Usage example can be found here ➶

    stream_params = 
        {"-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 
            ]}
    

  • -video_source (string): This attribute takes valid Video path as input and activates Single-Source Mode, for transcoding it into multiple smaller chunks/segments for streaming after successful validation. Its value be one of the following:

    Usage example can be found here ➶

    • Video Filename: Valid path to Video file as follows:
      stream_params = {"-video_source": "/home/foo/foo1.mp4"} # set input video source: /home/foo/foo1.mp4
      
    • Video URL: Valid URL of a network video stream as follows:

      Make sure given Video URL has protocol that is supported by installed FFmpeg. (verify with ffmpeg -protocols terminal command)

      stream_params = {"-video_source": "http://livefeed.com:5050"} # set input video source: http://livefeed.com:5050
      

  • -audio (string/list): This attribute takes external custom audio path (as string) or audio device name followed by suitable demuxer (as list) as audio source input for all StreamGear streams. Its value be one of the following:

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

    • Audio Filename (string): Valid path to Audio file as follows:

      stream_params = {"-audio": "/home/foo/foo1.aac"} # set input audio source: /home/foo/foo1.aac
      
      !!! tip "Usage example can be found here ➶"

    • Audio URL (string): Valid URL of a network audio stream as follows:

      Make sure given Video URL has protocol that is supported by installed FFmpeg. (verify with ffmpeg -protocols terminal command)

      stream_params = {"-audio": "https://exampleaudio.org/example-160.mp3"} # set input audio source: https://exampleaudio.org/example-160.mp3
      
    • Device name and Demuxer (list): Valid audio device name followed by suitable demuxer as follows:

      stream_params = {"-audio": "https://exampleaudio.org/example-160.mp3"} # set input audio source: https://exampleaudio.org/example-160.mp3
      

      Usage example can be found here ➶

  • -livestream (bool): (optional) specifies whether to enable Livestream Support(chunks will contain information for new frames only) for the selected mode, or not. You can easily set it to True to enable this feature, and default value is False. It can be used as follows:

    Use window_size & extra_window_size FFmpeg parameters for controlling number of frames to be kept in New Chunks.

    stream_params = {"-livestream": True} # enable livestreaming
    

  • -input_framerate (float/int) : (optional) specifies the assumed input video source framerate, and only works in Real-time Frames Mode. It can be used as follows:

    Usage example can be found here ➶

    stream_params = {"-input_framerate": 60.0} # set input video source framerate to 60fps
    

  • -bpp (float/int): (optional) This attribute controls constant Bits-Per-Pixel(BPP) value, which is kind of a constant value to ensure good quality of high motion scenes ,and thereby used in calculating desired video-bitrate for streams. Higher the BPP, better will be motion quality. Its default value is 0.1. Going over 0.1helps to fill gaps between current bitrate and upload limit/ingest cap. Its value can be anything above 0.001, can be used as follows:

    Important BPP tips for streaming

    • -bpp a sensitive value, try 0.001, and then make increments in 0.0001 to fine tune
    • If your desired resolution/fps/audio combination is below maximum service bitrate, raise BPP to match it for extra quality.
    • It is generally better to lower resolution (and/or fps) and raise BPP than raise resolution and loose on BPP.
    stream_params = {"-bpp": 0.05} # sets BPP to 0.05
    

  • -gop (float/int) : (optional) specifies the number of frames between two I-frames for accurate GOP length. By increasing the length of the GOP, there will be fewer I-frames per time frame, which minimizes bandwidth consumption. So, for example, with extremely complex subjects such as water sports or action mode, you’ll want to use a shorter GOP length such as 15 or below that results in excellent video quality. For more static video such as talking heads, then much longer GOP sizes are not only sufficient but also more efficient. It can be used as follows:

    The larger the GOP size, the more efficient the compression and the less bandwidth you will need

    By default, StreamGear automatically sets recommended fixed GOP value (i.e. every two seconds) w.r.t input framerate and selected encoder.

    stream_params = {"-gop": 70} # set GOP length to 70
    

  • -clones (list): (optional) sets the special FFmpeg parameters that are repeated more than once in the command (For more info., see this issue) as list only. Usage is as follows:

    stream_params = {"-clones": ['-map', '0:v:0', '-map', '1:a?']}
    

  • -ffmpeg_download_path (string): (optional) sets the custom directory for downloading FFmpeg Static Binaries in Compression Mode, during the Auto-Installation on Windows Machines Only. If this parameter is not altered, then these binaries will auto-save to the default temporary directory (for e.g. C:/User/temp) on your windows machine. It can be used as follows:

    stream_params = {"-ffmpeg_download_path": "C:/User/foo/foo1"} # will be saved to "C:/User/foo/foo1"
    

  • -clear_prev_assets (bool): (optional) specify whether to force-delete any previous copies of StreamGear Assets (i.e. Manifest files(.mpd) & streaming chunks(.m4s) etc.) present at path specified by output parameter. You can easily set it to True to enable this feature, and default value is False. It can be used as follows:

    In Single-Source Mode, additional segments (such as .webm, .mp4 chunks) are also cleared automatically.

    stream_params = {"-clear_prev_assets": True} # will delete all previous assets
    

B. FFmpeg Parameters

Almost all FFmpeg parameter can be passed as dictionary attributes in stream_params. For example, for using libx264 encoder to produce a lossless output video, we can pass required FFmpeg parameters as dictionary attributes, as follows:

Kindly check H.264 docs ➶ and other FFmpeg Docs ➶ for more information on these parameters

All ffmpeg parameters are case-sensitive. Remember to double check every parameter if any error occurs.

In addition to these parameters, almost any FFmpeg parameter (supported by installed FFmpeg) is also supported. But make sure to read FFmpeg Docs carefully first.

stream_params = {"-vcodec":"libx264", "-crf": 0, "-preset": "fast", "-tune": "zerolatency"} 

Supported Encoders and Decoders

All the encoders and decoders that are compiled with FFmpeg in use, are supported by WriteGear API. You can easily check the compiled encoders by running following command in your terminal:

Similarily, supported demuxers and filters depends upons compiled FFmpeg in use.

# for checking encoder
ffmpeg -encoders           # use `ffmpeg.exe -encoders` on windows
# for checking decoders
ffmpeg -decoders           # use `ffmpeg.exe -decoders` on windows

 

logging

This parameter enables logging (if True), essential for debugging.

Data-Type: Boolean

Default Value: Its default value is False.

Usage:

StreamGear(logging=True)

 


  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: November 1, 2021