Broccoli Products home | contact us | about us
Profile Services Downloads Workshop Extras

RTMP Client Project in C#
(by Lou Brown)

The Brief
This is a guide for C# developers who want to connect to an RTMP server and download streamed content. I will start by describing the RTMP protocol and the quickest way to implement an RTMP client, then a description of a simple application that will connect to an RTMP server and download a file to your disk, and finally a list of classes and functions available in the RtmpClient library.

The libraries for this project can be found in RtmpClient.zip, which includes the RtmpClient library (BroccoliProducts.RtmpClient), and a low level library (BroccoliProducts.LowLevel) that the RtmpClient library uses.

File: BroccoliProducts.RtmpClient.dll
Current Build: 1.0.0.6 (7th December, 2009)
System Requirements:    Windows XP

The code for the sample project can be found in "Program.cs", a single C# file that compiles as a console application. I have compiled and run this file on XP with VS2005. If you want to run this program, make sure you include a reference to the BroccoliProducts.RtmpClient library.

What is RTMP?
RTMP (Real Time Messaging Protocol) is the dominant protocol for streaming audio and video content over the Internet. If you watch web-tv or listen to Internet radio, the chances are the data is being transmitted as RTMP messages (or one of its variants), from an RTMP server, to an RTMP client embedded in your browser. The most widely used RTMP client is Adobe's Flash Player.

RTMP streamed data in three separate channels, or sub-streams - audio data, video data and meta-data. For a film, the audio-data is the soundtrack, the video-data is the images. For audio streaming, such as mp3 files, there is no video data. The meta-data describes the format of the video and audio data, for example, the dimensions of the video (e.g. 640x480), or the duration of the audio track. The main body of meta-data arrives when streaming starts.

RTMP is a complex protocol. It is owned by Adobe, and Adobe's official RTMP specification is not complete. The majority of usable information available on the workings of RTMP has been discovered by software developers' reverse engineering raw network port data. If your application requirement is to grab streamed RTMP data from a media server, a freely available RTMP client library will save you time, even if only for the initial stages of your application project.

The RTMP Client Library
The RTMP Client Library (BroccoliProducts.RtmpClient) provides a simple interface to an RTMP Server, with enough functionality to connect, disconnect, invoke commands, open and delete streams, and control the flow of the stream (pause, seek etc...). There are also classes to help you roll-your-own RTMP messages, and a feature for pre-processing incoming RTMP messages.
Program.cs
Our brief is to connect to an RTMP server, and download a stream of content to our hard disk. The code for this application is available here Program.cs.

At the top of the Program.cs file are examples of connection parameters that connect to local servers running on your system as well as remote servers globally available on the Internet.

Here is a table showing the programmatic steps required to download a stream of RTMP data.

A    Open the target files. Two files will be needed - one for the audio data, and one for the video data. If an MP3 is being streamed, the video data will be empty.
B Create an RtmpClient object. The RtmpClient constructor takes one parameters, a reference to the main window of your application. Since out application runs in a console, which is windowless, this parameter can be null.
C Call an RtmpClient function to open an RtmpConnection object. The RtmpConnection encapsulates a connection to the RTMP server. Three parameters are required to create the connection - the host address, the host port (1935 for RTMP), and the protocol, which is RTMP.

There are several variants of RTMP, for example, RTMPT which is RTMP tunneled through HTTP, or RTMPE which is encrypted RTMP.
D Set up the behavior parameters for our RtmpConnection.

Some RTMP servers combine messages into one large message to save on processing overhead. Enable the automatic chopping up of aggregate messages to break these messages up into their sub-messages.

During the connection handshake, the RTMP sends a SetPeerBW messages, and expects a WindowsAck message in return. Enable AutoRespondToSetPeerBW to ensure this done automatically.

Every so often the RTMP server sends out a Ping message to see if the client is still alive, and the server expects a Pong response within a timeframe. Enable AutoPingPong to automatically send the Pongs back.

During connection handshake, the server sends out a ReceiveAckWindow, which is the number of bytes the client can receive from the server after which the server expects an acknowledgement. This value is usually 250,000 bytes, but can be much less. If no acknowledgement is received, the server stops sending. Enable AutoAckReceivedData to automatically send these acknowledgments.
E Call an RtmpConnection function to connect to the streaming application we are interested in. There are ten parameters for this function, defining the path of the stream, and the capabilities of the client. The AppName and the TcUrl are the most important. The audio and video capabilities can be set to ALL. The other parameters can often be left empty.

The RTMP connection parameters consist of application names, combined with relative locations. Look at the sets of connection parameters at the top of the Program.cs file for examples of these values.
F Call an RtmpConnection function to create a stream. This returns an RtmpStream object.

An RTMP connection can theoretically support multiple streams, but in reality only the more sophisticated RTMP servers can do this.
G Enable the RtmpStream's collecting buffers for audio and video data.

By enabling the CollectAudioDataFlag and CollectVideoDataFlag, the audio and video data that is received by a stream is added to two internal thread-safe buffers.

The amount of data in these buffers can be tested at any time using the AvailableAudioDataSize and AvailableVideoDataSize variables.

When data has been collected into the buffers, an external application can grab the data and write it to a file. This is what our application is doing in the _WriteAudioAndVideoDataToFiles function.
H Register for pre-processing on our RtmpStream.

The pre-processing callback allows us to look at RTMP messages as they arrive for our stream, before anything else is done with them. We can intercept meta-data messages and display them for the user.

Another method of storing our audio and video data would have been to intercept audio and video messages in a pre-processing callback function and write the message payload directly to the files. However in our application we use the RtmpStream's thread-safe buffers because they use less processor time.

Another use of pre-processing is to examine the messages sent from the RTMP server that indicate when the stream is paused, stopped, streaming and complete, and then update the application interface.

The pre-processor function is called from inside a thread. Any processing done in the pre-processing callback function should be minimal, and must not interact with any form controls. If you want to receive events from the RtmpClient, use the StatusChanged event of the RtmpClient, which is described below.
I Play the stream.

Playing the stream initiates a flow of audio and video data from the RTMP server, and some meta-data.
J Take the incoming audio and video data and write it to the target files. Keep doing this until the streaming stops.
K Clean up the Rtmp session. Delete the stream, close the connection, and destruct the RtmpClient object.
L Flush and close the target files.
M There is a good change the audio data will consist of MP3 packets, so attempt to convert this data into a valid MP3 files by calling one of the static helper functions of the RtmpClient, RebuildMP3File.

Additional Functionality
The following is a chart of the public functions and properties of each of the main Rtmp classes.

RtmpClient  
          Public function RtmpClient Construct a new RtmpClient object.
  Public function CreateConnection Create a new RtmpConnection object which encapsulates a connection to an RTMP server.
  Event StatusChanged An event to notify of changes to client, connection or stream. This event and its arguments are detailed below.
  Public function Static function RebuildMP3File A static helper function that converts a file of MP3 frames downloaded from an RtmpStream into a valid MP3 file that can be played with an MP3 player.
     
RtmpConnection  
    Property AutoRespondToSetPeerBW A boolean property for enabling automatic responses to the handshake message SetPeerBW.
  Property AutoChopUpAggregateMessages     A boolean property for enabling the chopping up of aggregate messages as soon as they are received.
  Property AutoPingPong A boolean property for enabling automatic ping message handling.
  Property AutoAckReceivedData A boolean property for enabling automatic data acknowledgment messages.
  Property Timestamp A UInt32 property for getting the current client-side timestamp. Used when creating your own messages.
  Property ChunkSize A UInt32 property for getting the current chunk size. Used when creating your own messages.
  Public function Close Close the current connection. Closes all streams for this connection.
  Public function IsValid Returns null if the stream is valid, otherwise returns a string description.
  Public function SendMessageAndWait Send a message and wait for a response. The response expected will have the same message target as the sent message, will have a string value for the first parameter (for example "_result" or "_onStatus"), and will be the same message type (for example, an Amf0 Command).
  Public function SendMessage Send a message and return immediately.
  Public function GetNextTransactionId Get the next transaction id, and increment the next transaction Id counter (2 - 0x7FFFFF).
  Public function GetNextAmfStreamId Get the next Amf Stream id. Amf stream ids are rotated on the client-side (3 - 28).
  Public function ConnectToApplication Connect to a streaming application on the server.
  Public function CreateStream Create a new RtmpStream object.
     
RtmpStream  
  Property StreamId A UInt32 property for getting the stream id that was assigned to the stream by the RTMP server.
  Property State An eState property for getting the current state. Values include Idle, Streaming, Reset, Paused, Stopped and Closed. Once a stream is closed, it cannot be re-opened.
  Property AvailableAudioDataSize A UInt32 property for getting the amount of data collected in the audio data buffer.
  Property AvailableVideoDataSize A UInt32 property for getting the amount of data collected in the video data buffer.
  Property CollectAudioDataFlag A boolean property to enable the collecting of audio data in the audio data buffer.
  Property CollectVideoDataFlag A boolean property to enable the collecting of video data in the video data buffer.
  Property ForwardMetaDataFlag A boolean property which when enabled, sends a StatusChanged event when meta-data is received for this stream.
  Public function IsValid Returns null if the stream is valid, otherwise returns a string description.
  Public function Play Sends the play command for the stream.
  Public function Pause Pause or resume streaming.
  Public function Seek Seek to a time offset within the stream.
  Public function Close Close the stream using the RTMP function "deleteStream".
  Public function SetBufferSize Set the buffer size in milliseconds.
  Public function ClearAudioCollector Clear the buffer of collected audio data.
  Public function ClearVideoCollector Clear the buffer of collected video data.
  Public function GetCollectedAudioData Grab collected audio data into the buffer provided.
 

Public function GetCollectedVideoData

 Grab collected video data into the buffer provided.
  Public function RegisterForPreProcessing Register a function as the pre-processing callback function for this stream.
  Public function Static function StreamNameFormatter A static helper function to help format stream names.


RTMP Messages
As message data is received it is translated into Rtmp messages.

Each RTMP message type has an associated class derived from RtmpMessage. Each message class has one or more properties for accessing the parameters of the message. Some of the message classes also have static helper functions to assist building commonly used messages.

RtmpMessage This is an abstract top-level class. All of the message classes are based on this class.
          Property AmfStreamId The Amf stream id for the message.
  Property Timestamp The server-side timestamp.
  Property MsgTarget The message target, which is either zero or a stream id.
  Property MsgType An eMsgType property for getting the RTMP type of the message.
  Public function ToBuffer Creates a buffer out of the message that can be sent over a socket connection.
  Public function ToString Creates a string description of the message.
     
RtmpMessage_AudioData The audio-data message.
  Property Data A byte-array property containing the audio-data payload of the message.
  Public function SetData Set the audio-data payload.
     
RtmpMessage_CommandAmf0      An AMF0 command message.
  Property Parameters A ParameterList property for getting a reference to the list of parameters.
  Public function Static function Build_NetConnection_Connect    A static helper function for building a "connect" message.
  Public function Static function Build_NetConnection_CreateStream    A static helper function for building a "createStream" message.
  Public function Static function Build_NetStream_Play A static helper function for building a "play" message.
  Public function Static function Build_NetStream_Pause A static helper function for building a "pause" message.
  Public function Static function Build_NetStream_Seek A static helper function for building a "seek" message.
  Public function Static function Build_NetStream_DeleteStream A static helper function for building a "deleteStream" message.
     
RtmpMessage_Control A control-code message. Control messages are used for a variety of functions, each with their own parameter set.
  Property ControlCode Set or get the ControlCode for the message, including STREAM_BEGIN, STREAM_EOF, STREAM_DRY, SET_BUFFER_SIZE, STREAM_IS_RECORDED, PING_REQUEST, PING_RESPONSE, SWFV_REQUEST,
SWFV_RESPONSE, UNKNOWN1 and UNKNOWN2.
  Property StreamId The stream-id parameter for the stream control code messages.
  Property PingTime The ping-time data in a ping request and returned in a ping response (a pong).
  Property SetBufferLength Get and set the SetBufferLength parameter in milliseconds.
  Property ResponseBuffer The response buffer for the SWFV_REQUEST and SWFV_RESPONSE control messages.
  Public function Static function Build_SetBufferSize A static helper function for building a SET_BUFFER_SIZE message.
  Public function Static function Build_Pong A static helper function for building a PING_RESPONSE message.
     
RtmpMessage_DataAck A acknowledgement of received data.
  Property Value Get or set a UInt32 value representing the amount of bytes received since the last DataAck message was sent.
  Public function Static function Build A static helper function for building a DataAck message.
     
RtmpMessage_MetaDataAmf0 Meta-data that is streamed with the audio and video data.
  Property Parameters A ParameterList property for getting a reference to the list of parameters.
     
RtmpMessage_SetChunkSize A chunk-size value, sent from the RTMP server, specifying how message data will be chopped up.
  Property Value A UInt32 property for getting and setting the new chunk size.
     
RtmpMessage_SetPeerBW A SET_PEER_BW message.
  Property eLimitType An eLimitValue property, including HARD, SOFT and DYNAMIC.
  Property Value A UInt32 property for getting and setting the bandwidth value.
     
RtmpMessage_VideoData The video-data message.
  Property Data A byte array property containing the video-data payload of the message.
  Public function SetData Set the video-data payload.
     
RtmpMessage_WindowAckSize A specification of the Ack data size.
  Property Value A UInt32 property for getting and setting the acknowledgement widow size in bytes.
  Public function Static function Build A static helper function for building a Window-Ack-Size message.

There is one further message class, and this one does not correspond to an RTMP message type.

RtmpMessage_Raw An Rtmp message with header and payload.
          Property Payload A byte array property for accessing the payload buffer.
  Public function SetPayload Set the payload buffer.

Messages that are not translated into one of the RTMP message type classes are encapsulated in as a raw message, RtmpMessage_Raw.
Reasons why a message would not be translated include the following:

  The message had a corrupt payload.
The messages caused the RtmpClient library to throw an exception during translation.
The message is of a type not currently supported by the BroccoliProducts.RtmpClient library, including Meta Data AMF3, AMF3 Commands, Shared Object AMF0, and Abort.
The message contained parameters not currently supported by the BroccoliProducts.RtmpClient, including MovieClip, Referencer, LongString, Unsupported, Recordset, XmlDocuments and TypedObject.

When a message cannot be translated, a StatusChanged event is fired with the CannotTranslateMsg flag, and a reference to the message.

By combining StatusChanged event monitoring and message pre-processing, and using the RtmpMessage class to create your own message, any message handling can be achieved by an external application, even if not directly supported by the RtmpClient library.

StatusChanged Events

StatusChanged events can be accessed using the RtmpClient::StatusChanged event handler. The event argument for the StatusChanged event is of type RtmpEventArgs. The members of this class are detailed as follows:

Property Hint A property of type RtmpEventArgs::eHint, describing the status change that raised the event. A table of possible values for the Hint is detailed below.

Note that eHint is an attributes flag, and can combine more than one value.
Property Stream      A reference to the RtmpStream object for this event.
Property Msg A reference to the RtmpMessage for this event.

Possible values for RtmpEventArgs::eHint are as follows:


ConnectionOpened A new connection has been created.
ConnectionClosed An existing connection has been closed.
StreamOpened A new stream has been opened. The Stream property of the RtmpEventArgs will have a reference to the new stream.
StreamClosed An existing stream has been closed. The Stream property of the RtmpEventArgs will have a reference to the closed stream.
CannotTranslateMsg     A message has been received from the RTMP server that cannot be translated. The Message property of the RtmpEventArgs will have a reference to a raw message class.
AudioDataAvailable Some audio data has been stored in the stream's audio data collector. This event is only sent when the collector was previously empty. The Stream property of the RtmpEventArgs will have a reference to the stream on which the data was received.
VideoDataAvailable See the description for AudioDataAvailable.
StreamBegin Streaming has begun. The Stream property of the RtmpEventArgs will have a reference to the stream on which the data was received.
StreamPaused A stream has been paused. The Stream property of the RtmpEventArgs will have a reference to the stream on which the data was received.
StreamReset A stream has been reset. The Stream property of the RtmpEventArgs will have a reference to the stream on which the data was received.
StreamStopped A stream has stopped. The Stream property of the RtmpEventArgs will have a reference to the stream on which the data was received.
IncomingMetaData A meta-data message has been received. The Stream property of the RtmpEventArgs will have a reference to the stream on which the data was received.
ParserTripped During translation of a received RTMP message, the RtmpClient library code fell over, and there can be no more translation of messages. This is a fatal error.
PingsExchanged A ping request was received, and a response was sent.
ReceivedDataAck A DataAck message was sent to acknowledge received data.

Creating Your Own RTMP Messages
There will be some messages that the RtmpClient library does not support. You can create these message yourself using the message classes derived from RtmpMessage.

There are two ways to create your own RTMP messages - create an instance of the whichever message class correspondents to a message type, for example, a Command(AMF0) message could be created using the RtmpMessage_CommandAmf0 class. Or create a raw message, and format the binary content yourself, which is a lot harder.

The following is an example of creating a "play" command message, starting with a new RtmpMessage_CommandAmf0 object.

The ComandAmf0 class has a property "Parameters", which is a reference to a list of parameters. The "Amf0" refers to the formatting of the parameters of the message.


// create a message object
RtmpMessage_CommandAmf0 cmd = new RtmpMessage_CommandAmf0(
     m_rtmpConnection.GetNextAmfStreamId(),
     m_rtmpConnection.Timestamp,
     1 // target is stream-id 1
);

// add parameter - string command for playing a stream
cmd.Parameters.Add( new RtmpParameter_String(null,"play") );

// add parameter - transaction id (must be 0)
cmd.Parameters.Add( new RtmpParameter_Number(null,0) );

// add parameter -- command object, can be null
cmd.Parameters.Add( new RtmpParameter_Null(null) );

// add parameter -- stream name
cmd.Parameters.Add( new RtmpParameter_String(null,"mp3:song01.mp3") );

// add parameter - start position (ms)
cmd.Parameters.Add( new RtmpParameter_Number(null,0) );

// add parameter - duration (-1 for all of it)
cmd.Parameters.Add( new RtmpParameter_Number(null,-1) );

// add parameter - reset (do not define true or false)
cmd.Parameters.Add( new RtmpParameter_Undefined(null) );

To send this message, pass the message to the connection's SendMessage function.

MORE INFORMATION

Wikipedia - RTMP

The Adobe RTMP Specification

The Adobe AMF0 Specification

The Adobe AMF3 Specification

SOFTWARE WORKSHOP SUPPORT
If you have any questions or have found an error, or would like more explanation of one of the items in the Software Workshop please contact Software Support.

Return to the Software Workshop.
Return to the Home Page.
Broccoli Products Ltd © 1998-2010 Broccoli Products Ltd
Reg Number: 2895355
Reg Office: 27 Old Gloucester Street, London. WC1N 3AX 		Bug Report Form Privacy Policy
Copyright Notice
Liability Disclaimer
Contact Us