Helix DNA Producer ActiveX Control User Guide |
![]() |
Last Modified: March 26, 2004 |
1 Introduction
2 System Requirements
2.1 Supported Programming Environments
2.2 Supported Operating Environments
2.3 Control Identification
3 General Information
3.1 Loading the Producer ActiveX Control
3.2 Using Constants
3.3 Control Behavior
3.4 Distribution
3.5 Installation
3.6 Security
3.7 General Configuration
3.8 Controls
3.9 Audience Enumeration
3.10 Server Enumeration
3.11 Device Control
3.12 Statistics
3.13 Logging
3.14 Preferences
3.15 Testing
3.16 Samples
4 RealMedia Events
4.1 Event Components
4.2 Event Actions
4.3 Enabling Event
4.4 Client Behavior
4.5 File to File Encoding of Events
4.6 Capture Input and/or Broadcast Output (real-time) of Events
4.7 Specifying a Target Frame
5 Special Topics
5.1 Pixel Aspect Ratio Correction
6 Programming Reference
6.1 Version
6.2 Job Control
6.3 Job Information
6.4 Device Control
6.5 Event Handlers
6.6 Logging
6.7 Preferences
6.8 Audience and Server Enumeration
6.9 RealMedia Events
6.10 HelixDuration Object
6.11 Constants
6.12 Unsupported Options
1 Introduction |
[Back to Top] |
The Helix DNA Producer ActiveX SDK provides developers the option of accessing Helix DNA Producer functionality through the Visual Basic programming language or as COM objects from C++ on Windows for development of custom encoding applications. This SDK allows developers control that performs the functionality listed below:
Note: There are no methods provided to set specific settings within a Helix DNA Producer job file which defines encoding settings. Instead, the developer writing an application will use tools such as MS XML Parser or VB.NET XML parsing methods in order to get or set any properties of a job file XML and that job will be set as the input for the Helix Producer ActiveX Control.
Given the above feature set, the programmatic usage of the ActiveX control generally will consist of the following steps:
2 System Requirements |
[Back to Top] |
This section identify system requirements for the Helix DNA Producer ActiveX Control.
The following programming environments are supported by the Helix Producer ActiveX Control:
All VBA applications are supported but the following applications are tested
Any browser that supports ActiveX controls is supported but the following browsers are tested.
The Helix Producer ActiveX control will be identified by the following:
3 General Information |
[Back to Top] |
The Helix Producer ActiveX Control supports multiple instances of the control in the same process space. This means you can instantiate the Producer ActiveX control to run multiple jobs within the same application.
An instance of the control can be created in one of two ways:
To dynamically create an instance of 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++). For example, in Visual Basic or VBScript:
Dim ProducerObj As Object Set ProducerObj = CreateObject("helix.producer")
A good way to test if the Helix Producer control is loaded is "Not
IsNull( CreateObject("helix.producer") )
". This
will return true if the control is loaded and false if it is not.
For Visual Basic the following syntax loads the control dynamically:
Public producerobj As HelixProducerLibCtl.HelixProducer (VB6) Public producerobj As New HelixProducerLib.HelixProducer (VB.NET)
.NET IDE instructions:
1. run regsvr32.exe prodctrl.dll from the producersdk\bin directory
2. Launch .NET IDE
3. Select menu item Tools/Customize Toolbox
4. Under the COM components tab scroll down until you see HelixProducerLib
Class
5. Place a check in the box next to the control
6. Select OK
You should now see the Helix Producer ActiveX Control in the Toolbox
Visual Studio 6 IDE instructions:
1. run regsvr32.exe prodctrl.dll from the producersdk\bin directory
2. Launch Visual Studio 6 IDE
3. Open a project
4. Select menu item Projects/Components
5. Under the Controls tab scroll down until you see helix.producer
6. Place a check in the box next to the control
7. Select OK
You should now see the Helix Producer ActiveX Control in the Toolbox.
Helix Producer ActiveX Control exposes a number of constants to facilitate more portable and easier to read code. For example, logging categories are defined by one of the four enumerations:
This allows the string 'hxLogCategoryError' to be typed instead of the number "3". This makes the code more readable. Whenever possible, Helix Producer defined constants should be used. However, there are some cases where the pre-defined enumeration values for Helix Producer cannot be used. They are:
Imports HelixProducerLib.eProducerCrtlEventType
Imports HelixProducerLib.eEnumerationType
Imports HelixProducerLib.eLogCategory
For a complete list of constants, see Constants.
There are two target audiences for the ActiveX control.
To serve on these two users groups, the Helix DNA Producer ActiveX Control is distributed in the following ways:
Helix DNA Producer ActiveX SDK is packaged in one of two ways as described under the Distribution section above
The Helix Producer ActiveX Control Runtime installer is a single executable which can be downloaded and installed on a computer. This runtime takes care of installing the necessary files, registering the control and allowing the user the option to mark the control as safe for scripting. The runtime installer also allows the control to be uninstalled later through the Windows Add/Remove Programs control panel.
To install the ActiveX Control Runtime, simply download and run the installer from RealNetworks.com and step through the installation wizard.
The Helix Producer ActiveX SDK package is a compressed package that must be installed and registered by hand or along with some other application installer. This is intended for use by developers including the Helix DNA Producer ActiveX control in their applications. When using the control in this way, the developer is responsible to ensure that the files are installed correctly and the application is registered.
The Helix DNA Producer ActiveX control consists of a DLL and supporting libraries and files. The ActiveX control is included with the Producer SDK.
To install the ActiveX control provided with the SDK, download the SDK package, unpack it and include the contents of the 'bin' directory in your application directory. The helixprodctrl.dll requires other files located in the bin directory so make sure to keep the contents of the 'bin' directory intact.. Then register the file 'prodctrl.dll' using the method described below in Registering the ActiveX Control.
Note: If the Helix Producer ActiveX Control DLL is invoked but unable to find the corresponding components of the Producer SDK, an visual basic runtime error is raised.
To use the Helix DNA Producer ActiveX SDK, the ActiveX Control DLL must first be registered. To register the control, open a command prompt in the 'bin' directory (directory where helix prodctrl.dll is located) and type the following:
regsvr32.exe helixprodctrl.dll
Note: The helixprodctrl.dll dynamic library is bundled with the Helix DNA Producer SDK. The helixprodctrl.dll library can not be moved relative to the audiences, codecs, common, plugins, and tools directories. The ActiveX Control depends on other libraries located in these directories.
For security reasons, VBScript is not marked as safe for scripting by default though may be turned on by modifying a key in the Windows Registry as described below. As a result, the browser will prompt the user with a dialog saying "An ActiveX object maybe be unsafe. Do you want it to be initialized and accessed by the script?". This dialog box can be avoided if the control is marked safe for scripting. To mark the Producer control as safe for scripting, the following registry keys must be set:
The Helix Producer ActiveX Control installer distributed by RealNetworks provides an option for the user to mark the control as safe for scripting. This option is off by default.
The following settings are configurable
The following general controls are provided through the ActiveX control:
RealMedia events are discussed in more detail below.
In order to assist developers creating job files, the Helix Producer ActiveX Control will provide a method to obtain information about all audiences in the 'audiences' directory defined in the preference path settings. The list of audiences are returned as an array of strings of type variant. The index in this case has no special meaning.
Audience enumeration is only provided to aid ActiveX control developers in creation of job files. No methods are available for setting audiences on a job or modifying audience properties. The developer can use the audience enumeration information to present a list of pre-defined audiences to a user. To use one of the audiences, the developer must read the desired file directly from the audiences directory, copy the contents of the audience file and insert that XML into a job file prior to setting the job file as input for the ActiveX control.
For more information about audience enumeration, see Audience and Server Enumeration.
In order to assist developers creating job files, the Helix Producer ActiveX Control will provide a method to obtain information about all servers in the 'servers' directory defined in the preference path settings. The list of servers are returned as an array of strings of type variant. The index in this case has no special meaning.
Server enumeration is only provided to aid ActiveX control developers in creation of job files. No methods are available for setting servers on a job or modifying server properties. The developer can use the server enumeration information to present a list of pre-defined servers to a user. To use one of the servers, the developer must read the desired file directly from the servers directory, copy the contents of the server file and insert that XML into a job file prior to setting the job file as input for the ActiveX control.
For more information about audience enumeration, see Audience and Server Enumeration.
In order to assist developers creating job files, the Helix Producer ActiveX Control provides a method to enumerate a list of available devices on the computer it is being run on. Information included for each device will include:
Device enumeration is only provided to aid ActiveX control developers in creation of job files. No methods are available for setting devices on the Helix Producer ActiveX control. The developer is expected to use the device enumeration information in order to enter appropriate values in the capture input section of the job file.
A method is provided to load the device dialog for a given device. This allows the user to set the properties of a device dialog in a driver-specific manor. Any settings set in a call to the device dialog are applied to the current job in the current ActiveX Control instance. The job file is updated only when the device dialog for a device that is specified in the currently loaded job is called.
Note: For VFW devices, driver setting changes are applied system-wide and thus affect any subsequent encoding sessions unless those applications reset the driver settings. For WDM devices, driver setting changes only affect the current encoding session.
Note: Helix Producer will only set video frame width and height explicitly, all other settings assume the device defaults for WDM or the current state of the device when it was loaded for VFW devices. Video frame width and height must be included in the job file or modified by invoking the device dialog in order to be set explicitly by Helix Producer.
To ensure the job file is updated with changes made to the modal dialog, producer needs to maintain a handle on the dialog. For this reason, the dialog will be opened as modal. Any application using the Helix Producer form will not be accessible while the dialog is opened and any calls to the Helix Producer ActiveX Control while a device dialog is opened will result in the Helix Producer ActiveX control raising a runtime Visual Basic Error.
For more information about device enumeration, see Device Enumeration.
Helix Producer ActiveX control will expose the following information through the appropriate interfaces:
For more information about collecting statistics, see Event Handlers.
Logging output from Helix DNA Producer is available through the following methods:
The following file logging properties can be set directly from the ActiveX Control:
Setting the filename enables loggings. Setting the file to an empty string disables logging.
The following event callback logging properties can be set directly from the ActiveX Control:
For more information about controlling logging, see Logging.
The following preferences can be defined through the ActiveX control
For more information about setting user preferences, see Preferences.
Sample applications are provided in the 'samples' directory of the SDK. Samples are provided for the following development environments:
4 RealMedia Events |
[Back to Top] |
The ActiveX control allows RealMedia events to be added to an on-demand RealMedia file or inserted into a live broadcast stream. This section describes RealMedia events and how they are used through the ActiveX Control.
For more information about using RealMedia URL, Title, Author, Copyright and custom events, see RealMedia Events.
An event consists on two components:
Events are enabled in the Helix Producer ActiveX Control in one of two ways
Every event (static and live) has a start and end time. The end time may be specified explicitly by setting a duration or implicitly by leaving the duration as its default value of infinite. If a subsequent event is defined subsequently, the new event will take place of the last event as opposed to adding to the last event. That is, events should not overlap.
The information below describes the behavior when events are included in a media stream in a client playing the RealMedia content. The types of events described are title, author and copyright events (TAC) or URL events. TAC and URL events each have their own defined behavior which we simply describe below as "triggered". No action is triggered automatically in the client for custom events unless this is programmed through the client APIs.
The following section describes what actions occur on the client:
Note: The above behavior is supported because Helix Producer SDK repeats a each event every 3 seconds using the same sequence number until the end time of the event is past. The client will not trigger an event if it has already received an event with the same sequence number. Thus, only newly connected clients receiving this event will trigger the event and clients that have already received and triggered the event will not re-trigger the event.
Note: A bug exists today in where the behavior described in #2 above is not occurring for URL events. That is, a URL event is not triggered for clients connecting to a live stream after the event has been triggered. It would appear that the event is only being inserted into the media stream once but this needs further investigation. The plan is to fix this problem for 9.2 release of Helix DNA Producer if possible.
Note: A relatively low priority bug exists in the RealOne Player version 1 and version 2 where author and copyright RealMedia Events inserted by Producer show up in the Clip Info dialog and main window of the 8.x RealPlayers but not in v1 or v2 of the RealOne Player. The Title RealMedia Event does work in all versions. This only affects the above mentioned display regions of the RealOne Player and these same RealMedia events do trigger a callback in the RealOne Player ActiveX control which is the most prominent use case for TAC and URL RealMedia Events.
URL events provide a mechanism to trigger a web page to be loaded on playback. URL events can either be defined without a target frame in which case the event loads into a new browser window or it can be targeted to a specific frame in a browser or pane of the RealONE Player. This section documents how to specify URL events and how to target frames of a frame-based web page loaded in a browser or a specific pane of the 3-Pane RealONE Player. More information on RealMedia events can be found in Chapter 4 (Clip-Encoded URLs) of the Introduction to Streaming Media guide at http://service.real.com/help/library/encoders.html.
URL Events are specified by using an EventName of "EVENT_TYPE_URL" and the URL in the EventValue of the call to AddRealMediaEvent(). The string "EVENT_TYPE_URL" is a special trigger to tell the ActiveX control to insert a URL type event. The EventValue should be a URL. This URL is encoded into the RealMedia stream, delivered to the player and subsequently passed to the browser at the appropriate time.
URL events can be targeted either to a new browser window or to a specific frame of a multi-frame html page within the browser. They can also be targeted to one of the three panes in the 3 Pane RealONE Player. By default, URL events open a new browser window. However, a frame can be specified to target the URL event into a specific frame of a multi-frame HTML document or into the Context or Media Browser panes of the RealONE Player.
The following syntax targets a specific frame:
&&FRAME&&URL
Where:
URL events can be used with the embedded player or in the stand alone player.
When URL events are used with a presentation embedded within the browser, any frame, other than the current HTML frame, can be specified to load the URL into. For example, the frameset below
Video Frame | Slide Frame (frame=main) |
Table of Contents (frame=toc) |
In the example above, URL events containing URLs to slides to be synchronized with a presentation would be targeted to the Slide Frame (main). The EventValue for this would be &&main&&http://youserver.yourcompany.com/slides/slide1.htm where the string main between the double ampersands (&&) indicate that the URL should be loaded into the Slide Frame.
When URL events are used with a presentation playing in the RealONE Player, any pane of the RealONE Player, other than the Media Playback Pane, can be specified to load the URL into.
The RealONE Player is split into the following display regions:
The different panes of the RealONE Player identified above are shown in the graphic below:
The Context Pane, the Media Browser Pane and the Secondary Browser Windows are able to display HTML pages and other web technologies like Flash or Images. Basically, anything that can be displayed in a browser can be loaded into either of these windows.
You can control which pane of the RealONE player an event is loaded in by using the appropriate frame name for that pane. The following table lists the frame name for each of the relevant RealONE panes:
Pane | Frame Name |
Media Playback Pane | NA (See below) |
Context Pane | _rpcontextwin |
Media Browser Pane | _rpbrowser |
Secondary Browsing Window | _rpexternal |
For example, to load a URL into the Media Browser frame, EventType would be EVENT_TYPE_URL and the EventValue would be &&_rpbrowser&&http://youserver.yourcompany.com/slides/slide1.htm where the string _rpbrowser between the double ampersands (&&) indicate that the URL should be loaded into the Media Browser Pane.
The URL must be a fully qualified HTTP URL. For the parameters, you can use rpcontextheight and rpcontextwidth when sending a URL to the related info pane. For target, use one of the following:
For launching media, such as a Audio or video clip, no frame name is required. This is because media clips will always play back in the Media Playback Pane and there is no need to target that pane specifically. In some rare cases, content that would otherwise play back in the Media Playback Pane can be loaded into the Media Browser Pane by embedding that media in an HTML page and loading that HTML page in the Media Browser Pane using the frame name identified in the table above.
5 Special Topics |
[Back to Top] |
This section documents special topics for the Helix Producer ActiveX Control.
For more information about performing pixel aspect ratio correction, see the Video Resize Prefilter section of the job file reference in the Helix Producer Users Guide..
Pixel aspect ratio correction is a process of correcting for video that appears stretched in height or width from the original size. This section documents how to correct for Pixel Aspect Ratio with the Helix Producer ActiveX control and provides tips on a simple user interface that enables users to be able to correct for this problem.
The shape of the pixel is dependent on the video standard being used:
The term which describes this is pixel aspect ratio. It is specified as a fraction of vertical (y) pixel size divided by (x) horizontal pixel size. The pixel aspect ratio for square pixels is 1/1.
When video containing non-square pixels is transferred to computer, most capture cards perform the task of correcting the pixel aspect ratio by resizing the width of the image such that the shape of the pixels is square. For example, capture cards that transfer NTSC signals onto the computer resize video that is 720x486 (the NTSC standard) to 640x480 (actually, the height is not scaled by rather 6 pixels are cropped from the top and bottom).
When encoding content to RealVideo for display on computers, video should always be corrected to contain square pixels if it does not already contain square pixels. Even if the content is intended to be displayed on a TV screen, the video should still be encoded to square pixels since the RealOne Player always assumes the pixels are square. If the device RealOne Player is rendering onto contains non-square pixels, RealOne Player will resize the video before rendering to the screen.
Most devices used to capture analog video to the computer are designed to correct for non-square video pixel aspect ratios by resizing the image horizontally. It is only with devices that do not correct for pixel aspect ratio or for input files which have non-square pixels that pixel aspect ratio correction needs to be applied in Helix Producer.
Pixels in an ITU-R BT.601-4 digital video signal (also known as Rec. 601 and formerly CCIR 601) are non-square. That is, each pixel is intended to be take up a rectangular region of the screen. For 525-line Rec.601 video, the pixel aspect ratio is exactly 11/10 (y/x). For 625-line Rec.601 video, the pixel aspect ratio is exactly 54/59 (y/x).
Helix Producer allows non-square pixels to be corrected using a video resize prefilter. This prefilter is used to correct the pixel aspect ratio of the source video by applying a horizontal resize which resamples each horizontal line with the number of pixels necessary to result in square pixels. The prefilter should be configured with a new horizontal size (while maintaining the original input vertical size of the input source video) to correct for non-square pixel aspect ratios and result in a pixel aspect ratio of 1. If the input pixel aspect ratio is 1 (default) Helix Producer ActiveX control does nothing to correct pixel aspect ratio.
This is done by setting resized height to the original height divided by the pixel aspect ratio of the input. With Helix Producer ActiveX Control, the video resize filter is applied by adding the appropriate XML to a job file loaded with JobFilename or to the JobXMLString. The syntax of the Helix Producer Video Resize Prefilter is as follows:
<prefilter xsi:type="videoResizePrefilter"> <pluginName type="string">rn-prefilter-videoresize</pluginName> <enabled type="bool">true</enabled> <videoResizeWidth type="uint">320</videoResizeWidth> <videoResizeHeight type="uint">240</videoResizeHeight> <videoResizeQuality type="string">fast</videoResizeQuality> </prefilter>
To add the prefilter to a job, populate the text above with appropriate values for Width and insert the XML into the prefilters section of the job file under the desired input.
Pixel aspect ratios for various input types are described below. The section below also discussed as simple UI that allows users to choose from one of the standard pixel aspect ratios or modify to correct for non-standard pixel aspect ratios.
There are several common pixel aspect ratios for certain input source video formats as shown below:
Source | Pixel Aspect Ratio | Input Frame Size | Desired Output Frame Aspect Ratio |
Square Pixels | 1 | 640x480 or 648x486 | 4:3 |
4:3 NTSC | 1.125 | 720x480 or 720x486 | 4:3 |
4:3 PAL | 1.017 | 720x576 | 4:3 |
D1/DV NTSC | 0.9 | 720x480 or 720x486 | 4:3 |
D1/DV NTSC Widescreen | 1.2 | 720x480 or 720x486 | 16:9 |
D1/DV PAL | 1.0666 | 720x576 | 4:3 |
D1/DV PAL Widescreen | 1.4222 | 720x576 | 16:9 |
Anamorphic 2:1 | 2.0 | anamorphic | Use this setting if your video was shot using an anamorphic film lens. |
D4/D16 Standard | 0.9481481 | 1440x1024 or 2880x2048 | 4:3 |
D4/D16 Anamorphic 8:3 | 1.8962962 | 1440x1024 or 2880x2048 | 8:3 |
Thus, a user interface might have the following choices in a dropdown list:
Where the value of the drop down entry is the numeric value and the string is used as a guide to help the user pick the appropriate value.
While the above values will correct for standard non-square pixels, there are cases where the user may need the ability to adjust pixel aspect ratio to non-standard values. For instance, while NTSC video from DV cameras should contain a pixel aspect ratio of 11/10, there are many cameras for which this is not the case. In these cases, the user can only eye the source video to determine what the appropriate pixel aspect ratio should be. A good user interface should expose the list of choices above and also allow the user to enter their own pixel aspect ratio values.
References:
6 Programming Reference |
[Back to Top] |
This section documents the properties, methods and events available with the Helix DNA Producer ActiveX Control. It is broken out into the following sections.
6.1 Version |
[Back to Top] |
Properties and methods to get information about the control.
VersionString | [Top] - [Top of Section] |
Real-only property containing the full version of the Helix DNA Producer ActiveX Control as a string of 4 integers separated by periods (e.g. 9.2.0.250).
Default:
No Default
Data Type:
String
Values:
Dot separated string containing 4 integers representing the major, minor,
subminor and sub-subminor control version. This corresponds to the version
of the Helix DNA Producer that he ActiveX Control was released with.
Access:
Read-only
Examples:
' Visual Basic 6
If prodctrl.VersionString = "10.0.0.123" Then '
If the version is what we expected print a message
MsgBox "Huston, we have a liftoff"
End If
MajorVersion | [Top] - [Top of Section] |
Real-only property containing the major version of the Helix DNA Producer ActiveX Control as an integer. This is useful for using numeric comparisons to an expected major version.
Default:
No Default
Data Type:
Integer
Values:
Any valid Integer
Access:
Read-only
Examples:
' Visual Basic 6
If prodctrl.MajorVersion >= 10 Then ' If the
version is greater than or equal to what we expected
' Assume no audio or video preview
Else
' Code for controlling audio and video
preview
End If
MinorVersion | [Top] - [Top of Section] |
Real-only property containing the minor version of the Helix DNA Producer ActiveX Control as an integer. This is useful for using numeric comparisons to an expected minor version.
Default:
No Default
Data Type:
Integer
Values:
Any valid Integer
Access:
Read-only
Examples:
' Visual Basic 6
If prodctrl.MajorVersion >= 10 AND prodctrl.MinorVersion >= 0 Then '
If the version is greater than or equal to what we expected
' Use Method 1
Else
' Use Alternate Method
End If
6.2 Job Control |
[Back to Top] |
Properties and methods to configure, start and stop jobs.
There are two properties used to set the input encoding settings. They are JobFilename and JobXMLString. The JobFilename is used to load encoding settings from a Job File. The JobXMLString is used to set job settings from an XML string stored in memory. The later method, JobXMLString also offers a convenient way to access the XML set via either of the two properties.
JobFilename | [Top] - [Top of Section] |
Property to indicate a job file that will be used to define encoding settings. Setting this property causes the XML from the job file to be loaded into the JobXMLString property.
Writing to this property defines the job file that will be used when StartJob() is called. If the Producer ActiveX Control is already encoding, then an error is returned if this property is set. That is, the job file may only be set if the Producer ActiveX Control is not currently encoding.
If the job file being loaded is a valid XML job file but contains errors, the IsReady property is set to False and errors are reported through the log file or log events. If the file being loaded is not a valid Helix Producer job file or the file is missing, then the current job filename or job XML string is not changed and a catchable visual basic runtime error is raised. See the IsReady property for more information about handling errors when loading a job file.
Reading from this property will return the current job filename that is set if any. If no job filename set, this property returns an empty string. However, this does not mean that no job is defined. A job can be set via the JobXMLString property instead. To check if encoding settings have been defined, access the property JobXMLString which will return XML formatted text in the format of a Job File.
Default:
No Default
Data Type:
String
Values:
Any valid Filename
Access:
Read/Write
Examples:
' Visual Basic 6
prodctrl.JobFilename="C:\webcast.rpjf"
JobXMLString | [Top] - [Top of Section] |
Property to set/get the encoding settings as an XML formatted string. This property accepts a properly formatted XML string representing a valid Helix Producer job file. The JobXMLString may also be set via the JobFilename property. In this case, the XML contents of the job file specified becomes the contents of JobXMLString. Use this property to check if encoding settings have been defined or to programmatically define a job and set this job on the Helix Producer ActiveX Control.
Writing to this property defines the job file that will be used when StartJob() is called. If the Producer ActiveX Control is already encoding, then an error is returned if this property is set. That is, the job file may only be set if the Producer ActiveX Control is not currently encoding.
If the job XML being loaded is a valid XML job but contains errors, the IsReady property is set to False and errors are reported through the log file or log events. If the XML being loaded is not a valid Helix Producer XML job, then the current job XML string is not changed and a catchable visual basic runtime error is raised. See the IsReady property for more information about
Reading from this property will return the XML representing the current encoding settings. This property will return a valid job either if a job has been set on the JobFilename property or if XML has been set on the JobXMLString property.
Its important to note that the value returned by JobXMLString may not be the same value that was set on it. When this property is set, the XML passed is loaded into the SDK. When this property is requested, the XML is extracted from the SDK. If the SDK made any changes (such as populating a default value) while loading, the XML returned may differ from the XML that was set. Typically the SDK will not add a property to the job file but that is not always the case. If you need access to the original XML, store that separately.
Default:
No Default
Data Type:
String
Values:
Any valid XML formatted string representing a valid job file.
Access:
Read/Write
Examples:
' Visual Basic 6
Dim MyJobXML As String
' Load XML from XML DOM into MyJobXML
MyJobXML = JobDOM.documentElement.XML
' Commands to load properly formatted XML into MyJobXML
prodctrl.JobXMLString=MyJobXML ' Load contents of
MyJobXML into JobXMLString.
Note: Before loading XML into the JobXMLString property, it is a good
idea to perform validation on the job file using the Helix Producer XML
Schemas. Helix Producer XML Schemas are included in the Helix Producer SDK
distribution.
prodctrl.JobFilename = "C:\MyJob.rpjf" '
Load XML from job file into JobXMLString
Text1.Text = prodctrl.JobXMLString ' Display contents
JobXMLString in a Textbox
AudioGain | [Top] - [Top of Section] |
Property to set/get the audio gain level for the audio gain prefilter. This property can only be set when a job is loaded. If set when no job is loaded, an error is generated.
Changing the audio gain by a value of 6 has the effect of doubling the audio level. Thus, an audio gain setting of +12 would increase the audio strength by 4. Reducing the audio gain by a value of 6 has the effect of halving the audio levels.
The audio gain may be set to any valid double precision value. If set very low, the effect is to mute the audio. A value of -48 will effectively mute the audio. If set very high, the result is to increase the audio strength by the indicated value up to 0 dB but no further. Because digitized audio greater than 0 dB results in clipping, the audio gain will never increase the audio levels above 0 dB.
Default:
0
Data Type:
Double
Values:
Any 32 bit floating point value though only values from -48 to 48 inclusive are
recommended.
Access:
Read/Write
Examples:
' Visual Basic 6
prodctrl.JobFilename="C:\webcast.rpjf" '
Set input job file
prodctrl.AudioGain = 0 ' Set initial audio gain
to 0
prodctrl.StartJob ' Start loaded job
prodctrl.AudioGain = 6 ' Increase audio gain
to +6
StartJob( ) | [Top] - [Top of Section] |
Method to start loaded job. Can only be called after either JobFilename or JobXMLString have been called. If StartJob is called before setting the input job, this method throws an error.
Usage:
producerobject.StartJob
Return Value:
No Return value.
Examples:
' Visual Basic 6
prodctrl.JobFilename="C:\webcast.rpjf" '
Set input job file
prodctrl.StartJob( ) ' Start loaded job
StopJob( ) | [Top] - [Top of Section] |
Method to Stop running job. Can only be called while encoding. If StopJob is called while encoding is not in progress this method throws an error.
Usage:
producerobject.StopJob
Return Value:
No Return value.
Examples:
' Visual Basic 6
prodctrl.JobFilename="C:\webcast.rpjf" '
Set input job file
prodctrl.StartJob ' Start loaded job
prodctrl.StopJob ' Stop running job
CancelJob( ) | [Top] - [Top of Section] |
Method to cancel running job. When this method is called, encoding is stopped and all temporary files are discarded without generating output files. Can only be called while encoding. If CancelJob is called while encoding is not in progress this method throws an error.
Usage:
producerobject.CancelJob
Return Value:
No Return value.
Examples:
' Visual Basic 6
prodctrl.JobFilename="C:\webcast.rpjf" '
Set input job file
prodctrl.StartJob ' Start loaded job
prodctrl.CancelJob ' Cancel running job
ReleaseResources( ) | [Top] - [Top of Section] |
Method to stop all activities in the ActiveX control and release any system resources and close files. Useful to force producer to release all resources for use in C# where reference counting on the control results in the inability to release the control fully.
Be careful when using this method. Only use it when you are ready to close the control or otherwise loose all settings. After calling this method, the control will be reset to its default values when the control is initially loaded (including loosing all job file settings).
A catchable runtime error is returned if this method is called while a job is running.
Usage:
producerobject.ReleaseResources
Return Value:
No Return value.
Examples:
' Visual Basic 6
prodctrl.ReleaseResources() ' Release all
resources in preparation of closing the app
6.3 Job Information |
[Back to Top] |
Properties obtain information about the loaded job.
JobDuration | [Top] - [Top of Section] |
Read-only property to return the total duration in seconds of an encoding job. For file input encodes, this is the input file duration. For capture input, this is either the value -1 which represents infinite duration or the capture duration set explicitly in the encoding settings. Because file to file encodes may run faster or slower than real-time, the JobDuration does not provide a measure of how long the job will take to run.
If this property is called before job is set, it will return 0. If called any time after encoding settings are defined, it reports the value appropriate for the input job.
Default:
No Default
Data Type:
Double
Values:
Any positive 64 bit double value in units of seconds or a value of -1 which
represents infinity.
Access:
Read-only
Examples:
' Visual Basic 6
' First start a job
prodctrl.JobFilename="C:\webcast.rpjf"
prodctrl.StartJob ' Start loaded job
' Then show the current duration in its raw form
of seconds
MsgBox ProducerObj.JobDuration
' Or create a new duration object and display the
duration in hh:mm:ss format
Dim D as New Duration ' Create new duration object
D.Seconds = ProducerObj.JobDuration ' Get
Job Duration and assign to Duration object
MsgBox D.GetDurationAsString ' Prints job format in
dd:hh:ss.ms format
ElapsedDuration | [Top] - [Top of Section] |
Read-only property to return the current timestamp in seconds of the media being encoded. This property is useful for reporting elapsed encoding time (time since the StartJob command was executed) to a user during live capture or broadcast to server.
Because file to file encodes may run faster or slower than real-time, the ElapsedDuration does not provide a measure of how long the job has been running. Instead, it indicates what timestamp is currently being encoded. For this reason, the ElapsedDuration should not be used to indicate progress during file to file encoding. Instead, use the percentage value reported from the OnProgress event.
Note: During the merge phase, the ElapsedDuration is left as the highest reported value during the encoding phase.
Default:
No Default
Data Type:
Double
Values:
Any positive 64 bit double value in units of seconds or a value of -1 if the job
is not started or stopped.
Access:
Read-only
Examples:
' Visual Basic 6
' First start a job
prodctrl.JobFilename="C:\webcast.rpjf"
prodctrl.StartJob( ) ' Start loaded job
' Then show the current elapsed duration in its
raw form of seconds
MsgBox ProducerObj.ElapsedDuration
' Or create a new duration object and display the
elapsed duration in hh:mm:ss format
Dim D as New Duration ' Create new duration object
D.Seconds = ProducerObj.ElapsedDuration ' Get
Job Duration and assign to Duration object
MsgBox D.GetDurationAsString ' Prints job format in
dd:hh:ss.ms format
JobStartTime | [Top] - [Top of Section] |
Read-only property to return the system timestamp in seconds when encoding was started. This is most useful if you need to provide absolute timestamps to a RealText or RealPix live encoder which requires absolute timestamps for text or image transition times. Unless you need to synchronize with some out-of-process encoder like the RealText or RealPix encoders or other Producer audio or video encodes, this property can be safely ignored.
The JobStartTime can be combined with the ElapsedDuration in order to obtain the absolute current timestamp. This should only be done for values of ElapsedDuration obtained during the Encoding phase for real-time encodes. This value will always be 0 for file to file encoding.
When encoding live (capture input or broadcast output) Helix Producer uses absolute timestamps. That is, timestamps added to the live stream based on the current system clock time. Absolute timestamps are known as wallclock time. Wallclock timestamps are useful for synchronizing multiple live streams. Using the correct syntax in SMIL, multiple live streams generated by different encoders can be synchronized as long as the system clock on every encoder are in synch with each other.
Note: Absolute timestamps should not be used as input to the AddRealMediaEvent or AddCustomRealMediaEvent methods. These method expect a relative 0-based timestamp. To set an event at the current time or relative to it, use the ElapsedDuration property or return value from the OnProgress event.
This method generates a catchable Visual Basic runtime error if called before encoding is started or after encoding is done.
Default:
No Default
Data Type:
Double
Values:
Any positive 64 bit double value in units of seconds or a value of -1 which
represents infinity.
Access:
Read-only
Examples:
' Visual Basic 6
' First start a job
prodctrl.JobFilename="C:\webcast.rpjf"
prodctrl.StartJob( ) ' Start loaded job
' Get the current wallclock time
Dim AbsTimestamp as Double
AbsTimestamp = prodctrl.SystemStartTime + prodctrl.ElapsedDuration
' Make a call to an out-of-process RealText Encoder and
pass AbsTimestamp
IsRunning | [Top] - [Top of Section] |
Property to indicate if the currently loaded job is running. This is a convenience property since it is possible to know the exact state of the current job via the information returned by the OnProgress() method. This is useful to quickly determine if a job is currently executing.
Returns False if executed w/o a job loaded or if a job is loaded but not running.
Default:
No Default
Data Type:
Boolean
Values:
Any valid Boolean Value where:
Access:
Read-only
Examples:
' Visual Basic 6
MsgBox prodctrl.IsRunning ' Displays
"True" if a job is currently running and "False" if not
.
IsReady | [Top] - [Top of Section] |
Property to indicate if the currently loaded job is valid and ready to execute. IsReady will return True if the job is valid and is not encoding. If the job is running, contains invalid syntax or for some other reason is not ready (e.g. capture device input file or output file does not exist) the IsReady property returns False.
If the IsReady property returns False, a list of errors in the current job can be obtained by checking the errors received via the file or event callback log messages while loading the job.
Default:
Not
Data Type:
Boolean
Values:
Any valid Boolean Value where:
Access:
Read-only
Examples:
' Visual Basic 6
If prodctrl.IsReady Then prodctrl.StartJob
If prodctrl.IsReady And Not prodctrl.IsRunning '
Currently loaded job contains errors
MsgBox "Currently
loaded job contains errors. Please check log."
End If
6.4 Device Control |
[Back to Top] |
The Helix Producer ActiveX Control provides methods to query the system about available devices and invoke the audio and video driver specific configuration dialog in order to allow the use to manipulate device settings. This allows the following operations:
Changes to device port and video frame size made to the device dialog take effect immediately in the active job. These changes made are reflected in the JobXMLString as well.
Driver specific configuration dialogs are referred to by device name or device number as obtained from the GetAudioDevices() and GetVideoDevices() methods.
Methods
GetAudioDevices() | [Top] - [Top of Section] |
Returns a list of available audio devices on a machine. This is a helper function to facilitate building XML configuration files.
Usage:
object.GetAudioDevices
Return Value:
Array of strings of type Variant. Each entry in the array is a single device name.
The array index represents the device number which can also be used to refer to
the device. For example, the following list of devices might be returned
from a call to GetAudioDevices():
Examples:
' Visual Basic 6
Dim MyAudioDevices as Variant
MyAudioDevices = prodctrl.GetAudioDevices
For i = 1 To UBound(MyAudioDevices)
DeviceNum = i
DeviceName = MyAudioDevices(i)
' Add item to drop down list of audio
devices
cmbVideoDevices.AddItem DeviceName
Next
' User picks entry from drop down list
' Use this information to set the device information in
the job file
GetVideoDevices() | [Top] - [Top of Section] |
Returns a list of available video devices on a machine. This is a helper function to facilitate building XML configuration files.
Usage:
producerobject.GetVideoDevices
Return Value:
Array of strings of type Variant. Each entry in the array is a single device name.
The array index represents the device number which can also be used to refer to
the device. For example, the following list of devices might be returned
from a call to GetVideoDevices():
Examples:
' Visual Basic 6
Dim MyVideoDevices as Variant
MyVideoDevices = prodctrl.GetVideoDevices
For i = 0 To UBound(MyVideoDevices)
DeviceNum = i
DeviceName = MyVideoDevices(i)
' Add item to drop down list of video
devices
cmbVideoDevices.AddItem DeviceName
Next
' User picks entry from drop down list
' Use this information to set the device information in
the job file
GetAudioDeviceDialogNames( ) | [Top] - [Top of Section] |
Often, a device has more than one dialog that can be called. Method to obtain a list of names for the various dialogs that are available for the indicated audio device.
Usage:
producerobject.GetAudioDeviceDialogNames DeviceID
Where:
Argument | Type | Values | Description |
DeviceID | Long | Any integer starting from 0. | Integer identifying the device number that can be used to reference the device. Used to refer to the device within a job file by name. Numbering starts from 0. |
Return Value:
Array of strings of type Variant. Each entry in the array is a single dialog name for the
indicated audio device. For example, the following list of device dialog
names might be returned from a call to GetAudioDevices:
Examples:
' Visual Basic 6
' This example extends on the example for GetAudioDevices
' Assume user selects an item from the ComboBox of audio
devices
' Get the selected audio device ID
Dim DeviceNum As Integer
DeviceNum = cmbAudioDevices.ListIndex
' Store the list of audio devices in a variable
Dim MyAudioDeviceDialogs As Variant
MyAudioDeviceDialogs = prodctrl.GetAudioDeviceDialogNames(DeviceNum)
' Now populate the audio device dialog list
For i = 0 To UBound(MyAudioDeviceDialogs)
DeviceDialogNum = i
DeviceDialogName = MyAudioDeviceDialogs(i)
' Add item to drop down list of
audio devices dialog names
cmbAudioDeviceDialogNames.AddItem DeviceDialogName
Next
GetVideoDeviceDialogNames( ) | [Top] - [Top of Section] |
Often, a device has more than one dialog that can be called. Method to obtain a list of names for the various dialogs that are available for the indicated video device.
Usage:
producerobject.GetVideoDeviceDialogNames DeviceID
Where:
Argument | Type | Values | Description |
DeviceID | Long | Any integer starting from 0. | Integer identifying the device number that can be used to reference the device. Numbering starts from 0. |
Return Value:
Array of strings of type Variant. Each entry in the array is a single dialog name for the
indicated video device. For example, the following list of device dialog
names might be returned from a call to GetVideoDevices():
Examples:
' Visual Basic 6
' This example extends on the example for GetVideoDevices
' Assume user has selected an item from the ComboBox of
video devices
' Get the selected video device ID
Dim DeviceNum As Integer
DeviceNum = cmbVideoDevices.ListIndex
' Store the list of video devices in a variable
Dim MyVideoDeviceDialogs As Variant
MyVideoDeviceDialogs = prodctrl.GetVideoDeviceDialogNames(DeviceNum)
' Now populate the video device dialog list
For i = 0 To UBound(MyVideoDeviceDialogs)
DeviceDialogNum = i
DeviceDialogName = MyVideoDeviceDialogs(i)
' Add item to drop down list of
video devices dialog names
cmbVideoDeviceDialogNames.AddItem DeviceDialogName
Next
LoadAudioDeviceDialog( ) | [Top] - [Top of Section] |
Method to load the audio device specific configuration dialogs returned by the GetAudioDeviceDialogs method. Generally there are two such dialogs: the Recording Mixer and the Vendor-Provided Controls.
This method can be called at any time and does not require a loaded job file. If a job file containing the device for which the device dialog was called is loaded, changes made to the device dialog settings will be updated in the currently loaded job. These changes will also be reflected in the JobXMLString.
To ensure the job file is updated with changes made to the settings dialog, the dialog is opened as a modal dialog. As typically the case with modal dialogs, while the dialog is opened all calls to the Helix Producer ActiveX Control will be queued and executed once the dialog is closed. The user will not be able to interact with the application (as long as its single threaded or the UI is in the same thread that the call was made from) until the dialog is closed.
Note: When loading the "Recording Mixer", the call to LoadDeviceDialog is modless. The recording mixer control panel is called as an executable and is run out-of-process and thus executes in a different process space.
Usage:
producerobject.LoadAudioDeviceDialog DeviceID, DialogName
Where:
Argument | Type | Values | Description |
DeviceID | Long | Any integer starting from 0. | Integer identifying the device number that can be used to reference the device. Numbering starts from 0. |
DialogName | String | Any string | String identifying a descriptive title reported by the
audio device. Standard values are:
|
Return Value:
No Return value.
Examples:
' Visual Basic 6
' This example extends on the example for GetAudioDeviceDialgoNames
' Assume user has selected an item from the ComboBox of
audio devices and device names
' Get the selected audio device ID
Dim DeviceNum As Integer
DeviceNum = cmbAudioDevices.ListIndex
' Get the selected audio device dialog name
Dim DeviceDialogName As String
DeviceDialogName = cmbAudioDeviceDialogNames.Text
' Load the device dialog for that device
prodctrl.LoadAudioDeviceDialog DeviceNum, DeviceDialogName
If you know the name of the dialog you are trying to access, you can
call this directly. For example:
' Load the device dialog using a string literal
LoadAudioDeviceDialog 0, "Recording Mixer"
LoadVideoDeviceDialog( ) | [Top] - [Top of Section] |
Method to load the video device specific configuration dialogs returned by the GetVideoDeviceDialogs method.
This method can be called at any time and does not require a loaded job file. If a job file containing the device for which the device dialog was called is loaded, changes made to the device dialog settings will be updated in the currently loaded job. These changes will also be reflected in the JobXMLString.
To ensure the job file is updated with changes made to the settings dialog, the dialog is opened as a modal dialog. As typically the case with modal dialogs, while the dialog is opened all calls to the Helix Producer ActiveX Control will be queued and executed once the dialog is closed. The user will not be able to interact with the application (as long as its single threaded or the UI is in the same thread that the call was made from) until the dialog is closed.
Usage:
producerobject.LoadVideoDeviceDialog DeviceID, DialogName
Where:
Argument | Type | Values | Description |
DeviceID | Long | Any integer starting from 0. | Integer identifying the device number that can be used to reference the device. Numbering starts from 0. |
DialogName | String | See table below. | String identifying a descriptive title reported by the
video capture device. Standard values are:
|
Return Value:
No Return value.
Examples:
' Visual Basic 6
' This example extends on the example for GetVideoDeviceDialgoNames
' Assume user has selected an item from the ComboBox of video
devices and device names
' Get the selected video device ID
Dim DeviceNum As Integer
DeviceNum = cmbVideoDevices.ListIndex
' Get the selected video device dialog name
Dim DeviceDialogName As String
DeviceDialogName = cmbVideoDeviceDialogNames.Text
' Load the device dialog for that device
prodctrl.LoadVideoDeviceDialog DeviceNum, DeviceDialogName
If you know the name of the dialog you are trying to access, you can
call this directly. For example:
' Load the device dialog using a string literal
LoadVideoDeviceDialog 0, "VfW Video Format"
6.5 Event Handlers |
[Back to Top] |
Helix Producer ActiveX Control reports events that occur within the application using a set of predefined functions known as event handlers. You can use the event handlers presented here in your ActiveX Control to intercept and interpret Helix Producer events, such as capturing progress reports, errors, or log messages. The following summarizes the available events.
OnJobStarted( ) | [Top] - [Top of Section] |
Event handler called when encoding has started successfully.
Usage:
producerobject.OnJobStarted
Examples:
' Visual Basic 6
Sub procctrl1_OnJobStarted( )
StatusBar1.SimpleText = "Encoding ..." '
Update status bar in user interface
End Sub
OnJobDone( ) | [Top] - [Top of Section] |
Event handler called when encoding has finished successfully.
This method is not called if the StopJob or CancelJob is called. If UI state needs to be updated at the end of an encode, make sure to do so in the methods that execute the StopJob or CancelJob methods explicitly instead of depending on the OnJobDone method. The best way to do this is to have the OnJobDone method call a common method that actually cleans up UI state.
Usage:
producerobject.OnJobDone
Examples:
' Visual Basic 6
Sub prodctrl1_OnJobDone( )
StatusBar1.SimpleText = "Encoding Done." '
Update status bar in user interface
End Sub
OnEvent( ) | [Top] - [Top of Section] |
Generic Event handler called for all events not handled by other specific callback methods.
For error handling, use this function. For handling specific errors use the OnLogMessage callback function.
Usage:
producerobject_OnEvent(EventType, EventXMLInfo, ErrorInfo)
Where:
Argument | Type | Values | Description |
EventType | EventTypeEnum | See table below. | Integer identifying the event for the list of EventTypeEnum enumerations. |
EventXMLInfo | String | See table below. | String in XML format passing additional information about the event. |
ErrorInfo | String | String containing description of error. | ErrorInfo will contain a more detailed text message regarding an error if the event is an error type event. This string is propagated from the source code where the error occurred. Not all errors will contain ErrorInfo. |
Event Types:
EventType Constant Name | EventType Constant Value | EventXMLInfo Contents | Description | |
Two Pass Analysis Started | hxEventTwoPassAnalysisStarted | 2 | Null | Triggered at the start of the first pass (analysis phase) of a 2-pass encode. |
Two Pass Analysis Finished | hxEventTwoPassAnalysisFinished | 3 | Null | Triggered at the end of the first pass (analysis phase) of a 2-pass encode. |
Two Pass Encoding Using Analysis Started | hxEventTwoPassEncodingUsingAnalysisStarted | 4 | Null | Triggered at the start of the second pass (encoding phase) of a 2-pass encode. |
Two Pass Encoding Using Analysis Finished | hxEventTwoPassEncodingUsingAnalysisFinished | 5 | Input configuration data | Triggered at the end of the second pass (encoding phase) of a 2-pass encode. |
Destination Started | hxEventDestinationStarted | 120 | Destination configuration data | Triggered for each output destination when it is started. This occurs once for each destination at the start of the encode. Future releases may support sequential destinations or destinations that start at absolute times after the start of the encode which is the primary reason for this event. There should be no reason to look for this event at this time. |
Destination Listening | hxEventDestinationListening | 126 | Destination configuration data | Occurs once for each pull broadcasting connection. Actual connections from a server are reported in the hxEventDestinationBroadcasting event (use OnJobDone instead) |
Destination Broadcasting | hxEventDestinationBroadcasting | 125 | Destination configuration data | Occurs whenever a server makes a connection to the pull split feed. |
Destination Reconnecting | hxEventDestinationReconnecting | 126 | Destination configuration data | Occurs if the server disconnects from the live stream unexpectedly and the TCP mode of pull broadcasting is in use. See reconnect support in the server documentation. |
Destination Finished | hxEventDestinationFinished | 122 | Destination configuration data | Occurs once for each destination at the end of the encode. Intended for support of multiple sequential destinations or destination scheduling. There should be no reason to look for this event at this time (use OnJobDone instead). |
Destination Error | hxEventDestinationError | 123 | Destination configuration data | This error occurs when an error is thrown in an output
destination. The following are errors that may get thrown.
|
Examples:
' The following handles different broadcast
conditions and writes message to status bar called 'StatusBar1'.
Sub proctrl1_OnEvent( Event as Long, XML as String, Err as String )
' Use Select Case statements to catch
specific error codes.
Select Case e
Case hxEventDestinationError
'
Parse contents of xml if desired to print server info
StatusBar1.SimpleText = "Error in destination."
Case hxEventDestinationBroadcasting
StatusBar1.SimpleText = "Server Connected."
Case hxEventDestinationReconnecting
StatusBar1.SimpleText = "Server Reconnecting."
Case hxEventDestinationListening
StatusBar1.SimpleText = "Waiting for Server Connection."
End Select
End Sub
OnProgress( ) | [Top] - [Top of Section] |
Event handler called for all progress events. This method allows the encoding progress to be displayed to a user. Encoding may have up to three different phases and occur in real-time (in which case a duration is useful in reporting the progress) or nonlinear (in which case a percentage value is useful in reporting the progress). The following table outlines the different phases of encoding for real-time and nonlinear encoding. Use this table as a guide to what to display as status to a user.
Activity | Phase | Status | |
Finite | File to File | Analyzing |
Analyzing:###% |
Encoding |
Encoding: ELAPSED/TOTAL (###%) |
||
Merging |
Merging:###% |
||
File to Server | Analyzing |
NA |
|
Encoding |
Encoding: ELAPSED/TOTAL (###%) |
||
Merging |
Merging:###% |
||
Device w/duration to File | Analyzing |
NA |
|
Encoding |
Encoding: ELAPSED/TOTAL (###%) |
||
Merging |
Merging:###% |
||
Device w/duration to Server | Analyzing |
NA |
|
Encoding |
Encoding: ELAPSED/TOTAL (###%) |
||
Merging |
Merging:###% |
||
Infinite | Device to File | Analyzing |
NA |
Encoding |
Encoding: ELAPSED |
||
Merging |
Merging: ###% |
||
Device to Server | Analyzing |
NA |
|
Encoding |
Encoding: ELAPSED |
||
Merging |
Merging: ###% |
Where:
Usage:
producerobject_OnProgress ( EventType, PercentProgress, DurationProgress,
ProgressXMLInfo)
Where:
Argument | Type | Values | Description |
EventType | ProgressEventTypeEnum | See table below. | Integer identifying the event from the list of ProgressEventTypeEnum enumerations. |
PercentProgress | Long Integer | Integer from 0 to 100 or -1 for infinite | An integer representing the percent completed for the current phase. |
DurationProgress | Double | Number of seconds as any positive double value. | The number of seconds since the start of the current progress event type. Reported as 0 during the Merge stage. |
ProgressXMLInfo | String | See table below. | String in XML format passing additional information about the event. |
Progress Event Types:
Progress Event | ProgressEventType Enumeration Name | ProgressEventType Enumeration Value | EventXMLInfo Contents |
Analysis Progress | hxAnalysisProgress | 6 | Null |
Encode Progress | hxEncodeProgress | 7 | Null |
Destination Merge Progress | hxDestinationMergeProgress | 121 | Destination configuration data |
Examples:
' The following handles progress status
messages.
Private Sub prod_OnProgress(ByVal eEventType As eProducerCrtlEventType, ByVal lPercentProgress As Long, ByVal lfTimeInSeconds As Double, ByVal bstrProgressXMLInfo As String)
Dim JobDur As String
'
Update the progress bar
If prodctrl.JobDuration < 0 Then
If ctlProgressBar.Value < 100 Then
ctlProgressBar.Value = ctlProgressBar.Value + 10 Else ctlProgressBar.Value = 10
Else
ctlProgressBar.Value = lPercentProgress
End If
'
Determine the total job duration
If prodctrl.JobDuration < 0 Then JobDur = "Infinite" Else JobDur =
prodctrl.JobDuration
' Convert
the elapsed duration as reported by OnProgress to a duration object so we can
print as colon separated string
Dim D As New HelixDuration
D.SetDuration 0, 0, 0, lfTimeInSeconds
' Update
the stats bar with the current encoding mode, elapsed and total duration
If eEventType = hxEventAnalysisProgress Then
StatusBar1.SimpleText = "Analyzing... Elapsed/Total Time: " & D.GetDurationAsString & " / " & JobDur
ElseIf eEventType = hxEventEncodeProgress Then
StatusBar1.SimpleText = "Encoding... Elapsed/Total Time: " & D.GetDurationAsString & " / " & JobDur
Else
StatusBar1.SimpleText = "Merging..."
End If
End Sub
6.6 Logging |
[Back to Top] |
Properties and methods to control logging to file or log events.
LogFilename | [Top] - [Top of Section] |
Property to designate the filename where log messages are written. Log messages can be written directly to file in addition to being passed via the event handler OnLogMessage. This is a convenience function to allow log messages to be written directly to file.
Setting this value to a valid filename causes log messages to be written to file. Not setting this value or setting the value to an empty string disables logging. If the file cannot be written to, an, an error is logged via the OnLogMessage call when encoding is started but encoding proceeds.
Default:
No Default.
Data Type:
String
Values:
Any valid String value.
Access:
Read/Write
Examples:
' Visual Basic 6
prodctrl.LogFilename = "C:\producer.log"
LogFileCategory | [Top] - [Top of Section] |
Property to designate the logging category used to filter what log messages are written to file. Log category is either error, warning, info or diagnostic.
Setting this property does not ensure that log messages are written to file. The property DoLogFile and LogFilename must also be set to enable logging to file.
Default:
"ERROR,INFO".
Data Type:
String
Values:
A comma separated list of either ERROR, WARNING, INFO or DIAGNOSTIC.
Access:
Read/Write
Examples:
' Visual Basic 6
prodctrl.LogFileCategory = "ERROR,WARNING,INFO,DIAGNOSTIC"
prodctrl.LogFileCategory = "DIAGNOSTIC"
LogEventsCategory | [Top] - [Top of Section] |
Property to designate the logging category used to filter log message events are passed to the OnLogMessage() event handler. Log category is either Error, Warning, Info or Diagnostic.
Setting this property does not ensure that log message events are returned. The property DoLogEvents must also be set to enable log events.
Default:
"Error,Warning".
Data Type:
String
Values:
A comma separated list of either Error, Warning, Info or Diagnostic.
Access:
Read/Write
Examples:
' Visual Basic 6
prodctrl.LogEventsCategory = "ERROR,WARNING,INFO,DIAGNOSTIC"
prodctrl.LogEventsCategory = "DIAGNOSTIC"
DoLogEvents | [Top] - [Top of Section] |
Property to indicate whether or not log message events are passed to the OnLogMessage() event handler. If log messages events are not going to be handled (i.e. there is no OnLogMessage() subroutine defined) then this should be set to False to conserve system resources. Setting this to true means that Helix Producer ActiveX control will register to receive log messages from the Helix Producer engine and, if available, propagate those to the OnLogMessage function.
This message is provided for performance reasons. To understand why, it is helpful to understand how log messages work within the Helix Producer architecture. Helix Producer has a generalized system for handling logging. A central hub receives messages from any of the Helix Producer plug-ins that act as log publishers. For example, an file or capture input plug-in might report problems about a source file or an output plug-in might issue warning about disk full conditions. These messages are passed to the central hub. Any messages in the central hub can be subscribed to by an log message observer. The ActiveX Control implements two log message observers. One is a logging to file observer (enabled by the DoLogFile property) and the other is a log message events observer (enabled by the DoLogEvents observer). Both of these log observers are independent of one another. Each observer will consume a certain amount of system resources (CPU and memory) when it is enabled. This is because, when enabled, the observer will receive messages from the central hub and will need to copy these into a buffer of its own as well as deliver them to its destination. The logging category for each of these observers (LogFileCategory and LogEventsCategory) helps to reduce the system resource requirements by setting properties on the log hub to filter log messages before they are passed to the observer. For frequent log messages like Diagnostic, this can have a significant effect on system resource requirements. For infrequent messages like Error, Warning and Info, this impact is negligible.
Default:
False
Data Type:
Boolean
Values:
Any valid Boolean Value where:
Access:
Read/Write
Examples:
' Visual Basic 6
prodctrl.DoLogEvents = True
FlushLog() | [Top] - [Top of Section] |
Method to flush all log messages to file. Useful if the log file must be rolled or otherwise accessed.
Usage:
producerobject.FlushLog
Return Value:
No return value
Examples:
' Visual Basic 6
prodctrl.FlushLog
OnLogMessage( ) | [Top] - [Top of Section] |
Event handler called for all log messages.
Usage:
producerobject_OnLogMessage( MessageNumber, MessageString, Timestamp, LogCategory)
Where:
Argument | Type | Values | Description |
MessageNumber | Long Integer | See table below. | Integer identifying the log message number. See logmessages.xml in the 'resources' directory of Helix Producer for a complete list of log messages. |
MessageString | String | A string with maximum length of 255 characters. | Log message providing a summary of the issue or problem that is being reported suitable for display to the end user. |
Timestamp | Date | Object of type Date | A visual basic Date object. See Examples below for helpful tips on how to format dates in Visual Basic. |
LogCategory | LogCategoryEnum | Any one of the Log Category enumeration constants or the equivalent integer described below. | Constant or equivalent integer identifying the logging
category. Log category identifies the level of importance and the volume
of occurrence of a given message type. Categories are:
|
Log Category enumeration constants:
Log Category Enumeration Name | Enumeration Value |
hxLogCategoryDiagnostic | 0 |
hxLogCategoryInfo | 1 |
hxLogCategoryWarning | 2 |
hxLogCategoryErrors | 3 |
Examples:
' The following handles different log messages.
Sub OnLogMessage( MessageNumber as Long, MessageString as Long, Timestamp as
Date, LogCategory as LogCategoryEnum )
' Append message to an MSFlexGrid
control called 'flexgridScreenLog
flexgridScreenLog.AddItem Join(Array(JobName, Time, Level, Msg),
",")
End Sub
6.7 Preferences |
[Back to Top] |
This section provides access to preferences.
Properties
TempDirectory | [Top] - [Top of Section] |
Property to designate a directory where temporary files are written. File are written to the temporary directory during encoding and moved to the target directory at the end of the merge process. If the temporary directory is on a different drive than the target location, a performance penalty may be incurred.
Note : TempDirectory not validated until the StartJob method is called (at which point, if there are problems, a warning will be logged if the DoLogFile or DoLogEvents properties are enabled). Validation of the TempDirectory is recommended before setting this property in the Helix Producer ActiveX Control or before executing the StartJob method.
Default:
%TEMP%
Data Type:
String
Values:
One of the following values:
Access:
Read/Write
Examples:
' Visual Basic 6
prodctrl.TempDirectory = "%OUTPUT%"
prodctrl.TempDirectory = "C:\Temp"
AudiencesDirectory | [Top] - [Top of Section] |
Property to designate a directory where audience files are located. This property is used by the audience enumeration function to locate audience definitions. If used, relative paths are interpreted relative to the working directory but absolute paths are preferred.
This property must be set before calling the GetAudiences() method or an error is returned.
Note : AudiencesDirectory not validated until the GetAudiences method is called (at which point, if there are problems, a warning will be logged if the DoLogFile or DoLogEvents properties are enabled). Validation of the AudiencesDirectory is recommended before setting this property in the Helix Producer ActiveX Control or before executing the GetAudiences method.
Default:
No Default
Data Type:
String
Values:
Any valid directory name and path.
Access:
Read/Write
Examples:
' Visual Basic 6
prodctrl.AudiencesDirectory = "C:\Program Files\Real\Helix
Producer\audiences"
prodctrl.AudiencesDirectory = App.Path & "\audiences" '
The directory 'audiences' in the application root directory
ServersDirectory | [Top] - [Top of Section] |
Property to designate a directory where server files are located. This property is used by the server enumeration function to locate server definitions. If used, relative paths are interpreted relative to the working directory but absolute paths are preferred.
This property must be set before calling the GetServers() method or an error is returned.
Note : ServersDirectory not validated until the GetServers method is called (at which point, if there are problems, a warning will be logged if the DoLogFile or DoLogEvents properties are enabled). Validation of the ServersDirectory is recommended before setting this property in the Helix Producer ActiveX Control or before executing the GetServers method.
Default:
No Default
Data Type:
String
Values:
Any valid directory name and path.
Access:
Read/Write
Examples:
' Visual Basic 6
prodctrl.ServersDirectory = "C:\Program Files\Real\Helix
Producer\Servers"
prodctrl.ServersDirectory = App.Path & "\servers" '
The directory 'servers' in the application root directory
CodecMappingFilename | [Top] - [Top of Section] |
The location of the codec mapping file used to define the mapping of old codecs to new. If set to a valid filename, audiences are updated to the latest codecs. If null or set to an invalid file, no changes are made to the codecs which may result in a job file being rejected if codecs that are no longer available are specified.
A sample codec mapping file is included with the ActiveX control that specifies a mapping for Helix Producer 9 to RealProducer 10 codecs including AAC.
If this property is set to an invalid codec mapping file (file does not exist or contains invalid syntax), an runtime error is raised by the control which must be handled by the On Error method.
Relative paths are interpreted relative to the Helix Producer ActiveX Control location. UNC and mapped drive paths are supported in addition to local drive letters.
Default:
Null String
Data Type:
String
Values:
Any valid Filename
Access:
Read/Write
Examples:
' Visual Basic 6
prodctrl.JobFilename = "resources\codecmapping.txt"
6.8 Audience and Server Enumeration |
[Back to Top] |
This section documents methods to help in identifying saved audiences and servers. Helix DNA Producer ActiveX Control ships with a set of pre-defined audiences. These are located in the audiences directory. Additional audiences or servers may be defined and saved to the audiences or servers directory respectively. These new audiences and servers will then be available in subsequent calls to GetAudiences() or GetServers().
The location of the audiences and servers directory is documented in the Preferences section above.
Methods
GetAudiences() | [Top] - [Top of Section] |
Returns a list of available audiences on a machine. This is a helper function to facilitate building XML configuration files.
Usage:
producerobject.GetAudiences( )
Return Value:
Array of strings of type Variant. Each entry in the array stores the XML from a single
audience. For example, the following list of audiences might be returned
from a call to GetAudiences():
MyAudiences(0) '<audience ...>
<name type="string">28k
Modem</name>
<avgBitrate type="uint">20000</avgBitrate>
. . .
</audience>'
MyAudiences(1) '<audience ...>
<name type="string">56k
Modem</name>
<avgBitrate type="uint">34000</avgBitrate>
. . .
</audience>'
. . .
Examples:
' Visual Basic 6
prod.AudiencesDirectory = AbsPath(GetPref("AudiencesDirectory", "audiences"))
' Create variant array to store list of audiences
Dim MyAudiences As Variant
MyAudiences = prod.GetAudiences
' Declare an MSXML DOM Parser to load and parse audiences
Dim XMLDOM As New DOMDocument40, i As Integer
' Turn off Validation since GetAudiences will do that
XMLDOM.validateOnParse = False
For i = 0 To UBound(MyAudiences)
' Use MSXML Parser to extract Name
DevLogMsg "Audience i: " & MyAudiences(i)
XMLDOM.loadXML MyAudiences(i)
' Loop thru each of the child nodes in the audiences to find the 'name' element
Dim ChildNode As IXMLDOMNode, Name As String
For Each ChildNode In XMLDOM.documentElement.childNodes
' If we find the name element, extract the audience name
If ChildNode.nodeName = "name" Then
Name = ChildNode.Text
End If
Next
If IsEmpty(Name) Then Name = "Unknown"
' Add name property to drop down list
lstAudiences.AddItem Name
Next
GetServers() | [Top] - [Top of Section] |
Returns a list of available servers on a machine. This is a helper function to facilitate building XML configuration files.
Usage:
producerobject.GetServers( )
Return Value:
Array of strings of type Variant. Each entry in the array stores the XML from a single
server. For example, the following list of servers might be returned from
a call to GetServers():
MyServers(0) '<server>
<name type="string">Server 1</name>
<address
type="string">server1.company.com</address>
. . .
</server>'
MyServers(1) '<server>
<name type="string">Server 2</name>
<address
type="string">server2.company.com</address>
. . .
</server>'
. . .
Examples:
' Visual Basic 6
prod.ServersDirectory = AbsPath(GetPref("ServersDirectory", "servers"))
' Create variant array to store list of servers
Dim MyServers As Variant
MyServers = prod.GetServers
' Declare an MSXML DOM Parser to load and parse servers
Dim XMLDOM As New DOMDocument40, i As Integer
' Turn off Validation since GetServers will do that
XMLDOM.validateOnParse = False
For i = 0 To UBound(MyServers)
' Use MSXML Parser to extract Name
DevLogMsg "Audience i: " & MyServers(i)
XMLDOM.loadXML MyServers(i)
' Loop thru each of the child nodes in the
servers to find the 'name' element
Dim ChildNode As IXMLDOMNode, Name As String
For Each ChildNode In XMLDOM.documentElement.childNodes
' If we find the name element, extract the audience name
If ChildNode.nodeName = "name" Then
Name = ChildNode.Text
End If
Next
If IsEmpty(Name) Then Name = "Unknown"
' Add name property to drop down list
lstServers.AddItem Name
Next
6.9 RealMedia Events |
[Back to Top] |
Properties and methods to add RealMedia events to the output.
EnableRealMediaEvents | [Top] - [Top of Section] |
Property to indicate whether or not RealMedia events are enabled.
When this property is True, a RealMedia events stream will be added to any jobs loaded. Use this property to enable the AddRealMediaEvent or AddCustomRealMediaEvent methods during an encoding session. Once set, this property remains set for any jobs loaded during that session.
If this property is False, a RealMedia event stream will not be added to each output and any calls to the AddRealMediaEvent or AddCustomRealMediaEvent will result in an error.
This property must be set before StartJob is called or it will return an error.
Default:
False
Data Type:
Boolean
Values:
Any valid Boolean Value where:
Access:
Read/Write
Examples:
' Visual Basic 6
prodctrl.EnableRealMediaEvents = True
AddRealMediaEvent( ) | [Top] - [Top of Section] |
Method to add RealMedia events to the output RealMedia files. RealMedia events are strings inserted into the media stream at a specific timestamp. RealMedia events have pre-defined actions in the player as described below. Can only be called when EnableRealMediaEvents is True. If EnableRealMediaEvents is False or not set this method throws an error.
When adding events with the value of -1 for StartTime just after StartJob has been called, there is a chance that event will be specified with a StartTime of 0 instead of some small number of milliseconds due to the fact that Helix Producer takes a few milliseconds to actually begin encoding. Once encoding has actually begun, any events added with the StartTime of -1 will be added at the current elapsed time.
When adding events with the value of -1 for StartTime just before the job completes its encoding phase, there is a chance that the Helix Producer ActiveX control will return an error because the job stops before the event can be added. In this case, the error indicates that the event was executed after the encoding phase was complete. A similar error will occur if an event is added during the merging phase of an encoding job.
Usage:
producerobject.AddRealMediaEvent EventType, EventValue, StartTime, EventDuration
Where:
Argument | Req'd | Type | Defalut | Values | Description |
EventType | Yes | EventTypeEnum | No Default | Any one of the system configuration constants or the equivalent integer described below. | Constant or equivalent integer identifying the event type.
Event type identifies the type of event that is to be inserted into the
RealMedia file. They are::
|
EventText | No | String | Empty String | String up to 64k characters. | Value for the corresponding EventType. For EventType of hxEventTypeTitle, hxEventTypeAuthor, or hxEventTypeCopyright this is a simple string. For EventType of hxEventTypeURL, this is a URL that is passed to the browser. See URL Events for information on targeting frames of a browser. |
StartTime | No | Double | -1 | Any positive 32 bit floating point value or a value of -1 which represents the current timestamp. | The time in seconds at which the event begins. A value of -1 represents the current timestamp. All events have a start time. The value -1 can only be called after encoding has started. See RealMedia Events for information on adding events and how event timing is handled in the player. |
EventDuration | No | Double | -1 | Any positive 32 bit floating point value greater than 200 milliseconds or a value of -1 which represents infinity. | Duration defines how long in seconds the event will be active for. A value of -1 represents the current timestamp. The value -1 can only be called after encoding has started. See RealMedia Events for information on adding events and how event timing is handled in the player. Duration is used to compute the end time. If duration is not provided then the event duration is infinite. If the duration provided is less than 200 ms, then the value is automatically adjusted to 200 ms. |
Event Type enumeration constants:
Log Category Enumeration Name | Enumeration Value |
hxEventTypeURL | 0 |
hxEventTypeTitle | 1 |
hxEventTypeAuthor | 2 |
hxEventTypeCopyright | 3 |
Return Value:
No Return value.
Examples:
' Visual Basic 6
prodctrl.AddRealMediaEvent hxTitleEvent, "News Hour" '
Title event with current timestamp as start time (for live only)
prodctrl.AddRealMediaEvent hxAuthorEvent, "Channel 5 News", 10.0 '
Author event with start time only (end time assumed end of file or next
event, whichever comes first)
prodctrl.AddRealMediaEvent hxURLEvent, "http://www.channel5.com",
10.0, 20.0 ' URL Event with start and end time
prodctrl.AddRealMediaEvent hxURLEvent, "&&lower_frame&&http://www.channel5.com",
10.0, 20.0 ' Targeting a frame of the browser
' Setting start and end time from duration object
Dim MyStartTime As New HelixDuration
MyStartTime.SetDuration 0, 0, 3, 30 ' Sets duration in
MyStartTime object with duration 3:30 (3 minutes, 30 seconds)
Dim MyEndTime As New HelixDuration
MyEndTime.SetDuration 0, 0, 3, 30 ' Sets duration in
MyStartTime object with duration 3:30 (3 minutes, 30 seconds)
prodctrl.AddRealMediaEvent hxURLEvent, "http://www.channel5.com",
10.0, 20.0 ' URL Event with start and end time specified
from duration object
AddCustomRealMediaEvent( ) | [Top] - [Top of Section] |
Method to add a custom RealMedia events to the output RealMedia files. Custom RealMedia events are name/value pairs inserted into the media stream at a specific timestamp. Custom RealMedia events have no pre-defined action in the player like the built-in RealMedia events. Can only be called when EnableRealMediaEvents is True. If EnableRealMediaEvents is False or not set this method throws an error.
When adding events with the value of -1 for StartTime, if the AddRealMediaEvent or AddCustomRealMediaEvent method is called just before the job completes its encoding phase, there is a chance that the Helix Producer ActiveX control will return an error because the job stops before the event can be added. In this case, the error indicates that the event was executed after the encoding phase was complete. A similar error will occur if an event is added during the merging phase of an encoding job.
Usage:
producerobject.AddCustomRealMediaEvent( EventName, EventValue, StartTime, EventDuration)
Where:
Argument | Req'd | Type | Defalut | Values | Description |
EventName | Yes | Enum | No Default | Any string up to 255 characters. | Name of event. Events are name/value pairs inserted in the media stream at a given timestamp. Custom events have no specific action in the player. [DOCUMENT HOW TO ACCESS CUSTOM EVENTS IN PLAYER or elsewhere?] |
EventText | No | String | Empty String | String up to 64k characters. | Value for the corresponding EventType. |
StartTime | No | Double | -1 | Any positive 32 bit floating point value or a value of -1 which represents the current timestamp. | The time at which the event begins. A value of -1 represents the current timestamp. The value -1 can only be called after encoding has started. All events have a start time. See RealMedia Events for information on adding events and how event timing is handled in the player. |
Event Duration | No | Double | -1 | Any positive 32 bit floating point value or a value of -1 which represents infinity. | Duration defines how long the event will be active for. A value of -1 represents the current timestamp. The value -1 can only be called after encoding has started. See RealMedia Events for information on adding events and how event timing is handled in the player. Duration is used to compute the end time. If duration is not provided then the event duration is infinite. |
Return Value:
No Return value.
Examples:
' Visual Basic 6
prodctrl.AddCustomRealMediaEvent "SlideID", "Slide2",
10:00, 20 ' Custom Event with start and end time
See AddRealMediaEvent() for more examples of start/end time syntax.
6.10 HelixDuration Object |
[Back to Top |
Object to create and manipulate zero-based time duration in dd:hh:mm:ss.xyz format. This object is useful when working with RealMedia Events. The AddRealMediaEvent() function takes a duration object as its input. Use this object to create a duration object for use with the AddRealMediaEvent() method.
Summary of object
If you are adding multiple events, the utility method SetDuration() allows the duration to be reset to a new value for subsequent calls to the AddRealMediaEvent function. The methods AddSeconds(), AddMinutes, AddHours() and AddDays() offer a handy mechanism to adjust the duration value by a number of seconds, minutes, hours or days respectively to facilitate adding events in sequence, one after the other.
Typically one might create a single duration object for the start time and a second duration object for the end time and use the Set or Add methods to adjust the times.
Days | [Top] - [Top of Section] |
Property to designate the number of days in duration object.
Default:
0
Data Type:
Long
Values:
Any positive integer up to 2,147,483,647
Access:
Read-only
Examples:
' Visual Basic 6
MsgBox D.Days
Hours | [Top] - [Top of Section] |
Property to designate the number of hours in duration object.
Default:
0
Data Type:
Long
Values:
Any positive integer up to 2,147,483,647
Access:
Read-only
Examples:
' Visual Basic 6
MsgBox D.Hours
Minutes | [Top] - [Top of Section] |
Property to designate the number of minutes in duration object.
Default:
0
Data Type:
Long
Values:
Any positive integer up to 2,147,483,647
Access:
Read-only
Examples:
' Visual Basic 6
MsgBox D.Minutes
Seconds | [Top] - [Top of Section] |
Property to designate the number of days in duration object.
Default:
0.0
Data Type:
Double
Values:
Any positive 32 bit floating point value.
Access:
Read-only
Examples:
' Visual Basic 6
MsgBox D.Seconds
SetDuration( ) | [Top] - [Top of Section] |
Sets the value of a duration object to the value of days, hours, minutes and seconds passed in optional arguments.
Usage:
SetDuration( d, h, m, s )
Where:
Argument | Req'd | Type | Defalut | Values | Description |
d | No | Positive Long Integer | 0 | Any positive 32 bit integer. | The number of days. |
h | No | Positive Long Integer | 0 | Any positive 32 bit integer. If the value set is 24 or greater, the remainder is converted and stored in the Days property. | The number of hours. |
m | No | Positive Long Integer | 0 | Any positive 32 bit integer. If the value set is 60 or greater, the remainder is converted and stored in the Hours and Days properties. | The number of minutes. |
s | No | Positive Double | 0.0 | Any positive 32 bit floating point value. If the value set is 60 or greater, the remainder is converted and stored in the Minutes, Hours and Days properties. | The number of seconds and fractions of a second. |
Return Value:
No Return value.
Examples:
' Visual Basic 6
Dim MyStartTime As New HelixDuration
MyStartTime.SetDuration 0, 0, 3, 30 ' Sets duration in
MyStartTime object with duration 3:30 (3 minutes, 30 seconds)
Note: If you need to use a duration multiple times to create multiple
RealMedia events, use the Add or Set methods to modify the duration instead of
creating multiple duration objects to conserve memory.
AddDuration() | [Top] - [Top of Section] |
Adds the indicated seconds, hours, minutes and days to the value of a duration object.
Usage:
AddDuration( d, h, m, s )
Where:
Argument | Req'd | Type | Defalut | Values | Description |
d | No | Positive Long Integer | 0 | Any positive 32 bit integer. | The number of days. |
h | No | Positive Long Integer | 0 | Any positive 32 bit integer. If the value set is 24 or greater, the remainder is converted and stored in the Days property. | The number of hours. |
m | No | Positive Long Integer | 0 | Any positive 32 bit integer. If the value set is 60 or greater, the remainder is converted and stored in the Hours and Days properties. | The number of minutes. |
s | No | Positive Double | 0.0 | Any positive 32 bit floating point value. If the value set is 60 or greater, the remainder is converted and stored in the Minutes, Hours and Days properties. | The number of seconds and fractions of a second. |
Return Value:
No Return value.
Examples:
' Visual Basic 6
Dim MyStartTime As New HelixDuration
MyStartTime.SetDuration 0, 0, 3, 30 ' Sets duration in
MyStartTime object with duration 3:30 (3 minutes, 30 seconds)
MyStartTime.AddDuration 0, 0, 1, 30 ' Adds 1:30 to the
duration in MyStartTime object
AddSeconds( ) | [Top] - [Top of Section] |
Adds s seconds to a duration object.
Usage:
AddSeconds( s )
Where:
Argument | Req'd | Type | Defalut | Values | Description |
s | No | Double | 0.0 | Any signed 32 bit floating point value. If the value set is 60 or greater, the remainder is converted and added to the Minutes, Hours and Days properties. If the value set is 60 or greater, the remainder is converted and added to the Minutes, Hours and Days properties. | The number of seconds and fractions of a second to increment by. |
Return Value:
No Return value.
Examples:
' Visual Basic 6
Dim T as New HelixDuration
T.SetDuration 0, 0, 3, 30 ' Sets duration in T to 3:30
T.AddSeconds 30 ' Modifies duration object to 4:00
T.AddSeconds -0.1 ' Modifies the duration object to
3:59.9
AddMinutes( ) | [Top] - [Top of Section] |
Adds m minutes to a duration object.
Usage:
AddMinutes( m )
Where:
Argument | Req'd | Type | Defalut | Values | Description |
m | No | Long Integer | 0 | Any signed 32 bit integer. If the value set is 60 or greater, the remainder is converted and added to the Minutes, Hours and Days properties. If the value set is -60 or less, the remainder is converted and subtracted from the Minutes, Hours and Days properties. | The number of minutes to increment by. |
Return Value:
No Return value.
Examples:
' Visual Basic 6
Dim T as New HelixDuration
T.Set Duration 0, 0, 3, 30 ' Set duration to 3:30 (3
minutes, 30 seconds)
T.AddMinutes 1 ' Modifies duration object to 4:30
AddHours( ) | [Top] - [Top of Section] |
Adds h Hours to a duration object.
Usage:
AddHours( h )
Where:
Argument | Req'd | Type | Defalut | Values | Description |
h | No | Long Integer | 0 | Any signed 32 bit integer. If the value set is 60 or greater, the remainder is converted and added to the Days property. If the value set is -60 or less, the remainder is converted and subtracted from the Days property. | The number of hours to increment by. |
Return Value:
No Return value.
Examples:
' Visual Basic 6
Dim T as New HelixDuration
T.SetDuration 0, 0, 3, 30 ' Set duration to 3:30 (3
minutes, 30 seconds)
T.AddHours 1 ' Modifies duration object to 1:04:30
AddDays( ) | [Top] - [Top of Section] |
Adds d Days to a duration object.
Usage:
AddDays( d )
Where:
Argument | Req'd | Type | Defalut | Values | Description |
d | No | Long Integer | 0 | Any signed 32 bit integer. | The number of Days to increment by. |
Return Value:
No Return value.
Examples:
' Visual Basic 6
Dim T as New HelixDuration
T.SetDuration 0, 0, 3, 30 ' Set duration to 3:30 (3
minutes, 30 seconds)
T.AddDays 1 ' Modifies duration object to 1:00:04:30 (1
day, 0 hours, 4 minutes and 30 seconds)
GetDurationAsString( ) | [Top] - [Top of Section] |
Returns duration in d:hh:mm:ss.ms format suitable for printing. d, hh, and mm are omitted if zero.
Usage:
GetDurationAsString( )
Return Value:
No Return value.
Examples:
Dim D as New HelixDuration
D.SetDuration 0, 2, 3, 30 ' Set duration to 3:30 (3
minutes, 30 seconds)
MsgBox D.GetDurationAsString() ' Returns
"02:03:30.0"
D.SetDuration 0, 0, 0, 3
MsgBox D.GetDurationAsString() ' Returns "3.0"
D.SetDuration 1, 0, 0, 30.34
MsgBox D.GetDurationAsString() ' Returns
"1:00:00:30.34"
6.11 Constants |
[Back to Top |
The table below defines the constants in the ActiveX Control
' EventType hxEventTypeURL = 0 hxEventTypeTitle = 1 hxEventTypeAuthor = 2 hxEventTypeCopyright = 3 ' ProducerCrtlEventType ' Two-pass encoding started/finished events hxEventTwoPassAnalysisStarted = 2 hxEventTwoPassAnalysisFinished = 3 hxEventTwoPassEncodingUsingAnalysisStarted = 4 hxEventTwoPassEncodingUsingAnalysisFinished = 5 ' Encoding progress hxEventEncodeProgress = 6 hxEventAnalysisProgress = 7 ' Destinations hxEventDestinationStarted = 120 hxEventDestinationMergeProgress = 121 hxEventDestinationFinished = 122 hxEventDestinationError = 123 hxEventDestinationBroadcasting = 125 hxEventDestinationReconnecting = 126 hxEventDestinationListening = 127 ' LogCategory hxLogCategoryErrors = 0 hxLogCategoryWarning = 1 hxLogCategoryInfo = 2 hxLogCategoryDiagnostic =3 ' EnumerationType hxAudiences = 0 hxServers = 1 hxAudioDevices = 2 hxVideoDevices = 3 |
6.12 Unsupported Options |
[Back to Top |
This section documents properties or methods available through the Helix Producer ActiveX Control that are not supported.
GetSystemConfig() | [Top] - [Top of Section] |
Returns system configuration information. This is a helper function to facilitate building XML configuration files. This function is catch all to enable new system configuration information to be returned without adding new interfaces.
Usage:
GetSystemConfig( ConfigType )
Where:
Argument | Req'd | Type | Defalut | Values | Description |
ConfigType | Yes | ConfigTypeEnum | No Default | Any one of the system configuration constants or the equivalent integer described below. | Constant or equivalent integer identifying the system
configuration type. System configuration type identifies the type of
information desired about the system. Type are::
|
System Configuration Type enumeration constants:
Log Category Enumeration Name | Enumeration Value |
hxAudiences | 0 |
hxServers | 1 |
hxAudioDevices | 2 |
hxVideoDevices | 3 |
Return Value:
Array of strings of type Variant. The contents depend on the value of ConfigType. If
hxAudioDevices or hxVideoDevices, the return value is a list of audio and video
devices respectively. If hxAudiences or hsServers, the return value is a
list of audiences or servers respectively. In all cases, the return is
formatted in an array of XML as defined below. Each entry in the array
stores the XML from a single audience, server, audio device or video
device.
MyAudiences(0) '<audience>
<name type="string">28k
Modem</name>
<avgBitrate type="uint">20000</avgBitrate>
. . .
</audience>'
MyAudiences(1) '<audience>
<name type="string">56k
Modem</name>
<avgBitrate type="uint">34000</avgBitrate>
. . .
</audience>'
. . .
Examples:
' Visual Basic 6
Dim MyAudiences as Variant
MyAudiences = GetSystemConfig(hxAudiences)
Dim MyServers as Variant
MyAudiences = GetSystemConfig(hxServers)
Copyright © 2004, RealNetworks Inc. All rights reserved.
Helix, RealAudio, RealNetworks, RealSystem, RealVideo, and SureStream are trademarks or registered trademarks of RealNetworks, Inc. All other companies or products listed herein are trademarks or registered trademarks of their respective owners. All rights reserved.