Chapter 14: Using the Command-Line Application

This chapter explains how to run the RealProducer command-line application, which can encode media as both clips and live broadcasts. The command-line application can perform the same encoding functions as the RealProducer graphical application, and provides additional features not found in the graphical application.

Encoding From the Command Line

The command-line application is an executable file named producer.exe on Windows and producer on Linux. It provides the same encoding capabilities as the RealProducer graphical application, and allows you to perform batch encoding on any number of media files. You can run the application from the command line manually, or tie the application into any production or scripting system that can use your operating system's command line.

Using Job Files or Command Options

There are two basic ways to use the command-line application. You can enter all of the encoding information on the command line when you run the application. Or, when you use RealProducer Plus, you can define the encoding options in a job file, as described in Appendix B, and process the job file through the command line. Both methods allow you to specify the same general encoding options, but each method provides its own advantages:

• When you use a job file, you can define multiple inputs and outputs that are encoded in parallel. Without a job file, you can define a single input and single output for each encoding session. A single output can have multiple destinations, however. For example, you can send an encoded output to a broadcast server as well as save it to a local file.
• If you do not use a job file, you can use batch encoding. This allows you to process multiple clips one after the other, all with the same encoding settings. This is useful if you need to encode a lot of clips using the same settings.

Running the Command-Line Application

The command-line application uses the command name producer. This executable file is located in the main RealProducer installation directory. On Windows, the RealProducer installer adds this directory to your Path environment variable, so you can run the application from any directory. On Linux, you can add this directory to your path through your login shell. The RealProducer installer can also create a symbolic link to the command-line application.

File Locations and Temporary Directory

RealNetworks recommends that you run the command-line application from a directory other than the RealProducer installation directory. Your media files can be located anywhere on your network, but it is easiest to encode them from the directory in which you run the command-line application. For fastest operation, encode output on the same disk that holds input files, preferably the local RealProducer disk. Also, set the temporary directory to a directory on the same disk used for output.

For More Information: The section "Changing the File Location Preferences" explains how to set the temporary directory through the graphical application. You can also define the temporary directory in the preferences file, which Appendix E describes.

Command Line Syntax

To run the application, open a command line prompt and navigate to your content directory. Then enter the producer executable name along with your options, as shown in the following example:

producer -i movie.avi -o movie_streaming.rm ...additional options...

Notes About the Command-Line Syntax

Note the following about the command syntax:

• Each option is preceded by a dash, as in -i. Options are from one to three characters long.
• Some options, such as -i and -o require values, as shown above. Other options do not take values.
• An option's value immediately follows the option. Separate the two with a space.
• If an option value uses multiple words separated by spaces, enclose the entire option string in double or single quotation marks. Do not include the option flag itself with in the marks.
• If you do not include an option on the command line, the option's default value applies to the encoding job.
• The order of options on the command line does not matter.
• The command-line application supports cross-platform file naming, as described in "File and Directory Paths".

Stopping the Command-Line Application

You can stop an encoding session and save the resulting clip by pressing Ctrl+c. With SureStream clips, however, some merging time is required before the final output is written. To cancel encoding and delete the output and temporary files, press Ctrl+\ on Linux or Ctrl+Break on Windows (Break is on the upper-right row of the keyboard).

Sending Signals to the Linux Command-Line Application

On Linux, the command-line application listens to and responds to signals that notify it of important events. The kill command can use signal names or numbers as arguments to send the application a signal. The kill command takes two arguments: the signal name or number and the process ID:

kill signal process_id

Signals and Actions

The following table defines the signals to which the command-line application responds.

Note: No action results from sending a SIGHUP signal to the command-line application.

Process IDs

The kill command's second argument is the process ID. A single instance of RealProducer runs under several process IDs, but only one ID will accept a signal. To identify the correct ID, use the Process ID File (-pid) option to get the process ID. The following is an example:

producer -ac 0 -o out.rm -pid /tmp/producer.pid

Stop and Cancel Signals

To stop encoding but save the encoded output, use the kill command with a SIGINT signal as shown in the following example:

kill -SIGINT $(cat /tmp/producer.pid)

To cancel encoding and delete the output, use the kill command with a SIGQUIT signal as follows:

kill -SIGQUIT $(cat /tmp/producer.pid)

Tip: RealProducer includes a sample command-line utility, signalproducer, that sends signals to a running command-line application. This utility is available in source and binary formats in the samples/utilities/producer_signal_generator directory.

Sending Signals to the Windows Command-Line Application

On Windows, the RealProducer command-line application listens for window messages sent to its window handle. When the application starts, it registers a window handle based on the process ID (PID). You can obtain the PID from the Windows Task Manager. Or, you can record the PID using the Process ID File (-pid) option, as shown in the following example:

producer -ac 0 -o out.rm -pid "c:\pid.txt"

With the PID, you can send a stop or cancel request to the application by using a utility available as source and in binary form (signalproducer.exe) in the following directory under the main RealProducer installation directory:

samples\utilities\producer_signal_generator

The signalproducer.exe utility uses the following syntax, in which the stop option saves the output and cancel option discards it:

signalproducer.exe {-p PID|-P PIDFILE} [-a stop|cancel] [-q]

The following example shows how to send a cancel signal to the command- line application using a PID file:

signalproducer.exe -P c:\pid.txt -a cancel

You can also pass the PID directly using a lowercase -p option, as shown in the following example:

signalproducer.exe -p 2096 -a cancel

Monitoring the Return Value

You can use the command-line application's return value to detect if an error occurred if you run the application from a script. The application returns a value of 0 if no errors occurred during encoding. If errors occurred, the application returns a value of 1.

Getting the Return Value on Linux

On Linux, you can access the return code by assigning the function call to a variable, then testing that variable's value. The return value is stored in a special shell variable ($?). The following sample script checks the contents of the ? variable for an error. If the variable has a value of 1 or higher, the script prints an error string:

producer -i movie.mpeg
if [ $? -ge 1 ]; then echo "Encoding error occurred."

Getting the Return Value on Windows

DOS stores the return value of a command-line program in an environment variable called ERRORLEVEL. This following example checks the contents of ERRORLEVEL and prints an error string if ERRORLEVEL has a value of 1 or more:

producer -i movie.avi
IF ERRORLEVEL 1 echo Encoding error occurred.

Command-Line Functional Areas

The following tables summarize the major functional areas and options for using the RealProducer command-line application.

Job File Options

Job files, which use the file extension .rpjf, are XML-formatted files that specify the inputs, outputs, and encoding operations to perform. Appendix B explains the job file syntax. This section explains the options for using and creating job files with the command-line application of RealProducer Plus. Job file processing is not available with the command-line application of RealProducer Basic.

Job File Name (-j)

Use the -j option to specify the path and file name of the job file to use. You can use either a relative path from the current directory, or an absolute path. For example:

-j MyJob.rpjf

When you encode with a job file, the job file defines the input and output, as well as the encoding options. You therefore cannot use most other options on the command line. The following options are allowable, however, along with the -j option:

• Create Job File (-cj) option
• Disable Codec Updates (-duc) option
• Disable Audio Watchdogs (-daw) option
• Logging Category (-lc) option
• Process ID File (-pid) option
• Video Codec Override (-vco) option
• Encoding Complexity Override (-eco) option

For More Information: See "Job File Examples" for samples of command-line syntax for encoding clips or broadcasts with job files. "Job File Syntax Update" shows how to update earlier job files to the RealProducer 10 format.

Create Job File (-cj)

If you have RealProducer Plus, you can use the -cj option to generate a job file from the command line options you provide. This allows you to capture command-line settings into a job file without encoding any content. You can later run the job file you created and perform the encoding by using the -j option. For instance, you may want to create a basic job file using the -cj option, then modify it manually as described in Appendix B before running it on the command line.

The value for the -cj option is a file name and path, which can be absolute or relative to your current directory. For example:

-cj NewJob.rpjf
-cj c:\Jobs\NewJob.rpjf
-cj /usr/realproducer/jobs/NewJob.rpjf

Warning! Job file properties are not validated until the job runs. You can create an invalid job file by specifying a non- existent audience, for example. In this case, you do not receive an error until you encode a job using the file.

Input and Output Options

The simplest way to create a job file is to specify an input file, a job file name, and the other encoding options on the command line. The following example creates the job file movie.rpjf. This file specifies movie.avi as the job input. It automatically sets the job output to movie.rm or movie.rmvb depending on the audiences chosen as part of the encoding options:

-i movie.avi -cj movie.rpjf ...encoding options...

To set the output clip to a different name, you include the -o option on the command-line:

-i movie.avi -o streaming_movie.rm -cj movie.rpjf ...encoding options...

For More Information: For more on defining inputs, refer to "Input File or Directory (-i)". The section "Output File or Directory (-o)" describes outputs.

Batch Job File Creation

You can create job files in batch mode by specifying an existing directory as the value of the -cj option. For example, you can create a job file for every AVI clip in a directory. In the following example, an input named movie.avi results in a job file named movie.rpjf in the jobfiles directory:

-i c:\media\videos\*.avi -cj c:\media\jobfiles

You can also specify just the input directory, as shown in the following example. RealProducer creates a job file for every media file in an acceptable input format, such as AVI, WAVE, or MPEG, that it finds in the input directory. It ignores files in other formats, such as .rm and .txt files:

-i /usr/producer/media/videos -cj /usr/producer/media/jobfiles

Disable Codec Updates (-duc)

When you have job or audience files created with the older Helix Producer, RealProducer 10 automatically updates the audience settings to use new audio and video codecs. This is the recommended action. Job or audience files that formerly specified the RealVideo G2 with SVT codec are updated to use RealVideo 8. The following table lists the RealAudio codecs substituted for older audio codecs.

If you want your audience or job files to retain the older codec information, however, you can include the -duc option on the command line:

-duc

Warning! RealProducer 10 no longer includes the RealVideo G2 codec, or RealAudio codecs based on ATRAC3 technology. If your existing audience or job files specify these codecs and you include the -duc option, RealProducer 10 will not be able to encode the job.

Tip: You can modify how RealProducer updates older codecs by modifying the settings of the codecmapping.txt file located in the resources directory under the RealProducer installation directory. You will need to know the codec names and flavors, which are listed in the codec tables in the section "RealAudio Codecs".

Input Options

This section describes the input options that allow you to specify a file or live capture as the input to be encoded. Note that you can specify just one input through the command line. In a job file, however, you can specify multiple inputs that are run in parallel, as described in "Audio and Video Inputs".

Input File or Directory (-i)

Use the -i option to indicate a digitized file on the network or local drive to be encoded. For the file path, you can specify either a relative path from the current directory, or an absolute path. The input file name is ignored if the Audio Capture Device ID (-ac) option or Video Capture Device ID (-vc) option is specified.

For More Information: For a list of supported input file types, refer to "Audio and Video Input Formats". For information about specifying output file locations and names, see "Output File or Directory (-o)".

Single File Input Examples

-i movie1.mpg
-i ../media/movie1.mpg
-i c:\files\media\movie1.avi
-i /home/encoder/media/movie1.mpg

Batch File Encoding

With RealProducer Plus, you can specify multiple files that are encoded serially. You can specify the directory that contains the source files, or use one or more asterisks (*) as wildcards in file names. You cannot use a wildcard in a directory path, however. If you do not specify output paths and names, the encoded clips are written to the input directory, using each input's base file name and the .rm or .rmvb extension, depending on the encoding type.

Batch File Input Examples

-i *.mpg
-i ../media/
-i c:\files\media\
-i c:\files\media\trailer*.avi
-i /home/encoder/media/*.mpg
-i /home/encoder/media/

Audio Capture Device ID (-ac)

The -ac option specifies the audio device ID for the input audio device. Using this option overrides the -i option for a file input. You can use one of the following values:

• Integer of value 0 or higher identifying a specific device number, such as:

-ac o

• String matching an existing device name:

-ac "Sound Blaster Live!"

• String with a wildcard (*) matching an existing device name, such as:

-ac "Sound Blaster *"

• UNIX device name or symbolic link to a device name, such as:

-ac /dev/audio

For More Information: Use the Print Device Information (-pd) optionto list values for your system.

Audio Capture Device Port (-ap)

Use -ap to specify the port for the audio device used for audio capture. You must specify the audio device ID as well. Using the -ap option overrides the -i option for a file input. If you omit the audio port, the current mixer settings are used. You can use one of the following values:

• Integer of value 0 or higher identifying a specific port number, such as:

-ap o

• String matching an existing port name:

-ap "Line In"

• String with a wildcard (*) matching an existing port name, such as:

-ap "Mic*"

Note: This option is not available on Windows or on Linux distributions that use the free OSS audio drivers. Instead, set the audio capture port using the Windows Recording Control Panel. On Linux, use mixer software specific to your Linux distribution.

For More Information: Use the Print Device Information (-pd) optionto list values for your system.

Capture Mono Audio (-cm)

The Linux-only -cm option forces the audio card to record a single, mono audio channel. Omitting the option enables stereo capture. The option does not require any values:

-cm

Tip: When capturing mono-only, you'll get best results when using one of the mono codecs listed in "Voice Codecs" or "Mono Music Codecs".

Video Capture Device ID (-vc)

Use -vc to set the device ID for the input video device. Using this option overrides the -i option for a file input. You can use one of the following values:

• Integer of value 0 or higher identifying a specific device number:

-vc 1

• String matching an existing device name:

-vc "Osprey Capture Card 1"

• String with a wildcard (*) matching an existing device name, such as:

-vc "Osprey*"

• UNIX device name or symbolic link to a device name, such as:

-vc /dev/video3

For More Information: Use the Print Device Information (-pd) optionto list values for your system.

Video Device Port (-vp)

The -vp option sets the port for the video capture device. If you use -vp, you must specify the video device ID as well. Using the -vp option overrides the -i option for a file input. If you omit the port, the current mixer settings are used. You can use one of the following values:

• Integer of value 0 or higher identifying a port number, such as:

-vp 1

• String matching an existing port name:

-vp "S-Video"

• String with a wildcard (*) matching an existing port name, such as:

-vp "Composite*"

Note: This option is not available with Video for Windows (VFW) devices. Instead, use the graphical application to set the port through the capture card dialog. See "Using Live Audio or Video as the Input" for instructions.

For More Information: Use the Print Device Information (-pd) optionto list values for your system.

Video Format (-vf)

The -vf option defines the video format on Linux only. It specifies the video format of the video capture device. On Windows, use the driver dialog to set the video format. This option is ignored if you do not also use the Video Capture Device ID (-vc) option. The default is NTSC. The following are the possible values:

• NTSC
• NTSC-JP
• PAL
• PAL-M
• PAL-N
• PAL-NC
• SECAM
• integer (specifies a format understood by your video driver)

Here are some examples:

-vf SECAM
-vf 8

Capture Frame Size (-cs)

The -cs option sets the size of the video capture when you use the Video Capture Device ID (-vc) option. It is ignored for audio-only and file-to-file encoding. If you do not specify this size, the dimensions set in the video capture card are used. The value specifies pixel dimensions in the form WidthxHeight, as shown in the following example:

-cs 320x240

Note: The RealVideo codec rounds each dimension down to the nearest 4 pixels. If you specify a height of 183 pixels, for example, the output clip has a height of 180 pixels.

For More Information: You can resize any video output, whether from a capture or with file-to-file encoding. See "Resize Video (-rs)".

Capture Duration (-d)

The -d option sets the duration that the audio or video capture lasts. This is not used when encoding from a file. The duration timer begins when you start the encoding. If you omit this option, encoding lasts until you stop it manually. The section "Duration Syntax" explains how to specify time values. Here are some examples:

Clip Information Options

The following clip information options are available through the command- line application. Adding clip information is highly recommended. For background on the information values, refer to "Adding Clip Information".

Title (-t)

The -t option defines a title for the clip or broadcast. The value can be any string up to 255 characters. For example:

-t "2004 Music Awards"

Author (-a)

Use the -a option to define the author of the clip or broadcast. The value can be any string up to 255 characters. For example:

-a "Brilliant Media Limited"

Copyright (-c)

The -c option defines the copyright owner and date for the recorded clip. The value can be any string up to 255 characters. For example:

-c "2004 Brilliant Media Limited"

Keywords (-k)

Using the -k option, you can define keywords that help search engines index your clip. The value can be any string up to 255 characters. For example:

-k "awards 2004 music"

Description (-de)

Using the -de option, you can set a description of the clip that is longer and more informative than the title. The value can be any string up to 64 Kilobytes in size. For example:

-de "An encore presentation of the 2004 music awards."

Content Rating (-r)

The -r option defines the age range for which the content is applicable. Use one of the following integer values (0 is the default):

For example:

-r 1

Prefilter Options

The following prefilter options are available through the command-line application. A prefilter modifies the audio or video input before it is encoded. Because all prefiltering is optional, no prefilters are applied by default.

Note: You cannot apply the audio compensation prefilter, which adjusts audio that is out of synchronization with video, through the command line. You can specify this prefilter in a job file, however. See "Audio Delay Compensation Prefilter".

Audio Gain Filter (-ag)

The -ag option applies the audio gain filter to amplify or attenuate the input audio. This can boost the audio signal or decrease it to prevent it from clipping. The value is a number from -48.0 (attenuation) to 48.0 (amplification). For example:

-ag -5.0

For More Information: For background on audio gain, refer to "Monitoring Audio".

Disable Audio Watchdogs (-daw)

The -daw option disables the audio watchdogs, which are a set of tests that RealProducer runs on the audio input to detect audio problems. You can use them when encoding from a file or a live capture, but they are most useful when capturing live media because you may be able to correct the problem through the capture equipment. Any audio problems discovered are logged periodically (typically every five seconds) while the problem persists. After logging 20 messages for the same problem, RealProducer suspends logging of that message for 16 hours. The following table describes the watchdog tests.

The option does not require a value, as shown here:

-daw

Black Level Filter (-bl)

This filter increases contrast in videos by making dark colors pure black and off-white colors pure white. The option does not require a value:

-bl

For More Information: The section "Black-Level Correction Filter" describes this filter.

Inverse-Telecine and De-interlace Filters (-di)

The -di option specifies the use of the inverse-telecine or de-interlace filter on the video input. The de-interlace filter is generally needed only on videos larger than 320 by 240. The inverse-telecine filter is for videos that were transferred from film. The following are the values that you can specify.

Here is an example:

-di auto

For More Information: The sections "Inverse-Telecine Filter" and "De-interlace Filter" explain how these filters operate.

Crop Video Input (-cr)

The -cr option applies the cropping prefilter, which crops out areas from the sides of the input video. The option uses four pixel values, separated by commas and no spaces. In order, these values indicate the values for Left, Top, Width, and Height.

In the following example, the cropping starts 10 pixels to the right of the video's left edge and 20 pixels down from the top edge. The resulting video is then 320 pixels wide by 240 pixels high.

-cr 10,20,320,240

Tip: As described in "Resize Video (-rs)", you can also resize a video. Because cropping occurs first, the final two numbers of the -cr value indicate the input size for the resizing operation.

Video Noise Filter (-nf)

As described in "Noise Filters", the noise filters can remove small distortions in the video image. Use a value of low for small distortions, a value of high if the noise is more pronounced. You should not apply these filters to video input that is free of distortion. Here is an example:

-nf high

Output and Destination Options

This section describes the output and destination options. Using the RealProducer Plus command-line application, you can encode a single output, but can send that output to any number of destinations, whether files or servers. With RealProducer Basic you can define one file destination and one server destination for each encoding session.

For More Information: If you create a job file, you can specify multiple outputs, each of which may have different encoding options and destinations. See "File and Server Outputs"

Output File or Directory (-o)

The -o option sets the output clip's file name and path to an existing directory. The path can be absolute or relative to the current directory. You must supply a file name for captured input. With file-to-file encoding, you can omit the -o option to encode the clip using the input file's base file name and the appropriate extension, either .rm for constant bit rate clips or .rmvb for variable bit rate clips. In this case, the output clip is saved to the directory that holds the input file. The following examples specify output paths and file names:

-o C:\Movies\movie1.rm
-o /usr/producer/output/movie2.rmvb

Batch Output Encoding

As described in "Batch File Encoding", you can encode multiple input files using wildcards. In this case, you do not need to specify the outputs to save the encoded clips in the directory that holds the input files. The outputs will use the input files' base file names along with the .rm or .rmvb extension. You can use the -o option to specify an output directory, however, if you want to save the clips in a different directory:

-o C:\Movies
-o /usr/producer/output/

Archive Clips

If you specify the name of clip that exists already in the output directory, RealProducer does not overwrite the existing clip. Instead, it archives the existing clip by appending _archNNN to the base file name. Hence, movie.rm becomes movie_arch001.rm before the new movie.rm clip is saved. If you encode the output again, the existing movie.rm becomes movie_arch002.rm. Higher numbers therefore represent newer archives.

Destination File Roll Size (-drs)

Use the -drs option to set an file size limit in Megabytes that causes RealProducer to create a new output file. The section "File Rolling" explains how file rolling works. The following example sets a roll size of 20 Megabytes:

-drs 20

Destination File Roll Time (-drt)

The -drt option sets an encoding duration after which RealProducer creates a new output file. The section "File Rolling" explains how file rolling works. See "Duration Syntax" for information about timing values you can use. The following example creates a new file archive after RealProducer has encoded the output for 15 minutes:

-drt 15:00

Push Server Destination (-sp)

The -sp option defines a push broadcast with Helix Server version 9 or later as the destination. You can perform an account-based push, password-only push, or multicast (RealProducer Plus only). Before running a push broadcast, review the broadcast issues described in Chapter 10 and be sure that you understand the broadcast features and server set-up requirements for your chosen type of broadcast, as described in one of the following sections:

• "Running an Account-Based Broadcast"
• "Setting Up a Password-Only Broadcast"
• "Multicasting a Live Stream"

Push Server Syntax

This broadcasting method uses the following syntax:

-sp username:password@address:port/path/stream

As the following table explains, you may not need to define every component in the broadcast stream, depending on the broadcast type and the server settings.

Default Broadcast Values

The -sp broadcasting option does not allow you to set advanced broadcast parameters such as the transport type and error correction features, which the section "Changing Advanced Push Broadcast Parameters" describes. Nor can you set the listen address if you are broadcasting through a firewall performing network address translation (NAT). Instead, this broadcasting option uses the default values for these features.

For More Information: If you need to change default values for advanced broadcast features, use the Server Template or Server File (-sd) option, or define the broadcasting options in a job file.

Push Broadcast Examples

The following examples show how to perform one of the three possible broadcast types using the -sp option.

Account-Based Broadcast Example

The presence of a user name and password causes RealProducer to start an account-based broadcast. In the following example, the port value is included because the server does not use port 80 for HTTP requests. No virtual path is given, and the stream name is news.rm.

-sp remote_encoder:as45er897@helixserver.example.com:8080/news.rm

If authentication is not required on the server, you can omit the user name, password, and @ sign:

-sp helixserver.example.com:8080/news.rm

Password-Only Broadcast Example

The presence of a password but no user name, along with a non-multicast IP address or DNS name, starts a password-only broadcast. In the following example, the port value is not given, so RealProducer delivers the stream to the default port 30001. A virtual path used by the server is provided, along with the stream name live.rm.

-sp TY45poiu@helixserver.example.com/sports/live.rm

Multicast Example

The presence of a password but no user name, along with a multicast IP address, starts a password-only broadcast. In the following example, the port value of 30011 is supplied. No virtual path is used with the stream name.

-sp 569ad42k@224.0.0.1:30011/playoffs.rm

Pull Server Destination (-si)

The -si option defines a pull broadcast accessible by Helix Server version 9 or later. Before running a pull broadcast, review the broadcast issues described in Chapter 10 and be sure that you understand the broadcast features and server set-up requirements described in "Running a Pull Broadcast".

Pull Server Syntax

This broadcasting method uses the following syntax:

-si password@listenAddress:listenPort/path/stream

As the following table explains, you may not need to define every component in the broadcast stream, depending on the server settings.

Default Broadcast Values

With pull broadcasting, the server that pulls the stream defines most of the advanced stream features, such as error correction. RealProducer defines a few advanced parameters, however, which the section "Defining a Pull Broadcast Server Destination" describes. When you use the -si option, the command-line application uses the default settings.

For More Information: If you need to change default values for advanced broadcast features, use the Server Template or Server File (-sd) option, or define the broadcasting options in a job file.

IP Address Values

To find the listen address of the RealProducer machine where the command line application is running, do the following:

• On the Linux command line, type the following to display the IP address on the screen:

ifconfig

• On Windows NT/2000/XP, open a command prompt and type the following to display the IP address on the screen:

ipconfig

• On Windows ME/98SE, open a command prompt and type the following to open a dialog that allows you to select different network cards and view their IP addresses:

winipcfg

Pull Broadcast Examples

The following example shows how to start a pull broadcast using the -si option and specifying all possible values, including a virtual path name:

-si dkgy435ty@192.168.224.221:3031/rock/radio.rm

To use the RealProducer default IP address and listen port, you would use a value such as the following. This example does not include a virtual path with the stream name:

-si dkgy435ty@0/radio.rm

Legacy Push Server (-sg)

The -sg option defines a push broadcast to a version of RealSystem Server that predates Helix Server version 9. It is available only with RealProducer Plus. Before running a legacy broadcast, review the broadcast issues described in Chapter 10 and be sure that you understand the broadcast features and server set-up requirements described in "Setting up a Legacy Broadcast".

Legacy Push Server Syntax

This broadcasting method uses the following syntax:

-sg username:password@address:port/path/stream

As the following table explains, you may not need to define every component in the broadcast stream, depending on the broadcast type and the server settings.

Legacy Broadcast Example

The following example shows how to perform a legacy broadcast using the -sg option. No virtual path is given, and the stream name is news.rm:

-sg encoder:as45er897@realserver.example.com:4040/news.rm

Server Template or Server File (-sd)

Available with RealProducer Plus, the -sd option allows you to broadcast in pull or push mode using a predefined server destination. When you use this option, a server destination template or file sets the necessary broadcast parameters, such as the server's IP address, transport method, and advanced parameters like error correction. This is the most flexible means of broadcasting, but requires the use of a separate, server destination template or file.

For More Information: Chapter 11 covers the different broadcasting methods and explains how to create a server destination using the graphical application. Appendix D explains the server file syntax.

Server Destination Syntax

This broadcasting method uses the following syntax:

-sd username:password@definition,path/stream

As the following table explains, you may not need to define every component in the -sd option's value, depending on the broadcast type.

Locating Server Definitions

As explained in Appendix D, a server destination file is an XML-formatted file that uses the extension .rpsd. To use a destination file, provide the full file name and extension, along with a relative or absolute path as the definition component. Relative paths are relative to the directory from which you run the command-line application.

You can also specify a server template, which is a server destination file stored in the servers directory under the main RealProducer installation directory. To use a template, you provide the template name, which is the value of the destination's name property. You can abbreviate the template name down to a unique set of letters.

Tip: Use the Print Servers (-ps) option to display a list of available server templates.

For More Information: You can change the location of the server templates by editing the preferences file as described in Appendix E

Server Definition Examples

The following example specifies the absolute path to a server destination file that sets up an account-based broadcast. Both a user name and password are supplied, as required by the account-based, push broadcast method:

-sd remote_encoder:as45er897@/usr/encoder/pushbroadcast.rpsd,football.rm

The next example provides the relative path to a server destination file that defines a password-only push broadcast. Accordingly, the -sd option value supplies just a password. A virtual path of hourly/ is included with the stream name:

-sd yop563sdf@../definitions/SydneyReceiver.rpsd,hourly/news.rm

The following example indicates a server destination template named Rock Radio Pull Broadcast stored in the default template directory. When you specify a template, you can abbreviate the name down to a unique set of characters, such as Rock in the following example:

-sd 567dlopf212@Rock,livefeed.rm

Encoding Options

This section lists the general encoding options that affect the output, whether a clip or a broadcast stream. Use these options to select the video codec, for example, or specify the encoding audiences.

Audience Definitions or Audience Files (-ad)

The -ad option defines the audiences for which the output is encoded. You can use the Print Audiences (-pa) option to display the available audience definitions. You can abbreviate an audience name to a unique set of characters. For example, you can specify the 28k Dial-up audience by using 28k. When you use just the audience name, RealProducer looks for the audience file in the location specified by the RealProducer preferences.

If an audience file does not reside in the default location, you can provide the location of the audience file, using a full or relative path along with the file name, including the extension (.rpad). Using either the audience name or file name, you can specify multiple, constant bit rate (CBR) audiences using a quoted, comma-separated list. With variable bit rate (VBR) video or RealAudio lossless encoding, you can specify only one audience. Here are examples:

-ad 150k 
-ad "28k,56k"
-ad "28k Dial-up,56k Dial-up,256k DSL/Cable Modem"
-ad "C:\settings\ModemGeneralAudience.rpad"
-ad "/files/28k.rpad,/files/56k.rpad"

Tips for Using Audience Definitions

Note the following about selecting audiences:

• Using RealProducer Plus, you can add any number of CBR audiences to a SureStream clip. With RealProducer Basic, you are limited to three audiences.
• If you specify no audiences with the -ad option and you do not use a job file that defines audiences, RealProducer encodes the output for the default audiences, which are described in the section "Default Audiences and Options".
• Chapter 7 describes the encoding settings of the predefined audiences.
• If you create your own audience definitions, you set the audience name through the name property, as described in "Audience Properties".
• RealProducer 10 automatically updates older audience files to use the latest codecs. You can disable this, however, with the Disable Codec Updates (-duc) option.
• The section "Adjusting RealProducer Preferences" explains how to find the default location of audience files.

Disable Two-Pass Encoding (-dt)

By default, RealProducer reads an input file in two passes. The first pass analyzes the data, the second pass encodes it. The -dt option disables two-pass encoding so that all actions occur in a single pass. This speeds encoding time, but lowers the encoded quality. Use the option without any values:

-dt

Automatic Disabling of Two-Pass Encoding

Two-pass encoding is automatically disabled when you specify the following options for live capture:

• Audio Capture Device ID (-ac)
• Video Capture Device ID (-vc)

It is also disabled if you send output to a server using any of the following options:

• Push Server Destination (-sp)
• Pull Server Destination (-si)
• Legacy Push Server (-sg)
• Server Template or Server File (-sd)

Audio Mode (-am)

Use the -am option to describe the basic audio content of the input, either voice or music. This determines whether a voice or audio codec is used to encode the audio. Values are voice or music. Because the default is music, you need to include this option only if encoding voice-only audio:

-am voice

For More Information: The actual codecs used are defined in the audience template. Each codec expects a certain type of input, such as mono, stereo, or discrete multichannel. For information about how an audience defines codecs, refer to "Audio Stream Context".

Disable Audio (-da)

The -da option strips the audio from the input source. Typically, you use this when encoding file-to-file or capturing video input for which you do not want to encode audio. The option does not require a value. For example:

-da

Tip: Do not use the -da option when capturing audio with the Audio Capture Device ID (-ac) option. Instead, omit the -ac option.

Audio Resampling Quality (-arq)

As explained in "Sampling Rate", RealProducer resamples audio if the input does not match the sampling rate expected by the chosen RealAudio codec. The -arq option determines the resampling quality. The default value of high produces the best results, but uses more processing power than the fast value, shown here:

-arq fast

Note: Neither the fast nor the high value causes pitch shifting.

Video Mode (-vm)

The -vm option influences the visual quality of the encoded video. It helps you to balance visual clarity against frame rate, and generally has more effect on videos encoded for low bandwidths. You can use it to help heighten the visual clarity or increase the encoded frame rate. You can use one of the following values:

For example:

-vm sharp

Disable Video (-dv)

The -dv option strips the video out of the input source. Typically, you use this when encoding file-to-file and want to capture only the audio portion of a video clip. The option does not require a value. For example:

-dv

Tip: Do not use the -dv option when capturing audio with the Video Capture Device ID (-vc) option. Instead, omit the -vc option.

Resize Video (-rs)

If you have RealProducer Plus, you can use the -rs option to set the output video's width and height in pixels. This option uses a value WidthxHeight, in which each component is an integer from 0 to 2048. The default value of 0x0 performs no resizing. If you set a single value to 0, that dimension scales in proportion to the other dimension, maintaining the input clip's aspect ratio. The following are examples:

Note: The RealVideo codec rounds each dimension down to the nearest 4 pixels. If you specify a height of 183 pixels, for example, the output clip has a height of 180 pixels.

For More Information: The Capture Frame Size (-cs) option can resize video capture input. This allows you to resize the encoded output by overriding the default video capture dimensions.

Resize Quality (-rq)

When you resize the encoded video using the -rs option, the -rq option affects the resulting quality. Using the default high value results in a higher-quality output, but requires considerably more processing power during encoding. The fast value uses less processor power, but results in lower quality:

-rq fast

Video Codec Override (-vco)

Using RealProducer Plus, you can choose a video codec other than the default RealVideo 10. This allows you to use RealVideo 9 or RealVideo 10 for faster encoding, or backwards-compatibility with RealPlayer 8. The selected codec encodes all video streams for the output. Acceptable values are rv10, rv9, and rv8, as shown here:

-vco rv8

Encoding Complexity Override (-eco)

With RealProducer Plus, you can set a complexity mode, which the section "Encoding Complexity Modes" explains. This mode affects RealVideo 9 or 10 clips, as well as RealAudio lossless clips. The default value of high produces the best results, but requires the most processing power. A value of medium or low speeds processing time, but results in lower quality for video clips or a larger file size for lossless audio clips. Here is an example:

-eco medium

Note: When you use a server as a destination, RealProducer automatically scales down the encoding complexity as needed. You therefore do not need to use this option when producing a broadcast. See "Broadcast Load Management" for more information.

Logging Options

The following options affect the messages that RealProducer creates as it encodes a job. The log file location is set through the RealProducer preferences, as described in "Adjusting RealProducer Preferences".

Logging Category (-lc)

The -lc option determines the level of logging messages used, overriding the logging category set in the preferences. These messages are written to the log file or printed to the screen, depending on the other logging options you use. For the value, use a comma-separated string that includes any of the following:

You can abbreviate each value down to the first letter, as shown in the following examples:

-lc "error,warning,info"
-lc "err,warn,info,diag" 
-lc "e,w,i,d"

For More Information: The section "Changing Log File and Log Viewer Preferences" explains how to set logging preferences through the graphical application. You can also set these preferences manually, as described in Appendix E.

Disable Logging to File (-dlf)

The -dlf option disables logging to the log file. Messages may still display on the screen. The option takes no value:

-dlf

Disable Logging to Screen (-dls)

The -dls option disables logging to the screen. Log messages may still be written to the log file, however. The option takes no value:

-dls

Quiet Mode (-q)

The -q option prevents any information, including log messages, from being printed to the screen. Use this option if you are running the command-line application from another application that will fail if output is written to the standard output device. The option takes no value:

-q

Process ID File (-pid)

The -pid option writes a file that holds the process ID of the current encoding section. This ID is useful for shutting down the command-line application remotely, as described in "Stopping the Command-Line Application". The option uses as a value a file name and path, which can be absolute or relative to the current directory. Here are some examples:

-pid ..\Jobs\job18.pid
-pid /usr/log/job34.pid

Help Options

The following sections explain the help options that you can display through the RealProducer command-line application.

Display Help (-h)

Use the -h option without any other options to display a list of commands that you can use with the command-line application. The option does not require a value, as shown here:

-h

Display Detailed Help (-m)

Use the -m option without any other options to display full information about the commands that you can use with the command-line application. The option does not require a value, as shown here:

-m

Print Device Information (-pd)

The -pd option extracts audio and video capture device information. Use only this option without a value on the command line:

-pd

You can use the returned device information with the following options:

• Audio Capture Device ID (-ac) option
• Audio Capture Device Port (-ap) option
• Video Capture Device ID (-vc) option
• Video Device Port (-vp) option

Tip: If the -pd option does not return audio port information on Linux, use mixer software to adjust the input audio port.

Print Audiences (-pa)

This option prints a list of acceptable audiences that you can use with the Audience Definitions or Audience Files (-ad) option. Use only this option on the command line. It does not require a value:

-pa

Print Servers (-ps)

Use the -ps option alone on the command line to list the accepted server definitions for use with the Server Template or Server File (-sd) option. No value is required. Example:

-ps

Print Version (-v)

The -v option displays version and copyright information for RealProducer. No value is required:

-v

Command Line Usage Examples

The following sections provide examples of how to run the RealProducer command-line application.

Basic Encoding Examples

The following examples illustrate the most basic uses of the command-line application.

Simple Encode

The following example is the simplest possible encoding of a media clip. Because no audiences are specified, RealProducer encodes using the default audiences described in "Default Audiences and Options". Because no output is specified, the encoded clip is named movie.rm. The .rm extension is used because the default audiences are constant bit rate audiences:

producer -i movie.avi

To save the clip to a different directory or file name, you can include the -o option:

producer -i movie.avi -o c:\videos\movie_streaming.rm