This chapter shows you how to use the RealProducer ActiveX control to set up, start, monitor, and end an encoding session. The RealProducer ActiveX control allows you to access all of the properties and options available through the RealProducer and RealProducer Plus applications.
An easy way to use the ActiveX Control is to insert the control, named RealProducer Control, into your Automation Controller and then drag the control onto your form or dialog. Then, use the property browser and the custom property pages to control the settings for your RealProducer control.
To dynamically create the RealProducer ActiveX Control, you can use the ProgID with the CreateObject function (in Visual Basic) or the GUID with the CoCreateInstance function (Visual C++).
prodxctl.RealProducer Control
56919D41-BE39-11D2-A404-00104BDF4755
Using the ActiveX Control to control an encoding session involves the following steps:
The rest of this chapter will look into each of these steps in more detail.
Here is a sample application implemented in Visual Basic that illustrates each step. This example assumes that you have placed the RealProducer Control on your form, as well as two CommandButtons named cmdStart and cmdStop. For simplicity, the example does not include steps 3 and 4 (since they are optional).
Private Sub cmdStart_Click()
'Step 1: Load the settings from the last run of the RealProducer application
'(please see the next section for information on modifying settings)
ProducerControl1.LoadProducerSettings
'Step 2: Tell the RealProducer control to start encoding
ProducerControl1.StartEncoding
End Sub
Private Sub cmdStop_Click()
'Step 5: Stop encoding
If ProducerControl1.IsEncoding Then
ProducerControl1.StopEncoding
Else
MsgBox "Not Encoding Yet"
End If
End Sub
This section shows you how to use the ActiveX control to view and change settings that effect how the final RealMedia clip will be encoded.
To encode from an input file, set the property InputType to the value INPUT_SOURCE_FILE. Then set the property InputFilename to the name of the file you want to encode.
To capture audio and/or video from your input devices, set the property InputType to the value INPUT_SOURCE_CAPTURE. Then you can set the drivers that you want to use for capturing via the properties InputCaptureAudioDriver and InputCaptureVideoDriver.
If you want to encode audio, video, and/or events as part of your encoding session, you will need to set InputDoAudio, InputDoVideo, and InputDoEvents accordingly.
To create an output file, set the property DoOutputFile to True. Then set the OutputFilename to the name of the file you want to create. The filename should have an .rm extension. You can also set the temporary directory used during the encoding with the TempDirectory property.
To broadcast a stream directly to a server, set the property DoOutputServer to True. You must set the InputType to INPUT_SOURCE_CAPTURE if you are broadcasting to a server. Then set the ServerName, ServerPort, and ServerStream (the filename that users will use to access your stream from the server). You can also set the ServerUsername and ServerPassword if those are required to log into your server.
You can also set the transport used to broadcast to the server with ServerTransport. Use SERVER_TRANSPORT_UDP for UDP, which is recommended, or SERVER_TRANSPORT_TCP for TCP which can be broadcast through firewalls.
Clip Properties allow you to set the information that is stored in the file. Set your values for such properties as Title, Author, and Copyright just like you would in RealProducer.
Use the methods SetStringProperty() and SetNumberProperty() to add custom information to your RealMedia file. This information will be stored in the RealMedia file. You can view this information using the RMEditor command-line tool. Use GetStringProperty(), GetNumberProperty() and RemoveProperty() to manage custom properties you have added.
Target settings allow you to choose the target audiences and audio and video settings for your encoding. To select or deselect a target audience, set its property (for example: Target28KModem) to True or False.
To use SureStream encoding, set SureStream to True; otherwise, for Single rate encoding, set SureStream to False. Set your desired AudioContent and VideoQuality to one of the available settings.
If you would like your file or stream to be backwards compatible for 5.0 players, set PlayerCompatibility to PLAYER_5. Otherwise, set PlayerCompatibility to PLAYER_6. If you are encoding audio files to be streamed with other multimedia such as RealPix, set DoAudioOnlyMultimedia to True, otherwise, set DoAudioOnlyMultimedia to False.
To change the codecs or bit rates for a particular Target Audience, you can do so with the TargetAudience object. You can get a TargetAudience object using the TargetAudienceInfo() method. You need to pass in the desired target audience, TARGET_28_MODEM, TARGET_56_MODEM, etc.
For any Target Audience, you can set the Bitrate, MaxFrameRate, AudioCodec, and VideoCodec. When you set the AudioCodec, you need to indicate which type of content you want to use that audio codec for (audio-only content: TARGET_AUDIENCES_AUDIO, video only content: TARGET_AUDIENCES_VIDEO, or audio for multimedia: TARGET_AUDIENCES_MULTIMEDIA). You also need to indicate which audio format you want to use that audio codec for (voice, voice with background, music, stereo).
Below is an example of setting the bit rate for the LAN target audience to 450 Kbps.
'Get the TargetAudienceInfo for LAN
Dim LANAudience As TargetAudienceInfo
Set LANAudience = ProducerControl1.TargetAudienceInfo(TARGET_LAN_HIGH)
'Change the bitrate
LANAudience.TargetBitrate = 450
To change the codecs for any target audience, you will first want to find out which codecs are available. You will use the AudioCodecEnum and VideoCodecEnum properties of the RealProducer control to get a list of audio or video codecs. You can go through the list using the EnumIDispatch object which is returned. To reset the enumerators and get the first element in the list, use the First() method. Use the Next() method to enumerate through the list. Use GetCount() on these enumerators to find out how many codecs are available. Each element in the AudioCodecEnum will be an AudioCodecInfo object. Each element in the VideoCodecEnum will be a Video Codec Info object.
Here is an example of setting the Audio Codec for the 28K Modem target audience for music videos to 11 Kbps music.
'Get the TargetAudienceInfo for 28K Modem
Dim ModemAudience As TargetAudienceInfo
Set ModemAudience = ProducerControl1.TargetAudienceInfo(TARGET_28_MODEM)
'Get the Audio Codec list
Dim MyAudioCodecEnum As EnumIDispatch
Set MyAudioCodecEnum = ProducerControl1.AudioCodecEnum
'Get the first Audio Codec Info
Dim MyAudioCodec As AudioCodecInfo
Set MyAudioCodec = MyAudioCodecEnum.First
'Go through the codec list until we find the codec named
'"11 Kbps Music"
For i = 1 To MyAudioCodecEnum.GetCount - 1
If MyAudioCodec.CodecName = "11 Kbps Music" Then
Exit For 'we've found the desired codec
Else
Set MyAudioCodec = MyAudioCodecEnum.Next
End If
Next i
'Set the AudioCodec on the Target Audience Info for music videos
ModemAudience.AudioCodec(TARGET_AUDIENCES_VIDEO,AUDIO_CONTENT_MUSIC) = MyAudioCodec.CodecCookie
If you have changed the Target Audience settings, and want to revert all target audiences to the defaults, call the method RestoreTargetDefaults().
Video settings allow you to change the size of your video and crop your input video. To resize the video, set VideoResizingEnabled to True, and set the VideoOutputWidth and VideoOutputHeight to the desired values (in pixels). If you want the video to be the same size as the input, just set VideoResizingEnabled to False. To crop your video, set VideoCroppingEnabled to True, and set the crop rectangle: VideoCropLeft, VideoCropTop, VideoCropWidth, and VideoCropHeight.
To find out the size of the input video from the file or capture card, you need to first open the source, calling the OpenSource() method on the RealProducer Control. Once the source is open, call GetInputVideoSize() to get the width and height of the video (in pixels). To close the source without encoding, call the StopEncoding() method.
If the input source is a video capture card, you may want to allow the user to change the settings on the video capture card using the capture card's settings dialogs. You can show the video format dialog [ShowVideoCardFormatDialog()], the video source dialog [ShowVideoCardSourceDialog()], and the video compression dialog [ShowVideoCardCompressionDialog()]. You can only show these dialogs after you have called OpenSource(), and before you have called StartEncoding(). You cannot access these dialogs during encoding.
You can add events to your RealMedia stream. These events cause the RealPlayer to send URLs to the user's browser when the stream is played. You can also send events to change the Title, Author, or Copyright which appear in the RealPlayer. Events are added to on-demand files and broadcast streams in the same way.
To add events while you are encoding, set InputDoEvents to True before you start encoding. Then, add events to the file or stream using the SendRealMediaEvent() method. Timestamp and Duration are optional parameters of this function that specify when the event begins and how long the event lasts. The duration of an event only applies to live broadcasting. Users who start playing a stream after the event was sent, but still during the duration of the event, will receive the event. For on-demand clips, duration of an event is ignored.
The RealProducer ActiveX Control exposes a number of events that notify you of encoding progress. You can also access statistics about the streams that are created before you start encoding, and get updates of those statistics during the encoding.
The control sends events when encoding has started with OnEncodingStarted() or stopped with OnEncodingStopped(). When encoding files as your input, you will receive the OnEncodingStopped() event when the end of the file is reached.
During the encoding process and after every half-second of data, you receive an update of the encoding progress with the OnEncodingProgressChanged() event. This event will contain the following information:
You can access information about the streams that are being created during an encoding session. This information closely parallels the information shown on the Statistics dialog in RealProducer.
Before you start encoding, you can use UpdateStatistics() to force the stream lists to update based on the current target settings. If you change any of the target audiences, audio content, or video quality, call UpdateStatistics() before you access the stream information or it may not be correct. During encoding, statistics such as frame rate, bit rate, real-time performance, and latency are updated automatically.
A target stream is a stream for a particular target audience that includes an audio stream and a video stream (if you are encoding both audio and video). More than one target stream can share the same audio or video stream due to SureStream bandwidth management.
Access the target streams using the GetTargetStream() function, passing in the index for the stream you want the information for. The target streams are indexed starting from 0. Use the NumTargetStreams property to find out how many target streams there are.
Access the information about Audio and Video streams using the GetAudioStream() and GetVideoStream() functions. These streams are indexed starting from 0 as well. For video, the bit rate, frame rate, and latency will be updated automatically during the encoding. You can access the most recent information at any time during encoding.
Below is some sample code to iterate through the streams and add up the bit rates of all audio and video streams.
Dim TotalBits As Long
'Update the statistics with the latest stream information
ProducerControl1.UpdateStatistics
'Declare the variables we are passing to the statistics functions
Dim CodecName As String
Dim FrequencyResponse As Long, Latency As Long, Bitrate As Long
Dim Performance As Long, Quality As Long
Dim FrameRate As Single
Dim Compatible As Boolean
'Go through the Audio Streams to sum up all the bitrates
For i = 0 To ProducerControl1.NumAudioStreams - 1
ProducerControl1.GetAudioStream i, CodecName, Bitrate, FrequencyResponse, Latency, Performance, Compatible
TotalBits = TotalBits + Bitrate
Next i
'Go through the Video Streams to sum up all the bitrates
For i = 0 To ProducerControl1.NumVideoStreams - 1
ProducerControl1.GetVideoStream i, CodecName, Bitrate, FrameRate, Latency, Quality, Performance, Compatible
TotalBits = TotalBits + Bitrate
Next i
When any errors occur using the RealProducer ActiveX Control, these errors are returned to your application via the OnErrorOccurred() event. This event returns both an error code and an error string that is displayed to the user.
For example, when you call StartEncoding() but have not specified a valid input file, the error code returned will be 262210 and the error string will be "Invalid Source specified."
OnErrorOccurred() events may be triggered during the OpenSource(), StartEncoding(), or StopEncoding() functions. Errors will occur during OpenSource() or StartEncoding() if the RealProducer control has not been initialized correctly.
Errors may also occur at any time during the encoding if an error occurs, such as the server that was being broadcast to is no longer responding, or if the user runs out of disk space.