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.

The following example shows how to stream from a file source to a single client:

To stop the stream, call m.reset(). 

The 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 filesimple, udpsimple and rtpsimple components. The following example works exactly the same as media streaming in 4.7:

m.SetPipeline("filesimple:///data/clip.ts, udpsimple://239.192.0.0:1234/")

Note that the filesimple component only works with udpsimple/rtpsimple, and vice versa.

The media streamer, represented by the SetPipeline() method, has four states:

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: Initialise(), Connect(), and 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 Start(). 

When a media streamer is in the RUNNING state, it can be moved backwards through the states by calling, respectively, Stop(), Disconnect(), and 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 Reset(). While Stop() does stop any output from emerging from the pipeline, there may still be some internal activity.

Calling 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. mem:/ and memsimple:/) cannot be called until they are first created using destination components, which are described in the next section.

filesimple:///filename

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 udpsimple:, rtpsimple:, or memsimple: components. The optional loop parameter can be appended to cause the input file to loop:

m.SetPipeline("filesimple:///file.ts?loop, udpsimple://239.192.0.0:1234/")

file:///filename

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 key and iv parameters for file encryption / decryption.

The optional loop parameter can be appended to cause the input file to loop:

m.SetPipeline("file:///file.ts?loop, hls:///file?duration=3")

hdmi:[///]

This component receives audio and video from the HDMI® Input. It can then be fed through an Media Streamer esencoder component below and streamed or written to a file.

display:[///]

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 EncodingDisplay Encoding page for more info about using this component.

udp://IP_address:port/

This component receives a stream using the UDP protocol.

rtp://IP_address:port/

This component receives a stream using the RTP protocol.

rtsp://IP_address:port/path

This component receives a stream using the RTSP protocol. An optional dtcp.port parameter can be included to specify a DTCP-IP encrypted session:

rtsp://10.1.243:554/stream1?dtcp.port=8888

http://IP_address:port/path

This component receives a stream using the HTTP protocol.

https://IP_address:port/path

This component receives a stream using the HTTPS protocol.

gst://IP_address:port/path

This component receives a GStreamer pipeline and generates a non-simple stream using it.

gstsimple://IP_address:port/path

This component receives a GStreamer pipeline and generates a simple stream using it.

memsimple:/name/stream.ts

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:

m.SetPipeline("memsimple:/livestream/stream.ts, rtpsimple://239.192.0.0:5004/")

A 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 StreamingMemory Streaming page for more details.

mem:/name/stream.ts

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:

m.SetPipeline("mem:/livestream/stream.ts, decoder:, encoder:, rtp://239.192.0.0:5004/")

This section lists the currently available destination components.

udpsimple://IP_address:port/

This component streams its input over UDP to the given IP address and port. This destination only works with the filesimple: or memsimple: source component as input.

rtpsimple://IP_address:port/

This component streams its input over RTP to the given IP address and port. This destination only works with the filesimple: or memsimple: source component as input.

httpsimple:///socket=num

This component streams its input over an HTTP connection. This destination only works with the filesimple: or memsimple: source component as input. It is intended for use as an HTTP media serverHTTP media server and cannot be used to stream directly to a client.

udp://IP_address:port/

This component streams its input over UDP to the given IP address and port.

rtp://IP_address:port/

This component streams its input over RTP to the given IP address and port.

http:///socket=num

This component streams its input over an HTTP connection. This component is intended for use as an HTTP media serverHTTP media server and cannot be used to stream directly to a client.

file:///filename

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 key and iv parameters for file encryption.

display:[///]

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.

memsimple:/name

This component works only with the filesimple: component. It writes its input to a memory streammemory 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.

m.SetPipeline("filesimple:///file.ts, memsimple:/file?size=2")

mem:/name

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 streammemory stream, which can be re-read by the mem: source component. It can therefore be used to support HLS streaming.

m.SetPipeline("file:///file.ts, mem:/file?duration=3&size=25")

The mem: destination component accepts two optional parameters:

hls:///path

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:

m.SetPipeline("file:///file.ts, hls:///file?duration=3")

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.

The following options apply to the udpsimple, rtpsimple, udp, and rtp destination components.

maxbitrate

The 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:

rtp://IP_address:port/?maxbitrate=2000

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

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

Example:

rtp://IP_address:port/?ttl=64

encoder:[///][param=value]

This component receives an un-encoded input and outputs audio/video data encoded as an MPEG-2 transport stream. The following are valid parameters:

This component utilizes H.264 for video and AAC for audio. The default video format is 720p30, and the default bitrate is 6Mbps.

The following example encodes video from the HDMI Input and writes it to the local storage as a .ts file:

m.SetPipeline("hdmi:, encoder:vformat=480p25&vbitrate=1000, file:///hdmi.ts")

esencoder:[///][param=value]

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 audiodelay, vformat, and vbitrate parameters as the encoder: component.

Since non-simple components expect an MPEG-2 transport stream, this component only works with the following: rtpsimple:, udpsimple:, httpsimple:, and memsimple:.

decoder:[///]

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:

The roMediaStreamer object will handle HDCP authentication and de-authentication as follows:

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:

hdmi:encryption=hdcp

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

To initialize the roMediaStreamer instance and begin the stream, use the following:

To stop the stream, use the following:

m.reset()

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:

m.SetPipeline("filesimple:///data/clip.ts, udpsimple://239.192.0.0:1234/")

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:

m.reset()

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:

m.reset()

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:

m.reset()

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:

m.reset()

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

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: