Chapter 10: Using the Command Line

This chapter shows you how to run Helix Producer from the command line. The Helix Producer command line application gives you the ability to encode streaming media, both as files and as a live broadcast. You will also learn about other installed utilities that allow you to use the command line to create and modify streaming media files.

Overview: Command Line Programs

The following command line programs are available to you:

• The producer.exe command line application allows you to create RealMedia files and broadcast to a server from RealNetworks. Using commands, you have the ability to set up input devices, use video prefilters, select destinations, and change audience settings. For more information, see "Using the producer.exe Application" below.
• The rmeditor.exe utility allows you to change information about a RealMedia file, trim the length of the clip, combine multiple RealMedia files, and create a text file containing the file's information. For more information, see "Using the rmeditor.exe Utility".
• The rmevents.exe utility allows you to merge image map and event text files into an existing RealMedia file, and extract events and image maps from a RealMedia file into a text file. For more information, see "Using the rmevents.exe Utility".

Using the producer.exe Application

The producer.exe application is fully functional, giving you the same encoding capabilities as the Helix Producer main interface. This application is also designed for users who want to encode a batch of files using wildcards.

There are two ways to use this application. The first way to use producer is to run the program, typing in options and their values for the different aspects of the encoding process. The second way is to create a job file and run the program with that job file. A job file is a saved text file that shows Helix Producer how to run an encoding session.

The rest of this section shows you the full syntax of the producer.exe application, then breaks down all of the options into different sections, giving a description of each option. Finally, some examples of common uses are provided.

producer.exe Syntax

This section shows you the basic syntax to encode streaming media with the producer command-line application. It also gives you a brief description of the options you can use with the application. Use the references to find more detailed information about these options, located later in this chapter.

The basic syntax of the producer.exe command-line application is as follows:

producer [input] [output] [general_options]

Where [input] is one of the following:

And where [output] is one or more of the following:.

[username:password@]ServerDefinition,streamname

And where [general_options] are any of the following:

You can also use the application to display information without encoding streaming media:

producer [information_options]

Where [information_options] is one of the following:.

Input and Output Options

The following sections describe in more detail the input and output options used with the producer command-line application.

Input File (-i)

The input file to be encoded, located on a network or local drive. Wildcards can be used to run a batch of jobs. The value is a valid file name of a job file. You can use either a relative path from the working directory, or an absolute path. Here are some examples:

-i myfile.avi
-i c:\files\movie.avi
-i c:\files\*.avi

Audio Capture Device ID (-ac)

Specifies the audio device ID for the input audio devices. Using this option overrides the -i option. Use the Print Device Information (-pd) option to list values on your system. You can also use wildcards. Here are some examples:

-ac 0
-ac "Sound Blaster*"

Audio Capture Device Port (-ap)

Specifies the audio port for the input audio devices. Overrides the -i option. Use the Print Device Information (-pd) option to list values on your system. For example:

-ap "mic"

Video Capture Device ID (-vc)

Specifies the device ID for the input video device. Overrides the -i option. Use the Print Device Information (-pd) option to list values on your system. Here are some examples:

-vc 0
-vc "Osprey*"
-vc /dev/video3

Video Device Port (-vp)

Specifies the device port for the input video capture device. If omitted, the current mixer settings are used. Overrides the -i option. Use the Print Device Information (-pd) option to list values on your system. You can also use wildcards. Examples:

-vp 0
-vp "Composite 1"

Video Format (-vf)

Linux only option. Specifies the video format of the input video capture device. Value can be NTSC, PAL, SECAM, AUTO, or an integer. Examples:

-vf SECAM
-vf 8

Audio/Video Device Duration (-d)

Specifies the amount of time before the job ends and encoding from the device stops. Duration can be specified in Days:Hours:Minutes:Seconds:

[d:][h:][m:][s[.ms]]

The default is an infinite duration. Here are some examples:

-d 90 (90 seconds) 
-d 1:00:00 (1 hour)

Output File or Directory (-o)

The file name for the output RealMedia file, or the directory if multiple input files are used (batch encoding). If multiple files are used, the output names are automatically generated. If the specified output directory does not exist, it will be created.

The general file extension for RealMedia files is .rm. If you are encoding with Variable Bit Rate (VBR), you must use the .rmvb extension.

Examples:

-o C:\files\movie.rm
-o C:\output\variable.rmvb
-o C:\Movies

Push Server (Server 9) (-sp)

Settings required for a live server output using the Push Broadcast method available in Helix Universal Server 9 and greater. Value is:

[password@]address[:startPort[-endPort]]/streamname

Where:

Example:

-sp pass@server.co.com:3000-30001/live.rm

Pull Server (Server 9) (-si)

Settings required for a server-initiated broadcast output stream using the Pull Broadcast method available in Helix Universal Server 9 and greater. Value is:

[password@]listenAddress:listenPort/streamname 

Where:

Examples:

-si pass@192.168.224.221:3031/live.rm
-si 205.198.34.3/wildlife.rm

Legacy Push Server (-sg)

Settings required for encoding to RealServer versions G2 through 8.01. Value is:

[username:password@] address[:port]/streamname

Where:

Examples:

-sg name:pass@realserver.yourcompany.com/live.rm 

-sg jdoe:letmein@172.16.0.34:4040/meeting.rm

Server Definition or Server File (-sd)

May be either the name of a Server defined within the Helix Producer or a Server File located anywhere on the hard drive. If a Server File is referenced, the full filename must be included, including file extension. The producer application will search for a filename matching the filename first and then look in the Servers defined within the Helix Producer. If relative paths provided for server files, the location is relative to the working directory. Value is:

[username:password@]ServerDefinition,streamname

Where:

Examples:

-sd janedoe:letmein@RBN Hosting Server,live.rm
-sd Server1,/live/radio.rm
-sd janedoe:letmein@C:\settings\Server1.rpsd/live.rm

General Options—Encoding Options

You can use the following encoding setting options with the producer utility.

Audience Definitions or Audience Files (-ad)

This option provides a list of Audience Definitions defined within the Helix Producer. The name of the audience may be abbreviated with the first few letters. The closest matching audience is used. For example, "28k Dial-up" may be abbreviated with "28." The default is 28k Dial-up and 56k Dial-up. The value is a comma-separated list of strings that matches the names of an Audience Definitions defined within the Helix Producer.

You can also use an Audience File that you have created. An Audience File is an XML-based file that specifies the video codec, audio codec, bit rate and other settings for the audience. If you use an Audience File, you must enter the full filename, including the extension. For information on using Audience Files, see "Creating an Audience File".

Here are examples:

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

Audio Mode (-am)

Describes the type of audio content. This setting determines which audio codec is to be assigned from an audience. Values are voice or music. The default is voice. Example:

-am music

Video Mode (-vm)

Setting to control the picture quality of the encoded video. Values include sharp, normal, smooth, and slideshow. The default is normal. For example:

-vm sharp

Disable Two-Pass Encoding (-dt)

The input file is read in two passes, the first to analyze, and the second to encode. Only applies for encoding file-to-file. It is ignored if the input is a device (-d) or the output is a server (-sg, -sp, -si, -sd). No value is required. For example:

-dt

Disable Audio (-da)

If used, the audio from the input source will be stripped out. No value is required. For example:

-da

Disable Video (-dv)

If used, the video from the input source will be stripped out. No value is required. For example:

-dv

Resize Quality (-rq)

Affects the resulting quality of an output file when resize is applied. Choosing high results in a better quality resize, but uses considerably more CPU. Ignored if the -rs option is omitted. Values are fast (default) and high. Example:

-rq high

Resize Video (-rs)

Sets the output video width and height in pixels. If either is set to 0, its value is computed from the original video's aspect ratio. Value is:

WxH

Where:

Examples:

-rs 320x240
-rs 320x0 (resize width to 320 and maintain aspect ratio)
-rs 0x240 (resize to 240 high but maintain aspect ratio)
-rs 0x240 (resize to 240 high but maintain aspect ratio)

Audio Resampling Quality (-arq)

Allows you to specify the quality of audio resampling. Resampling must be done if the sample rate required by the target audio codec is different from the input file or device sample rate. The producer automatically invokes the resampler for each audio codec as needed.

Values are high or fast. Choosing high results in an audio-only encode using as much as 2 times as much CPU for live broadcasting or taking twice as long to encode for file-to-file encoding. Choosing fast does not incur additional CPU but the encoded output will have a slightly lower quality. In all cases, there is no pitch shift incurred by the audio resampler.

For example:

-arq fast

General Options—Prefilter Options

The following prefilter options are available for the producer utility.

Audio Gain Filter (-ag)

Prevents the audio signal from clipping by applying dynamic range compression, as well as offering gain control to increase or decrease the gain of the signal. The value is any number from -12.0 to 12.0. For example:

-ag 0

Black Level Filter (-bl)

This filter is designed to make black colors darker. If the source video has a washed-out appearance, use this filter to help restore proper color. No value is required. Example:

-bl

Inverse Telecine and Deinterlace Filters (-di)

Specifies use of inverse telecine and/or deinterlace filters. If you are unsure whether input was created using the telecine or interlace processes, you can specify autodetect. Values is auto, d, i or both, where:

Example:

-di auto
-di i

Crop Video Input (-cr)

Prefilter that crops out unwanted video. Values are pixel values for left, top, width, and height. For example:

-cr 2,2,320,240

Video Noise Filter (-nf)

Removes small distortions or static in the video image. Value is low or high. Examples:

-nf low
-nf high

General Options—Clip Information Options

The following clip information options are available for use with the producer utility.

Title (-t)

The title for the recorded clip. Use quotes if spaces are used. The value can be any string up to 255 characters. Example:

-t "A Slug's Life"

Author (-a)

The author of the recorded clip. Use quotes if spaces are used. The value can be any string up to 255 characters. Example:

-a "Billy Shakespeare"

Copyright (-c)

The copyright owner and date for the recorded clip. Use quotes if spaces are used. The value can be any string up to 255 characters. Example:

-c "Diznee 2001"

Keywords (-k)

Keywords that will help search engines locate your clip. Use quotes if spaces are used. The value can be any string up to 1023 bytes. Example:

-k "pets slugs"

Description (-de)

A brief description of the clip. Use quotes if spaces are used. The value can be any string up to 64 kb. Example:

-de "a gripping story about a man and his pet banana slug

Content Rating (-r)

Defines the age range for which the content is applicable. Available options are: 0 - No Rating , 1- All Ages 2 - Older Children, 3 - Younger Teens, 4 - Older Teens (15 & Up), 5 - Adult Supervision Recommended, 6 - Adults Only. Example:

-r 1 

General Options—Screen Output Options

You can use the following screen output options with the producer utility.

Logging Category (-lc)

Determines the level of logging messages used. Informational messages are low volume and high importance while diagnostic messages are high volume and generally low importance. Values are error, warning, info, and diagnostic. Value may be abbreviated. Examples:

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

Disable Logging to File (-dlf)

Suppresses logging to file. No value is required. Example:

-dlf

Disable Logging to Screen (-dls)

Suppresses logging to the screen. No value is required. Example:

-dls

Quiet (-q)

All output is disabled. Useful if you are running the producer from within another application that fails if data output to standard output or standard error. No value is required. Example:

-q

Information Options

The following information options are available for use with the producer utility.

Help (-h)

Returns help for using the command line producer. No value is required. Example:

-h

Print Device Information (-pd)

Extracts audio and video device information from the system for use in the -d option. See "Audio/Video Device Duration (-d)" for information on how to use the information printed with this command. This option may only be used by itself on the command line. No value is required. Example:

-pd

Print Audiences (-pa)

Prints a list of accepted Audience Definitions for use in the -ad option. No value is required. Example:

-pa

Print Servers (-ps)

Prints a list of accepted Server Definitions for use in the -sd option. No value is required. Example:

-ps

Print Version Information (-v)

Prints the version of Helix Producer used. No value is required. Example:

-v

Examples

This section shows you some examples of how to put the preceding options together for some common uses of the producer.exe command line program.

Simple Encode

The following example is a simple encode of a media file. Using the default values for all options, the output is named file.rm and is encoded using the 28k and 56k audience definitions.

producer -i file.avi

Batch Encoding with a Wildcard

The following example encodes a batch of files using a wildcard to designate the input files. The output files are all placed in the movies directory.

producer -i C:\capture\*.avi -o C:\movies\

Live Input Capture to File

The following example captures input from the video capture card and the audio sound card and writes to output file capturefile.rm.

producer -vc 0 -ac 0 -o c:\capturefile.rm

Live Input Capture for Broadcast

The following example captures audio and video and streams to a standard Helix Universal Server using streamname live.rm.

producer -v 0:2 -ac 0 -s janedoe:pass@realserver.mycompany.com:4040/live.rm

Capture with Audience Targets

The following example captures audio and video and streams both to a server and to a file. It also targets the 56k and 150k audiences.

producer -v 0:2 -ac 0 -s me:letmein@realserver.abc.com:4040/live.rm
-o archive.rm -ad "56k,150k"

Clip Information

The following example shows you how to encode using clip information: a title, author, and copyright.

producer -i myfile.mov -o output.rm -t "Summer Vaction" -a "John Doe"
-k "Cape Cod Summer Vacation 2001"
-de "Video from summer vacation in Cape Cod."

Prefilters

The final example shows you how to use prefilters. Here, the example uses the audio gain with a value of 4, audio mode of music, resizes to 240 high by maintaining aspect ratio, uses high quality resize, applies a black level filter and performs auto-detection of De-interlace and Inverse Telecine.

producer -i vacation.mov -o vacation.rm -ag 4 -am music -rs 240x0 -rq high -bl -di auto

Encoding With a Job File

When you use a job file, all encoding options are listed within the file, and you need to pass a maximum of two options on the command line. Use the following syntax when encoding with a job file:

producer -j job_filename -sa Username:Password@ServerDefinition

Job Filename (-f)

Tells the utility to run a Job File from the command line. The value is a valid file name of a job file. You can use either a relative path from the working directory, or an absolute path. For example:

-j MyJob.rpjf

Create Job File (-cj)

Generates a Job File from the command line options provided. The value is a valid file name of a job file. You can use either a relative path from the working directory, or an absolute path. For example:

-cj NewJob.rpjf

Creating an Audience File

Audience Files are XML-based files that you edit using any text editor. These files can be used with the command line application to customize the audiences that you will use for encoding.

Helix Producer is installed with a number of default Audience Files that you can use to modify and create your own. These default files are located in the Audiences directory off of the application directory. It is recommended that if you modify a default audience file, you save it under a different filename.

Changing RealAudio Stream Sections in an Audience File

Within the Audience File, there is a section for each audio stream used. For each stream you specify the codec name, codec flavor, and the context of the codec used.

Below are tables that lists codec names and flavors, and also lists the corresponding RealAudio codec. See "Appendix A: RealAudio Codec Reference" for more information on RealAudio codecs.

Changing the RealVideo Stream Section in an Audience File

Within the Audience File, there is a section for the video stream. Here, you specify the following:

• codecName—the RealVideo codec name used to encode the video. Below is a table that lists codec names and the corresponding RealVideo codec.

  Table 3: RealVideo Codecs

  Name	RealAudio Codec Used
  rv9	RealVideo 9
  rv8	RealVideo 8
  rvg2svt	RealVideo G2 with SVT

• encodingType—the type of encoding used can be Constant Bit Rate (cbr), Variable Bit Rate using quality of video as a goal (vbrQuality), or Variable Bit Rate using an average bit rate as a goal (vbrBitrate). If you use Variable Bit Rate, you can only use one audience and the output file name must use a .rmvb extension.
• quality—the target quality percentage that the video codec will attempt to encode the video at. Used if you specify the encodingType to be vbrQuality.
• maxStartupLatency—the maximum time (from 4 to 25 seconds) that the clip will buffer before playing begins.
• maxFrameRate—the ideal, maximum frame rate (up to 30 frames per second) that the video codec will attempt to encode the output video at.
• maxKeyInterval—the time (from 0 to 60 seconds) in between key frames of encoded video.
• enableLossProtection—whether or not (true or false) to add error correction information to the encoded file.

Using the rmeditor.exe Utility

The rmeditor.exe utility allows you to edit a RealMedia file, or get information about an encoded file. There are three ways to use this utility. The first is to get information about a RealMedia file (also called a "dump"). The second is to change metadata, such as title, author, and copyright information. The third way to use this utility is to cut files and paste two files together. The following table summarizes the rmeditor options, which have both long and short option flags.

Getting Information from a RealMedia File

Use the following syntax to create a text-based dump file that contains information about an encoded RealMedia file:

rmeditor -inputFile filename.rm -dumpFile filename.txt

Editing Metadata

rmeditor {-inputFile <filename>} {-outputFile <filename>}

[-t | -title <title>] [-a | -author <author>] [-c | -copyright <copyright>]

[-q | -description <description>] [-n | -keyword <keywords>]

Cutting and Pasting Files

rmeditor {-i | -input | -inputFile <input> [-s | -startTime <dd:hh:mm:ss.xyz>] [-e | -endTime <dd:hh:mm:ss.xyz>] }

[-i | -input | -inputFile <input> [-s | -startTime <dd:hh:mm:ss.xyz>] [-e | - endTime <dd:hh:mm:ss.xyz>] ]

...

{-o | -output | -outputFile <filename>}

[-t | -title <title>] [-a | -author <author>] [-c | -copyright <copyright>]

[-q | -description <description>] [-n | -keyword <keywords>]

Using the rmevents.exe Utility

The rmevents.exe utility lets you encode HTML-page URLs into a RealMedia clip. You can even target a specific HTML pane in RealOne Player's three-pane environment. Using rmevents.exe, you can also encode clip information such as title, author, and copyright, and create image maps with clickable hot spots in different shapes.

For More Information: To learn more about RealOne Player's three-pane environment, download Introduction to Streaming Media with RealOne in PDF or zipped HTML format from http://service.real.com/help/library/encoders.html.

Writing an Events File

You first create an events file, which is a plain text file that uses the standard text extension of .txt. This file describes events that occur as the clip plays. You write each event on a separate line, and you can use a pound sign (#) to start a comment line. Each event line follows this format:

flag start_time end_time event_syntax

The flag indicates the type of event, which can be either to display clip information, or to open a URL in RealOne Player HTML pane automatically. The starting time and ending time are relative to the start of clip playback. You indicate the time value with the following format, in which only the seconds field is required:

dd:hh:mm:ss.x

Note: Define each event on a single line within the events text file. Do not press Enter to wrap long lines manually.

Specifying URL Events

When opening a URL automatically in a RealOne Player HTML pane, you use the u event flag. The event syntax looks like this:

u start_time end_time &&target&&URL?parameters

The URL must be a fully qualified HTTP URL. For the parameters, you can use rpcontextheight="pixels" and rpcontextwidtht="pixels" when sending a URL to the related info pane. For target, use one of the following:

The following is a sample events file that opens two URLs in the related info pane at different times, and two URLs in the media browser pane at different times:

# Open a URL in the related info pane when the clip starts, and size the pane.
u 00:00:00.0 00:01:59.9 &&_rpcontextwin&&
http://www.example.com/info1.html?rpcontextheight=250&rpcontextwidth=280
#
# Open a URL in the media browser pane at the 1-minute mark.
u 00:01:00.0 00:01:59.9 &&_rpbrowser&&http://www.example.com/index.html
#
# Open a second URL in the related info pane at the 2-minute mark.
u 00:02:00.0 00:04:00.0 &&_rpcontextwin&&http://www.example.com/info2.html
#
# Open a second URL in the media browser pane at the 3-minute mark.
u 00:03:00.0 00:04:00.0 &&_rpbrowser&&http://www.example.com/index2.html

Note the following about this sample:

• When you open multiple URLs, list the events in ascending order according to the start times.
• The related info pane size is set for the duration of the clip by the first URL that opens in that pane. Any subsequent URLs that target the related info pane therefore do not require sizing information.
• The end times indicate a point past which the URL should not open. In the second event defined above, the URL is scheduled to open at 1:00 minutes, but no later than 1:59.9 minutes. If a viewer starts the clip and immediately seeks to its 3-minute mark, for example, the URL doesn't display because the clip never plays at any point between the URL's start and end times.

Adding Clip Information

Using rmevents.exe, you can encode the RealOne Player clipinfo parameters into the clip. Separate the subvalues with vertical lines, or "pipes." For example, the following shows an events file line that specifies clip information, using i as the event flag:

i 00:00:00.0 00:00:10.0 clipinfo:title=My Presentation|artist name=Pat Morales|...(Does not work with Player version 8)

For clip information, you can specify the start time as the clip's starting time (00:00:00.0). Specifying an end time is required, but the actual end time doesn't matter because the clip information will display throughout the length of the clip playback. In the example above, the end time is set to 10 seconds after the clip starts.

The following table describes the name and value pairs that you can use with clipinfo. You can use any set of values, and list them in any order. Most text values can be over 100 characters long.

Note: Do not use the title, author, and copyright parameters along with clipinfo.

Merging the Events File with the Clip

After you write your events file, you use the RMEvents utility to merge the events file with your clip.

To merge an events file with a RealAudio or RealVideo clip on Windows:

1. Open a command line prompt from the Start menu.
2. Move to the main Helix Producer directory. The default main directory is c:\Program Files\Real\Helix Producer Basic or c:\Program Files\Real\Helix Producer Plus.

Here is an example:

C:\>cd "C:\Program Files\Real\Helix Producer Basic"

3. Enter the following command, which uses three flags to indicate the input clip, output clip, and events file:

rmevents -i input.rm -o output.rm -e events.txt

where:

• input.rm is the path and name of the input clip
• output.rm is the path and name of the output clip
• events.txt is the path and name of the events file

Tip: Always choose a new output name so that you can save your original clip without any encoded events.

©2002 RealNetworks, Inc. For more information, visit RealNetworks Click here if the Table of Contents frame is not visible at the left side of your screen.