mumble-voip · toby63 · Dec 12, 2020 · Dec 12, 2020 · Dec 12, 2020 · Dec 12, 2020
diff --git a/README.md b/README.md
@@ -24,9 +24,12 @@ Vista may be supported, but we can't guarantee it.
 If you don't want to encounter potential issues, you may download Mumble 1.3.x,
 the last version to provide support for XP.
 
-The documentation of the project can be found on the [wiki](https://wiki.mumble.info/wiki/Main_Page). The
-[FAQ](https://wiki.mumble.info/wiki/FAQ/English) can also be found there.
+## Installation & Usage
+
+Take a look at the [Userguides](docs/user-guides/README.md).
 
+Further documentation of the project can be found on the [wiki](https://wiki.mumble.info/wiki/Main_Page). The
+[FAQ](https://wiki.mumble.info/wiki/FAQ/English) can also be found there.
 
 ## Contributing
 
@@ -36,82 +39,7 @@ We always welcome contributions to the project. If you have code that you would
 
 For information on how to build Mumble, checkout [the dedicated documentation](docs/dev/build-instructions/README.md).
 
-
 ## Reporting issues
 
 If you want to report a bug or create a feature-request, you can open a new issue (after you have checked that there is none already) on
 [GitHub](https://github.com/mumble-voip/mumble/issues/new/choose).
-
-
-## Windows
-
-### Running Mumble
-
-After installation, you should have a new Mumble folder in your
-Start Menu, from which you can start Mumble.
-
-### Running Murmur
-
-Doubleclick the Murmur icon to start murmur. There will be a small icon on your
-taskbar from which you can view the log.
-
-To set the superuser password, run murmur with the parameters `-supw <password>`.
-
-
-## MacOS
-
-### Running Mumble
-
-To install Mumble, drag the application from the downloaded
-disk image into your `/Applications` folder.
-
-### Running Murmur
-
-Murmur is distributed separately from the Mumble client on MacOS.
-It is called Static OS X Server and can be downloaded from the main webpage.
-
-Once downloaded it can be run in the same way as on any other Unix-like system.
-For more information please see the "Running Murmur" in the Linux/Unix section below.
-
-
-## Linux/Unix
-
-### Running Mumble
-
-If you have installed Mumble through your distributon's package
-repostory, you should be able to find Mumble in your start menu. No
-additional steps necessary.
-
-### Running Murmur
-
-Murmur should be run from the command line, so start a shell (command prompt)
-and go to wherever you installed Mumble. Run murmur as
-
-```
-murmurd [-supw <password>] [-ini <inifile>] [-fg] [v]
-
--supw   Set a new password for the user SuperUser, which is hardcoded to
-        bypass ACLs. Keep this password safe. Until you set a password,
-        the SuperUser is disabled. If you use this option, murmur will
-        set the password in the database and then exit.
-
--ini    Use an inifile other than murmur.ini, use this to run several instances
-        of murmur from the same directory. Make sure each instance is using
-        a separate database.
-
--fg     Run in the foreground, logging to standard output.
-
--v      More verbose logging.
-```
-
-### OpenGL Overlay
-
-The OpenGL overlay works by intercepting the call to switch buffers, and just
-before the buffer switch, we draw our nice GUI.
-
-To load a game with the overlay enabled, start the game like this:
-  LD_PRELOAD=/path/to/libmumble.so.1.1 gamename
-
-If you have Mumble installed through the binary packages, this can be done by
-simply typing:
-  mumble-overlay gamename
diff --git a/docs/user-guides/README.md b/docs/user-guides/README.md
@@ -0,0 +1,17 @@
+# Userguides for Mumble
+
+The following Userguides include information on installation, configuration and starting of Mumble and the Mumble Server (murmur).
+
+Choose the specific guide for your operating system:
+
+- [Userguide for Windows](userguide_windows.md)
+- [Userguide for Linux/Unix](userguide_linux.md)
+- [Userguide for macOS](userguide_macos.md)
+
+**Additional Guides:**
+
+- [Client Configuration Guide](client_config_guide.md)
+
+- [Server Configuration Guide](server_config_guide.md)
+
+- [OpenGL Overlay](overlay_openGL.md): A Mumble overlay for Games and other applications.
diff --git a/docs/user-guides/client_config_guide.md b/docs/user-guides/client_config_guide.md
@@ -0,0 +1,138 @@
+# Client Configuration Guide
+
+**Note:** For Installation and Starting of the Mumble Client, see the specific [Userguides](README.md) for your Operating System.
+
+<!-- Note: The pictures below are from a Mumble Client on Arch Linux, using the Dark Standard Theme, with already adjusted options. -->
+
+<!-- Todo -->
+<!--
+
+- Add Troubleshooting section or seperate guide?
+
+- Pictures or even Gifs could be added for better presentation
+
+![Alt-Text](/Path/to/picture.jpg)
+Here should be a picture
+
+--->
+
+
+<!--## Audio Wizard? -->
+
+<!--## Important Config Options -->
+
+<!-- 
+Topics suggested by Krzmbrzl: 
+- change theme between Lite and Dark mode, 
+- (done) echo cancellation, 
+- (almost done)transmission modes (VAD, PTT, continous),
+- shortcuts 
+
+-->
+
+## Configuration Menu
+
+<!-- where to find config options, add gif? -->
+
+Click on `Configure`->`Settings` or on the `gear`-symbol to open the Configuration Menu.
+
+*Tip: A small description of each option is displayed, when you hover your mouse pointer over it.*
+
+
+Below you find a list with the most important options:
+
+### Audio Input
+
+![Here should be a picture](pictures/audio-input.png)
+
+#### Interface
+
+##### Echo Cancellation
+
+If enabled, this will filter echo from the audio you send to others.
+
+You should usually enable it, because even when you use headsets, they might transmit undesired noise.
+
+Choose one of the following options:
+
+| Option: |	Description: | Usecases: |
+| --- | --- | --- |
+| Mixed echo cancellation | This is the basic Option: It will process all loudspeaker outputs bundled together.
+This is less accurate than the Multichannel option, but will also use less CPU. 	| Sufficient for setups with loudspeakers near to the microphone. |
+| Multichannel echo cancellation | Extended option: This will process all audio channels seperately, this is more accurate, but will result in higher CPU usage. |	For setups with (multiple) loudspeakers farther away from the microphone. |
+| Disabled | Disables echo cancellation (not recommended).  | You use a very good headset. Or you use external echo cancellation (for example via pulseaudio on Linux). Or echo cancellation is causing problems. |
+
+#### Transmission
+
+You can choose between three transmission modes:
+
+1. **Push to Talk**
+
+Your voice is only transmitted when you press a button.
+You can set the button in the `Shortcuts`-Menu (see below).
+
+![Here should be a picture](pictures/audio/push-to-talk.png)
+
+
+2. **Voice Activity**
+
+Your voice is only transmitted when a certain limit (loudness) is reached.
+All noise below the limit will be canceled.
+
+*Tip:* Use the `Audio Wizard`(`Configure`->`Audio Wizard`) to configure this option correctly.
+
+<!-- what is the difference between `Amplitude` and `Signal to noise` ? -->
+
+![Here should be a picture](pictures/audio/voice-activity.png)
+
+The coloured bar will show the noise-level when you speak, adjust `Silence below` (everything below the marker will not be transmitted) and `Speech above` (everything above the marker will be transmitted) accordingly.
+
+3. **Continuous**
+
+All Audio from your microphone will be transmitted continuously.
+
+**Note:** You should usually **not** use this option, as it can be very annoying for listeners.
+It is intended for special usecases (Music bots, Recording etc.) or when you use external tools for audio filtering instead.
+
+#### Compression
+
+**Quality:**
+Sets the maximum bandwidth the client will try to accomplish (it is limited by the Server you are connected to).
+Setting it higher will increase the audio quality.
+Only set it higher if your internet connection is good enough.
+<!-- maximum? -->
+
+<!-- Audio per packet: What does it do? Which is option is better for which scenario? -->
+
+#### Audio Processing 
+
+**RNNoise**
+
+RNNoise is a noise suppression library.
+It is intended to filter background noises from the audio that you send sent to other users.
+RNNoise uses a deep learning algorithm so it should work better than most regular filters.
+
+More information can be found on various websites:
+
+- [RNNoise GitHub repo](https://github.com/xiph/rnnoise)
+- [Article at Mozilla.org on RNNoise](https://hacks.mozilla.org/2017/09/rnnoise-deep-learning-noise-suppression/)
+
+
+
+### Shortcuts
+
+![Here should be a picture](pictures/shortcuts.png)
+
+<!-- insert gif? -->
+
+
+### Overlay
+
+If enabled, it implements a small window inside other applications (mostly Games), that will show the users and their status in your Mumble channel.
+
+![Here should be a picture](pictures/overlay.png)
+
+In tab <!-- slider? --> `Layout` you can adjust the position of the window.
+
+In tab `Overlay Exceptions` you can either specify a list of programs where the overlay is allowed (whitelist) or where the overlay is denied (blacklist).
+<!-- whitelist and blacklist are considered problematic nowadays, use alternatives? -->
diff --git a/docs/user-guides/overlay_openGL.md b/docs/user-guides/overlay_openGL.md
@@ -0,0 +1,12 @@
+### OpenGL Overlay
+
+<!-- Add a description -->
+
+The OpenGL overlay works by intercepting the call to switch buffers, and just before the buffer switch, we draw our nice GUI.
+
+To load a game with the overlay enabled, start the game like this:
+  LD_PRELOAD=/path/to/libmumble.so.1.1 gamename
+
+If you have Mumble installed through the binary packages, this can be done by
+simply typing:
+  mumble-overlay gamename
diff --git a/docs/user-guides/pictures/audio-input.png b/docs/user-guides/pictures/audio-input.png
diff --git a/docs/user-guides/pictures/audio-output.png b/docs/user-guides/pictures/audio-output.png
diff --git a/docs/user-guides/pictures/audio/push-to-talk.png b/docs/user-guides/pictures/audio/push-to-talk.png
diff --git a/docs/user-guides/pictures/audio/voice-activity.png b/docs/user-guides/pictures/audio/voice-activity.png
diff --git a/docs/user-guides/pictures/messages.png b/docs/user-guides/pictures/messages.png
diff --git a/docs/user-guides/pictures/network.png b/docs/user-guides/pictures/network.png
diff --git a/docs/user-guides/pictures/overlay.png b/docs/user-guides/pictures/overlay.png
diff --git a/docs/user-guides/pictures/plugins.png b/docs/user-guides/pictures/plugins.png
diff --git a/docs/user-guides/pictures/shortcuts.png b/docs/user-guides/pictures/shortcuts.png
diff --git a/docs/user-guides/pictures/userinteface.png b/docs/user-guides/pictures/userinteface.png
diff --git a/docs/user-guides/server_config_guide.md b/docs/user-guides/server_config_guide.md
@@ -0,0 +1,88 @@
+# Server Configuration Guide
+
+**Note:** For Installation and Starting of the Mumble Server, see the specific [Userguides](README.md) for your Operating System.
+
+The Configuration involves three steps:
+
+1. [Network configuration](#network-configuration)
+2. [Main configuration file](#main-configuration-file) (`murmur.ini`)
+3. [Administration with Mumble Client](#administration-with-mumble-client)
+
+<!-- In addition there are some other interesting topics:
+
+- Bots (Music Bots)
+- Web interfaces (outdated)
+- gRPC (remote control) (buggy, not ready)
+- WebRTC bridge
+
+-->
+
+## Network Configuration
+
+### Static vs. dynamic IP
+
+Users connect to your server via an IP or a Domainname (e.g. `mumble.example.com`).
+
+To make this work continuously, you either need a static IP (that means: the IP does not change) or in case you have a dynamic IP (it changes every few days), a Dynamic DNS Service (see below). Otherwise you would need to send the new IP to your users, every time the IP changes.
+
+*Tip:*
+
+* If your Mumble Server is running on a computer at your home, you will likely have a dynamic IP, thus you need a Dynamic DNS Service.
+* If your Mumble Server is running on a rented server at a Provider, you will in most cases have a static IP (already).
+
+#### Dynamic DNS Service 
+
+A Dynamic DNS Service will give you a subdomain (e.g. `mymumbleserver123.dyndns-example.com`) and/or a static IP which your users can use to connect to your server.
+
+In the background the service will route them to your dynamic IP.
+A special software running on your computer will tell the service whenever your dynamic IP changes.
+
+For more information and a list of services and software, take a look at the [Arch Wiki - Dynamic DNS](https://wiki.archlinux.org/index.php/Dynamic_DNS) for example.
+
+### Firewall & Ports
+
+In order for your users to be able to connect to your server, you need to allow incoming connections to a specific port that the Mumble Server uses. 
+
+The standard port is `64738` (recommended).
+You can also change it to every available port by editing the main configuration file (`murmur.ini`; see below).
+
+**Note:** Use a port that is not standardized (widely used by known programs/services), see e.g. [Wikipedia - List of Ports](https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers).
+
+Allow connections to the port for both protocols (TCP and UDP).
+
+Check and adjust your:
+
+- Computer's/Server's Firewall
+- (optional) Computer's Antivirus Program(s)
+- (for Home-Use) Router's Firewall
+
+<!-- more ports, for specific usecases? -->
+
+## Main configuration file
+
+The main server configuration file is called `murmur.ini` (it can be renamed though).
+
+You should find an example murmur.ini file in the program folders, but you can also look at the most recent **example murmur.ini (with explanations) on [Github](https://github.com/mumble-voip/mumble/blob/master/scripts/murmur.ini)**.
+
+Below is a list of the most important options:
+
+| Config Key: | Mandatory: | Default value: | Example: | Description: | Alternative(s): |
+| --- | --- | --- | --- | --- | --- |
+| welcometext= | no | - | "Welcome to our Server!" | the text will be send to every new user via chatmessage; if it's empty, no message will be send | welcometextfile= |
+| port= | yes | 64738 | - | sets the port (see above for details) | - |
+| serverpassword= | no | - | "supersecurepassword634%" | sets the Serverpassword; if it's empty, users can connect without a password. | - |
+| bandwidth= | yes | 72000 | - | sets the maximum bandwidth per user (in bits per second); setting it higher can increase the audio quality | - |
+| users= | yes | 100 | - | sets the maximum number of online users | - |
+| registerName= | no | - | "MyServer" | sets the Servername and the name of the main channel | - |
+| database= | no | empty (murmur.sqlite) | seconddatabase.sqlite | set this option, if you want to run multiple instances of murmur, so each instance has it's own database. Using sqlite is recommended. | Start multiple virtual servers (for now this is buggy (gRPC) or outdated (dbus; Ice)). See [Mumble Wiki - gRPC](https://wiki.mumble.info/wiki/GRPC) for details on setup etc. <!-- Ice and dbus [Mumble Wiki - Remote server control](https://wiki.mumble.info/wiki/Murmurguide#Remote_Controlling_the_Server) --> |
+
+For all available options and explanations, take a look at [Mumble Wiki - Murmur.ini](https://wiki.mumble.info/wiki/Murmur.ini).
+
+## Administration with Mumble Client
+
+- Use the Mumble client GUI for administration
+
+<!-- 1. Promote a normal User to be admin -->
+
+<!-- Channel creation, General Configuration, ACL and Groups -->
+