Skip to content

Commit

Permalink
updates to usage guide
Browse files Browse the repository at this point in the history 
All straighforward click events now handled at document level
Result header no longer appears as an orpahned element
  • Loading branch information
@Mattk70
Mattk70 committed Mar 5, 2024
1 parent 35ea33b commit efed791
Show file tree
Hide file tree
Showing 8 changed files with 184 additions and 243 deletions.
3 changes: 2 additions & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -122,4 +122,5 @@ dist/
poetry.lock
pyproject.toml

scratchpad.txt
scratchpad.txt
js/animation.html
44 changes: 24 additions & 20 deletions Help/settings.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,42 +27,46 @@
<th>Confidence Threshold</th>
<td>This setting determines the minimum confidence level required for the model to report a detection.
Increasing the value reduces false positives but increases the risk of missing genuine calls.
A value around 50% provides a good balance between detecting genuine calls and minimizing false positives.
<b>N.B.</b> Confidence can be adjusted at any time. The results are updated even after analysis.
</td>
</tr>
<tr>
<th>List</th>
<td><p><b>Local Birds</b>. Exclude birds unlikely to be found in your location.</p>
<p style="padding-left: 2em">With this option selected, an additional panel appears. The <b>Threshold</b> value represents the eBird checklist frequency.
So, a value of 0.03 means birds that are predicted to occur in less than 3% of eBird checlists in the area are excluded.
If you also check "Use Week", it excludes birds not expected at the time of year the recording was made - which is read from the files' timestamp.
So, a value of 0.03 means birds that are predicted to occur in less than 3% of eBird checklists in the area are excluded.
If you also check "Use Week", it excludes birds not expected at the time of year the recording was made - which is read from the file's timestamp.
<br /> <b>N.B.</b> Currently, a limitation to the week specific filters is that the summary of detections will use the
list from the latest file in a batch of files.
For example, if you analyse files from April 22, October 23 and February 24 in a batch, the list for February 24 will be used for the summary.
</p>
<p><b>Nocturnal Birds</b>. This will exclude detections of bird song and the calls of species which do not typically vocalise during the night.</p>
<p><b>Nocturnal Birds</b>. This will exclude detections of bird song and the calls of species which do not typically vocalise during the night.
When you enable "<b>Use Location settings</b>" for the BirdNET model, the list will comprise the birds on the <b>Local Birds</b> list, excluding those
which do not call at night.</p>
<p><b>Birds</b>. Include detections for all birds, excluding non-avian classes.
</p>
<p><b>Everything</b>. In addition to all bird species, show non-bird detections including segments that were considered noise.</p>
<p><b>Custom</b>. Provide a list for the model to use. You may use a different custom list for both BirdNET and Chirpity models. The format for a
custom list file is, as for BirdNET Analyzer's custom lists, "scientific name_common name", with each species on a new line. You can export a starting
list in the correct format from the Help menu, using the "<i>What species are detected?</i>" link.
</p><p>Custom lists allow you to:</p>
<p><b>Custom</b>. Provide a list for the model to use. Custom lists allow you to:</p>
<ol>
<li>Precisely define the detections you would like Chirpity to report on</li>
<li>Search only for a specific species</li>
</ol>



<p><i>If you wish to see the full list of species used for predictions each model was trained on, check the Help menu &gt; <b>What species are detected?</b></i>.</p>
You may use a different custom list for both BirdNET and Chirpity models. The format for a
custom list file is "scientific name_common name", with each species on a new line. You can export a starting
list in the correct format from the Help menu, using the "<i>What species are detected?</i>" link.
</p>
<p><i>If you wish to see the full list of classes each model was trained on, check the Help menu &gt; <b>What species are detected?</b></i>.</p>
</td>
</tr>
<tr>
<th>Only analyse night time periods</th>
<td>
Only search for detections at night. Chirpity calculates the end and start of civil twilight for the dates
of the files and the location that is set.
Only search for detections at night. Chirpity calculates the end and start of civil twilight from the timestamps of your audio files using the location you have set. If your recording
spans both daylight and nighttime periods, the day periods will be skipped. If you are only interested in nocturnal calls this has two benefits:
<ol>
<li>There will be fewer false positves, since both models make more mistakes when many species vocalise at once (e.g. during the dawn chorus)</li>
<li>The analysis will complete faster, since it ignores any daytime period</li>
</ol>
</td>
</tr>
<tr>
Expand All @@ -74,7 +78,8 @@
class="rounded figure-img float-end img-fluid">
<figcaption class="figure-caption text-muted text-end">File name context menu.</figcaption>
</figure>
Set the default location to use for calculating the start and end of civil twilight. This setting can be overriden for individual files by assigning a custom location in the filename context menu.
Set the default location to use for calculating the start and end of civil twilight and also generating your <b>Local Birds</b> list. This setting can be overriden for individual
files by assigning a custom location in the filename context menu.
</td>
</tr>
<tr>
Expand Down Expand Up @@ -127,7 +132,7 @@
</tr>
<tr>
<td><b>Volume Adjustment</b></td>
<td>If your recordings are very quiet, you can increase the loudness of the audio by adding gain. The volume of audio can be increased by up to 50 decibels.</td>
<td>If your recordings are very quiet, you can increase the loudness of the audio by increasing the gain. The volume of audio can be increased by up to 50 decibels.</td>
</tr>
<tr>
<td><b>Normalise audio</b></td>
Expand All @@ -138,13 +143,13 @@
</tr>
<tr>
<th>High Pass filter</th>
<td> This applies a filter to the audio, removing the sound below the frequency selected.
Intended primarily for recordings made in in urban settings, this will reduce the level of low-frequency hum.
<td> This filter removes the sound below the frequency selected.
Intended primarily for recordings made in in urban settings, this suppresses low-frequency hum.
</td>
</tr>
<tr>
<th>Low Shelf filter</th>
<td> This applies an audio filter similar to the High Pass filter, however, rather than simply remove noise, it reduces the volume of low frequency noise.
<td> This filter is similar to the High Pass filter. However, rather than simply remove noise, it reduces the volume of low frequency noise.
The advantage of a low shelf filter is that you can reduce the hum, whilst still being able to hear species which have low frequency calls.
You can set the threshold frequency, and the strength of the filter to apply (Attenuation).
</td>
Expand Down Expand Up @@ -235,7 +240,6 @@
<td>
Chirpity sends usage information anonymously to an analytics server. This information is used to help understand how people use Chirpity, and try to identify any bugs
or errors. Both help improve the software and prioritise changes for future releases. If you would prefer that Chirpity did not send any usage data, you can disable it here.

</td>
</tr>
</table>
Expand Down
111 changes: 43 additions & 68 deletions Help/usage.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,74 +7,31 @@
</head>

<body>
<h4 class="text-center bg-dark text-white p-3">Suggested Workflow</h4>
<div class="row mb-3">
<div class="col-sm-6">
<div class="card">
<div class="card-header">Using Chirpity</div>
<div class="card-body">
<iframe width="100%" height="100%"
src="https://www.youtube.com/embed/5_37FMPRkwY?si=qnQNUKJJyuCJ_U4b?vq=hd720&cc_load_policy=1"
title="YouTube video player" frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowfullscreen></iframe>
<p class="card-text">An introductary tour of the key features of Chirpity. Best viewed in fullscreen
mode</p>
</div>
</div>
</div>
<div class="col-sm-6">
<div class="card">
<div class="card-header">Chirpity Settings</div>
<div class="card-body">
<iframe width="100%" height="100%"
src="https://www.youtube.com/embed/zMdu8P2CBQo?si=kK3FwkQ9_QMeawe6?vq=hd720"
title="YouTube video player" frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowfullscreen></iframe>
<p class="card-text">An overview of the settings menu in Chirpity. Best viewed in fullscreen mode
</p>
</div>
</div>
</div>
</div>

<h4 class="text-center text-bg-light p-3">Suggested Workflow</h4>
<figure class="figure float-end m-3">
<img src="Help/amend file.png"
alt="The context menu accessed from the filename contains options to amend the file's start time and the recording location"
class="rounded figure-img float-end img-fluid">
<figcaption class="figure-caption text-muted text-end">File name context menu.</figcaption>
</figure>
<ol>
<li>Open an audio file or files. There are a three ways to do this:
<li>Open an audio file, files or folder of audio. There are a three ways to do this:
<ol>
<li>Right-click on the audio file(s) in Windows Explorer and select "Open with" &gt; Chirpity Nocmig</li>
<li>In the Chirpity Nocmig application, select File &gt; Open Audio File or press Ctrl-O and select the

<li>Drag and drop the files or folders onto the Chirpity Nocmig application</li><li>In the Chirpity Nocmig application, select File &gt; Open Audio File or press Ctrl-O and select the
files to open</li>
<li>Drag and drop the files or folders onto the Chirpity Nocmig application</li>
<li>Right-click on the audio file(s) in Windows Explorer (or Finder on a Mac) and select "Open with" &gt; Chirpity</li>
</ol>
Ideally, files will be those recorded by your digital recorder with their original
timestamp. In this scenario, you will be able to take advantage of the <b>Time of Day</b> mode for the
timestamp. In this case, you will be able to take advantage of the <b>Time of Day</b> mode for the
spectrogram timeline, which will show the actual time calls were
detected. If not, you can still display (and store) the correct time of day for the file and detections if
you edit its start time.
This can be edited by right-clicking the filename in the control bar.
<figure class="figure float-end m-3">
<img src="Help/amend file.png"
alt="The context menu accessed from the filename contains options to amend the file's start time and the recording location"
class="rounded figure-img float-end img-fluid">
<figcaption class="figure-caption text-muted text-end">File name context menu.</figcaption>
</figure>
</li>
<li>Choose whether to use <b>Nocmig mode.</b> Once the file is loaded, the spectrogram will appear, along with
transport controls for
navigating the audio. A <i>nocmig mode</i> button (<span
class="material-symbols-outlined align-bottom">nights_stay</span>) will also appear on the
right hand side. Nocmig mode takes its
cue from the file creation date and time. It limits the analysis to calls occurring both after the end of
civil
twilight and before the beginning of civil twilight the following day. The default location used for
dawn/dusk calculations can be set from the settings menu, and a custom location can be applied to an
individual file or open files
<b>N.B.</b>
If active, Nocmig mode is temporarily disabled for the Analysis of selections.

</li>
<li>
Having determined whether to use Nocmig mode, select &quot;<i>Analyse file</i>&quot; from the
Select &quot;<i>Analyse file</i>&quot; from the
<b>Analysis</b> menu. Depending on the file length, this may take several minutes. A progress indicator will
appear as a guide to how long this is likely to take. To stop the analysis at any point, press the
<b>Esc</b>
Expand All @@ -86,7 +43,7 @@ <h5 class="pt-2">Exploring Detections</h5>
<ol start="4">
<li>
As the model makes detections, they appear in a table below the spectrogram. Clicking the detection's row in
the table will cause the playhead to jump to the start of that detection and highlight it's location on the
the table will cause the playhead to jump to the start of that detection and highlight its location on the
spectrogram.
Right-clicking the row will bring up the detection context menu.
<figure class="figure float-end m-3">
Expand All @@ -110,8 +67,7 @@ <h5 class="pt-2">Summary and Filtering Detections</h5>
<ol start="6">
<li>
A summary table appears to the left of the results once the model has completed its analysis. Importantly,
this
table allows you to filter the results displayed in the main results
this table allows you to filter the results displayed in the main results
table. Click the species name in the summary to limit
the display to that single species. This is <i>extremely</i> useful if several hundred Robin calls were
detected!
Expand All @@ -133,7 +89,7 @@ <h5 class="pt-2">Custom "Deep Dive" Detections</h5>

<h5 class="pt-2">Amending Results</h5>
<ol start="8">
<li>It is possible to remove results from what will be saved by selecting <span
<li>It is possible to remove results by selecting <span
class="delete material-symbols-outlined">delete_forever</span> <b>Delete Record</b> in the context menu.
This can be selected on a per-detection basis in the results table, or a per-species basis in the summary.
</li>
Expand All @@ -142,13 +98,13 @@ <h5 class="pt-2">Amending Results</h5>

<h5 class="pt-2">Saving Results</h5>
<ol start="9">
<li>Once the analysis is complete, and after you have made any amendments, you can save the results to a
database by selecting <b>Records &gt; <span class="material-symbols-outlined">archive</span> Save to Archive </b>
<li><p><b>N.B.</b> Results are not saved by default.</p>Save results by selecting <b>Records &gt; <span class="material-symbols-outlined">archive</span> Save to Archive </b>

</li>
</ol>

<h5 id="reload" class="pt-2">Restoring Results</h5>
<p>When you save your detections in Chirpity Nocmig, a database is updated with the details of the detections. If
<p>When you save your detections in Chirpity, a database is updated with the details of the detections. If
you
reload your file at a later date, and select analyse file, the saved results are restored. <b>N.B.</b> If the
original file is missing because it has
Expand All @@ -163,10 +119,6 @@ <h5 id="reload" class="pt-2">Restoring Results</h5>
<h5 id="export" class="pt-2">Exporting Results</h5>
There are a number of ways to export detections.
<ol>
<li>Save the detections as a label file in Audacity format. Press <b>Ctrl-A</b> or select <b>File &gt; Save
Audacity Labels</b> from the menu. By default, the label file will have the same name as the
audio file,with a ".txt" extension.
</li>
<li>
Export an audio clip of a detection. To do this, select <span class="material-symbols-outlined">
music_note
Expand All @@ -182,7 +134,30 @@ <h5 id="export" class="pt-2">Exporting Results</h5>
ios_share
</span><b>Export results to CSV</b> from the file menu. This will export the results to a CSV file in the folder you choose.
</li>
<li>Save the detections as a label file in Audacity format. Press <b>Ctrl-A</b> or select <b>File &gt; Save
Audacity Labels</b> from the menu. By default, the label file will have the same name as the
audio file,with a ".txt" extension.
</li>
</ol>
<div class="row mb-3">
<div class="col-sm-6">
<div class="card">
<div class="card-header">Example of using Chirpity</div>
<div class="card-body">
<div class="ratio ratio-16x9">
<iframe width="100%" height="100%"
src="https://www.youtube.com/embed/5_37FMPRkwY?si=qnQNUKJJyuCJ_U4b?vq=hd720&cc_load_policy=1"
title="YouTube video player" frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowfullscreen>
</iframe>
</div>
<p class="card-text">An introductary tour of the key features of Chirpity.</p>
</div>
</div>
</div>
</div>

</body>

</html>
2 changes: 1 addition & 1 deletion css/style.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -558,7 +558,7 @@ input[type="range"].vertical {
}

.offcanvas-backdrop {
display: none !important;
background-color: rgba(0, 0, 72, 0.1);
}

#settingsMap {
Expand Down
Loading

0 comments on commit efed791

Please sign in to comment.