StreamGear API Parameters¶

output¶

This parameter sets the valid filename/path for storing the StreamGear assets, including Manifest file (such as MPD in case of DASH) or a Master Playlist (such as M3U8 in case of Apple HLS) and generated sequence of chunks/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 the Manifest file. This can be defined as follows:

  DASHHLS

  # Define streamer with output directory path for saving DASH assets 
  streamer = StreamGear(output = "/home/foo/bar") 
  

  # Define streamer with output directory path for saving HLS assets
  streamer = StreamGear(output = "/home/foo/bar", format="hls")  
  

• Filename (with/without path): Valid filename (with a valid extension) of the output Manifest or Playlist file. If the filename is provided without a path, the current working directory will be used. This can be defined as follows:

  DASHHLS

  # Define streamer with output manifest filename
  streamer = StreamGear(output = "output_dash.mpd") 
  

  # Define streamer with output playlist filename
  streamer = StreamGear(output = "output_hls.m3u8", format="hls") 
  

• URL: Valid URL of a network stream with a protocol supported by the installed FFmpeg (verify with the ffmpeg -protocols command). This is useful for directly storing assets to a network server. For example, you can use an HTTP protocol URL as follows:

  DASHHLS

  # Define streamer with output manifest URL
  streamer = StreamGear(output = "http://some_dummy_serverip/live/output_dash.mpd") 
  

  # Define streamer with output playlist URL
  streamer = StreamGear(output = "http://some_dummy_serverip/live/output_hls.m3u8", format="hls")
  

format¶

This parameter enables the adaptive HTTP streaming format. This parameter currently supported these formats: dash (i.e MPEG-DASH) and hls (i.e Apple HLS).

Data-Type: String

Default Value: Its default value is dash

Usage:

# Define streamer with DASH format
StreamGear(output = "output_dash.mpd", format="dash")

# Define streamer with HLS format
StreamGear(output = "output_hls.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:

# Define streamer with custom ffmpeg binary
StreamGear(output = 'output_foo.mpd', custom_ffmpeg="C://foo//bar//ffmpeg.exe")

stream_params¶

This parameter allows developers to leverage nearly all FFmpeg options, providing effortless and flexible control over its internal settings for transcoding and generating high-quality streams. All supported parameters can be formatted as attributes within 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 bitrate or spatial resolutions) for streaming.

  Important Information about -streams attribute

  • In addition to the user-defined Secondary Streams, StreamGear automatically generates a Primary Stream (at index 0) with the same resolution as the input frames and at default framerate¹, at the index 0.
  • You MUST define the -resolution value for each stream; otherwise, the stream will be discarded.
  • You only need to define either the -video_bitrate or the -framerate for a valid stream.
    • If you specify the -framerate, the video bitrate will be calculated automatically.
    • If you define both the -video_bitrate and the -framerate, the -framerate will get discard automatically.

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

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

    # produce a 1280x720 resolution/scale stream
    "-streams" = [{"-resolution": "1280x720"}]  
    

  • -video_bitrate (string): This is an optional sub-attribute (can be ignored if the -framerate parameter is defined) that generally determines the bandwidth and quality of the stream. The higher the bitrate, the better the quality and the larger the bandwidth, which can place more strain on the network. Its value is typically in k (kilobits per second) or M (Megabits per second). Define this attribute as follows:

    # produce a 1280x720 resolution and 2000 kbps bitrate stream
    "-streams" : [{"-resolution": "1280x720", "-video_bitrate": "2000k"}] 
    

  • -framerate (float/int): This is another optional sub-attribute (can be ignored if the -video_bitrate parameter is defined) that defines the assumed framerate for the stream. Its value can be a float or integer, as shown below:

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

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

  stream_params = 
      {"-streams": 
          [
          {"-resolution": "1920x1080", "-video_bitrate": "4000k"}, # Stream1: 1920x1080 at 4000kbs bitrate
          {"-resolution": "1280x720", "-framerate": 30}, # Stream2: 1280x720 at 30fps
          {"-resolution": "640x360", "-framerate": 60.0},  # Stream3: 640x360 at 60fps 
          ]
      }
  

  Its usage example can be found here ➶

• -video_source (string): This attribute takes a 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 can be one of the following:

  • Video Filename: Valid path to a video file as follows:

    # set video source as `/home/foo/bar.mp4`
    stream_params = {"-video_source": "/home/foo/bar.mp4"}
    

  • Video URL: Valid URL of a network video stream as follows:

    Ensure the given video URL uses a protocol supported by the installed FFmpeg (verify with ffmpeg -protocols terminal command).

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

  Its usage example can be found here ➶

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

  Ensure the provided -audio audio source is compatible with the input video source. Incompatibility can cause multiple errors or result in no output at all.

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

    # set audio source as `/home/foo/foo1.aac`
    stream_params = {"-audio": "/home/foo/foo1.aac"} 
    

    Its usage examples can be found here ➶ and here ➶

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

    Ensure the given audio URL uses a protocol supported by the installed FFmpeg (verify with ffmpeg -protocols terminal command).

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

  • Device name and Demuxer (list): Valid audio device name followed by a suitable demuxer as follows:

    # Assign appropriate input audio-source device (compatible with video source) and its demuxer
    stream_params = {"-audio":  [
        "-f",
        "dshow",
        "-i",
        "audio=Microphone (USB2.0 Camera)",
    ]} 
    

    Its usage example can be found here ➶

• -livestream (bool): (optional) specifies whether to enable Low-latency Live-Streaming in Real-time Frames Mode only, where chunks will contain information for new frames only and forget previous ones, or not. The default value is False. It can be used as follows:

  The -livestream optional parameter is NOT supported in Single-Source mode.

  stream_params = {"-livestream": True} # enable live-streaming
  

  Its usage example can be found here ➶

• -input_framerate (float/int) : (optional) This parameter specifies the assumed input video source framerate and only works in Real-time Frames Mode. Its default value is 25.0 fps. Its value can be a float or integer, as shown below:

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

  Its usage example can be found here ➶

• -bpp (float/int): (optional) This attribute controls the constant BPP (Bits-Per-Pixel) value, which helps ensure good quality in high motion scenes by determining the desired video bitrate for streams. A higher BPP value improves motion quality. The default value is 0.1. Increasing the BPP value helps fill the gaps between the current bitrate and the upload limit/ingest cap. Its value can be anything above 0.001 and can be used as follows:

  Important points while tweaking BPP

  • BPP is a sensitive value; start with 0.001 and make small increments (0.0001) to fine-tune.
  • If your desired resolution/fps/audio combination is below the 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 to raise resolution and lose BPP.

  # sets BPP to 0.05
  stream_params = {"-bpp": 0.05} 
  

• -gop (float/int) : (optional) This parameter specifies the number of frames between two I-frames for accurate GOP (Group of Pictures) length. Increasing the GOP length reduces the number of I-frames per time frame, minimizing bandwidth consumption. For example, with complex subjects such as water sports or action scenes, a shorter GOP length (e.g., 15 or below) results in excellent video quality. For more static video, such as talking heads, 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 a recommended fixed GOP value (i.e., every two seconds) based on the input framerate and selected encoder.

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

• -clones (list): (optional) This parameter sets special FFmpeg options that need to be repeated more than once in the command. For more information, see this issue. It accepts values as a list only. Usage is as follows:

  # sets special FFmpeg options repeated multiple times
  stream_params = {"-clones": ['-map', '0:v:0', '-map', '1:a?']}
  

• -ffmpeg_download_path (string): (optional) This parameter sets a custom directory for downloading FFmpeg static binaries in Compression Mode during the Auto-Installation step on Windows machines only. If this parameter is not altered, the binaries will be saved to the default temporary directory (e.g., C:/User/foo/temp) on your Windows machine. It can be used as follows:

  # download FFmpeg static binaries to `C:/User/foo/bar`
  stream_params = {"-ffmpeg_download_path": "C:/User/foo/bar"} 
  

• -clear_prev_assets (bool): (optional) This parameter specifies whether to remove/delete all previous copies of StreamGear assets files for selected format (i.e., manifest (mpd) in DASH, playlist (mu38) in HLS, and respective streaming chunks (.ts,.m4s), etc.) present at the path specified by the output parameter. The default value is False. It can be enabled as follows:

  Additional segments (such as .webm, .mp4 chunks) are also removed automatically.

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

• -enable_force_termination (bool): sets a special flag to enable the forced termination of the FFmpeg process, required only if StreamGear is getting frozen when terminated. Its usage is as follows:

  The -enable_force_termination flag can potentially cause unexpected behavior or corrupted output in certain scenarios. It is recommended to use this flag with caution.

  # enables forced termination of FFmpeg process
  stream_params = {"-enable_force_termination": True} 
  

B. FFmpeg Parameters¶

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

# libx264 encoder and its supported parameters
stream_params = {"-vcodec":"libx264", "-crf": 0, "-preset": "fast", "-tune": "zerolatency"} 

Supported Encoders and Decoders¶

All encoders and decoders compiled with the FFmpeg in use are supported by the StreamGear API. You can check the compiled encoders by running the 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)