DOC: Add sine example

Closes #189.

Author: mgeier

doc/examples.rst

@@ -15,6 +15,13 @@ Play a Very Long Sound File
 
 .. literalinclude:: ../examples/play_long_file.py
 
+Play a Sine Signal
+------------------
+
+:download:`play_sine.py <../examples/play_sine.py>`
+
+.. literalinclude:: ../examples/play_sine.py
+
 Input to Output Pass-Through
 ----------------------------
 

examples/play_sine.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Play a sine signal."""
+import argparse
+import sys
+
+
+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(
+    '-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)')
+parser.add_argument(
+    'frequency', nargs='?', metavar='FREQUENCY', type=float, default=500,
+    help='frequency in Hz (default: %(default)s)')
+parser.add_argument(
+    '-a', '--amplitude', type=float, default=0.2,
+    help='amplitude (default: %(default)s)')
+args = parser.parse_args()
+
+try:
+    import numpy as np
+    import sounddevice as sd
+
+    if args.list_devices:
+        print(sd.query_devices())
+        parser.exit(0)
+
+    samplerate = sd.query_devices(args.device, 'output')['default_samplerate']
+    start_idx = 0
+
+    def callback(outdata, frames, time, status):
+        if status:
+            print(status, file=sys.stderr)
+        global start_idx
+        t = (start_idx + np.arange(frames)) / samplerate
+        t = t.reshape(-1, 1)
+        outdata[:] = args.amplitude * np.sin(2 * np.pi * args.frequency * t)
+        start_idx += frames
+
+    with sd.OutputStream(device=args.device, channels=1, callback=callback,
+                         samplerate=samplerate):
+        print('#' * 80)
+        print('press Return to quit')
+        print('#' * 80)
+        input()
+except Exception as e:
+    parser.exit(type(e).__name__ + ': ' + str(e))