Configure whisperCast

See also: Run whisperCast

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 on which whisperCast is run and port is the http serving port.

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 starting 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.

Please check the Run whisperCast document in order to see how to properly start whisperCast.

Standard Elements

whisperCast comes with a set of standard elements, which allow a wide range of applications. For detailed information on these elements, please check the elements page.

Global vs. Non-Global Elements

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

The global elements are singletons created when the server starts while 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, let's suppose you have a FileElement, named "archive" that serves files from a directory where you put the file named "event.flv", and you have as well a TimeSavingElement, named "ts" to save the current play state for a request, and a NormalizingElement, named "norm", to make sure timestamps for the media played comes in good order.

If you want the "event.flv" file served through both the normalizer and the state saving element, you can use "norm/ts/archive/event.flv" as the path for the media.

If you want to get the file directly, with no normalization nor state saving you can request it as "archive/element.flv". Or, if you want it normalized but without any state saving you can use "norm/archive/element.flv".

Flow Control

This is a very important issue and is related to the speed at which tags (media) goes down the media stream. The idea is that media should not go faster than the user can consume it (i.e. network speed) or to allow media to be wasted (i.e. user downloads 10 min. of a clip but after 2 min. he quits viewing).

We achieve flow control by telling tag sources to slow down (ie. stop reading that file for a while, or pause that http connection). The question is where we do it (normally we would like to do it close to the export) and how we separate flow control between multiple users (e.g. we need to arrange the sources/ config such to not allow a pause command given by a slow user would not pause the stream for everybody for a live source).

We can do flow control in two ways: via NormalizingElement-s or at export, by setting the enable_buffer_flow_control_ flag in the export. They can be both enabled. For example we can imagine a setup with a file source f, served via a normalizer n that has flow_control_write_ahead_ms_=10000 using a path n/f on an export with enable_buffer_flow_control_ set. This would determine the export point to perform flow control based on the user network speed, but do not allow the user to download further than 10 seconds ahead of play time.

It is a good idea not to serialize normalizers that do flow control, and to avoid setting enable_buffer_flow_control_ for live streams that are intended to be shared (viewed) by multiple users.

Exporting Media

In order to make media accessible to the users (and, of course, only the media you want to be accessible!), that specific media must be exported. By doing this, you associate an externally available 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__ http path.

You need to specify a protocol for exporting, which can be either 'http' or 'rtmp', a path under which to export (we will 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 following:
http://<hostname>:<http_port>/<media_http_export_path>/<protocol_path>.

For rtmp, you need to prepend to the path a '/whispercast/' path component, as following:
rtmp://<hostname>:<rtmp_port>/whisperCast/<protocol_path>.

In terms of the Flash player, 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 the 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).