SoundWire Server for Raspberry Pi / Raspbian
--------------------------------------------

For installation instructions please see INSTALL.txt.
For license information please see license.txt and any additional license files.

1) Launch Pulse Audio Volume Control, needs the GUI running.
      pavucontrol &
The first time you use SoundWire you should have the GUI (window manager) 
running, if possible, so that you can configure Pulse Audio using pavucontrol. 
If pavucontrol doesn't start then it may not be installed, or it may not be in
your search path. You can also start it from your GUI. If you have no GUI you
should configure Pulse Audio as required manually if SoundWire doesn't work by
editing configuration files or using 'pacmd'.

2) Start the SoundWire Server application from the command line:
      SoundWireServer
When running the program in the current directory use: ./SoundWireServer 
To run in the background add an ampersand '&' at the end of the command.
If the program cannot start due to library errors please see INSTALL.txt. 
SoundWire Server will write various messages to the console. The IP address
(IPv4) of the server will be shown on the console, or several addresses if
there's more than one possibility. You should see the message "Audio capture
running". If not then there is a problem, check the console output for details.
To see the complete console output start SoundWireServer with the -verbose
option, this will display messages from PortAudio. Note that most error
messages generated by PortAudio do not indicate a problem. If you have
problems like audio dropouts or garbled audio see "Additional Notes" below
for troubleshooting ideas. If you have no GUI then skip ahead to step 6. 

3) In Pulse Audio Volume Control go to the Configuration tab, select Internal
Audio profile "Analog Stereo Output" or a similar name. If it exists you can
also use "Analog Stereo Duplex". Try different configuration profiles if you
have problems. If more than one audio device is shown under Configuration it may
help to set the ones you don't need to "Off". SoundWire can also work with no
audio hardware present, in which case the Configuration tab may be empty. 
You can simulate having no audio hardware by setting all profiles to "Off",
SoundWire should still work properly by monitoring Pulse's dummy output.

4) In Pulse Audio Volume Control go to the Recording tab. Find "SoundWireServer"
(it must be running). If a button is shown to change the input source select
"Monitor of Built-in Audio" or a similar name. To use other audio inputs such
as microphone make another selection as appropriate. If no selections are
possible then don't worry, it means there are no other input devices, or you've
selected the profile "Off" in the Configuration tab. If SoundWireServer doesn't
show up in the Recording tab see "Additional Notes" below.

5) Check the level meter (horizontal bar just below the volume controls in 
Pulse Audio Volume Control) for presence of audio and correct audio level. 
Adjust the level if necessary. SoundWire Server is now ready to use!
If you don't see the meter move you must correct your RPi system's audio
configuration and/or make your music player use Pulse Audio.

6) In the SoundWire Android app, press the connect button (coiled wire image).
If auto-locate doesn't work then enter your server's IP address.

Summary of Command Line Options
-------------------------------
-p NNNNN   Use the indicated network port number. The next port number 
           (one higher) is used for auto-locate. You can also specify the
           port number by setting environment variable SOUNDWIRE_SERVER_PORT. 
-verbose   Write all messages to the console, including those from PortAudio.

48 kHz Audio
------------
SoundWire supports both 44.1 kHz and 48 kHz sample rate audio. The server
displays the sample rate currently being used on the console. The default is
usually 44.1 kHz, but if PortAudio reports a device sample rate of 48 kHz then
SoundWire Server will use 48 kHz. To change the SoundWire Server sample rate, 
define environment variable SOUNDWIRE_SERVER_SAMPLE_RATE giving it the value
48000 or 44100. Make sure to configure the Pulse Audio sample rate to match,
otherwise sample rate conversion may be required, reducing audio quality and
placing extra load on the CPU. See 'man pulse-daemon.conf' and the 
'default-sample-rate' setting for more info. Ideally your audio source material,
Pulse Audio, and SoundWire Server should all use the same sample rate.

Additional Notes
----------------
If you have trouble connecting or the IP address indicated by SoundWireServer 
is wrong check the beginning of the console output for possible alternate IP 
addresses to try.

Pulse Audio Volume Control main volume / mute may affect audio transmitted to
your phone, adjust as needed. You can silence your RPi audio by turning the
main volume down but not all the way down in the Output Devices tab. You can 
also silence the RPi by selecting profile "Off" in the Pulse Audio Volume
Control Configuration tab. If audio transmitted to your phone is too quiet
and you've already turned your music player volume all the way up go to the
Pulse Audio Volume Control Recording tab and turn the volume for SoundWire
Server up. Turn it past 100% if needed. 

If you hear garbled audio or large numbers of dropouts from your RPi's regular 
audio output (e.g. headphone jack) after starting SoundWire Server this is due
to a bug in Pulse Audio or PortAudio. Try quitting SoundWire Server and 
restarting it several times (ctrl-C to quit if running in the foreground). It
may also help to temporarily change the sample rate as described above. If the 
problem persists you may have to select profile "Off" in the pavucontrol
Configuration tab as described above in step (3), which will mute the regular
audio output.  

If you experience audio dropouts at your Android device first try increasing the
audio buffer size in the SoundWire app. If this doesn't help the problem might
be caused by poor server performance or CPU load from other linux applications.
In this case we recommend using nice level -19 when starting SoundWire Server,
e.g.
    sudo nice --19 ./SoundWireServer
Should show up as nice level -19 (not 19) in 'top'. Close Pulse Audio Volume
Control when it's not needed since it always uses some CPU. You could also try
a negative nice level for your music player. 
Warning: On Raspberry Pi SoundWire Server may not be able to capture audio when 
running as root. In this case you should run as a regular user.

If SoundWireServer doesn't show up in the pavucontrol Recording tab make sure
SoundWireServer is currently running. If this is not the problem ensure that 
the pulseaudio server program is running before you start SoundWireServer:
type 'pulseaudio --start'. Check your Pulse Audio configuration (client.conf)
to ensure that the Pulse server is set to start automatically (autospawn = yes)
and ensure all programs use the same (local) server.

Please send any feedback to soundwire@georgielabs.net
