Page Comparison

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:

...

Media Streamer State Machine

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

...

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.

Source Components

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.

...

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#encoder component 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 Encoding page for more information 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:

...

See the Memory 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/")

Destination Components

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

...

• 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).

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

...

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.

...

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

Other Components

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:

...

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.

HDCP

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.

HDCP Workflow

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.

Encryption Flags

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:

...

File Encryption

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.

...

m = CreateObject("roMediaStreamer")
m.SetPipeline("http://<ip-address>/playlist.m3u8,file:///file.ts?key= 30313233343536373839616263646566&iv=30313233343536373839616263646566")
m.Start()

Streaming Examples

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:

...

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

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:

m.reset()

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:

m.reset()

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:

m.reset()

Re-streaming

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()

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:

...