= Configure '''whisperCast''' = ''See also: [wiki:whisperCast/Run Run whisperCast]'' == General == In order to make '''whisperCast''' work the way you want, you need to configure a set of [wiki:whisperCast/Elements 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 [wiki:RPC], available at '''!http://:/!__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 [wiki:whisperCast/Run 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 [wiki:whisperCast/Elements 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 [wiki:whisperCast/Elements/HttpClientElement 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 [wiki:whisperCast/Elements/FileElement 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 [wiki:whisperCast/Elements/FileElement FileElement], named "'''archive'''" that serves files from a directory where you put the file named "'''event.flv'''", and you have as well a [wiki:whisperCast/Elements/TimeSavingElement TimeSavingElement], named "'''ts'''" to save the current play state for a request, and a [wiki:whisperCast/Elements/NormalizingElement 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 [wiki:whisperCast/Elements/NormalizingElement 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:[[BR]] '''!http://://'''. For rtmp, you need to prepend to the path a '/whispercast/' path component, as following:[[BR]] '''!rtmp://:/'''whisperCast'''/'''. In terms of the Flash player, you should use ''''!rtmp://:/whisepercast/''' for !NetStream.connect and '''''' 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://:/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://:/'''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://:/whispercast/x/norm/norm/ts/norm/ts/ts/archive/event.flv''' would be possible (in such a case unnecessary processing happens).