changeset 375:fbfdd3e04999

Update Readme

--- a/README.rst	Thu Jan 21 22:19:47 2021 +0100
+++ b/README.rst	Thu Jan 21 22:51:12 2021 +0100
@@ -24,20 +24,32 @@
 files in *wav* or *raw* formats. if you want more features, the following
 packages are needed:
 
-    - `pydub <https://github.com/jiaaro/pydub>`_ : read audio files in popular
-       audio formats (ogg, mp3, etc.) or extract audio from a video file.
-    - `pyaudio <http://people.csail.mit.edu/hubert/pyaudio/>`_ : read audio data
-       from the microphone and play audio back.
-    - `tqdm <https://github.com/tqdm/tqdm>`_ : show progress bar while playing
-       audio clips.
-    - `matplotlib <http://matplotlib.org/>`_ : plot audio signal and detections.
-    - `numpy <http://www.numpy.org>`_ : required by matplotlib. Also used for
-       some math operations instead of standard python if available.
+- `pydub <https://github.com/jiaaro/pydub>`_ : read audio files in popular audio formats (ogg, mp3, etc.) or extract audio from a video file.
+- `pyaudio <http://people.csail.mit.edu/hubert/pyaudio/>`_ : read audio data from the microphone and play audio back.
+- `tqdm <https://github.com/tqdm/tqdm>`_ : show progress bar while playing audio clips.
+- `matplotlib <https://matplotlib.org/stable/index.html>`_ : plot audio signal and detections.
+- `numpy <https://numpy.org/>`_ : required by matplotlib. Also used for some math operations instead of standard python if available.
+
+Install the latest stable version with pip:
+
+.. code:: bash
+
+    sudo pip install auditok
+
+Install with the latest version from github:
 
 .. code:: bash
 
     pip install git+https://github.com/amsehili/auditok
 
+or
+
+.. code:: bash
+
+    git clone https://github.com/amsehili/auditok.git
+    cd auditok
+    python setup.py install
+
 
 Basic example
 -------------
@@ -54,24 +66,52 @@
         max_silence=0.3, # maximum duration of tolerated continuous silence within an event
         energy_threshold=55 # threshold of detection
     )
-    for region in audio_regions:
-        region.play(progress_bar=True)
-        filename = region.save("/tmp/region_{meta.start:.3f}.wav")
+
+    for i, r in enumerate(audio_regions):
+
+        # Regions returned by `split` have 'start' and 'end' field metadata
+        print("Region {i}: {r.meta.start:.3f}s -- {r.meta.end:.3f}s".format(i=i, r=r))
+
+        # play detection
+        # r.play(progress_bar=True)
+
+        # detection's metadata can be used with `save`
+        # (no need to explicitly specify region's object and `format` arguments)
+        filename = r.save("region_{meta.start:.3f}-{meta.end:.3f}.wav")
         print("region saved as: {}".format(filename))
 
+output example:
+
+.. code:: bash
+
+    Region 0: 0.700s -- 1.400s
+    region saved as: region_0.700-1.400.wav
+    Region 1: 3.800s -- 4.500s
+    region saved as: region_3.800-4.500.wav
+    Region 2: 8.750s -- 9.950s
+    region saved as: region_8.750-9.950.wav
+    Region 3: 11.700s -- 12.400s
+    region saved as: region_11.700-12.400.wav
+    Region 4: 15.050s -- 15.850s
+    region saved as: region_15.050-15.850.wav
+
+
 Split and plot
 --------------
 
+Visualize audio signal and detections:
+
 .. code:: python
 
     import auditok
     region = auditok.load("audio.wav") # returns an AudioRegion object
-    regions = region.split_and_plot() # or just region.splitp()
+    regions = region.split_and_plot(...) # or just region.splitp()
 
 output figure:
 
 .. image:: doc/figures/example_1.png
 
+
 Limitations
 -----------