Windows Media Encoder Automation

Yi Zhu
Microsoft Windows Media Technologies

July 21, 1999

Microsoft® Windows Media™ Encoder can be controlled programmatically with the Automation application programming interface (API) to provide flexible tools for converting media content into Advanced Streaming Format (ASF) streams.

By using Window Media Encoder Automation, a unique feature of Windows Media Encoder, you can automate the tedious process of encoding. This article shows how to use the Automation encoder object, and includes the following sections:

Introducing Windows Media Encoder presents a general description of Window Media Encoder.
About Windows Media Encoder Automation describes the advantages of using Automation, and the difference between Windows Media Encoder and the Automation encoder object.
Using Windows Media Encoder Automation outlines how to correctly use Automation.
Sample Application provides sample code that demonstrates how properties and methods exposed through Automation can be used.
Properties and Methods describes the properties and methods exposed through the Automation encoder object.
Additional Information provides pointers to related documentation.

Introducing Windows Media Encoder

Windows Media Encoder, part of Microsoft Windows Media Tools, is primarily used for encoding media content (such as live output from a microphone or a video camera, or stored media files) into an ASF stream or file, which can be delivered to clients through a server running Microsoft Windows Media Services. With the state-of-the-art compression technologies in Windows Media Encoder, you can convert and compress audio content, video content, and script commands into ASF content.

Windows Media Encoder is an extremely useful tool for creating ASF content for two reasons:

It can accept a live source.
It can compress the video source (live or stored) so that the resulting ASF stream or .asf file fits in a target bandwidth.

With other video conversion tools, you must edit the video before you convert it to an ASF stream or .asf file. But without any preparation, you can use Windows Media Encoder to convert video (.avi) or sound (.wav or MP3) files into .asf files. With Windows Media Encoder, you can set the size of the display window and choose which codec to use for compressing the output ASF stream.

Windows Media Encoder does not deliver ASF streams directly to the client. It delivers the encoded content to a Windows Media server. Then the server streams the content to the client over the network.

ASF is a file format designed particularly for streaming audio and video data from Windows Media servers on the Internet to clients around the globe.

The codecs are compression/decompression algorithms used to compress audio and/or video media, either from live sources or other media formats, to fit on available network bandwidth. Windows Media Encoder can use any codec installed on your computer; however, the computer on which Microsoft Windows Media Player is installed must have the same codec installed in order to play the .asf file or ASF stream.

About Windows Media Encoder Automation

The unique features of Windows Media Encoder are exposed through Automation (formerly called OLE Automation). Through the methods and properties that are exposed, client applications written in Microsoft Visual Basic® or Microsoft Visual C++® can be used to control the activities of Windows Media Encoder.

Windows Media Encoder Automation is extremely useful and convenient in creating ASF content for two reasons:

It can be used to automate encoding.
It can be easily used to run multiple instances of Windows Media Encoder.

Automating encoding provides clients great flexibility in accomplishing tedious encoding tasks. By automating the process, the clients can perform error checking and change editable properties in applications. For example, you can write an application that runs encoding while you are out of the office, or performs some error checking tasks.

Many computers that are currently available can support multiple audio and video capture cards as well as more than one instance of Windows Media Encoder. So in videotaping a live rock concert, for example, you can use two instances of Windows Media Encoder to separately stream content from two cameras set at different angles. If the two instances of Windows Media Encoder are embedded in your application, viewers can choose the angle from which they want to watch the concert.

You can perform similar functions by either using a Windows Media Encoder object created through Automation or administering Windows Media Encoder through the executable file (Nsrex.exe). However, there are some differences. When created as an Automation object, the Windows Media Encoder user interface is not visible. Also, you cannot use Automation to create an ASF Stream Descriptor (.asd) file for configuring Windows Media Encoder.

Using Windows Media Encoder Automation

To correctly use Windows Media Encoder Automation in your application, you must perform the following steps in the order shown:

Create an object of the encoder.
Load an .asd file.
Start the encoder.
Access the properties and invoke the methods exposed by Windows Media Encoder Automation.
Stop the encoder.

Creating an Object of the Encoder

Before an instance of Windows Media Encoder can be used in your application, you must explicitly create an object of the encoder. To do so, pass the object name of Windows Media Encoder into the CreateObject() method. The object name of Windows Media Encoder is Asf.RealTimeEncoder.

Loading an .asd File

After the encoder object is created, you must load an .asd file to configure the encoder object. Then the object can be used to create content.

The .asd file contains the settings that the encoder object uses to create the ASF stream or .asf file, such as the audio and video cards used, the audio and video codecs used, the destination of the ASF stream, the size of the video display window, the pixel format that the video display uses, and so on. The ASF content that the encoder object produces can be delivered to a Windows Media server, saved to an .asf file, or both.

An encoder object configuration can be saved as an .asd file so that it can be reused or, if necessary, supplied to a Windows Media server. The Windows Media server uses the information in the .asd file in preparing to stream the ASF content associated with that configuration. Once you have created an encoder object configuration file, you can start the encoder.

To change or create an instruction or setting, you must change or create an .asd file by using Windows Media Encoder. An .asd file cannot be created by using Automation.

Starting the Encoder Object

After the encoder object has been properly configured by accepting the default property settings, you can start it by invoking the Start method. However, if you want, you can modify the values of some of the editable properties before you call the Start method.

For example, you can change the name of the input file to be encoded by assigning a new String value to the InputSourceFile property in your application. Once the Start method is invoked, you cannot change the InputSourceFile property. Also, the value of this property must include both the path and file name, such as "C:\MyInputFileName".

To check if the encoder object has started encoding, display the IsStarted property.

Accessing Properties and Invoking Methods Exposed by Encoder Automation

When an encoder object starts encoding, it does not necessarily mean that the object automatically starts recording the encoded content to a local .asf file. To record content, you have two options:

Before the Start method is called in your application, assign a True value to the RecordAutoStart property.
Or, after the Start method is called in your application, invoke the RecordStart method. By assigning the RecordFileName property a new String value, you can change the output .asf file name. This changes the previously set value in the .asd file. However, if you change the RecordFileName property while the encoder object is recording an .asf file, an error occurs. To change the name of the .asf file that is being created during recording, stop recording by calling the RecordStop method, and then set the file name. To begin recording again, call the RecordStart method.

Stopping the Encoder Object

After encoding completes, you can stop the encoder object by invoking the Stop method in your application.

Sample Application

Microsoft Visual Basic is recommended for developing most applications because it hides the details of connecting to the IDispatch and other COM interfaces.

By using Automation, the following sample, written in Visual Basic, demonstrates how to:

Create an object of the encoder.
Load an .asd file.
Invoke methods exposed by Automation.
Change properties previously set in an .asd file.
Perform error checking.

Note This sample is not fully functional unless Windows Media Services is installed. To download the complete suite of Windows Media Services, see the Windows Media Technologies Web site .

'Create multiple instances of the encoder object
  Dim Encoder1 As Object
  Dim Encoder2 As Object
  Set Encoder1 = CreateObject("ASF.RealTimeEncoder")
  Set Encoder2 = CreateObject("ASF.RealTimeEncoder")

'Load previously created ASF Stream Descriptor (.asd) file for Encoder1
  Encoder1.LoadASD("C:\SampleConfig1.asd")

'Load a different .asd file for Encoder2. However, you can use the same .asd
'file for Encoder2.
  Encoder2.LoadASD("C:\SampleConfig2.asd")

'Reset the input file name of the source to be encoded for Encoder1
  Encoder1.InputSourceFile = "C:\MySource.avi"

'Start encoding
  Encoder1.Start
  Encoder2.Start

'Check if Encoder1 has started encoding
  If Encoder1.IsStarted Then
   MsgBox("Encoder1 starts encoding")
  Else
   MsgBox("Encoder1 does not start encoding.")
  End If

'Stop Encoder2 if the AllowScripts property is False - Error-checking
  If Not Encoder2.AllowScripts Then
   MsgBox("Script commands are not allowed for Encoder2.")
   Encoder2.Stop
   Set Encoder2 = Nothing
  End If

'Start recording the content encoded by Encoder1 to the .asf file previously
'set in the .asd file
  Encorder1.RecordStart

'Change the output .asf file name for Encoder2 after the encoder starts
'recording
  Encoder2.RecordStop
  Encoder2.RecordMaxSize = 5000
  Encorder2.RecordFileName = "C:\MyNewOutputFileName.asf"
  Encorder2.RecordStart

'Stop recording by Encoder1 and Encoder2 
  Encoder1.RecordStop
  Encoder2.RecordStop

'Stop encoding
  Encoder1.Stop
  Encoder2.Stop

'Releases the encoder objects from memory
  Set Encoder1 = Nothing
  Set Encoder2 = Nothing

Properties and Methods

The Windows Media Encoder Automation API exposes the following properties:

Property	Access	Description
AllowAudio	Read Only	Returns a Boolean value specifying whether audio content can be encoded
AllowScripts	Read Only	Returns a Boolean value specifying whether script commands can be sent
AllowVideo	Read Only	Returns a Boolean value specifying whether video content can be encoded
AudioFormatTag	Read Only	Returns a Long value specifying the format of the audio codec
AudioSource	Read Only	Returns a BSTR value specifying the audio source
Bandwidth	Read Only	Returns a Long value specifying the bandwidth
BitsPerPixel	Read Only	Returns a Short value specifying the color depth for a video image, such as 16-bit or 24-bit
DelayBuffer	Read Only	Returns a Short value specifying the size of the delay buffer
Description	Read Only	Returns a BSTR value specifying the description of the Windows Media Encoder session
FramesPerSecond	Read Only	Returns a Short value specifying the number of video frames per second
ImageHeight	Read Only	Returns a Short value specifying the image height, in pixels
ImageWidth	Read Only	Returns a Short value specifying the image width, in pixels
InputSourceFile	Read/Write	Returns or sets a BSTR value specifying the name of the source file to be encoded
IPPort	Read Only	Returns a Short value specifying the IP port
IsNetEnabled	Read Only	Returns a Boolean value specifying whether Windows Media Encoder is using the network
IsRecording	Read Only	Returns a Boolean value specifying whether Windows Media Encoder is recording content to an (.asf) file
IsStarted	Read Only	Returns a Boolean value specifying whether Windows Media Encoder has been started
NumClients	Read Only	Returns a Short value specifying the number of clients connected to Windows Media Encoder
RecordAutoOverride	Read/Write	Returns or sets a Boolean value indicating whether Windows Media Encoder is going to replace a file with the same name
RecordAutoOverride	Read/Write	Returns or sets a Boolean value indicating whether Windows Media Encoder is going to replace a file with the same name
RecordAutoStart	Read/Write	Returns or sets a Boolean value indicating whether recording content to a file begins automatically when the Start method is called
RecordDuration	Read/Write	Returns or sets a Long value specifying the duration of the file to be recorded
RecordFileName	Read/Write	Returns or sets a BSTR value specifying the name of the .asf file to be created in a recording session
RecordMaxSize	Read/Write	Returns or sets a Long value specifying the maximum file size for a recording
RecordSize	Read Only	Returns a Long value specifying the current size of the file being recorded
SecondsPerIFrame	Read Only	Returns a Short value specifying the number of seconds before a complete video frame must be sent
StreamAlias	Read Only	Returns a BSTR value specifying the stream alias used to connect to the server running Windows Media Services
VideoCodecFOURCC	Read Only	Returns a Long value specifying the format of video codec
VideoInputFOURCC	Read Only	Returns a Long value specifying the video source
Windows MediaServer	Read Only	Returns a BSTR value specifying the name of the server that is running Microsoft Windows Media Services and is being used for primary distribution

Windows Media Encoder Automation exposes the following methods:

Method	Description
LoadASD	Loads a configuration into Windows Media Encoder from an .asd file
RecordStart	Starts recording to an .asf file
RecordStop	Stops recording to an .asf file
SendScript	Inserts a script command into the ASF stream
Start	Starts an encoding session
Stop	Stops an encoding session

Additional Information

For more information about Windows Media Encoder Automation, see the Windows Media Technologies Software Development Kit . For more information about using Windows Media Encoder, see Windows Media Tools Help .