3. FAQ¶
This section of the Vesper documentation answers frequently asked questions (FAQs) regarding Vesper.
3.1. When I start the Vesper server, it tells me I have “unapplied migrations”. What does that mean, and what can I do about it?¶
It means that the relational database of your Vesper archive has an older and different structure than that expected by your version of the Vesper software. This kind of version mismatch can happen when you update Vesper to a new version, or if somebody supplies you with an archive created with an older version of Vesper than yours. The mismatch may (or may not, depending on the particular differences) make it impossible for Vesper to work properly with the database.
The process of updating the structure of your database is called migration, and it is typically straightforward. To migrate your database:
- Make a backup copy of the
Archive Database.sqlite
database file that’s in your archive directory.
Warning
Always make a copy of your archive database before migrating it. Then if something goes wrong with the migration, you can always recover by restoring the original version of the database from your copy. If you don’t make a copy of your database and the migration fails, you may lose some or all of your data!
Run the command:
vesper_admin migrate
in your archive directory from an Anaconda Prompt (on Windows) or terminal (on macOS or Linux). This should apply any needed migrations to your database to bring it up to date.
Note
In some Vesper installations (such as ones including Python 3.9.6
and Django 3.2.6) the vesper_admin migrate
command will
migrate your database correctly but not terminate. If the command
seems to hang, producing no output for at least thirty seconds,
type Ctrl-C
on your keyboard to terminate it.
3.2. I ran the vesper_admin
command and it hung. What do I do?¶
In some Vesper installations (such as ones including Python 3.9.6 and
Django 3.2.6) the vesper_admin
command will function properly, for
example by creating a superuser or migrating a database, except that
it won’t terminate. If the command seems to hang, producing no output
for at least thirty seconds, type Ctrl-C
on your keyboard to
terminate it.
3.3. How do I use Nighthawk with Vesper?¶
Nighthawk is a nocturnal flight call detector developed by Benjamin Van Doren and collaborators. While Vesper and Nighthawk are separate software development efforts, you can use Nighthawk from within Vesper just like any other supported detector. For example, you can use Vesper to run Nighthawk on your recordings, view the resulting clips in clip albums, annotate them with species classifications, etc.
To get set up to use Nighthawk with Vesper:
Install the
nighthawk
andvesper-nighthawk
Python packages according to Vesper’s Nighthawk installation instructions.Add one or more Vesper detectors for Nighthawk to your archive database. To do this, use Vesper’s
File->Import metadata
command to import an appropriate metadata YAML file. Please see theNighthawk Detectors.yaml
file of theMetadata YAML
subdirectory of the Vesper archive template for an example. Most users can just import the example file as is to get started. If you want to customize the example file, be sure to read the comments at the top of the example to understand how to name your detectors so that Vesper will be able to use them.Customize Vesper’s classification menus for use with Nighthawk. In this step you’ll add an annotation constraint to your archive database and modify the
Classification
annotation to use it. An annotation constraint specifies the values that a Vesper annotation will have, and Vesper uses it to build the annotation value menus that it presents in its user interface.To add one or more annotation constraints to your archive database that describe Nighthawk classifications, use Vesper’s
File->Import metadata
command to import an appropriate metadata YAML file. Please see theNighthawk Annotation Constraints.yaml
file of theMetadata YAML
subdirectory of the Vesper archive template for an example. The example defines two annotation constraints, one namedNighthawk eBird Classification
that uses eBird species codes and another namedNighthawk IBP Classification
that uses four-letter Institute for Bird Populations (IBP) species codes. Most users will just want to import the example file as is, and then choose one or the other of the imported annotation constraints to use in the next step.To modify the
Classification
annotation of your archive database to use one of the annotation constraints added in the previous step:- Go to the Django administration page of your Vesper server,
typically by visiting the URL
localhost:8000/admin
in your browser. - Select
Annotation infos
along the left side of the display. - Select
Classification
in the main part of the display. - In the
Constraint
menu in the main part of the display, select one of the annotation constraints that you added in stepa
to use for theClassification
annotation. If you imported the example file as is, this will be either theNighthawk eBird Classification
constraint or theNighthawk IBP Classification
constraint.
Warning
The procedure described in this section uses the Django administration interface to modify your archive database. While this interface is sometimes very helpful, it is also relatively easy to accidentally corrupt your database or delete data you didn’t intend to with it. We recommend avoiding its use when there are safer alternatives like the normal Vesper user interface, and using it carefully when you must.
- Go to the Django administration page of your Vesper server,
typically by visiting the URL
Once you have completed the above steps, you can run Nighthawk on your
recordings using the Process->Detect
command and process the
resulting clips according to your personal or project workflow. Note
that if you’d like to export Nighthawk clips from Vesper to work with
in Raven Pro, for example to provide Nighthawk model feedback
to help improve the detector, you can use Vesper’s
File->Export clip metadata to CSV file
command with the
Clip Table Format
preset named Nighthawk Raven Output
to export a
Raven selection table that you can open in Raven Pro. We are also looking
into the possibility of allowing Vesper users to submit Nighthawk model
feedback directly from Vesper.
3.4. How do I use BirdVoxDetect with Vesper?¶
BirdVoxDetect is a nocturnal flight call detector developed by the BirdVox project. While Vesper and BirdVox are separate software development efforts, you can use BirdVoxDetect from within Vesper just like any other supported detector. For example, you can use Vesper to run BirdVoxDetect on your recordings, view the resulting clips in clip albums, annotate them with species classifications, etc.
To use BirdVoxDetect with Vesper, first install it according to
Vesper’s BirdVoxDetect installation instructions.
Then, add one or more BirdVoxDetect instances to your Vesper archive
as described in the answer to this question.
You can then run any of the BirdVoxDetect instances you added using
Vesper’s Process->Detect
command.
3.5. How do I add a new detector to a Vesper archive?¶
First, a note about terminology. Within Vesper, the term detector
is used in three different senses, and it is important to
understand how these senses differ to avoid confusion. The three
senses are termed detector series, detector version, and
detector instance, and they differ in their level of specificity.
A detector series is a sequence of detector versions, which
correspond to the usual notion of software versions. For example,
the BirdVoxDetect
detector series has to date included several
versions, such as BirdVoxDetect 0.4.0
, BirdVoxDetect 0.4.1
,
and BirdVoxDetect 0.5.0
. Each detector version typically
has one or more settings, such as a detection threshold, whose
values must be specified before the detector can actually run. A
detector version plus a set of values for its settings is a
detector instance. Examples of BirdVoxDetect
instances are
BirdVoxDetect 0.5.0 FT 50
, which is version BirdVoxDetect 0.5.0
with a fixed threshold of 50, and BirdVoxDetect 0.5.0 AT 40
,
which is the same version with an adaptive threshold of 40.
Currently, when you add a new detector to a Vesper archive, you
add a detector instance. There’s no such thing (yet, at least)
as adding the detector series BirdVoxDetect
to an archive, or
even the detector version BirdVoxDetect 0.5.0
. You always add
a detector instance, like BirdVoxDetect 0.5.0 FT 50
. With that
understood, in what follows we will use the term detector as a
shorthand for detector instance.
Vesper’s Process->Detect
command allows you to run one or more
detectors on a set of recordings. For a detector to appear in the
form for that command, it must first be added to the archive database.
You can do this with the File->Import metadata
command.
It is common to import YAML metadata for one or more detectors when
you create an archive, as described in the Importing data section of the Vesper tutorial.
See the example YAML metadata files of the tutorial, particularly the
Processors
sections of those files, for examples of detector
metadata.
It often happens, however, that after creating a Vesper archive and using it for awhile, you decide that you would like to add a new detector to the archive. This can happen for a variety of reasons. A new detector version might appear in a detector series you’ve been using, or you might want to try a new instance of a detector version you’ve been using, say with a different detection threshold.
Suppose, for example, that you’ve been using the detector
BirdVoxDetect 0.5.0 FT 50
, but would like to try
BirdVoxDetect 0.5.0 FT 40
, i.e. the same detector version with
a lower threshold. To do that, you can create a YAML metadata file
for just the new detector and import it. Specifically, you can:
Create a text file (
BirdVoxDetect 0.5.0 FT 40.yaml
, say, but you can call it anything you’d like since Vesper doesn’t care about the file name) with the following contents. Note that the first line should not have any leading space, and the other lines should be indented relative to the first exactly as shown:detectors: - name: BirdVoxDetect 0.5.0 FT 40 description: BirdVoxDetect 0.5.0 NFC detector with a fixed threshold of 40.
Select
File->Import metadata
in Vesper to display theImport metadata
form.Drag your text file into the
Metadata YAML
text area of the form. The contents of the file should appear in the form.Press the
Import
button to run the command.After the command completes, restart the Vesper server for your archive to ensure that the server recognizes the new detector.
After these steps, the new detector should appear in all the appropriate
places in the Vesper user interface, for example in the Filter clips
clip album modal and the Detect
form.
Note that in the case of BirdVoxDetect, you must also make sure that the appropriate version of BirdVoxDetect is installed on your system in an appropriately-named Conda environment. See Vesper’s BirdVoxDetect installation instructions for how to create such an environment.
3.6. How do I modify the classification options displayed in Vesper?¶
The Vesper user interface (UI) presents classification options in several
places, for example to let you specify which clips should be displayed in
a clip album or which clips you would like to export to audio files. The
options presented are determined by annotation constraints specified in
the archive database. When you create a new archive, you typically create
annotation constraints by importing a metadata YAML file using the
File->Import metadata
command, as in the Vesper tutorial.
If you later decide you would like to modify an annotation constraint, for example to add or remove a species from it, you can do so using the Django admin interface. Django is a third-party web framework used by Vesper, and the admin interface is a set of web pages provided with Django that allow you to edit your Vesper archive database. Eventually, when the Vesper UI is more complete, it will never be necessary to use the Django admin interface to edit Vesper archives, but as of this writing it is still needed for some tasks.
Warning
We strongly recommend that you make a copy of your archive database
before you edit it with the Django admin interface. The archive
database is contained in the file Archive Database.sqlite
in your
archive directory. If you make a copy of this file before editing it,
then if you make a mistake in your editing, you can always recover
from the mistake by restoring the original version of the database
from your copy. If you don’t make a copy of your database and
accidentally mangle it with your edits, you may be very sorry!
To edit an annotation constraint with the Django admin interface, first
point your browser to the URL localhost:8000/admin
. Within that
interface, select Annotation constraints
and then the name of the
constraint you want to edit, for example Classification
. This will
display a form that you can use to edit the selected constraint. The
constraint contains a YAML text field called Text
. The value of
that field is a YAML mapping that includes an item named values
that you can edit to add or remove classification values.
Once you have edited an annotation constraint, you should restart your Vesper server to be sure to pick up your changes.
3.7. How do I modify the key bindings of a clip album?¶
Vesper clip albums allow you to type keys on your keyboard to invoke
a variety of clip album commands. For example, you might type “>”
to invoke a command to navigate to the next clip album page, “n” to
annotate the selected clip as a “Noise”, or “/” to play the selected
clip. You can configure which keys (or key sequences) invoke which
commands using clip album command presets. Each of these presets is a
YAML file in the Presets/Clip Album Commands
subdirectory of your
archive directory. To modify any of the presets, just use your favorite
text editor. After you edit a preset, you should restart your Vesper
server to be sure to pick up your changes.
Only one clip album command preset can be active at a time in a given
clip album. To choose the active preset for a clip album, select
Choose presets...
from the rightmost button to the right of the album’s
title. To choose the default preset for your clip albums, edit the
default_presets
item in your archive preferences, stored in the file
Preferences.yaml
in your archive directory. After you edit this file,
you should restart your Vesper server to be sure to pick up your changes.