RTMP command API

When commands are called from an RTMP connection rather than an HTTP request they are given access to the RTMP connection they were called within. These commands are then able to perform RTMP specific functionality like creating render streams, discovering installed video codecs and returning RTMP statistics.

Identifying RTMP

When called within an RTMP connections the server attaches an mi::rswservices::IRtmp_context object to the service request that can be obtained by the command:

      mi::base::Handle<mi::IMap> attachments(context->get_attachments());
      h_rtmp = attachments->get_value<mi::rswservices::IRtmp_context>("rtmp_context");
      if (!h_rtmp.is_valid_interface()) {
          // is an RTMP command request
      }
      

This interface will then provide all access to the RTMP server. It's main functionality is creating and editing Render Loops and Stream Encoders which are used to stream video to the RTMP client.

RTMP Render Loops

An RTMP render loop is a server controlled loop that continually renders images and provides a frame source for video streams. Rendering itself is performed by user implemented render handlers. Render loops are created with mi::rswservices::IRtmp_context::create_render_loop for a specific scene and scope.

Render loops are named and are able to be shared between different RTMP connections. This allows for collaborating users to view the same scene without each having to perform their own render. Shared render loops are created by specifying a public_pool argument when creating them. They can then be retrieved by supplying the same name and public_pool in any connection made to the host it was created on. Render loops are not shared across the cluster.

A render loop on it's own cannot be streamed to the client. Loops need to be associated with a video encoder for streaming.

RTMP Stream Encoders

Stream encoders associate a video codec with a render loop. They are created with mi::rswservices::IRtmp_context::create_encoder and require a name unique to the connection, the name of the video codec to use and the name (and possibly pool name) of a previously created render loop. Once created the stream encoder will need to have its resolution, render rate and codec parameters set. Once setup the client can create a NetStream object and call NetStream.play() specifying the stream encoders name as the file to play. This will initialize the encoder, start the render loop if necessary and begin streaming video back to the client.

Setting codec parameters on the stream encoder will be passed through to the codec as soon they are set. If the codec supports changing that parameter on the fly then the changes will be seen immediately. If not, the client can call NetStream.play() again with the same stream name and the codec will be reinitialized with the new parameters and playback begins again.