Media Streamer

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 docid\ kxuyhjbrdmol7zmofc525 section below) will continue running internally, so the reset() method may be preferable for terminating the stream xd5 players do not support encoding you can stream existing files to other players and clients, but you cannot change the file bitrate or resolution using media streamer encoding simple file streaming the following example shows how to stream from a file source to a single client m = createobject("romediastreamer") m setpipeline("file ///data/clip ts, udp\ //239 192 0 0 1234/") m start() 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 do not use ports 8888 or 9999 since these ports may be used by brightsignos 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 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 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 this component accepts the optional key and iv parameters for media streamer docid\ kxuyhjbrdmol7zmofc525 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 encoding docid 7hq21ifivyfedf3gl0yhi 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 streaming docid\ ud 8kloqn7xk eq0rhoxi 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 media server docid\ fqzkxjbxz7ykvlop2k2l8 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 media server docid\ fqzkxjbxz7ykvlop2k2l8 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 media streamer docid\ kxuyhjbrdmol7zmofc525 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 streaming docid\ ud 8kloqn7xk eq0rhoxi 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 streaming docid\ ud 8kloqn7xk eq0rhoxi , 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 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 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 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 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 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 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 format can be specified as any of the following 480i50 480p25 720p24 720p25 720p30 720p50 720p60 1080i50 1080i60 1080p24 1080p25 1080p30 1080p50 1080p60 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 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 hdmi\ encryption=hdcp important the hdcp encryption status of a stream cannot be removed by setting the encryption parameter to none 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 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 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 stream an mpeg 2 ts file over udp to initialize the romediastreamer instance and begin the stream, use the following m = createobject("romediastreamer") m setpipeline("file ///data/clip ts, udp\ //239 192 0 0 1234/") m start() 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/") stream 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 m = createobject("romediastreamer") m setpipeline("hdmi , encoder , rtp\ //239 192 0 0 1234/") m start() to stop the stream, use the following m reset() record a file the following code will record an hdmi input and save it as a file named hdmi ts m = createobject("romediastreamer") m setpipeline("hdmi , encoder , file ///hdmi ts") m start() to stop the recording process, use the following m reset() transcode and stream 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 m = createobject("romediastreamer") m setpipeline("file ///file ts, decoder , encoder\ vbitrate=1000, rtp\ //239 192 0 0 5004/") m start() 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 m = createobject("romediastreamer") m setpipeline("http //172 30 1 37/file ts, rtp\ //239 192 0 0 5004/") m start() to stop the stream, use the following m reset() segment 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 m = createobject("romediastreamer") m setpipeline("file ///file ts, hls\ ///media segment?duration=10") m start() 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 & 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 udpsimple , rtpsimple , and 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 udpsimple , rtpsimple , or httpsimple when memory streaming docid\ ud 8kloqn7xk eq0rhoxi the mem source component should only be used with the hls destination component ( or file if debugging)