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).

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:

  DASHHLS

  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.

  DASHHLS

  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:

  DASHHLS

  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).

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.

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:

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 framerate¹ 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:

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:

# 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)