## Helix DNA Producer ActiveX Control User Guide |
| Last Modified: March 26, 2004

### Table of Contents

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:

- Configuration
  - Set a job file to define encoding settings
  - Modify user preferences
- Controls
  - Start/Stop/Cancel encoding jobs
  - Adjust audio gain prefilter
  - Insert RealMedia Events for live or on-demand encoding jobs
- Statistics and Logging
  - Receive standard events such as start job and stop job
  - Receive non-standard events such as server disconnected
  - Receive encoding status reports as % progress and elapsed duration
  - Log directly to file or receiving log messages programmatically

Phase two work is underway for audio and video GUI preview. The latest progress of this work can be found in the Helix Producer project at helixcommunity.org.

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:

1. Collect user input and create a job file or an XML formatted string.
   - Helper functions exist to collect a list of audiences, servers and devices on the users system
   - For some applications, the developer may choose to have the user choose for a list of pre-defined jobs and not require editing of the job itself.
2. Set the job file as input to the Helix Producer ActiveX control.
3. Call the start encoding method.
4. Monitor for events and logging callbacks if desired.
5. Call the stop encoding method.

# 2 System Requirements | [Back to Top]

This section identify system requirements for the Helix DNA Producer ActiveX Control.

## 2.1 Supported Programming Environments

The following programming environments are supported by the Helix Producer ActiveX Control:

- Microsoft Visual Basic 6.0 and .NET
- Microsoft Visual Basic for Applications
- Microsoft Visual C++ 6.0 and .NET
- VBScript

## 2.2 Supported Operating Environments

### 2.2.1 Operating Systems

- Windows 98 SE
- Windows ME
- Windows NT4
- Windows 2000
- Windows XP

### 2.2.2 VBA Applications

All VBA applications are supported but the following applications are tested

- Microsoft Excel
- Microsoft Access

### 2.2.3 Browsers

Any browser that supports ActiveX controls is supported but the following browsers are tested.

- Internet Explorer 6

## 2.3 Control Identification

The Helix Producer ActiveX control will be identified by the following:

- The Control Library name for the Helix Producer ActiveX Control is "HelixProducerLib".
  - In VB6, the Control library is referenced as "HelixProducerLibCtl.<ObjectName>"
  - In VB.NET, the Control library is referenced as "HelixProducerLib.<ObjectName>"
- The ProgID for the Helix Producer ActiveX Control is "helix.producer"
- The ProgID for the Helix Producer Duration control is "helix.duration"
- The Helix Producer object name is "HelixProducer". The class name is "HelixProducerClass".
- The Duration object name is "HelixDuration". The class name is "HelixDurationClass".
- The ActiveX Control DLL filename is 'helixprodctrl.dll'
- The GUID for the Helix Producer ActiveX Control is "66F8592D-33E8-11D7-8A24-00045A785B71"
- The control icon is the same icon as used with Helix Producer.

# 3 General Information | [Back to Top]

## 3.1 Loading the Producer ActiveX Control

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:

1. Dynamically

   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)

2. Statically

   .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.

## 3.2 Using Constants

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:

- hxLogCategoryDiagnostic = 0
- hxLogCategoryInfo = 1
- hxLogCategoryWarning = 2
- hxLogCategoryErrors = 3

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:

- From VBScript or Microsoft JScript - VBScript does not support the use of enumeration types. Therefore, values like hxLogCategoryErrors will have no value when executed from VBScript. In those cases, the numeric values for the constants must be used in their place.
- If the control is loaded dynamically (e.g. CreateObject) then the numeric values for the constants must be used instead of the constant names.
- For .Net, if the control is loaded dynamically, the constants can be imported by adding the following to the top of the form:

  Imports HelixProducerLib.eProducerCrtlEventType
  Imports HelixProducerLib.eEnumerationType
  Imports HelixProducerLib.eLogCategory

For a complete list of constants, see Constants.

## 3.3 Control Behavior

- All standard visual basic properties such as width and height are supported.
- The property browser can be used to modify the settings for the Helix Producer ActiveX control.
- When added to a form, the control is visible. To make the control invisible, set the Visible property to False.
- Properties that show up in the properties grid are categorized as defined in the Interfaces Specification along with the property description.

## 3.4 Distribution

There are two target audiences for the ActiveX control.

1. Developers distributing an application
   The first audience is developers who wish to distribute an application built with the producer ActiveX control. These developers will be providing their own installers. For this group of developers, the ActiveX control should be licensed for distribution in the same way that the C++ SDK is licensed and distributed.
2. Developers developing for VBA
   The second audience is developers who wish to build VBA and browser-based applications. These developers rely on the Helix Producer ActiveX control installer. This group of developers will want to instruct their users to download and install the Helix Producer ActiveX Control Installer from RealNetworks and access functionality in those products from other products like Microsoft Access using VBA.

To serve on these two users groups, the Helix DNA Producer ActiveX Control is distributed in the following ways:

1. Bundled with Helix Producer SDK
   - The necessary components are shipped with the Helix Producer SDK
   - A batch file is included in the SDK containing the commands to register the control
   - Instructions in the SDK are provided for how to register the control programmatically
   - The Helix Producer SDK documentation is extended to include ActiveX control
   - The Helix Producer SDK license agreement is extended to include ActiveX control
2. Installed and registered with the ActiveX installer distributed from RealNetworks website
   - The Helix Producer ActiveX Control installer distributed from RealNetworks will register the ActiveX control automatically

## 3.5 Installation

Helix DNA Producer ActiveX SDK is packaged in one of two ways as described under the Distribution section above

1. Helix Producer ActiveX SDK - The Helix DNA Producer ActiveX Control is packaged in a compressed archive with all supporting files needed to run the Helix DNA Producer ActiveX SDK
2. Helix Producer ActiveX Runtime Installer - The Helix DNA Producer ActiveX Control is installed by an executable downloaded from RealNetworks.com.

### Helix DNA Producer ActiveX Control Runtime Installer

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.

### Helix DNA Producer ActiveX SDK

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.

#### Registering the ActiveX Control

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.

## 3.6 Security

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:

- HKEY_CLASSES_ROOT\CLSID\{66F8592D-33E8-11D7-8A24-00045A785B71}\Implemented Categories\{7DD95801-9882-11CF-9FA9-00AA006C42C4}
- HKEY_CLASSES_ROOT\CLSID\{66F8592D-33E8-11D7-8A24-00045A785B71}\Implemented Categories\{7DD95802-9882-11CF-9FA9-00AA006C42C4}

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.

## 3.7 General Configuration

The following settings are configurable

- Input Job
  - Input job can be defined either as a filename or as raw XML passed directly to the control.
- Logging
  - Log Filename
  - Log Category (Error, Warning, Info, Diagnostic)
- Directory and File Locations
  - Temporary scratch directory
  - Audiences and Servers directory
  - Codec Mapping file

## 3.8 Controls

The following general controls are provided through the ActiveX control:

- Stop/Start/Cancel Job
- Insert RealMedia Event during encode
- Launch device specific dialogs
- Release Resources (Useful to ensure control is unloaded properly)

RealMedia events are discussed in more detail below.

## 3.9 Audience Enumeration

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.

## 3.10 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.

## 3.11 Device Control

### 3.11.1 Device 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 Name (e.g. o100vc.dll - Osprey Capture Card 1)
- Device Number (e.g. 01)
- Device availability (e.g. In Use or Available) [If available on Windows]

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.

### 3.11.2 Load Device Dialogs

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.

## 3.12 Statistics

Helix Producer ActiveX control will expose the following information through the appropriate interfaces:

- Programmatic Events raised by the encoder (e.g. callbacks for specific actions such as job start, broadcast done, server disconnected, etc)
- Encoding progress status
  - Separate progress reporting for analyzing, encoding and merging
  - The following information is provided programmatically through callbacks:
    - Percentage
    - Elapsed duration
  - The following information cab be queried:
    - Elapsed and Total duration

For more information about collecting statistics, see Event Handlers.

## 3.13 Logging

Logging output from Helix DNA Producer is available through the following methods:

- Log output to file specified by filename with the following functionality:
- Callback that propagates log messages as strings to caller

The following file logging properties can be set directly from the ActiveX Control:

- Filename
- Log Category (Error, Warning, Info, Diagnostic)

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:

- Enable Log Events
- Log Events Category (Error, Warning, Info, Diagnostic)

For more information about controlling logging, see Logging.

## 3.14 Preferences

The following preferences can be defined through the ActiveX control

- Paths
  - Temporary directory. The default is the system temporary directory.
  - Audiences directory. The default is the audiences directory installed with the ActiveX control.
  - Servers directory The default is the servers directory installed with the ActiveX control.
- Update Codec and Update codec mapping file
  - Helix Producer ActiveX Control supports the update codec feature which is used to update job and audience files to the latest codec versions.
  - The Update Codec property is used to specify if old codecs are mapped to new ones
  - The Codec Mapping File property is used to define where the file exists that contains the mapping of old codecs to new.
  - The updated codecs option is false by default (i.e. codecs are not updated by default). If turned on, the codec mapping file *must* also be specified in order to perform the mapping or an error is generated.

For more information about setting user preferences, see Preferences.

## 3.16 Samples

Sample applications are provided in the 'samples' directory of the SDK. Samples are provided for the following development environments:

- Visual Basic application with source in Microsoft Visual Basic 6 development tool
- ActiveX control programmatically controlled using VBScript and a web form controls in Internet Explorer 6.
- Visual Basic .NET

# 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.

## 4.1 Event Components

An event consists on two components:

1. An event type
   - All RealMedia event types are supported including:
     - Standard (Fixed name with user-supplied value)
       - URL
       - Title
       - Author
       - Copyright
     - Custom (Any name/value pair)
2. An event value
   - A string that specifies the appropriate value for the event. The strings have the following syntax.
     - URL - <FRAME>:<URL>
       - Where <URL> is the URL that should be passed to the browser and <FRAME> is the name of a frame in which the event should be directed.
       - The format of the URL should not be assumed to follow any specific URL syntax and in fact can be any legal string accepted by a browser including "JavaScript:" syntax. This string may also contain multi-byte characters. The length is limited to 65k-1 bytes.
     - Title, Author and Copyright - strings which can contain any data up to 65k-1 bytes in length. This information should generally be characters but should not be assumed to be single-byte characters.
     - Custom - Any string up to 65k-1 characters. This information should generally be characters but should not be assumed to be single-byte characters.

## 4.2 Event Actions

1. RealMedia URL events cause the RealPlayer to send URLs to the user's browser at a specified time when the stream is played.
2. Title, Author, or Copyright events change the title, author or copyright information that can be displayed in a player.
3. Custom events have no pre-defined action in the player. Any action taken from a custom event must be programmed into the client using one of the Client APIs such as C++, Visual Basic, VBScript or JavaScript.

## 4.3 Enabling Event

Events are enabled in the Helix Producer ActiveX Control in one of two ways

1. A job specified through the ActiveX control has one or more audiences containing an event stream.
2. A method or property is provided by the ActiveX control to enable events for that encoding session.
   - This method or property remains in effect even if a job is subsequently set that does not contain an event stream in one of the audiences.

## 4.4 Client Behavior

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:

1. The start time is when the event will first be triggered (a browser window is opened or the title, author or copyright field is changed in the player)
2. The event will no longer be triggered after the end time under any circumstances
3. In an on-demand presentation:
   1. When a player reaches the start time for a given event, that event is triggered. Each event is triggered once and only once.
   2. A seek operation to a point in time after the start time but before the end time will result in the event being triggered (unless that event has already been triggered once before).
   3. Events are not cumulative. New events replace older events. That is, if the end time of one event overlaps the start time of a subsequent event, the new event replaces the first event. For example given the following events:
      Event1: StartTime=0, EndTime=60
      Event2: StartTime=30, EndTime=60
      If the player seeks to time=45 seconds, only Event2 is triggered.
4. In a live presentation:
   1. If a player is connected prior to the start time, the event is trigged when the start time is reached. Each event is triggered once and only once as long as the player does not stop and restart the stream.
   2. A new player connection at a point in time after the start time but before the end time will result in the event being triggered.
   3. No event is triggered for players connecting after the end time has passed.

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.

## 4.5 File to File Encoding of Events

1. Adding events
   1. Events should be added prior to encoding is started.
      - Inserting an event in a file to file encode after encoding has started is allowed but not advised because the encoding is not being performed in real-time so the time of the event will be unpredictable.
      - Events must be added in order of increasing start time. Adding an event with a start time less than a previously added event, will result in an error.
   2. Start time is specified explicitly
      - Start time is required if set prior to encode time. Not setting the start time before encoding is started will result in an error.
   3. End time is computed from the duration.
      - If the duration is not set, duration defaults to infinity
      - Duration can be set explicitly to infinity
      - Subsequent events will overwrite existing events as defined in above.
   4. For Title, Author, Copyright and URL events, the minimum allowable value of duration is 200 milliseconds. If an event contains a duration lower than 200 milliseconds, the duration is automatically modified by the SDK to 200 milliseconds. This rule does not apply to custom events.
2. Deleting Events
   - No means is provided to delete events. Once an event is added to the stream, no method exists to remove it.
3. Moving Events
   - No means is provided to move events on the timeline (e.g. move the start or end times).

## 4.6 Capture Input and/or Broadcast Output (real-time) of Events

1. Adding events
   1. Events can be added prior to starting encoding or after encoding has started.
      - Events must be added in order of increasing start time. Adding an event with a start time less than a previously added event, will result in an error.
   2. Start time is specified either
      - Implicitly - Setting the start time to some sentinel value or not setting the start time will result in the event being inserted using the current encoding timestamp.
      - Explicitly - Start time can be specified explicitly in the call to add a RealMedia event. A method is provided to get the current timestamp.
        - Adding events with Start times earlier than the current elapsed time of the encoding job can result in unpredictable behavior with live broadcasts. This is not advised.
   3. The end time can be defined by either:
      - The duration of the event is specified and end time is computed from the duration.
      - The duration is not set and allowed to assume its default value of infinity.
      - The duration is explicitly set to infinity.
   4. For Title, Author, Copyright and URL events, the minimum allowable value of duration is 200 milliseconds. If an event contains a duration lower than 200 milliseconds, the duration is automatically modified by the SDK to 200 milliseconds. This rule does not apply to custom events.
2. Deleting Events
   - No means is provided to delete events in a live stream. Once an event is added to the stream, no method exists to remove it.
3. Moving Events
   - No means is provided to move events on the timeline in a live stream (e.g. move the start or end times).

## 4.7 Specifying a Target Frame

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:

- FRAME is optional and identifies a HTML frame to be used as the target
- URL is the URL that is to be loaded

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:

- Media Playback Pane (Playback of audio, video and other multimedia data types)
- Related Pane or Context Pane (Display of related information)
- Media Browser Pane (Display or related web pages )
- Secondary Browser Windows (Other web pages displayed in a separate window)

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..

## 5.1 Pixel Aspect Ratio Correction

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.

### 5.1.1 Background

The shape of the pixel is dependent on the video standard being used:

- Computer monitors contain pixels where the width of each pixel is equal to the height
  - Video generated for display on computer monitors is said to contain square pixels
- TV screens contain rectangular pixels where the width is longer than the height
  - Video signals like NTSC or PAL intended for display on TV screens are said to contain non-square pixels.

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).

### 5.1.2 Correcting for Pixel Aspect Ratio in Helix Producer

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.

### 5.1.3 Pixel Aspect Ratio Recommended User Interface Options

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:

- 0.9 (D1/DV NTSC)
- 0.9481481 (D4/D16 Standard)
- 1 (Square Pixels)
- 1.017 (4:3 PAL)
- 1.0666 (D1/DV PAL)
- 1.125 (4:3 NTSC)
- 1.2 (D1/DV NTSC Widescreen)
- 1.4222 (D1/DV PAL Widescreen)
- 1.8962962 (D4/D16 Anamorphic 8:3)
- 2 (Anamorphic 2:1)

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:

- Square and Non-Square Pixels

# 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.

- Properties
  - VersionString
  - MajorVersion
  - MinorVersion

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.

- Properties
  - JobFilename As String (Read/Write) - Load the job specified by filename.
  - JobXMLString As String (Read/Write) - Load the job given by the specified XML.
  - AudioGain As Double (Read/Write) - Change the audio gain before or during an encode.
- Methods
  - StartJob( ) - Start the currently loaded job.
  - StopJob( ) - Stop the currently running job.
  - CancelJob( ) - Stop the currently running job without creating output files.
  - SaveJob( ) - Save the currently loaded job.
  - ReleaseResources() - Start the currently loaded job.

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.

- Properties
  - JobDuration
  - ElapsedDuration
  - JobStartTime
  - IsRunning
  - IsReady

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:

- A value of True means the job is running.
- A value of False means the job is not running or no job is loaded.

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:

- vcA value of True means the job is read to execute.
- A value of False means the job is not ready to execute or is already running.

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:

- Generate a list of available audio and video devices to allow the user to select which audio and video device they wish to capture from.
  - This information can be used to subsequently set this information in the capture section of a job file or load preview for the audio or video capture device
- Allow a user to modify driver-specific capture settings.
  - If a job is loaded in the Helix Producer ActiveX control but not running, changing settings in the driver dialog will also change the corresponding settings in the job file as applicable and take effect when the job is started. The changes are also be reflected in the XML if the XML string is subsequently extracted from the ActiveX Control using the JobXMLString property.
  - If the job is already running, a catchable error is generated if the dialog is invoked.

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()
- GetVideoDevices()
- GetAudioDeviceDialogNames( )
- GetVideoDeviceDialogNames( )
- LoadAudioDeviceDialog( )
- LoadVideoDeviceDialog( )

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():

- MyAudioDevices(0) "Osprey 220 Audio"
- MyAudioDevices(1) "Sound Blaster Live!"

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():

- MyVideoDevices(0) "Osprey 220 Video"
- MyVideoDevices(1) "Microsoft DV"

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:

- MyAudioDeviceNames(0) "Recording Mixer"
- MyAudioDeviceNames(1) "Vendor-Provided Controls"

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():

- MyVideoDeviceDialogNames(0) "Video Format"
- MyVideoDeviceDialogNames(1) "Video Source"

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: "Recording Mixer" and "Vendor-Provided Controls".

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: "VfW Video Format" "VfW Video Source" "DirectShow Filter" "DirectShow Pin" "DirectShow TV Tuner" "DirectShow TV Audio"

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() - Called when encoding has started successfully.
- OnJobDone() - Called when all inputs have reached the end and encoding has completed successfully.
- OnEvent() - Generic event handler.
- OnProgress() - Called frequently to report encoding progress.
- OnLogMessage() - Called whenever a new log message is generated. Documented in the Logging section of this document.

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. Failed to connect to sever Server %s disconnected. Specified host name could not be found for server %s. Failed to create network TCP socket for server %s. Failed to establish a TCP connection with server %s. Timeout for server %s waiting for authentication. Authentication failed for server %s. Please check username and password. Did not receive port range from server %s. Monitoring connection to server %s failed,stopping broadcast. Failed to lookup address for server %s. Failed to bind to listen pull port for %s. Authentication read timed out for server %s.

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:

- # - All numbers represented by pound signs are right justified. The number of digits is fixed as represented above to keep the display from shifting constantly.
- ELAPSED and TOTAL times are represented in dd:hh:mm:ss.f format where dd or hh are omitted if 0. mm and ss are always 2 digits padded with a 0 to prevent the display from shifting constantly. The decimal and one place to the right of the decimal (f) is always displayed, even if 0 to make it clear that the value to the left of the decimal is seconds.
- ELAPSED, when shown, time is based on the current timestamp in the output.
- If no audio input or audio is disabled for all outputs, the VU meter is not displayed.

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.

- Properties
  - LogFilename As String (Read/Write)
  - LogFileCategory As String (Read/Write)
  - LogEventsCategory As String (Read/Write)
  - DoLogEvents As Boolean (Read/Write)
- Events Callbacks
  - OnLogMessage( MessageNumber, MessageString, Timestamp, LogCategory)

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:

- A value of True means log events callbacks to the OnLogMessage event handler will be made.
- A value of False means no log events callbacks will be made.

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: Error - High importance Warning - Medium importance Info - Low volume, average importance Diagnostic - high volume, low importance

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
- AudiencesDirectory
- ServersDirectory
- CodecMappingFilename

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:

- %TEMP% - Temporary files are written to the system temporary directory. This varies system to system. For example, on Windows NT this is C:\WinNT\Temp. If the system temporary directory is modified, Helix Producer will automatically being to use the new location.
- %OUTPUT% - Temporary files are written to the same directory as the output file. This is on a destination by destination basis so if more than one destination are being written to more than one location, the temporary files for each output file are written to the respective output directory.
- Any Valid Path - Temporary files are written to the location specified.

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`

Servers Directory | [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()
- GetServers()
- GetSystemConfig()

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.

- Properties
  - EnableRealMediaEvents As Boolean (Read/Write)
- Methods
  - AddRealMediaEvent( EventType, EventValue, StartTime, EventDuration)
  - AddCustomRealMediaEvent( EventName, EventValue, StartTime, EventDuration)

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:

- A value of True means the ability to add RealMedia Events is enabled.
- A value of False means the ability to add RealMedia Events is disabled.

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:: URL Event - Triggers a URL flip in the player (URL is passed to the browser or targeted into a frame for the embedded player) Title Event - Triggers a title change in the player (may also be caught programmatically via JavaScript or ActiveX) Author Event - Triggers an author change in the player (may also be caught programmatically via JavaScript or ActiveX) Copyright Event - Triggers a copyright change in the player (may also be caught programmatically via JavaScript or ActiveX)
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

- Objects
  - helixduration
- Properties
  - Days (Long, Read-only) - Gets the number of days for the duration
  - Hours (Long, Read-only) - Gets the number of hours for the duration
  - Minutes (Long, Read-only) - Gets the number of minutes for the duration
  - Seconds (double, Read-only) - Gets the number of seconds for the duration
- Methods
  - SetDuration( d, h, m, s ) - Sets a duration object to a new value
  - AddDuration( d, h, m, s ) - Adds values to a duration object
  - AddSeconds( s ) - Adds s seconds to a duration object
  - AddMinutes( m ) - Adds m minutes to a duration object
  - AddHours( h ) - Adds h hours to a duration object
  - AddDays( d ) - Adds d days to a duration object
  - GetDurationAsString() - Returns duration in d:hh:mm:ss.ms format where d, hh, mm and ms are not printed if zero.

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:: Audiences - Audience configuration files located in the directory defined by AudiencesDirectory property Servers - Server configuration files located in the directory defined by ServersDirectory property Audio Devices - Audio devices (sound card, virtual mixer, etc) installed on the system. Video Devices - Video devices (video capture card, IEEE 1394 devices, etc) installed on the system.

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.