Merge branch 'master' of https://github.com/BirdVox/birdvoxdetect

README.md

@@ -9,18 +9,84 @@ It relies on per-channel energy normalization (PCEN) and context-adaptive convol
 It is made available both as a Python library and as a command-line tool for Windows, OS X, and Linux.
 
 
-
-
-# Installation instructions
+## Installation
 
 The simplest way to install BirdVoxDetect is by using the ``pip`` package management system, which will also install the additional required dependencies
 if needed.
 
     pip install birdvoxdetect
+
+ Note that birdvoxdetect requires:
+* Python (==3.6)
+* birdvoxclassify
+* h5py (==2.9)
+* librosa (==0.7.0)
+* numpy (==1.16.4)
+* pandas (==0.25.1)
+* scikit-learn (==0.21.2)
+* tensorflow (==1.15)
+
+
+## Usage
+
+### From the command line
+
+To analyze one file:
+
+    python -m birdvoxdetect /path/to/file.wav 
+
+To analyze multiple files:
+
+    python -m birdvoxdetect /path/to/file1.wav /path/to/file2.wav
+
+To analyze one folder:
+
+   python -m birdvoxdetect /path/to/folder
+
+Optional arguments:
+
+    --output-dir OUTPUT_DIR, -o OUTPUT_DIR
+                          Directory to save the output file(s); The default
+                          value is the same directory as the input file(s).
+    --export-clips, -c    Export detected events as audio clips in WAV format.
+    --export-confidence, -C
+                          Export the time series of model confidence values of
+                          eventsin HDF5 format.
+    --threshold THRESHOLD, -t THRESHOLD
+                          Detection threshold, between 10 and 90. The default
+                          value is 30. Greater values lead to higher precision
+                          at the expense of a lower recall.
+    --suffix SUFFIX, -s SUFFIX
+                          String to append to the output filenames.The default
+                          value is the empty string.
+    --clip-duration CLIP_DURATION, -d CLIP_DURATION
+                          Duration of the exported clips, expressed in seconds
+                          (fps). The default value is 1.0, that is, one second.
+                          We recommend values of 0.5 or above.
+    --quiet, -q           Print less messages on screen.
+    --verbose, -v         Print timestamps of detected events.
+    --version, -V         Print version number.
+
+
+### From Python
+
+Call syntax:
+
+    import birdvoxdetect as bvd    
+    df = bvd.process_file('path/to/file.wav')
+
+`df` is a Pandas DataFrame with three columns: time, detection confidence, and species.
+
+Below is a typical output from the test suite (file `fd79e55d-d3a3-4083-aba1-4f00b545c3d6.wav`):
 
+       Time (hh:mm:ss) Species (4-letter code)  Confidence (%)
+    0     00:00:08.78                    SWTH           100.0
+
 
+## Contact
 
-# Acknowledging BirdVoxDetect
+Vincent Lostanlen, Cornell Lab of Ornithology (`@lostanlen` on GitHub).
+For more information on the BirdVox project, please visit our website: [https://wp.nyu.edu/birdvox](https://wp.nyu.edu/birdvox)
 
 Please cite the following paper when using BirdVoxDetect in your work: