Skip to content

Commit

Permalink
Help files and menu items
Browse files Browse the repository at this point in the history 
Updating functionality using Hazel
  • Loading branch information
@Mattk70
Mattk70 committed Mar 17, 2022
1 parent b708916 commit 4ff8ffe
Show file tree
Hide file tree
Showing 10 changed files with 417 additions and 21 deletions.
46 changes: 46 additions & 0 deletions Help/about.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>About Chirpity Nocmig</title>
</head>
<body>
<h6>The Chirpity Vision, and a Note on Accuracy</h6>
<p>
Chirpity Nocmig works by detecting calls found in 3-second audio windows. Actually, it detects <i>images</i> of
calls generated from audio files. Behind the scenes it takes audio, converts and resamples it from the source format
and creates a
spectrogram for each audio sample. It performs 1200 predictions per hour. By one measure - number of predictions /
number correct - it often achieves around 99% accuracy. However, that figure will not reflect the experience of
using the software in the real world. The fact is, most of us are not interested to know that thousands of "no call"
predictions were correct, it's the quality of species detections that matter.
</p>
<p>
The reality is that this prototype can still easily be thrown off by novel sounds, sounds it has not seen enough of
during its training. A new car alarm sound can trigger dozens of false IDs. Wind in trees, pops and bangs, people
playing football a quarter of a mile away - all these noises can appear similar to a bird call.
</p>
<p>
Generally though, it is not difficult to breeze past these shortcomings with a little practice. You learn that
people and dogs may be confused with geese and swans, that a car alarm can be confused with a wader. As the dawn
chorus approaches and the density of bird vocalizations increases the chance that it may mistake a snatch of robin
sub-song for a skylark.
</p>
<p>
The value of Chirpity Nocmig lies in its ability to <i>simplify and support</i> the process of identifying birds by
sound. It is
sufficiently accurate, even now, to be a useful tool. It's a long way from beating Kasparov at Chess, but for anyone
struggling to get a handle on bird identification by sound, this software will help enormously.
</p>
<p>
Over time, the software will improve. As the model is exposed to a greater variety of noise data, it will learn
to ignore more of those noises, and the false positives will diminish. Refinements to the deep learning architecture
will also bring improvements - future updates may incorporate location and date information to refine predictions,
for example.
</p>
<p>
If you don't expect perfection, you won't be disappointed.
</p>

</body>
</html>
63 changes: 63 additions & 0 deletions Help/keyboard.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Keyboard shortcuts</title>
</head>
<body>

<table class="table table-hover p-1">
<tr>
<td colspan="2" class="text-center"><h5>File handling</h5></td>
</tr>
<tr>
<td><b>Ctrl-O</b></td>
<td>Show file open dialog</td>
</tr>
<tr>
<td><b>Ctrl-S</b></td>
<td>Save label file for Audacity. Only active after file analysis, when there are labels to save!</td>
</tr>
<tr>
<td><b>Esc</b></td>
<td>Abort an operation. Effective for file loading and analysis</td>
</tr>
<tr>
<td colspan="2" class="text-center"><h5>Transport Controls</h5></td>
</tr>
<tr>
<td><b>SpaceBar</b></td>
<td>Toggle Play/Pause the audio</td>
</tr>
<tr>
<td><b>P</b></td>
<td>Play the selected region. Only active if a region has been selected.</td>
</tr>
<tr>
<td><b>Home</b></td>
<td>Move the playhead to the beginning of the file</td>
</tr>
<tr>
<td><b>End</b></td>
<td>Move the playhead to the end of the file</td>
</tr>
<tr>
<td><b>PgUp</b></td>
<td>Move the playhead back by a screen width</td>
</tr>
<tr>
<td><b>PgDn</b></td>
<td>Move the playhead forward by a screen width</td>
</tr>
<tr>
<td><b>Left arrow (>)</b></td>
<td>Move the playhead forward. Can be used to shift the screen view if a call is cut off at the screen edges</td>
</tr>
<tr>
<td><b>Right arrow (<)</b></td>
<td>Move the playhead backward. Can also be used to shift the screen view if a call is cut off at the screen edges</td>
</tr>
</table>

</body>
</html>
71 changes: 71 additions & 0 deletions Help/options.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Chirpity Nocmig Options</title>
</head>
<body>

<table class="table table-hover p-1">
<tr>
<td colspan="2" class="text-center"><h5>Model options</h5></td>
</tr>
<tr>
<td><b>Use whitelist</b></td>
<td>Enabled by default. This option limits the species detections shown to those recorded at UK Nocmig sites
submitting data to Trektellen.
<p>If disabled, the full list of potential detections is used. This includes
UK vagrants as well as those birds not known to call or fly at night. Non-bird detections will also
appear. </p>
This full list comprises 306 bird species and the following non-bird classes:
<ul>
<li><b>Ambient noise:</b> wind, rain, pops and bangs. Things that go bump in the night...</li>
<li><b>Animals:</b> cats, dogs, bats, etc.</li>
<li><b>Human:</b> voices, whistles, etc.</li>
<li><b>Vehicles:</b> Wheel and engine noise of cars, trucks, trains and aircraft. Also sirens and alarms
(including domestic burglar alarms) and horns.
</li>
</ul>
<p>If you wish to see the full list of species Chirpity <i>Nocmig</i> was trained on, it is contained in the
feedback prompt offered when giving feedback on an incorrect prediction.</p>
Disabling the whitelist is <em>not</em> recommended for general use. It will lead to an increase in false
positive detections, and clutter the results table with irrelevant detections.
</td>
</tr>
<tr>
<td colspan="2" class="text-center"><h5>Spectrogram options</h5></td>
</tr>
<tr>
<td><b>Enable</b></td>
<td>Whether to display the Spectrogram view. Will reduce the computer RAM required for larger files, at the cost
of significantly reduced functionality. However, results will be displayed and a label file may be exported
for use in Audacity.
</td>
</tr>
<tr>
<td><b>Timeline</b></td>
<td>Whether to display a timeline above the spectrogram. The timeline has two modes.
<ul>
<li>
<b>Time Elapsed</b> displays the time from the beginning of the file.
</li>
<li>
<b>Time of Day</b> uses the file timestamp to
calculate the actual time of the calls detected. If a file does not have a timestamp reflecting the
time of the recording, this will give a spurious reading.
</li>
</ul>
</td>
</tr>
<tr>
<td><b>Colour</b></td>
<td>Displays the spectrogram in colour</td>
</tr>
<tr>
<td><b>Grayscale</b></td>
<td>Displays the spectrogram in black and white.</td>
</tr>
</table>

</body>
</html>
127 changes: 127 additions & 0 deletions Help/usage.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Chirpity Nocmig usage guide</title>
</head>
<body>
<h4 class="text-center">Suggested Workflow</h4>
<ol>
<li>Open an audio file. Ideally, this will be the file that was recorded by your digital recorder with its original
timestamp. By using this file, you will be able to take advantage of the <b>Options > Spectrogram >
Timeline >
Time of Day</b> mode for the spectrogram timeline, which will show the actual time calls were detected.
<b>N.B.</b>
It is possible to cancel a file load operation by pressing the <b>Esc</b> key.
</li>
<li>
Once the file has loaded, select &quot;<i>Analyse entire file</i>&quot; from the <b>Analysis</b> menu. Depending
on the file length, this may take several minutes. A progress indicator will appear to guide you on how long
this is likely to take. To stop the analysis, press the <b>Esc</b> key.
</li>
</ol>
<h5 class="pt-2">Exploring Detections</h5>
<ol start="3">
<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. Press <b>P</b>, or the
<span class='material-icons play pointer align-bottom'>play_circle_filled</span> icon to play the detection.
Alternatively, you may press the SpaceBar to play from the beginning of the selection and continue playing the
audio until you press the SpaceBar again. Clicking the spectrogram will move the playhead to that position.
Playback will continue, so this allows you to replay a call repeatedly.
</li>
<li>
Selecting the <img src="img/logo/XC.png" alt="XC"> icon will open a search result (in your default web broswer)
for the
detected species' night flight calls on the Xeno Canto website. Here you can compare the result to Nocmig
recordings
uploaded by others.
</li>
<li>
If multiple species were detected, or if the detection has an alternative ID for the call, a
<span class='material-icons-two-tone'>expand_more</span> icon will be displayed in the Other IDs
table column. Clicking this will open rows beneath with the details of those species.
</li>
</ol>
<h5 class="pt-2">Summary and Filtering Detections</h5>
<ol start="6">
<li>
<button type="button" class="btn btn-primary btn-sm" data-toggle="modal">
Show Summary
</button>
appears once the model has completed its analysis. Clicking the button will open a summary table of the
detections across the file. Importantly, this table allows you to filter the results displayed in the main
results
table. Click the filter icon ( <span class="material-icons-two-tone align-bottom ">filter_alt</span> ) to limit
the
display to that single species, or the <span class="material-icons-two-tone align-bottom ">clear</span> icon to
exclude a species from the result table. This is <i>extremely</i> useful if several hundred Robin calls were
detected!
</li>
</ol>
<h5 class="pt-2">Custom "Deep Dive" Detections</h5>
<ol start="7">
<li>Sometimes, a call is missed or a detection is erroneous due to the position of the analysis window in relation
to the call. The window can be moved by dragging it, or you can create a new window by clicking and
dragging out a custom region on the spectrogram. Once you have a new region, select <b>Analysis > Analyse
selected interval</b> from the menu. The custom detection is placed at the top of the results table.
<b>N.B.</b> The detection threshold is much reduced for custom detections, so exercise appropriate caution since
false positives are more likely. Uncoloured confidence icons should be treated as a "wild guess", even
considered by the model more likely to be wrong than right.
</li>
</ol>

<h5 class="pt-2">Saving Results</h5>
<ol start="8">
<li>Currently, there are three ways to save results:
<ul>
<li>Save the detections as a label file in Audacity format. Press <b>Ctrl-S</b> or select <b>File > 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>
Save a 3-second audio clip of a detection (in MP3 format). To do this, click the <span
class='material-icons-outlined align-bottom'>
file_download</span> icon in the result table. By default, the filename will contain the species and
timestamp of the detection identifying its position in the original audio file.
</li>
<li>
Save a custom MP3 clip. Select a region of the spectrogram by dragging the mouse over the area of audio
you
want
to save.
From the File menu, select <b>Export Selected Audio</b> to bring up a file save dialog.
</li>
</ul>
</li>
</ol>
<h5 class="pt-2">Feedback</h5>
<ol start="9">
<li>
<p>Machine Learning requires vast amounts of data. Adequate results can be obtained from a few hundred examples
of a
call, but for robust and reliable results several thousand examples are needed. Those examples need to be
representative of the
range of vocalisations a bird can make, under a wide range of conditions.
Providing feedback is the best way to help improve the quality of detections and takes as few as two clicks
of a
mouse.</p>
<ul>
<li>
If you think a detection is correct, click the <span
class='material-icons-two-tone text-success align-bottom'>
thumb_up_alt</span> icon and confirm to submit the feedback.
</li>
<li>
If you think the prediction is incorrect, click the <span
class='material-icons-two-tone text-danger align-bottom'>
thumb_down_alt</span> icon. This will bring up a prompt inviting you to say what you think the prediction
should have been. The list can be filtered by entering the first few letters of the species in the box.
Selecting the species will check the ID, and hitting send will submit the feedback.
</li>
<li>In either case, hitting <b>Esc</b> will cancel the submission.</li>
</ul>
</li>
</ol>
</body>
</html>
5 changes: 0 additions & 5 deletions css/style.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,6 @@ html, body {

tr[id^="sub"] {
font-size: 12px;

}

span[id^="filename_"] {
Expand Down Expand Up @@ -215,7 +214,3 @@ div#contentWrapper {
#myUL li a:hover:not(.header) {
background-color: #eee; /* Add a hover effect to all links, except for headers */
}

.modal-body {
max-height: 320px;
}
31 changes: 30 additions & 1 deletion index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,18 @@
</ul>
</div>
</li>
<li class="nav-item dropdown active">
<a class="nav-link dropdown-toggle" href="#" id="help" role="button" data-toggle="dropdown"
aria-haspopup="true" aria-expanded="false">
Help
</a>
<div class="dropdown-menu" aria-labelledby="navbarDropdown">
<a class="dropdown-item" id="usage" href="#">Usage</a>
<a class="dropdown-item" id="options" href="#">Options</a>
<a class="dropdown-item" id="keyboard" href="#">Keyboard Shortcuts</a>
<a class="dropdown-item" id="about" href="#">About Chirpity Nocmig</a>
</div>
</li>
</ul>
<img class="" src="img/logo/chirpity_logo2.png" alt="Chirpity Birdcalls: Identifying birds by sound"
height="50px"/>
Expand Down Expand Up @@ -171,6 +183,23 @@ <h5 class="modal-title" id="feedbackModalLabel">Feedback</h5>
</div>
</div>
</div>
<!-- Help Modal -->
<div class="modal fade" id="helpModal" tabindex="-1" aria-labelledby="helpModalLabel" aria-hidden="true">
<div class="modal-dialog modal-xl modal-dialog-centered modal-dialog-scrollable">
<div class="modal-content">
<div class="modal-header justify-content-center">
<h5 class="modal-title" id="helpModalLabel">Help</h5>
<button type="button" class="close" data-dismiss="modal" aria-label="Close">
<span aria-hidden="true">&times;</span>
</button>
</div>
<div id="helpModalBody" class="modal-body"></div>
<div class="modal-footer justify-content-center">
<button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
</div>
</div>
</div>
</div>
<!-- Load audio file hint -->
<div class="d-flex h-100 flex-column text-dark align-items-center justify-content-center" id="loadFileHint">
<div class="row">
Expand Down Expand Up @@ -244,7 +273,7 @@ <h5 class="modal-title" id="feedbackModalLabel">Feedback</h5>
</span></th>
<th scope="col" class="text-center">Other IDs</th>
<th scope="col" class="specFeature text-center">Play</th>
<th scope="col" class="specFeature text-center">XC</th>
<th scope="col" class="text-center">XC</th>
<th scope="col" class="specFeature text-center">Save</th>
<th scope="col" class="specFeature text-center">Feedback</th>
</tr>
Expand Down
Loading

0 comments on commit 4ff8ffe

Please sign in to comment.