SCVOICE(1)

NAME
scvoice - SeisComP Documentation

Real time voice alert.

DESCRIPTION

This tool runs an external script whenever an event has been created or updated. It can also run a script in case an amplitude of a particular type or a preliminary origin (heads-up message) has been sent. The common purpose for this tool is to play a sound or to convert a message to speech using external tools like festival or espeak. There are three possible trigger mechanisms for calling scripts:

•   Event creation/update

•   Amplitude creation

•   Origin creation (with status = preliminary)

    Although this tool was designed to alert the user acoustically it can also be used to send e-mails, sms or to do any other kind of alert. scvoice can only run one script per call type at a time! A template (scalert) Python script with more options has been added to SeisComP to be used as source for custom notifications.

EXAMPLES

  Event script

The following script is used as event script. It requires festival which should be available in almost any Linux distribution.

IMPORTANT: When saving the scripts given below do not forget to set the executable bit otherwise scvoice cannot call the scripts. In Linux just run:

chmod +x /path/to/file

1.  Save an executable script file, e.g., under, e.g. ~/.seiscomp/event.sh:

    #!/bin/sh
    if [ "$2" = "1" ]; then
    echo " $1" | sed 's/,/, ,/g'   | festival --tts;
    else
    echo "Event updated, $1" | sed 's/,/, ,/g'   | festival --tts;
    fi

2.  Add the file to the configuration of scripts.event in the file SEISCOMP_ROOT/etc/scvoice.cfg or ~/.seiscomp/scvoice.cfg:

    scripts.event = /home/sysop/.seiscomp/event.sh

  Amplitude script

1.  Save an executable script file, e.g., under ~/.seiscomp/amplitude.sh

    #!/bin/sh
    # Play a wav file with a particular volume
    # derived from the amplitude itself.
    playwave ~/.seiscomp/beep.wav -v $3

2.  Add the file to the configuration of scripts.amplitude in the file SEISCOMP_ROOT/etc/scvoice.cfg or ~/.seiscomp/scvoice.cfg:

    scripts.amplitude = /home/sysop/.seiscomp/amplitude.sh

  Alert script

1.  Create a sound file siren.wav for accoustic alerts.

2.  Save an executable script file under, e.g., ~/.seiscomp/alert.sh:

    #!/bin/sh
    playwave /home/sysop/.seiscomp/siren.wav

3.  Add the script filename to the configuration of scripts.alert in the file SEISCOMP_ROOT/etc/scvoice.cfg or ~/.seiscomp/scvoice.cfg.

    scripts.alert = /home/sysop/.seiscomp/alert.sh

MODULE CONFIGURATION
etc/defaults/global.cfg
etc/defaults/scvoice.cfg
etc/global.cfg
etc/scvoice.cfg
~/.seiscomp/global.cfg
~/.seiscomp/scvoice.cfg

scvoice inherits global options.

firstNew
    Default: false

    Type: boolean

    Treat an event as new event when it is seen the first time.

agencyIDs
    Type: list:string

    Define a white list of agencyIDs to alert an event. The agencyID is extracted from the preferred origin of the event. If this list is empty, all agencies are allowed.

poi.message
    Type: string

    The default message string for the event-script is "earthquake, [HOURS] hours [MINS] minutes ago, [DESC], magnitude [MAG], depth [DEP] kilometers" whereas [DESC] is the string given in the event.description attribute. This string can be overwritten using one of the following options. There are three placeholders that can be used: @region@, @dist@ and @poi@. Example: "@region@, @dist@ kilometers from @poi@ away".

poi.maxDist
    Default: 20

    Type: double

    Unit: deg

    When using the nearest point of interest (city) as part of the message string, specify the maximum distance in degrees from the event. Any point of interest farther away will be ignored.

poi.minPopulation
    Default: 50000

    Type: double

    Minimum population for a city to become a point of interest.

scripts.amplitude
    Type: string

    Specify the script to be called if an amplitude arrives, network-, stationcode and amplitude are passed as parameters $1, $2 and $3.

scripts.alert
    Type: string

    Specify the script to be called if a preliminary origin arrives, latitude and longitude are passed as parameters $1 and $2.

scripts.event
    Type: string

    Specify the script to be called when an event has been declared; the message string, a flag (1=new event, 0=update event), the EventID, the arrival count and the magnitude (optional when set) are passed as parameter $1, $2, $3, $4 and $5.

COMMAND-LINE OPTIONS

scvoice [options]

  Generic

-h, --help
    Show help message.

-V, --version
    Show version information.

--config-file arg
    Use alternative configuration file. When this option is used the loading of all stages is disabled. Only the given configuration file is parsed and used. To use another name for the configuration create a symbolic link of the application or copy it. Example: scautopick -> scautopick2.

--plugins arg
    Load given plugins.

-D, --daemon
    Run as daemon. This means the application will fork itself and doesn't need to be started with &.

--auto-shutdown arg
    Enable/disable self-shutdown because a master module shutdown. This only works when messaging is enabled and the master module sends a shutdown message (enabled with --start-stop-msg for the master module).

--shutdown-master-module arg
    Set the name of the master-module used for auto-shutdown. This is the application name of the module actually started. If symlinks are used, then it is the name of the symlinked application.

--shutdown-master-username arg
    Set the name of the master-username of the messaging used for auto-shutdown. If "shutdown-master-module" is given as well, this parameter is ignored.

--first-new
    Overrides configuration parameter firstNew.

  Verbosity

--verbosity arg
    Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info, 4:debug.

-v, --v
    Increase verbosity level (may be repeated, eg. -vv).

-q, --quiet
    Quiet mode: no logging output.

--component arg
    Limit the logging to a certain component. This option can be given more than once.

-s, --syslog
    Use syslog logging backend. The output usually goes to /var/lib/messages.

-l, --lockfile arg
    Path to lock file.

--console arg
    Send log output to stdout.

--debug
    Execute in debug mode. Equivalent to --verbosity=4 --console=1 .

--log-file arg
    Use alternative log file.

  Messaging

-u, --user arg
    Overrides configuration parameter connection.username.

-H, --host arg
    Overrides configuration parameter connection.server.

-t, --timeout arg
    Overrides configuration parameter connection.timeout.

-g, --primary-group arg
    Overrides configuration parameter connection.primaryGroup.

-S, --subscribe-group arg
    A group to subscribe to. This option can be given more than once.

--content-type arg
    Overrides configuration parameter connection.contentType.

--start-stop-msg arg
    Set sending of a start and a stop message.

  Database

--db-driver-list
    List all supported database drivers.

-d, --database arg
    The database connection string, format: service://user:pwd@host/database. "service" is the name of the database driver which can be queried with "--db-driver-list".

--config-module arg
    The config module to use.

--inventory-db arg
    Load the inventory from the given database or file, format: [service://]location .

--db-disable
    Do not use the database at all

  Alert

--amp-type arg
    Specify the amplitude type to listen to.

--amp-script arg
    Overrides configuration parameter scripts.amplitude.

--alert-script arg
    Overrides configuration parameter scripts.alert.

--event-script arg
    Overrides configuration parameter scripts.event.

  Cities

--max-dist arg
    Overrides configuration parameter poi.maxDist.

--min-population arg
    Overrides configuration parameter poi.minPopulation.

  Debug

-E, --eventid arg
    Specify event ID that is used for testing. After running the alert scripts scvoice will exit.

AUTHOR
gempa GmbH, GFZ Potsdam

COPYRIGHT
gempa GmbH, GFZ Potsdam