The media streamer is controlled by setting a pipeline configuration. The stream-source component and stream-destination component are specified by passing a string to the roMediaStreamer.SetPipeline() method. This string contains both the source and destination components concatenated together; the different stages of the pipeline are delimited by commas.
The pipeline is started by calling the
start() method (without extra arguments). The
stop() method can be used to stop the pipeline. However, some of the pipeline stages (described in the Media Streamer State Machine section below) will continue running internally, so the
reset() method may be preferable for terminating the stream.
Simple File Streaming
The following example shows how to stream from a file source to a single client:
To stop the stream, call
file source and
udp/rtp destinations do not function the same as in 4.7 firmware. However, the 4.7 method of file streaming is still available using the
rtpsimple components. The following example works exactly the same as media streaming in 4.7:
Note that the
filesimple component only works with
udpsimple/rtpsimple, and vice versa.
Media Streamer State Machine
The media streamer, represented by the
SetPipeline() method, has four states:
- RESET: The media streamer has been created, but nothing is allocated or running.
- INITIALISED: Some allocation may have happened and some resources may be reserved, but nothing is running.
- CONNECTED: All structures have been created and all the pipeline components are connected together. Though the pipeline is producing no output, some internal parts of it may already be running.
- RUNNING: The pipeline is running.
When a media streamer is created, it starts in the RESET state. After calling
SetPipeline(), the states can be progressed through using the following roMediaStreamer methods:
Start(). Moving to a later state causes any intervening states to be traversed automatically, which is why a pipeline can be started by simply calling
When a media streamer is in the RUNNING state, it can be moved backwards through the states by calling, respectively,
Reset(). As before, intermediate states can be omitted, so it is possible to stop the media streamer and de-allocate all its resources simply by calling
Stop() does stop any output from emerging from the pipeline, there may still be some internal activity.
SetPipeline() always causes the media streamer to return to the RESET state. All of the above interface functions, aside from
SetPipeline(), take no arguments.
This section lists the currently available source components for a streaming pipeline. Note that some source components (i.e.
memsimple:/) cannot be called until they are first created using destination components, which are described in the next section.
This component reads the named file from the local storage. The file must be an MPEG-2 transport stream (usually with a .ts suffix). This component can only be connected to
memsimple: components. The optional
This component can act as either a source or a destination. As a source, it reads from an MPEG-2 transport stream file and can be connected more generally to other components. This non-simple component must be used when connected to
hls: destination components (because it uses an indexed stream). Because it uses fewer resources, we recommend using the
filesimple: component instead of the
file: component whenever it is sufficient.
This component accepts the optional
iv parameters for file encryption/decryption.
The optional loop parameter can be appended to cause the input file to loop:
This component receives audio and video from the HDMI Input. It can then be fed through an Media Streamer#encoder component and streamed or written to a file.
This component receives the audio and video of the current presentation, allowing the player to encode and stream its current display output. See the Display Encoding page for more information about using this component.
This component receives a stream using the UDP protocol.
This component receives a stream using the RTP protocol.
This component receives a stream using the RTSP protocol. An optional
dtcp.port parameter can be included to specify a DTCP-IP encrypted session:
This component receives a stream using the HTTP protocol.
This component receives a stream using the HTTPS protocol.
This component receives a GStreamer pipeline and generates a non-simple stream using it.
This component receives a GStreamer pipeline and generates a simple stream using it.
This component reads from a previously created (destination) memory stream component with the given name, and forwards the results to other simple components. Note that
/stream.ts is appended to denote "the entire memory buffer". The following example will multicast a memory stream:
memsimple: source component can originate from either a simple memory stream (using the
memsimple: destination component) or a non-simple, "indexed" memory stream (using the
mem: destination component).
See the Memory Streaming page for more details.
This component reads from a previously created destination memory stream with the given
name; it can then forward the results to other non-simple components. Note that
/stream.ts is appended to denote "the entire memory buffer". Assuming sufficient resources, the following example will transcode and stream a memory stream:
This section lists the currently available destination components.
This component streams its input over UDP to the given IP address and port. This destination only works with the
memsimple: source component as input.
This component streams its input over RTP to the given IP address and port. This destination only works with the
memsimple: source component as input.
This component streams its input over an HTTP connection. This destination only works with the
memsimple: source component as input. It is intended for use as an HTTP media server and cannot be used to stream directly to a client.
This component streams its input over UDP to the given IP address and port.
This component streams its input over RTP to the given IP address and port.
This component streams its input over an HTTP connection. This component is intended for use as an HTTP media server and cannot be used to stream directly to a client.
This component writes its input to the named file, which will be saved as an MPEG-2 transport stream file. This component accepts the optional
iv parameters for file encryption.
This component allows you to see what's in a stream (often in conjunction with the decoder component) and is provided for debugging only: BrightScript primarily utilizes the roVideoPlayer and roAudioPlayer objects to play back streaming content.
This component works only with the
filesimple: component. It writes its input to a memory stream named
/name. This constitutes a simple memory stream, meaning that it is not indexed and cannot be input to a
mem: source, only another
memsimple: source. This component takes an optional size parameter that specifies the size of the memory buffer in megabytes. The default memory buffer size is 5MB.
This component creates a memory stream with the specified
/name. This component can receive input from general components and writes to an indexed (rather than simple) memory stream, which can be re-read by the
mem: source component. It can therefore be used to support HLS streaming.
mem: destination component accepts two optional parameters:
size: The size of the memory buffer in MB (megabytes). For HLS streaming, this needs to be a large buffer.
duration: The target duration of the index points (which become HLS segments).
This component segments the incoming stream and writes it to the given path. The written segments will have the name "path_000000.ts", "path_0000001.ts", etc., and the index file will be named "path_index.m3u8".
The HLS destination component accepts the parameter
duration, which specifies the approximate target length, in seconds, of the HLS segments. The default value is 5, so to segment a file into 3 second durations you could use code similar to the following:
The above function would split the file.ts file into segments of approximately 3 seconds each, named "file_000000.ts", "file_000001.ts", "file_000002.ts", etc.
Destination Component Options
The following options apply to the
rtp destination components.
maxbitrate parameter throttles the maximum instantaneous bitrate (in Kbps) of a stream. For example, the following component would never stream at a rate greater than approximately 2Mbps:
This number needs tuning both for the content being streamed and the network over which they are being sent. Note that it can be challenging to configure bitrates for some wireless networks.
ttl parameter specifies how many times multicast packets can be forwarded across switches and other network infrastructure. The default value for this parameter is 1.
This component receives an un-encoded input and outputs audio/video data encoded as an MPEG-2 transport stream. The following are valid parameters:
audiodelay=[delay_in_ms]: The audio synchronization offset in milliseconds. The default value is 0. A positive value will delay the audio with respect to the video, while a negative value will delay the video with respect to the audio.
delay=[delay_in_ms]: The A2P delay in milliseconds. If this parameter is set to 0 (the default value), the encoder determines the delay.
pframes=[frames]: The number of P-slices between I-slices in the GOP
bframes=[frames]: The number of B-slices between P-slices in the GOP
vbitrate=[bitrate]: The video bitrate specified in Kbps
vformat=[format]: The resolution and frame rate of the video output. The
formatcan be specified as any of the following:
This component utilizes H.264 for video and AAC for audio. The default video format is 720p30, and the default bitrate is 6Mbps.
With firmware versions 6.2.63 and later, the H.264 video is encoded at High profile with B-frames. With earlier versions of firmware, video is encoded at level 4.1 without B-frames.
The following example encodes video from the HDMI Input and writes it to the local storage as a .ts file:
This component receives an un-encoded input and outputs video data as an elementary H.264 stream (as opposed to the standard
encoder: component, which outputs an MPEG-2 transport stream). The H.264 stream has no audio data. This component accepts the same
vbitrate parameters as the encoder: component.
Since non-simple components expect an MPEG-2 transport stream, this component only works with the following:
This component receives an encoded input and decodes it. The primary uses of this component are to pass a video stream to the
display: destination for playback or to pass a video file to an
encoder: component for transcoding.
The roMediaStreamer object will honor the copy-protection status of its inputs by assigning the same status to its outputs. Each stream can have one of the following levels of copy protection:
- None: No copy protection is enabled. These streams can be saved to files or streamed over the network without restriction.
- HDCP: The input is protected with HDCP. It can be neither saved nor streamed, but it can be output to an HDCP-authenticated display.
The roMediaStreamer object will handle HDCP authentication and de-authentication as follows:
- If a non-HDCP authenticated stream becomes HDCP authenticated, any file or IP-streaming destination components will stop immediately and send an EOS_ERROR event. If the connected display cannot be HDCP authenticated, the display destination will hide the video output .
- If a stream that was previously HDCP authenticated becomes unprotected, the file and IP streaming destination components will not be resumed. However, if the display destination is not HDCP authenticated, it will begin displaying video. An HDCP-authenticated display will be unaffected either way.
The encryption level can be forced by flagging it on the source component. For example, the following source component will force any connected display receiving HDMI input to be HDCP authenticated:
The HDCP encryption status of a stream cannot be removed by setting the encryption parameter to none.
file:/// source and destination components accept the optional
key and iv parameters, which can be used to encrypt or decrypt a file using the AES CTR algorithm. The
key and iv values must be specified as 16-byte hex strings.
Note that this file encryption process is distinct from HDCP authentication. There are no restrictions on how encrypted files may be used in a pipeline, but you cannot use this form of encryption on a stream that was originally HDCP protected.
The following example saves an HLS stream as an encrypted file. Once the file is written, it can be decrypted from a
file:/// source component using the same
key and iv values:
The following code snippets provide examples for common types of media streaming.
Streaming an MPEG-2 TS File over UDP
To initialize the roMediaStreamer instance and begin the stream, use the following:
To stop the stream, use the following:
You can also use the simple form of components for most common streaming tasks. The following would operate identically to the above stream, while using fewer resources:
Streaming an Encoded HDMI Input over RTP
The resolution and bitrate of the streamed video can be changed by adding parameters to the
encoder: component. Use the following code to stream the input using the native resolution and default bitrate:
To stop the stream, use the following:
Recording a File
The following code will record an HDMI Input and save it as a file named hdmi.ts:
To stop the recording process, use the following:
Transcoding and Streaming a File
The output of a
decoder: component can be connected to the input of an
encoder: component to transcode the data. This is useful if you want to modify the bitrate of the video before streaming it over the network. The following code will transcode the file.ts video before streaming it over RTP:
To stop the transcoding process, use the following:
The player can be used to output a streaming input using a different protocol by connecting an IP client component to an IP server component. The following code will receive an HTTP stream and then stream it using RTP:
To stop the stream, use the following:
Segmenting a File Using HLS
An existing .ts file can be segmented for streaming using the HLS protocol. The resulting file segments can then be streamed directly by making HTTP requests to an HTTP Media Server. The following code will use the file.ts video to generate segments that are approximately 10 seconds in duration:
In this case, the files will begin with media_segment_000000.ts, and the counter will increment once for each segment. The index file will be written as "media_segment_index.m3u8".
Simple and Non-Simple Components
To conserve system resources, we recommend using the simple versions of components whenever possible. Use the following guidelines to determine whether simple or non-simple components should be used:
- Use simple components when streaming a file from local storage using UDP, RTP, or HTTP protocols (without any encoding or transcoding involved in the pipeline).
- Use non-simple components whenever the pipeline includes encoding, transcoding, or HLS streaming.
- When ingesting a stream from a remote source and re-streaming it, use the
httpsimple:destination components. If you need to modulate the stream (or re-stream using HLS), use non-simple components.
- Since a
memsimple:source component can read from a
mem:destination component, use the
memsimple:source component in conjunction with
httpsimple:when memory streaming. The
mem:source component should only be used with the
hls:destination component ( or