Indiva Manual

<< Indiva Home

Setting Up Indiva Managers

How to compile and install Indiva

First, make sure that your local OpenMash source code is up to date by running "cvs update", "make", and "make import". Run "make indiva" under your mash build directory (usually mash-code/mash) to create Indiva scripts. Created scripts are located under the bin sub-directory.

The scripts created are: imgr (Indiva Manager), ihm (Indiva Host Manager), iae (Indiva Audio Encoder), ive (Indiva Video Encoder), ifwd (Indiva Forwarder), ikld (Indiva Kaleido Controller), irs (Indiva Routing Switcher), iview (Indiva Viewer), ictrl (Indiva Controller). You should make sure that the scripts (as well as the executables mash and smash) are in your PATH environment variable.

Setting up Indiva Manager

imgr accepts the following parameters

-port port or -p port: Use port for RPC communication. Default to 9500.
-root root or -r root: Use root as the root of Indiva resource directory. Default to $HOME/.indiva
-log filename or -l filename: Write log messages to file named filename. By default, log messages are written to stdout.

The manager also listens to (RPC port + 1) for HTTP connection.

Defining Indiva Resources

Resources in Indiva domains are represented by files or directories located under the Indiva root directory. Every non-hidden file or directory under the Indiva root directory will be treated as a resource.

TIP: Hiding a file or directory is a convenient way to "comment" out a particular resource.

Resources are classified according to their classes. A 2-3 letters extension in the file or directory name indicates the class of the resource. The following table shows the list of available classes.

Extension Class ID Description

.cam camera Camera

.mic microphone Microphone

.pc hostmachine Host PC

.rtp stream RTP stream

.ses session MBone session (audio and video)

.con conference MBone conference

.mix mixer Mixer (eg. Kaleido)

.cap capturecard Capture Card

.rs routingswitch Routing Switcher

.in inport Input Port

.out outport Output Port

.ch channel TV Channel

In this document, I will refer to the input and output ports collectively as ports, and camera, microphone, mixer, routing switcher and capture cards collectively as devices. Conferences, sessions and streams will be collectively called media resources.

Putting resource A under the directory of resource B means that A belongs to B. Therefore, the following constraints holds:

RTP streams and ports must be represented by files. Everything else must be represented by a directory.
An RTP stream must be located in a .ses session directory, and a session directory must be located in a .con conference directory.
Ports must be located either in a device directory, or in some sub directories under a device directory.

Resource Attributes

Each resource has some associated metadata, given by a list of (key,value) pairs.

Metadata for RTP streams and ports is stored in the file that represents the resource. For other resources, metadata is stored in a hidden file named ".info" under the directory that represents the resource. Indiva uses plain text in Tcl's list format (for ease of parsing) to store the metadata. The format of the metadata is as follows:

        classid {
            key1 {value1}
            key2 {value2}
              :
              :
        } 
        {
        }

classid is a string that represents the class of the resource (used for sanity check). It must be exactly the string as shown in the above class table. The last empty list item { } in the metadata is reserved for future extension.

Some (key,value) pairs are required. You can also define your own keys. Keys can appear in any order in the metadata file. Here are some of the required keys that may break the system if not defined correctly.

Keys for MBone session

Key Description

addr Address of the session.

port Port for the session

ttl TTL for the session

type Type of session. Must be either "video" or "audio".

Keys for Devices

Key Description

defaultout Default output port of the device. Must be one of the output port that belongs to the device.

hostname Name of the host that controls the device.

id A string used by Mash to identify a device. For example, The id of a capture card $device must match the value returned by [$device nickname]. For others, it must match the Mash class that controls the device.

norm Norm of output from the device. Must be either "ntsc" or "pal" or "secam"

path Unix path to the device (e.g. /dev/video0).

friendlyname A user-friendly description of the device.

action A string that identifies what to do when dealing with this device. Must be either "encode", "switch", "capture" or "kaleido". There must be an implementation of this action inside Indiva.

Keys for Ports

Key Description

to Path (absolute or relative) of the resource(s) this resource is connected to. Glob style regular expression is allowed.

type Type of port. Must be either "composite", "svhs", "s-video" or "audio".

id Mash identifier for a particular port on a capture card. It must be one of the values returned by [$device get_attribute ports] (for video capture card) or [$device get_input_ports] (for sound card).

Adding a new resource in Indiva is as easy as creating a text file. Remember that each resource is represented by a text file or by a directory containing a hidden file .info. Just create a file with the intended name and properly define their attributes. The resource will be recorgnized by Indiva after Indiva Manager restarts.

Setting Up Indiva Host Manager

Indiva host manager (ihm) is responsible for launching services. Therefore, it must be running on hosts that run services. These include the capture machines and the control machines. You must also make sure that ihm have executable access to all the services. You should also ensure that smash is in your PATH environment variable, and the service scripts are accesible by ihm. By default, ihm looks for the scripts in the current directory. However, you can specify the scripts directory using option -path.

Multicast must be working between ihm and imgr.

ihm accepts the following parameters

-log filename or -l filename: Write log messages to file named filename. By default, log messages are written to stdout.
-path directory: Location of Indiva services.

There are a whole bunch of other parameters ihm supports. But I never tested them. The default values to those parameters seem to be working fine.

Active Service Parameters

The managers and services uses Active Service AS1 protocol to communicate with each other. There are a few more command line arguments that you can give to imgr, ihm and services to configure the behavior of Active Services. You normally don't need this.

-as_service value: If value is yes, then Active Service is turned on. If value is no, AS1 Protocol will be turned off. This is useful if you want to run a service as a stand-alone application. Default is yes.
-as_spec addr/port/ttl: Use multicast channel addr and port port for AS1 communication. Default is 224.4.5.24/50000/1
-as_bw bw: Limit the bandwidth of AS1 messages to bw bps. Default is 50000.