Initial version of the README file

diff --git a/Tools/audiopy/README b/Tools/audiopy/README
new file mode 100644 (file)
index 0000000..60d6768
--- /dev/null
+++ b/Tools/audiopy/README
@@ -0,0 +1,98 @@
+audiopy - a program to control the Solaris audio device.
+Author: Barry A. Warsaw <bwarsaw@python.org>
+
+Introduction
+
+    Audiopy is a program to control the Solaris audio device, allowing 
+    you to set both the input and output devices.  It can be run
+    either as a standalone command-line script, or as a Tkinter based
+    GUI application.
+
+    Note that your version of Python must have been built with the
+    sunaudiodev module enabled.  It is not enabled by default however!
+    You will need to edit your Modules/Setup file, uncomment the
+    sunaudiodev module spec line and rebuild Python.
+
+    Using audiopy, you can select one of three possible input devices:
+    the microphone, the line-in jack, or the CD in.  These choices are
+    mutually exclusive; you can only have one active input device at
+    any one time (this is enforced by the underlying device).  Some
+    input devices may not be supported on all Solaris machines.
+
+    You can also choose to enable any of the three possible output
+    devices: the headphone jack, the speakers, or the line-out jack.
+    You can enable any combination of these three devices.
+
+Running as a GUI
+
+    Simply start audiopy with no arguments to start it as a Tkinter
+    based GUI application.  It will pop up a window with two sections: 
+    the top portion contains three radio buttons indicating your
+    selected input device; the bottom portion contains three
+    checkboxes indicating your selected output devices.
+
+    Note the underlined characters in the button labels.  These
+    indicate keyboard accelerators so that pressing Alt+character you
+    can select that device.  For example, Alt-s toggles the Speaker
+    device.
+
+    Alt-q is also an accelerator for selecting Quit from the File
+    menu.
+
+    No unsupported devices will appear in the GUI.  When run as a GUI, 
+    audiopy monitors the audio device and automatically updates its
+    display if the state of the device is changed by some other
+    means.  In pre-Python 1.5.2 this is done by occasionally polling
+    the device, but in Python 1.5.2 no polling is necessary (you don't 
+    really need to know this, but I thought I'd plug 1.5.2 :-).
+    
+Running as a Command Line Program
+
+    You can run audiopy from the command line to select any
+    combination of input or output device, by using the command line
+    options.  Actually, any option forces audiopy to run as a command
+    line program and not display its GUI.
+
+    Options have the general form
+
+        --device[={0,1}]
+        -d[-{0,1}]
+
+    meaning there is both a long-form and short-form of the switch,
+    where `device' or `d' is one of the following:
+
+        (input)
+            microphone -- m
+            linein     -- i
+            cd         -- c
+
+        (output)
+            headphones -- p
+            speaker    -- s
+            lineout    -- o
+
+    When no value is given, the switch just toggles the specified
+    device.  With a value, 0 turns the device off and 1 turns the
+    device on.  Any other value is an error.
+
+    For example, to turn the speakers off, turn the headphones on, and 
+    toggle the cd input device, run audiopy from the command line like 
+    so:
+
+    % ./audiopy -s=0 -p=1 -c
+
+    Audiopy understands two other command line options:
+
+    --version
+    -v
+        Print the version number and exit
+
+    --help
+    -h
+        Print a help message and exit
+        
+
+\f
+Local Variables:
+indent-tabs-mode: nil
+End: