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.
StreamGear API will throw ValueError
if the provided output
is empty or invalid.
Make sure to provide a valid filename with a valid file extension for the selected format
value (such as .mpd
for MPEG-DASH and .m3u8
for APPLE-HLS), otherwise StreamGear will throw AssertionError
.
You can easily delete all previous assets at the output
location by using the -clear_prev_assets
attribute of the 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 the Manifest file. This can be defined as follows:
-
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:
-
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 anHTTP
protocol URL as follows:
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).
Make sure to provide a valid filename with a valid file extension in the output
parameter for the selected format
value (i.e., .mpd
for MPEG-DASH and .m3u8
for APPLE-HLS), otherwise StreamGear will throw an AssertionError
.
Any improper value assigned to format
parameter will result in a ValueError
!
Data-Type: String
Default Value: Its default value is dash
Usage:
custom_ffmpeg
¶
This parameter assigns the custom path/directory where the custom/downloaded FFmpeg executables are located.
Behavior on Windows Systems
On Windows, if a custom FFmpeg executable's path/directory is not provided through this custom_ffmpeg
parameter, the StreamGear API will automatically attempt to download and extract suitable Static FFmpeg binaries at a suitable location on your Windows machine. More information can be found here ➶.
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.
Please read the FFmpeg Documentation carefully before passing any additional values to the stream_params
parameter. Incorrect values may cause errors or result in no output.
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 framerate1, at the index0
. - 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.
- If you specify the
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: -
-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 ink
(kilobits per second) orM
(Megabits per second). Define this attribute as follows: -
-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:
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 ➶
- In addition to the user-defined Secondary Streams, StreamGear automatically generates a Primary Stream (at index
-
-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:
-
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).
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:
-
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). -
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 isFalse
. It can be used as follows:The
-livestream
optional parameter is NOT supported in Single-Source mode.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 is25.0
fps. Its value can be a float or integer, as shown below: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 is0.1
. Increasing the BPP value helps fill the gaps between the current bitrate and the upload limit/ingest cap. Its value can be anything above0.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.
- BPP is a sensitive value; start with
-
-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.
-
-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:
-
-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:
-
-clear_prev_assets
(bool): (optional) This parameter specifies whether to remove/delete all previous copies of StreamGear assets files for selectedformat
(i.e., manifest (mpd
) in DASH, playlist (mu38
) in HLS, and respective streaming chunks (.ts
,.m4s
), etc.) present at the path specified by theoutput
parameter. The default value isFalse
. It can be enabled as follows:Additional segments (such as
.webm
,.mp4
chunks) are also removed automatically.
-
-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.
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:
Please check the H.264 documentation ➶ and FFmpeg Documentation ➶ for more information on following parameters.
All FFmpeg parameters are case-sensitive. Double-check each parameter if any errors occur.
In addition to these parameters, almost any FFmpeg parameter (supported by the installed FFmpeg) is also supported. Be sure to read the FFmpeg Documentation carefully first.
# 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:
Faster Transcoding with Stream Copy in Single Source Mode
For faster transcoding of input video, utilize Stream copy (-vcodec copy
) as the input video encoder in the Single-Source Mode for creating HLS/DASH chunks of the primary stream efficiently. However, consider the following points:
- Stream copy is NOT compatible with Real-time Frames Mode, as this mode necessitates re-encoding of incoming frames. Therefore, the
-vcodec copy
parameter will be ignored. - Stream copying NOT compatible with Custom Streams (
-streams
), which also require re-encoding for each additional stream. Consequently, the-vcodec copy
parameter will be ignored. - When using the audio stream from the input video, the Audio Stream copy (
-acodec copy
) encoder will be automatically applied.
# for checking encoder
ffmpeg -encoders # use `ffmpeg.exe -encoders` on windows
# for checking decoders
ffmpeg -decoders # use `ffmpeg.exe -decoders` on windows
Similarly, supported audio/video demuxers and filters depend on the FFmpeg binaries in use.
logging
¶
This parameter enables logging (if True
), essential for debugging.
Data-Type: Boolean
Default Value: Its default value is False
.
Usage:
-
In Real-time Frames Mode, the Primary Stream's framerate defaults to
-input_framerate
attribute value, if defined, else it will be 25fps. ↩