Administrator Guide

Check the installation instructions for a quick overview of the process. Please consult the README and INSTALLATION files included in the archive. In addition, you can ask questions or report problems in the issues page on Github.

The application takes several steps when a file is imported. These steps prepare the file, populates the required fields in the database and creates auxiliary files to allow working with this files from a web browser. The steps are:

  1. The file is checked to see that it is a valid soundfile. This check is done with the application SoX.
  2. Technical data of the file (duration, format, number of channels, bit rate, sampling rate) are extracted using the utility soxi and stored in the database.
  3. Waveform and a spectrogram images are created using a Python script.
  4. An mp3 version of the file is created using LAME. This allows to hear the file over the web.

The following figure illustrates a typical flow of the data in the application. The sounds are recorded and then stored as digital files, preferably in an uncompressed format like wav. The soundfiles in wav format can be compressed using the lossless format FLAC, which reduces the file size by about 50%. Then the files are imported to the application to populate the database and create the auxiliary files.

Development

This section includes topics like:

Additional options for the config.php file

The config.php file requires, at the least, the credentials for the MySQL database.

#Database settings
$host = "localhost";
$user = "";
$password = "";
$database = "";

The rest of these settings are optional:

Custom logo

If you want to display a particular logo, set $app_logo to its relative or absolute address

$app_logo="images/logo2.png";

Custom logo link

If you want to send the user to a particular page when clicking the logo, set $homelink to the relative or absolute address

$homelink = "http://www.example.com/somedir/";

Name for the tag for the marking tool

The viewer allows to select an area and save it in the database. By default, this includes a field for the species that made the sound. This can be changed to something like the name of the song or syllable, a unique code for the type of sound, etc.

$mark_tag_name = "Species";

Use R

When true, the application can extract more data from the files by running custom code that can be used for quality control. It also lets the R plugin know where to find R. 

$useR = FALSE; #TRUE or FALSE
If true, you can set the custom path for the R installation you want to use and other Rscript arguments. Can be left as it is to use the default:

$Rscript = "Rscript --vanilla ";
For ADI calculation, set these variables:

#ADI settings
$R_ADI_db_value = "-50"; #dBFS

##The spectrogram should be drawn from 0 to this
## frequency, in Hertz. Default is 10000 Hz.
$R_ADI_max_freq = "10000"; #in Hz

##How wide is each frequency band
$R_ADI_freq_step = "1000"; #in Hz

Use Wordpress for users

When true, the application will use the Wordpress user management to determine who is logged in and what they can do. You must also provide the relative path to the file wp-blog-header.php in the Wordpress directory

$login_wordpress = FALSE; #TRUE or FALSE
$wordpress_require = '/wp-blog-header.php';

Set as a no login website?

When true, there is no option to log in. Useful for public websites that will rarely need someone logged in. May set to true whenever someone needs to log in. 

$no_login=FALSE; #TRUE or FALSE

Force login?

When true, no guests are allowed. 

$force_login=FALSE; #TRUE or FALSE

Disable viewer

When true, the files can not be opened using the viewer. 

$special_noopen=FALSE;

Disable background processes

When true, the application will not try to perform background processes (adding files, generating spectrograms, converting mp3 files). Useful when hosting the application in a host that do not allow to install programs after generating these files in a server that does allow it. 

$special_noprocess=FALSE;

Integration with other software

The application is intended to be used as a stand-alone installation or as part of an already-existing sounds database.

The script file_obtain.php will manage a sound file from another sound database, archive or even from anywhere in the web!

Obtaining files from the web

To obtain a sound file from the web you need to install GNU Wget (if its not already installed). Using any language, just provide file_obtain.php with 3 variables using GET:

Its important to note: don't include the http:// part in the file path. The script will use wget to obtain the file. Then another script will check that the file is a valid sound file or delete it from the server if it can not determine that it is valid.

Example using a Cuckoo sound sample from birdsongs.it: 

http://www.localserver.com/pumilio/file_obtain.php?file=www.birdsongs.it/songs/cuculus_canorus/call1.wav&method=2&fileid=101

Obtaining files from the same server

Using any language, just provide file_obtain.php with 3 variables using GET:

Its important to note: the path name must be the internal path, for example /var/www/.... The script will copy the file. Then another script will check that the file is a valid sound file or delete it from the server if it can not determine that it is valid.

Example: 

http://www.localserver.com/pumilio/file_obtain.php?file=/var/www/anotherapp/sounds/sound1.wav&method=1&fileid=101