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. API will throw RuntimeError, if it fails to detect valid FFmpeg executables on your system.
- In this mode, API auto generates a primary stream of same resolution and framerate1 as the input video (at the index
0
). - In this mode, if input video-source (i.e.
-video_source
) contains any audio stream/channel, then it automatically gets mapped to all generated streams. - Always use
close()
function at the very end of the main code.
DEPRECATION NOTICES for v0.3.3
and above
- The
terminate()
method in StreamGear is now deprecated and will be removed in a future release. Developers should use the newclose()
method instead, as it offers a more descriptive name, similar to the WriteGear API, for safely terminating StreamGear processes. - The
-livestream
optional parameter is NOT supported in this Single-Source Mode.
Faster Transcoding of Primary Stream with Stream Copy in Single Source Mode
For faster transcoding of input video in this mode, utilize Stream copy (-vcodec copy
) as the input video encoder for creating HLS/DASH chunks of the primary stream efficiently. However, consider the following points:
- Stream copying NOT compatible with Custom Streams (
-streams
), which require re-encoding for each additional stream. Therefore, 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.
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.
After running this bare-minimum example, StreamGear will produce a Manifest file (dash_out.mpd
) with streamable chunks, containing information about a Primary Stream with the same resolution and framerate as the input.
After running this bare-minimum example, StreamGear will produce a Master Playlist file (hls_out.mpd
) with streamable chunks, containing information about a Primary Stream with the same resolution and framerate as the input.
Usage with Additional Streams¶
In addition to the Primary Stream, you can easily generate any number of additional Secondary Streams with variable bitrate or spatial resolutions, using the exclusive
-streams
attribute of thestream_params
dictionary parameter.
To generate Secondary Streams, add each desired resolution and bitrate/framerate as a list of dictionaries to the -streams
attribute. StreamGear will handle the rest automatically. The complete example is as follows:
A more detailed information on -streams
attribute can be found here ➶
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.
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 and framerate as the input video-source (i.e.-video_source
). - Ensure that your system, machine, server, or network can handle the additional resource requirements of the Secondary Streams. Exercise discretion when configuring multiple streams.
- 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
Always use the -streams
attribute to define additional streams safely. Duplicate or incorrect definitions can break the transcoding pipeline and corrupt the output chunks.
Usage with Custom Audio-Input¶
In single source mode, by default, if the input video source (i.e.,
-video_source
) contains audio, it gets automatically mapped to all generated streams. However, if you want to add a custom audio source, you can use the exclusive-audio
attribute of thestream_params
dictionary parameter.
To add a custom audio source, provide the path to your audio file as a string to the -audio
attribute. The API will automatically validate and map the audio to all generated streams. The complete example is as follows:
Ensure the provided -audio
audio source is compatible with the input video source (-video_source
). Incompatibility can cause multiple errors or result in no output at all.
You can also assign a valid audio URL as input instead of a file path. More details can be found here ➶
Usage with Variable FFmpeg Parameters¶
For fine-grained control over the transcoding process, StreamGear provides a highly extensible and flexible wrapper around FFmpeg library and access to almost all of its configurational parameter.
In this example, we'll use the H.265/HEVC video encoder and AAC audio encoder, apply various optimal FFmpeg configurational parameters.
This example assumes that the given input video source (-video_source
) contains at least one audio stream.
This example is just conveying the idea on how to use FFmpeg's internal encoders/parameters with StreamGear API. You can use any FFmpeg parameter in the similar manner.
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.
-
In Real-time Frames Mode, the Primary Stream's framerate defaults to
-input_framerate
attribute value, if defined, else it will be 25fps. ↩