Element Configuration

General

In order to make whisperCast work the way you want, you need to configure a set of media elements. These are software components that process media inside whisperCast. Each element has a well defined purpose, depending on its type. The main interface they provide, can be seen as a source of media for other elements. Some elements are designed such that they need some input (from other elements) in order to perform.

Users can interconnect these elements, in their configuration, in order to provide some specific, desired effects.

Configuration

Configuration, at this point, can be done by using the standard generated forms for the configuration RPC, available at http://<hostname>:<port>/admin, where hostname is the host where you run whisperCast and port is the http serving port. Please check the Running whisperCast document in order to see how to properly start whisperCast.

The interface for adding elements is best used (and available) under the specific configuration page of each loaded module.

Alternately, the configuration can be edited directly in the whispercast.config file, that is on the disk in the directory pointed by the --media_config_dir flag, when startin whisperCast. We do not recommend this method, as it is prone to errors, and also, whisperCast needs to be restarted in order to load the new configuration. This method is good if you want to save / backup a configuration file. In such a case, to use a backup copy of the config file, you should copy the backup copy over the live config file and restart whisperCast.

Standard Elements

whisperCast comes with a set of standard elements, which allow a wide range of applications. Here is a short list of those staandard elements:

• FileElement - you can configure a FileElement in order to read (and serve) files from a directory. It reads the files on request and provides the data that it reads downstream.
• HttpClientElement - this element reads data from a remote http server. You can configure it with the remote location you want this data to be read.
• HttpServerElement - this element registers a path on which someone can push data into the system. This element accepts it and pushes it downstream.
• SwitchingElement - this is an element which provides switching capabilities. It provides the data that is received from other, upstream, elements, and it can switch between these providers. The way it switches depends on an associated element policy. As an example, consider a situation in which one would like to mix a live stream (obtained, say from an HttpClientElement), with some files, obtained from a FileElement.
• NormalizingElement - this element normalizes the time of the media it receives. You may want one of these after each SwitchingElement, and should normally use one just before exporting some unnormalized media to the user.
• TimeSavingElement - this is an element which saves the state of media playing, so the user can restore its play position very close from where he left in case of a problem with connection or with the server. For example, if you serve a one-hour long media file, if something goes wrong (like: connection if lost, server restarts etc), you may want your viewers to restart viewing from where they left, not from the beginning. To achieve this, insert one of these elements.
• DroppingMediaElement - this element drops stuff from media, like all the audio tags (to get a muted stream), or all video (to get just the sound), or all video except a key frame every 10 seconds, to get a low-bandwidth-what's-going-on stream.
• SplittingElement - this takes unformatted (raw) data and splits it in tags. Normally, a tag splitter is included in most of the elements that produce data. However it is possible to declare those splitters to produce 'raw' data, which is just a stream of amorphous data chunks. For taking those chunks and organizing them in media tags, you need one of this elements.

Global vs. Non-Global Elements

Elements can be configured in two ways: global or non-global.

The global elements are created when the server starts, and is one for all users, the non-global are created one for each user request that needs it. The difference is small but subtle and can have a big impact in how things behave.

For example, consider an HttpClientElement. When created global, whisperCast creates one at the start of the aplication, making one connection to the remote http server, and serves all requests for the media produced by that element from that initial http connection (possibly reconnecting it). When created non-global, one element is created for each request that needs that media, and implicitly, one connection is realized to the remote server for each and every user.

For FileElements?, reading a file is started each time a request for a file content has been issued, independently if the element is created global or not. Global elements should depend on a source of media only from global elements. Non-global elements can depend on global or non-global elements as their source of media.

Media Naming

Elements bear, beside their type, a name, which must be unique in a whisperCast configuration (i.e. you can't have two elements with the same name). A name can contain alpha-numeric characters and underscore(s) ('_').

You can put together media paths for naming a specific media piece by concatenating element names with slash ('/') separators.

For example, suppose you have a FileElement, named 'archive' that serves files from a directory where file 'event.flv' is readable, and you have as well a TimeSavingElement, named 'ts' to save the position of play, and a NormalizingElement, named 'norm', to make sure timestamps for the media played comes in good order. A media name for this path would be: 'norm/ts/archive/event.flv'. If you want to get the file directly, with no normalization or time state saving by using directly 'archive/element.flv'.

Exporting Media

In order to make media accessible to the users (and only the media you like to make available), this media must be exported. By doing this, one associates an external visible path (be it http or rtmp) to an internal media path (as described above). In order to perform an export, use the StartElementExport command from the main configuration menu available under the /admin.

You need to specify a protocol for exporting, which can be 'http' or 'rtmp', a path under which to export (we should call this the protocol path), and the media path that identifies the media you want to export. For http, the path for the URL which

exports the media is prepended by a standard media path, given by the

--media_http_export_path flag as follows: http://<hostname>:<http_port>/<media_http_export_path>/<protocol_path>. For rtmp, you need to prepend to the path a '/whispercast/' path component: rtmp://<hostname>:<rtmp_port>/whispercast/<protocol_path>. In terms of Flash, you should use 'rtmp://<hostname>:<rtmp_port>/whisepercast/ for NetStream.connect and <protocol_path> for NetStream.play.

Use empty string for the root path.

When requesting a media URL, you can append to the protocol path other path components in order to properly identify the media. For example, considering the situation from the previous section, one may export under rtmp protocol, and under path 'events' the following media path: 'norm/ts/archive'. At this point, when user asks for rtmp://<hostname>:<port>/whispercast/events/event.flv, they would refer to 'norm/ts/archive/event.flv'. In the same case is possible to export the full media path 'norm/ts/archive/event.flv', under path 'event', in which case, that particular file only would be available under path rtmp://<hostname>:<port>/whispercast/event. Please note that you should be very careful about which path you export, as whisperCast lets elements resolve whatever comes after the exported protocol path. For example, in our situation, exporting 'norm/ts' under protocol path 'x', would give access to anyone to all your media, and strange constructions like rtmp://<hostname>:<port>/whispercast/x/norm/norm/ts/norm/ts/ts/archive/event.flv would be possible (in such a case unnecessary processing happens, potentially harmful).