Chapter 7: Command Line Utilities

RealProducer is installed with utilities that allow you to use the command line to modify streaming media files (.rm files). You run these utilities through the MS-DOS prompt.

The following programs are available to you:

RMEditor allows you to change information about an .rm file, trim the length of the clip, combine multiple .rm files, and create a text file containing the file's information.
RMEvents allows you to merge image map and event text files into an existing .rm file and extract events and image maps from a .rm file into a text file.

Using RMEditor

RMEditor allows you to modify a previously created .rm file by changing clip information, recording and downloading options, and clip length.

To use the command line editor:

Open the MS-DOS prompt.
Change the directory to the main RealProducer directory.
The default main directory is c:\Program Files\Real\RealProducer.
Type rmeditor -i input.rm -o output.rm <switches> where input.rm is the name of the input file, output.rm is the name of the output file, and <switches> are the editing switches you specify. See the table below for more details on all necessary switches.

Switches

The following table describes each switch that you can use on the command line.

RMEditor Switches
Syntax	Description	Example
-a <author>	name of the author of the clip	-a "New Name"
-t <title>	title of the clip	-t "New Title"
-c <copyright>	copyright information	-c "1999 by My Company"
-C <comment>	any comments about the clip; for example, any changes made and who made them	-C "changed title on Sept. 24"
-q <description>	a brief description of the clip	-q "blah blah"
-n <keywords>	keywords that will help search engines locate your clip	-n "word key"
-IN 0 or 1	allows search engines to index your content	-IN 1
-AR 1, 2, 3, or 4	audience rating; 1 - general, all ages 2 - parental guidance 3 - adult supervision required 4 - adults only	-AR 2
-k 0 or 1	allow download	-k 1
-r 0 or 1	allow recording for RealPlayer Plus users	-r 1
-s <dd:hh:mm:ss>	start time of the edited clip in days:hours:minutes:seconds	-s 00:00:30:45.20
-e <dd:hh:mm:ss>	end time of the edited clip in days:hours:minutes:seconds; use 0 to specify the end of the input file	-e 00:02:15:00.00
-l <file>	the path and name of the log file; edit results are written to this file	-l c:\Real\Producer\logs\logfile.txt
-d <file>	the path and name of the dump file; the contents of the input file are written to this file	-d c:\Real\Producer\dumps\dumpfile.txt
-?	displays help information

Examples

The following example allows you to view the current title, author, copyright, comments, mobile playback and selective record settings:


rmeditor -i input.rm

The following example changes the title of input.rm to "New Title" and saves the file as output.rm:


rmeditor -i input.rm -t "New Title" -o output.rm

The following example disables the selective record option and saves the file as output.rm:


rmeditor -i input.rm -r 0 output.rm

The following example trims both the beginning and end of input.rm and saves the result as output.rm:


rmeditor -i input.rm -s 0:0:3:2.20 -e 0:0:4:2.20 -o output.rm

Note
The start and end times will be adjusted in video clips so that the clip starts and ends on keyframes.

	Note
The start and end times will be adjusted in video clips so that the clip starts and ends on keyframes.

The following example pastes several .rm files together into one output file:


rmeditor -i input1.rm -i input2.rm -i input3.rm -o output.rm

Note
If more than one input file is specified, any start and end time arguments will be ignored.

	Note
If more than one input file is specified, any start and end time arguments will be ignored.

Using RMEvents

RMEvents allows you to merge events and image map text files to an .rm file. Events and image map text files are created using a text editor. See "Creating an Events File" and "Creating an Image Map File" below for more information.

RMEvents also allows the user to extract events and image maps from a .rm file into a text file, so they may be edited using any text editor.

To use the command line events utility:

Open the MS-DOS prompt.
Change the directory to the main RealProducer directory.
The default main directory is c:\Program Files\Real\RealProducer.
Type rmevents -i input.rm -o output.rm <switches> where input.rm is the name of the input file, output.rm is the name of the output file, and <switches> are the events switches you specify. See the table below for more details on all necessary switches.

Switches

The following table describes each switch that you can use on the command line.

RMEvents Switches
Syntax	Description	Example
-e <file>	path and name of the event text file	-e c:\Real\event.txt
-m <file>	path and name of the image map text file	-m c:\Real\image.txt
-d <dump>	the path and name of the dump files that hold the image maps and events dumped from the input file; events will be dumped into <dump>_evt.txt and image maps to <dump>_imap.txt	-d c:\Real\events\input
-?	displays help information

Examples

The following example merges an event text file with a .rm file:


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

The following example merges an image map text file with a .rm file:


rmevents -i input.rm -m image.txt -o output.rm

The following example dumps image maps and events from the input file into files named input_imap.txt and input_evt.txt, respectively:


rmevents -i input.rm -d input

Creating an Events File

An events file is a simple text file that describes the different components of the event. Before you begin, make sure you have an updated list of the URLs you want to use. Events files should be created using a text editor and saved as text-only files.

The syntax for each entry in an events file is as follows:


Type of Event	Syntax
URL	`u <starttime> <endtime> <URL>`
Title	`i <starttime> <endtime> <title>`
Author	`a <starttime> <endtime> <author>`
Copyright	`c <starttime> <endtime> <copyright>`

The time for <starttime> and <endtime> is represented as:


[[[days:]hours:]minutes:]seconds[.tenths]

The input file may also contain comment lines beginning with the # symbol. The comment lines are ignored by rmevents.

For example, the following text shows how an event file might look. Note that the time of each line must be in ascending order.


u 00:00:10.0 00:00:59.9 http://www.real.com/


u 00:01:00.0 00:02:00.0 http://www.mysite.com/page2/

This input file tells the RealPlayer to point the user's default Web browser to the RealNetworks home page ten seconds into the presentation. One minute into the presentation, the browser is pointed to a page from www.mysite.com.

Creating an Image Map File

An image map file is a text file with HTML-like tags that create a clickable image map within a RealVideo clip. Image maps can be a multitude of shapes, and they can be changed over a number of different times during the clip. They should be created using a text editor and saved as text-only files.

All tags shown below are required unless stated otherwise. Negative values for numbers are not allowed.

Duration Tag

This tag must be at the beginning of the file. The DURATION tag specifies the amount of time from the start of the first map to the end of the last map in the file. The syntax is as follows:


DURATION=days:hours:minutes:seconds:milliseconds

All time parameters must be present. If you don't need to use a time parameter, fill zeros in that space.

Map Tag

This tag describes the overall properties of the image map. You may have as many MAP tags in a file as you wish. The syntax is as follows:


<MAP START=days:hours:minutes:seconds.milliseconds END=days:hours:minutes:seconds.milliseconds COORDS=x,y,x1,y1>


</MAP>

As with the DURATION tag, all time parameters must be specified. The COORDS tag defines the rectangle of the video clip that the image map will occupy. If you enter an area bigger than the display area, the entire area is inactive. Any area not located within this rectangle will be inactive as well.

Area Tag

This tag describes the region within the map that is active. You can define more than one area within each map; all areas for a map must be between the <MAP> and the </MAP> tags. The syntax is as follows:


<AREA START=days:hours:minutes:seconds:milliseconds END=days:hours:minutes:seconds:milliseconds SHAPE=shape COORDS=x0,y0,x1,y1,x2,y2,...xn,yn action_tag ALT="">

The following table describes each sub-tag:

Area Sub-Tags
Tag	Description
START	specifies the start time of this area of the map; optional
END	specifies the end time of this area of the map; optional
SHAPE	this tag can be one of three values, with the corresponding COORD tag:`CIRCLE` - COORDS should specify centerX,centerY,radius `RECTANGLE` - COORDS should specify left,top,right,bottom `POLYGON` - COORDS should specify at least six values (x and y coordinates for three points)
action_tag	The action_tag is one of the following: `PLAYER` - specifies a new stream to play in the RealPlayer; for example, `PLAYER="pnm://video.real.com/welcome.rm"URL` - specifies an URL to play in the browser; for example, `URL="http//www.real.com"SEEK` - specifies a time in the current clip to seek to; for example, `SEEK=0:0:0:5:0`
ALT	text that appears in the status bar of the player when the mouse is over this area; if you want to show no text use `""` only

Example


DURATION=0:0:0:40:0


<MAP START=0:0:0:0:0 END=0:0:0:5:20 COORDS=0,0,100,100>


<AREA SHAPE=CIRCLE COORDS=50,50,10 URL="http://www.real.com" ALT="Home Page">


</MAP>


<MAP START=0:0:0:5:20 END=0:0:0:20:3 COORDS=0,0,100,100>


<AREA SHAPE=RECTANGLE COORDS=0,0,50,50 SEEK=0:0:0:3:98 ALT="Seek to a point in the clip">


</MAP>


<MAP START=0:0:0:20:3 END=0:0:0:40.0 COORDS=0,0,100,100>


<AREA END=0:0:0:30:0 SHAPE=POLYGON COORDS=0,50,50,0,100,50 PLAYER="pnm://video.real.com/welcome.rm" ALT="">


<AREA START=0:0:0:31:0 SHAPE=POLYGON COORDS=0,25,25,0,100,50 SEEK=0:0:0:0:0 ALT="Rewind to beginning">


</MAP>