Run whisperer

See also: Configure whisperer

whisperer is the application that is providing the encoded data to whisperCast.

This document covers the command line flags and general file and directory configuration necessary for running whisperer. For information regarding the configuration, please visit the Configure whisperer document.

Upon installation with make install (please check the Install document), several directories and a test/demo configuration is created. You can use that structure as a starting point, or you can use cpack to prepare a debian package to be installed on multiple of your servers.

In that demo structure, you can look in $INSTALL_PREFIX/bin/start_whispercast.sh to see an example for starting whisperer: 

$> $INSTALL_PATH/bin/whispershell.sh $INSTALL_PATH/bin/whispercast --flagfile=$INSTALL_PATH/whispercast/etc/ini/whisperer.ini

You may have noticed that a shell script is used to launch the demo - this is needed for every invocation of whisperer, as a special environment must be set-up for whisperer to run properly (mainly related to the modified gstreamer whisperer uses). Also, the --flagfile flag is used to load the rest of the demo related flags.

The whispershell.sh can be used to launch an interactive shell with all the environment set-up for whisperer and we strongly recommend you to use it while running and testing whisperer. Just launch: 

$INSTALL_PATH/bin/whispershell.sh

The command line flags are of great importance of how whisperer runs and behaves. You can get the long list of parameters by running 

$> whisperer --help

Here are the parameters, grouped by their category and their meaning.

Directories:

  • -media_config_dir
    This is where the configuration files are placed (normally should be set to $INSTALL_PATH/whisperCast/etc/config). Must be unique for each whisperer instance.

  • -media_state_dir
    Here whisperCast saves its state - a checkpoint and some log files (normally should be set to $INSTALL_PATH/whisperCast/var/state). Pair -media_state_dir / -media_state_name must be unique for each whisperer instance.

  • -media_state_name
    whisperCast prefixes the state files with this identifier. Pair -media_state_dir / -media_state_name must be unique for each whisperer instance.

  • -rpc_js_form_path
    If specified, we make RPC interface available via auto-generated forms, and we read the extra js sources from here (normally should be set to $INSTALL_PATH/whisperCast/var/www/js/rpc)

Basic network parameters:

  • -http_port
    The port on which we accept HTTP connections (default: 8080). If you want to bind to the standard HTTP port (80) you may be tempted to start whisperer as root, which we strongly NOT advise. Alternately, you may run it on port 8080 and use iptables to map port 80 to port 8080 (of course, other solutions, that do not imply running whisperer as root, may also be available on your system).

  • -http_max_num_connections
    We accept at most these many concurrent HTTP connections (default: 1000). NOTE: your system may have limits set for the number of file descriptors opened by user / process (usually 1024). If you increase this flag, make sure that you do not run into that limit (look for man ulimit and /etc/security/limits.conf file).

Authorization:

  • -admin_passwd
    The admin password for whisperer. We strongly encourage you to put this in a file and use (--flagfile option).

  • -authorization_realm
    If you set an admin password, you also need this, as it is the realm returned for a failed basic-authentication HTTP request.

Provider Configuration:

The providers are the actual components that provide media data to be delivered.

  • -max_lag
    The maximum allowed amount of data, in bytes, that a request can lag behind it's provider - this is needed to control how much memory can be allocated in case of slow clients.

  • -publishing retry_timeout
    The timeout after a failed HTTP POST is retried, in milliseconds. If 0, there is no timeout, if -1 the POST will not be retried.

  • -encoder_fireup_timeout
    The time to wait, in milliseconds, for an encoding pipeline to start running.

  • -encoder_idle_timeout
    The time to keep an encoding pipelina alive, after it's last client has left, in milliseconds.

  • -source_fireup_timeout
    The time to wait, in milliseconds, for a source pipeline to start running.

  • -source_idle_timeout
    The time to keep a source pipelina alive, after it's last client has left, in milliseconds.

  • -provider_link_soft_limit
    The lag, in miliseconds, after a multifdsink client in the stream provider will be resynced.

  • -provider_link_hard_limit
    The lag, in miliseconds, after a multifdsink client in the stream provider will be disconnected.

Other:

  • -selector_high_alarm_precission
    Loose some CPU time and gain that extra mili-second precission for selector alarms. (default: false).

Logging and Messages:

  • -alsologtostderr
    If this is turned on, we also write log lines to this stderr (default: false).

  • -logdir
    We write the log file under this directory. (default: "/tmp").

  • -loglevel
    We initialize the log at this maximum level. (i.e. we log messages with levels less or equal then this). Levels: 0 - FATAL, 1: ERROR, 2: WARNING, 3: INFO, 5: DEBUG (lower - deep debugging) (default: 3 - INFO).

  • -logtid
    Log the thread ID in each message (default: false).

  • -logcolors
    If this is turned on, the log will use bash colors for log messages (default: false).

Debugging:

  • -loop_on_crash
    Causes the program to hang on bad signals waiting for your debugger. (default: false).

  • -loop_on_exit
    If this is turned on, we loop before exiting (waiting for your debuger to attach) (default: false).

  • -http_connection_dlog_level
    Turn on deep debugging messages on HTTP connections (default: false).

  • -debug_check_long_callbacks_ms
    If greater than zero, we check (in debug mode only !) that processing functions, callbacks and alarm functions take less then this amount of time, in miliseconds) (default: 500).

Help on Command Line Flags:

We use google flags library for our command line flags. These are flags offered by that library:

  • -help
    Show help on all flags [tip: all flags can have two dashes].

  • -helpfull
    Show help on all flags -- same as -help).

  • -helpmatch
    Show help on modules whose name contains the specified substr.

  • -helpon
    show help on the modules named by this flag value.

  • -helppackage
    Show help on all modules in the main package.

  • -helpshort
    Show help on only the main module for this program.

  • -helpxml
    Produce an xml version of help.

  • -version
    Show version and build info and exit.

Flags related to Flags:

We use google flags library for our command line flags. These are flags offered by that library:

  • -flagfile
    Load flags from file.

  • -fromenv
    Set flags from the environment [use 'export FLAGS_flag1=value'].

  • -tryfromenv
    Set flags from the environment if present.

  • -undefok
    Comma-separated list of flag names that it is okay to specify on the command line even if the program does not define a flag with that name. IMPORTANT: flags in this list that have arguments MUST use the flag=value format).