SoundWire Server for Linux
--------------------------

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 then 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 Duplex" or a similar name. If there is no Duplex
entry use "Analog Stereo Output". 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) and 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 you've selected the profile
"Off" in the Configuration tab, or there's no audio input hardware. If SoundWire
Server 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 Linux 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).
-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.
-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. 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. If you can't turn down main volume without losing SoundWire audio
on laptops plug something into the audio output (headphone) jack.
You may also be able to silence your computer 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 SoundWireServer up. Turn it past 100% if needed. Also check that you've
selected the "Monitor" record input for SoundWireServer in pavucontrol or you
may unintentionally hear audio from your microphone.

If you experience audio dropouts 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.

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
(c)2012-2020 GeorgieLabs and Georg Feil
