SoundWire Server with GUI for for Raspberry Pi OS / Raspbian
------------------------------------------------------------

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

1) Start the SoundWire Server application. If the program cannot start due to
library errors (shown on console) please see INSTALL.txt. 
A few seconds after the program starts you should see the green message
"Audio capture running at 44.1 kHz" in the GUI, or similar console message. 
If not then there is a problem, check the console for details. To see the
complete console output start SoundWireServer from the command line with the
-verbose option, this will display messages from PortAudio. Note that most
error messages generated by PortAudio do not indicate a problem. See "Additional
Notes" below for some troubleshooting ideas.

2) Press the large button to launch Pulse Audio Volume Control. If it doesn't
start then it may not be installed, or pavucontrol may not be in your search
path. You can also start it from your GUI applications list, or from the command
line by typing pavucontrol. If you have no GUI (you run command-line only)
on a 32-bit OS then SoundWire Server version 2.1.2 for RPi is recommended. 
To continue with this version skip ahead to step 6 (you should configure 
Pulse Audio as required manually if SoundWire doesn't work by editing
 configuration files or using the 'pacmd' tool).

3) In Pulse Audio Volume Control go to the Configuration tab, select Built-in
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.
Note: If you are connecting through VNC with a virtual desktop then it's normal
for the Configuration tab to be empty.

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
-------------------------------
-nogui     Run SoundWire Server as a daemon (no GUI window, no X server 
           connection).
-verbose   Write all messages to the console, including those from PortAudio.
-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.
-b N.N.N.N Bind the server to a specific network interface by specifying its
           IP address. You can also say which network interface to bind to
           by setting environment variable SOUNDWIRE_SERVER_BINDADDR.
           Caution: This option should not normally be used, it can cause
           connection failures. Without this option SoundWire Server will
           bind to all available interfaces, allowing all connections.
-platform  This Qt5 option selects which graphics back-end to use. Don't use
           this option unless needed to fix Qt-related problems. See Qt5 docs. 

48 kHz Audio
------------
SoundWire supports both 44.1 kHz and 48 kHz sample rate audio. The server
displays the sample rate currently being used. 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. In some situations PortAudio will report an incorrect sample
rate. 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 (under Output Devices) may affect
audio transmitted to your phone, adjust as needed. You can silence your computer
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. 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.

If you get errors like "Audio capture failed" or the program hangs it may be 
caused by misbehaving audio drivers, or the pulseaudio server is not running.
For example if SoundWire Server hangs at startup and "Initializing PortAudio"
is the last message printed on the command line this indicates an audio driver
problem. Try disabling or disconnecting audio devices you don't need, e.g. HDMI
monitor with speakers (may need to reboot after disconnecting). You can check
which audio devices are present in the pavucontrol Configuration tab. 

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
