DOC: Update examples

Author: mgeier

doc/examples.rst

@@ -1,5 +1,4 @@
-Example Programs
-================
+.. include:: ../examples/README.rst
 
 Play a Sound File
 -----------------

examples/README.rst

@@ -0,0 +1,11 @@
+Example Programs
+================
+
+Most of these examples use the `argparse` module to handle command line
+arguments.
+To show a help text explaining all available arguments,
+use the ``--help`` argument.
+
+For example::
+
+   python3 play_file.py --help

examples/asyncio_coroutines.py

@@ -8,6 +8,7 @@
 
 """
 import asyncio
+import sys
 
 import numpy as np
 import sounddevice as sd
@@ -70,4 +71,7 @@ async def main(frames=150_000, channels=1, dtype='float32', **kwargs):
 
 
 if __name__ == "__main__":
-    asyncio.run(main())
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        sys.exit('\nInterrupted by user')

examples/asyncio_generators.py

@@ -10,6 +10,7 @@
 """
 import asyncio
 import queue
+import sys
 
 import numpy as np
 import sounddevice as sd
@@ -36,7 +37,7 @@ async def stream_generator(blocksize, *, channels=1, dtype='float32',
 
     The output blocks are uninitialized and have to be filled with
     appropriate audio signals.
-    
+
     """
     assert blocksize != 0
     q_in = asyncio.Queue()
@@ -97,8 +98,11 @@ async def main(**kwargs):
     try:
         await audio_task
     except asyncio.CancelledError:
-        print('wire was cancelled')
+        print('\nwire was cancelled')
 
 
 if __name__ == "__main__":
-    asyncio.run(main(blocksize=1024))
+    try:
+        asyncio.run(main(blocksize=1024))
+    except KeyboardInterrupt:
+        sys.exit('\nInterrupted by user')

examples/play_file.py

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
 """Load an audio file into memory and play its contents.
 
-NumPy and the soundfile module (http://PySoundFile.rtfd.io/) must be
-installed for this to work.
+NumPy and the soundfile module (https://PySoundFile.readthedocs.io/)
+must be installed for this to work.
 
 This example program loads the whole file into memory before starting
 playback.
@@ -11,6 +11,9 @@
 """
 import argparse
 
+import sounddevice as sd
+import soundfile as sf
+
 
 def int_or_str(text):
     """Helper function for argument parsing."""
@@ -19,21 +22,34 @@ def int_or_str(text):
     except ValueError:
         return text
 
-parser = argparse.ArgumentParser(description=__doc__)
-parser.add_argument('filename', help='audio file to be played back')
-parser.add_argument('-d', '--device', type=int_or_str,
-                    help='output device (numeric ID or substring)')
-args = parser.parse_args()
+
+parser = argparse.ArgumentParser(add_help=False)
+parser.add_argument(
+    '-l', '--list-devices', action='store_true',
+    help='show list of audio devices and exit')
+args, remaining = parser.parse_known_args()
+if args.list_devices:
+    print(sd.query_devices())
+    parser.exit(0)
+parser = argparse.ArgumentParser(
+    description=__doc__,
+    formatter_class=argparse.RawDescriptionHelpFormatter,
+    parents=[parser])
+parser.add_argument(
+    'filename', metavar='FILENAME',
+    help='audio file to be played back')
+parser.add_argument(
+    '-d', '--device', type=int_or_str,
+    help='output device (numeric ID or substring)')
+args = parser.parse_args(remaining)
 
 try:
-    import sounddevice as sd
-    import soundfile as sf
     data, fs = sf.read(args.filename, dtype='float32')
     sd.play(data, fs, device=args.device)
     status = sd.wait()
-    if status:
-        parser.exit('Error during playback: ' + str(status))
 except KeyboardInterrupt:
     parser.exit('\nInterrupted by user')
 except Exception as e:
     parser.exit(type(e).__name__ + ': ' + str(e))
+if status:
+    parser.exit('Error during playback: ' + str(status))

examples/play_long_file.py

@@ -1,41 +1,60 @@
 #!/usr/bin/env python3
 """Play an audio file using a limited amount of memory.
 
-The soundfile module (http://PySoundFile.rtfd.io/) must be installed for
-this to work.  NumPy is not needed.
+The soundfile module (https://PySoundFile.readthedocs.io/) must be
+installed for this to work.  NumPy is not needed.
 
 In contrast to play_file.py, which loads the whole file into memory
 before starting playback, this example program only holds a given number
 of audio blocks in memory and is therefore able to play files that are
 larger than the available RAM.
 
+A similar example could of course be implemented using NumPy,
+but this example shows what can be done when NumPy is not available.
+
 """
-from __future__ import division, print_function
 import argparse
-try:
-    import queue  # Python 3.x
-except ImportError:
-    import Queue as queue  # Python 2.x
+import queue
 import sys
 import threading
 
+import sounddevice as sd
+import soundfile as sf
+
+
 def int_or_str(text):
     """Helper function for argument parsing."""
     try:
         return int(text)
     except ValueError:
         return text
 
-parser = argparse.ArgumentParser(description=__doc__)
-parser.add_argument('filename', help='audio file to be played back')
-parser.add_argument('-d', '--device', type=int_or_str,
-                    help='output device (numeric ID or substring)')
-parser.add_argument('-b', '--blocksize', type=int, default=2048,
-                    help='block size (default: %(default)s)')
+
+parser = argparse.ArgumentParser(add_help=False)
+parser.add_argument(
+    '-l', '--list-devices', action='store_true',
+    help='show list of audio devices and exit')
+args, remaining = parser.parse_known_args()
+if args.list_devices:
+    print(sd.query_devices())
+    parser.exit(0)
+parser = argparse.ArgumentParser(
+    description=__doc__,
+    formatter_class=argparse.RawDescriptionHelpFormatter,
+    parents=[parser])
+parser.add_argument(
+    'filename', metavar='FILENAME',
+    help='audio file to be played back')
+parser.add_argument(
+    '-d', '--device', type=int_or_str,
+    help='output device (numeric ID or substring)')
+parser.add_argument(
+    '-b', '--blocksize', type=int, default=2048,
+    help='block size (default: %(default)s)')
 parser.add_argument(
     '-q', '--buffersize', type=int, default=20,
     help='number of blocks used for buffering (default: %(default)s)')
-args = parser.parse_args()
+args = parser.parse_args(remaining)
 if args.blocksize == 0:
     parser.error('blocksize must not be zero')
 if args.buffersize < 1:
@@ -65,16 +84,12 @@ def callback(outdata, frames, time, status):
 
 
 try:
-    import sounddevice as sd
-    import soundfile as sf
-
     with sf.SoundFile(args.filename) as f:
         for _ in range(args.buffersize):
             data = f.buffer_read(args.blocksize, dtype='float32')
             if not data:
                 break
             q.put_nowait(data)  # Pre-fill queue
-
         stream = sd.RawOutputStream(
             samplerate=f.samplerate, blocksize=args.blocksize,
             device=args.device, channels=f.channels, dtype='float32',

examples/play_sine.py

@@ -3,6 +3,9 @@
 import argparse
 import sys
 
+import numpy as np
+import sounddevice as sd
+
 
 def int_or_str(text):
     """Helper function for argument parsing."""
@@ -12,31 +15,33 @@ def int_or_str(text):
         return text
 
 
-parser = argparse.ArgumentParser(description=__doc__)
+parser = argparse.ArgumentParser(add_help=False)
 parser.add_argument(
     '-l', '--list-devices', action='store_true',
     help='show list of audio devices and exit')
-parser.add_argument(
-    '-d', '--device', type=int_or_str,
-    help='output device (numeric ID or substring)')
+args, remaining = parser.parse_known_args()
+if args.list_devices:
+    print(sd.query_devices())
+    parser.exit(0)
+parser = argparse.ArgumentParser(
+    description=__doc__,
+    formatter_class=argparse.RawDescriptionHelpFormatter,
+    parents=[parser])
 parser.add_argument(
     'frequency', nargs='?', metavar='FREQUENCY', type=float, default=500,
     help='frequency in Hz (default: %(default)s)')
+parser.add_argument(
+    '-d', '--device', type=int_or_str,
+    help='output device (numeric ID or substring)')
 parser.add_argument(
     '-a', '--amplitude', type=float, default=0.2,
     help='amplitude (default: %(default)s)')
-args = parser.parse_args()
+args = parser.parse_args(remaining)
 
-try:
-    import numpy as np
-    import sounddevice as sd
-
-    if args.list_devices:
-        print(sd.query_devices())
-        parser.exit(0)
+start_idx = 0
 
+try:
     samplerate = sd.query_devices(args.device, 'output')['default_samplerate']
-    start_idx = 0
 
     def callback(outdata, frames, time, status):
         if status:
@@ -53,5 +58,7 @@ def callback(outdata, frames, time, status):
         print('press Return to quit')
         print('#' * 80)
         input()
+except KeyboardInterrupt:
+    parser.exit('')
 except Exception as e:
     parser.exit(type(e).__name__ + ': ' + str(e))

examples/plot_input.py

@@ -8,6 +8,11 @@
 import queue
 import sys
 
+from matplotlib.animation import FuncAnimation
+import matplotlib.pyplot as plt
+import numpy as np
+import sounddevice as sd
+
 
 def int_or_str(text):
     """Helper function for argument parsing."""
@@ -17,10 +22,21 @@ def int_or_str(text):
         return text
 
 
-parser = argparse.ArgumentParser(description=__doc__)
+parser = argparse.ArgumentParser(add_help=False)
 parser.add_argument(
     '-l', '--list-devices', action='store_true',
     help='show list of audio devices and exit')
+args, remaining = parser.parse_known_args()
+if args.list_devices:
+    print(sd.query_devices())
+    parser.exit(0)
+parser = argparse.ArgumentParser(
+    description=__doc__,
+    formatter_class=argparse.RawDescriptionHelpFormatter,
+    parents=[parser])
+parser.add_argument(
+    'channels', type=int, default=[1], nargs='*', metavar='CHANNEL',
+    help='input channels to plot (default: the first)')
 parser.add_argument(
     '-d', '--device', type=int_or_str,
     help='input device (numeric ID or substring)')
@@ -37,10 +53,7 @@ def int_or_str(text):
 parser.add_argument(
     '-n', '--downsample', type=int, default=10, metavar='N',
     help='display every Nth sample (default: %(default)s)')
-parser.add_argument(
-    'channels', type=int, default=[1], nargs='*', metavar='CHANNEL',
-    help='input channels to plot (default: the first)')
-args = parser.parse_args()
+args = parser.parse_args(remaining)
 if any(c < 1 for c in args.channels):
     parser.error('argument CHANNEL: must be >= 1')
 mapping = [c - 1 for c in args.channels]  # Channel numbers start with 1
@@ -77,14 +90,6 @@ def update_plot(frame):
 
 
 try:
-    from matplotlib.animation import FuncAnimation
-    import matplotlib.pyplot as plt
-    import numpy as np
-    import sounddevice as sd
-
-    if args.list_devices:
-        print(sd.query_devices())
-        parser.exit(0)
     if args.samplerate is None:
         device_info = sd.query_devices(args.device, 'input')
         args.samplerate = device_info['default_samplerate']

examples/rec_gui.py

@@ -82,7 +82,7 @@ class RecGui(tk.Tk):
     stream = None
 
     def __init__(self):
-        tk.Tk.__init__(self)
+        super().__init__()
 
         self.title('Recording GUI')