diff --git a/_data/en/navigation.yml b/_data/en/navigation.yml index 6b44e1401..6f8703e49 100644 --- a/_data/en/navigation.yml +++ b/_data/en/navigation.yml @@ -10,16 +10,16 @@ nav: url: /wiki/Installation-for-Macintosh - page: Linux url: /wiki/Installation-for-Linux - - page: Software Manual + - page: User Manual url: /wiki/Software-Manual + - page: FAQ + url: /wiki/FAQ - page: Troubleshooting url: /wiki/Client-Troubleshooting - title: More subfolderitems: - - page: Running a Server + - page: Server Administration url: /wiki/Running-a-Server - - page: Configuration - url: /wiki/Command-Line-Options - page: Tips & Tricks url: /wiki/Tips-Tricks-More - page: Community Knowledge Base diff --git a/assets/img/en-screenshots/bandwidth-diagram.png b/assets/img/en-screenshots/bandwidth-diagram.png index 9157ad994..b21358e67 100644 Binary files a/assets/img/en-screenshots/bandwidth-diagram.png and b/assets/img/en-screenshots/bandwidth-diagram.png differ diff --git a/assets/img/en-screenshots/linksys-port-forward.png b/assets/img/en-screenshots/linksys-port-forward.png deleted file mode 100644 index 948543a12..000000000 Binary files a/assets/img/en-screenshots/linksys-port-forward.png and /dev/null differ diff --git a/wiki/en/Central-Servers.md b/wiki/en/Central-Servers.md deleted file mode 100644 index 52484c598..000000000 --- a/wiki/en/Central-Servers.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: redirect -redirect: "/wiki/Directory-Servers" -lang: "en" -permalink: "/wiki/Central-Servers" -category: "hidden" ---- diff --git a/wiki/en/Choosing-a-Server-Type.md b/wiki/en/Choosing-a-Server-Type.md index 491c31033..d0188dcd2 100644 --- a/wiki/en/Choosing-a-Server-Type.md +++ b/wiki/en/Choosing-a-Server-Type.md @@ -1,65 +1,8 @@ --- -layout: wiki -title: "Choosing a Server Type" +layout: redirect +redirect: "/wiki/Running-a-Server" lang: "en" permalink: "/wiki/Choosing-a-Server-Type" +category: "hidden" --- -{% include breadcrumb.html root="More" branch1="Running a Server" branch1-url="Running-a-Server" %} - -# Server Types - -You can run your server in one of three "modes" (either at home or on a 3rd party host): - -### 1. Public - -Your server will be listed in the [directory server](Directory-Servers) list that clients use by default. Musicians can then discover and connect to your server. It is not necessary to run as a public server since many other people already run them. Just connect to one with low latency and start jamming. - -
Diagram of connections between clients within a Jamulus public server
- -This mode is activated by checking the "Register my server..." checkbox and (optionally) entering your server information. - -When running without the GUI ("headless"), the following would configure a public server: - -~~~ -Jamulus --nogui --server \ - --directoryserver genreServer:port \ - --serverinfo "yourServerName;yourCity;[country ID]" -~~~ - -**Note**: It is **not** necessary to port-forward or otherwise configure your router to run a public server. - -See also [Command Line Options](Command-Line-Options) for other parameters you can set. - - -### 2. Private - -This type of server will not be listed on a directory server list. You must give musicians your server address to connect their clients to. See [Running a Private Server](Running-a-Private-Server) for what needs to be done to enable others to connect to it. - -
Diagram of connections between clients within a Jamulus private server
- -This mode is activated by un-checking "Register my server...". - -When running without the GUI ("headless"), the following would configure a private server: - -```shell -Jamulus --nogui --server -``` - -See also [Command Line Options](Command-Line-Options) for other parameters you can set. - -### 3. Directory - -Configuring your server as a Directory Server need only be done under special circumstances (e.g. for online events or musical associations). Most people can ignore this type. - -To view servers listed by a custom directory server, musicians must enter the address in their client’s "Custom Directory Server" settings field. They will then see a Connection Setup list which is generated by that directory server. - -Normal server operators can also register with your custom directory server so their servers can show up in your server list by setting yours as their `--directoryserver` option. - -To run a server as a Directory Server, it should be configured with `--directoryserver localhost` (that is, specify itself as the directory server to query). - -#### Configuration points to note - -If you want to control which servers can register with your Directory Server, you can enable a whitelist with the `--listfilter` command line option. See the [command line options page](Command-Line-Options) for further information about this feature and other parameters you can set. - -When running a public Directory Server behind a NAT firewall on a private network, use the `--serverpublicip` option to specify the public IP address of the server(s) being listed by your Directory Server. This is necessary to allow clients on the public Internet to connect to them via NAT. Note that for the servers using this option, you will still need proper port forwarding in your router/firewall. diff --git a/wiki/en/Client-Troubleshooting.md b/wiki/en/Client-Troubleshooting.md index b83029379..2c00f65cf 100644 --- a/wiki/en/Client-Troubleshooting.md +++ b/wiki/en/Client-Troubleshooting.md @@ -6,6 +6,16 @@ permalink: "/wiki/Client-Troubleshooting" --- # Troubleshooting + {:.no_toc} + +
+ +Table of contents + +* TOC + {:toc} + +
### Don’t hear any sound/Others don’t hear you? diff --git a/wiki/en/Command-Line-Options.md b/wiki/en/Command-Line-Options.md index 311e76f28..94595fc42 100644 --- a/wiki/en/Command-Line-Options.md +++ b/wiki/en/Command-Line-Options.md @@ -1,68 +1,7 @@ --- -layout: wiki -title: "Command Line Options" +layout: redirect +redirect: "/wiki/Running-a-Server" lang: "en" permalink: "/wiki/Command-Line-Options" +category: "hidden" --- - -# Command Line Options - -Most common functions in Jamulus can be set using the GUI, but these and others can also be set using options given in a terminal window. Exactly how you do this will depend on your operating system. - -For example on Windows, to have a client use a specific settings file, right-click on the Jamulus shortcut and choose "Properties" > Target. Add the necessary arguments to Jamulus.exe: - -```shell -"C:\Program Files (x86)\Jamulus\Jamulus.exe" --inifile "C:\path\to\myinifile.ini" -``` - -For macOS, start a Terminal window and run Jamulus with the desired options like this: - -```shell - /Applications/Jamulus.app/Contents/MacOS/Jamulus --inifile "/path/to/myinifile.ini" -``` - -*** - -You can see all possible options your version supports by starting Jamulus with the `-h` option. - -_Note that the following options will not alter settings made in the GUI._ - -### General settings (client and server modes) - -| Short | Long name | `[...]` means optional parameter | Notes | -|---------|-------------------|--------------------------------------------------------------------------------------------------------------|----------------------------------------------------------| -| `-h,-?` | `--help` | This help text | | -| `-i` | `--inifile` | Set location of initialization file (overrides default) | Client (always) and server (with GUI) | -| `-n` | `--nogui` | Disable GUI | | -| `-p` | `--port` | Local UDP port number. Default is 22124 | | -| `-Q` | `--qos` | Sets the quality of service DSCP value. Default is 128. Disable with 0. | QoS is ignored by Windows, but see [Tips & Tricks](Tips-Tricks-More#quality-of-service) for how to apply it. | -| `-t` | `--notranslation` | Disable translations | | -| `-v` | `--version` | Output version information and exit | | - -### Server only - -| Short | Long name | `[...]` means optional parameter | Notes | -|-------|-------------------|----------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| -| `-d` | `--discononquit` | Disconnect all clients on quit | | -| `-e` | `--directoryserver` | Make the server public and sets its genre. See also `-o` | See [server types](Choosing-a-Server-Type#3-directory) | -| `-f` | `--listfilter` | Whitelist servers registering on the server list, format `ip address 1[;ip address 2]` | Directory servers only. [See note](Choosing-a-Server-Type#3-directory) | -| `-F` | `--fastupdate` | Reduces latency if clients connect with "Enable Small Network Buffers" option. Requires faster CPU to avoid dropouts, and more bandwidth to enabled clients. | | -| `-l` | `--log` | Enable logging, set path and file name | | -| `-L` | `--licence` | Show an agreement window before users can connect | | -| `-m` | `--htmlstatus` | Enable HTML status file, set path and file name | | -| `-o` | `--serverinfo` | Location details in the format: `[name];[city];[locale value]` (see [values](https://doc.qt.io/qt-5/qlocale.html#Country-enum)) | Public servers only | -| `-P` | `--delaypan` | Start with delay panning enabled | See [Server Setup](Server-Win-Mac#other-options) | -| `-R` | `--recording` | Include a writeable path where the files should be stored (in quotes if needed). | See [Server Setup](Server-Win-Mac#recording). | -| | `--norecord` | Disable recording when enabled by default by `-R` | | -| | `--serverbindip` | Specify the IP address to bind to | - -### Client only - -| Short | Long name | `[...]` means optional parameter | Notes | -|-------|-------------------|---------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------| -| `-M` | `--mutestream` | Starts Jamulus in muted state | | -| | `--mutemyown` | Mute me in my personal mix | Headless only | -| `-c` | `--connect` | Connect to given server address on startup, format `address[:port]` | | -| `-j` | `--nojackconnect` | Disable auto JACK connections | | -| | `--ctrlmidich` | MIDI controller channel to listen on, control number offset and consecutive CC numbers (channels). Format: `channel[;f*][;p*][;s*][;m*]` | See [Tips & Tricks](Tips-Tricks-More#using-ctrlmidich-for-midi-controllers) | -| | `--clientname` | Window title and JACK client name | | diff --git a/wiki/en/Directory-Servers.md b/wiki/en/Directory-Servers.md index 4c7c33245..f397a6f9e 100644 --- a/wiki/en/Directory-Servers.md +++ b/wiki/en/Directory-Servers.md @@ -1,30 +1,7 @@ --- -layout: wiki -title: "Directory Servers" +layout: redirect +redirect: "/wiki/Running-a-Server" lang: "en" permalink: "/wiki/Directory-Servers" +category: "hidden" --- - -{% include breadcrumb.html root="More" branch1="Running a Server" branch1-url="Running-a-Server" %} - -# Public Server Registration - -Because there is a limit of 150 servers per directory server, you need to select which directory server you want to advertise your server on. Select a genre if you intend to limit players to that style (players can then see your server in their genre list). - -When you start a public server, you will see a message saying whether your server has been successfully listed or not. If not, and you leave your server running, it will keep trying to register until a free slot becomes available. - - -## Headless servers - -Set directory (genre) server using the `--directoryserver` (`-e`) option as follows: - - -| Genre | Server address | -|-----------|------------------| -|**Any Genre 1** |`anygenre1.jamulus.io:22124`| -|**Any Genre 2** |`anygenre2.jamulus.io:22224`| -|**Any Genre 3** |`anygenre3.jamulus.io:22624`| -|**Genre Rock** |`rock.jamulus.io:22424`| -|**Genre Jazz** |`jazz.jamulus.io:22324`| -|**Genre Classical/Folk** |`classical.jamulus.io:22524`| -|**Genre Choral/Barbershop** |`choral.jamulus.io:22724`| diff --git a/wiki/en/FAQ.md b/wiki/en/FAQ.md index 89bd7648c..9009cbd19 100644 --- a/wiki/en/FAQ.md +++ b/wiki/en/FAQ.md @@ -6,8 +6,18 @@ permalink: "/wiki/FAQ" --- # Jamulus FAQ + {:.no_toc} -This is an overview of common questions. For common problems and their solutions, see the [Troubleshooting](/wiki/Client-Troubleshooting) page. +
+ +Table of contents + +* TOC + {:toc} + +
+ +**For common problems and their solutions when using Jamulus, see the [Troubleshooting](/wiki/Client-Troubleshooting) page.** ### Is there a metronome, synchronization, or some other way of keeping in time? @@ -16,7 +26,7 @@ No. Musicians on a Jamulus server simply play in real time time together as they ### How do I know if I can join a server? Are there rules? -In general, if somebody sets up a public server, then [by definition](/wiki/Choosing-a-Server-Type) they accept that anyone can play on it. Jamulus has no password protection or other authentication mechanisms. However, some servers may state their policies in the welcome message you will see in the chat window. +In general, if somebody sets up a public server they accept that anyone can play on it. Jamulus has no password protection or other authentication mechanisms. However, some servers may state their policies in the welcome message you will see in the chat window. You can also set up a private server on Jamulus and give others your address to connect to that. Have a look at [this page for more information](/wiki/Running-a-Server). @@ -34,7 +44,7 @@ Of course, if you are playing an acoustic instrument, or are a singer, it will b ### Do I need a fast Internet connection? -For most people on standard broadband (e.g. 10 Mbit/s down and 1 Mbit/s up) you will have no problems. For those running servers at home, depending on how many people join, you may encounter issues if your upstream bandwidth is lower than about 5 Mbit/s. [More information on network requirements here](/wiki/Network-Requirements). +For most people on standard broadband (e.g. 10 Mbit/s down and 1 Mbit/s up) you will have no problems. For those running servers at home, depending on how many people join, you may encounter issues if your upstream bandwidth is lower than about 5 Mbit/s. ### Do I need to run a server? @@ -50,3 +60,14 @@ Jamulus works on the client-server principle. Everybody’s audio is sent to a s ### Why doesn't Jamulus provide video support? Adding video support adds a lot of complexity. You can use other software like Jitsi or Zoom if you want to see others when playing (or have an "audience"), but the video will be significantly behind the Jamulus audio. + + +## Server FAQ + +### Why do public servers not need port forwarding? + +Normally, network address translation (NAT) firewalls prevent incoming requests initiated from outside the local network. Inbound traffic is only possible for packets relating to an outbound request (strictly speaking, “related” and “established” packets to an initial outbound connection). In public server mode, when your Jamulus server connects to a Directory Server it of course initiates an outbound connection. From then on, the Directory Server sends (established/related) connection “pings” (not ICMP pings) to your server at regular intervals to keep the relevant NAT port(s) open on your router/firewall. + +However, in private mode, clients have to **initiate** connections into the server’s network. NAT firewalls prevent this, so you need to tell them to allow incoming connection requests on the Jamulus port using port forwarding. + + diff --git a/wiki/en/Network-Requirements.md b/wiki/en/Network-Requirements.md index f68f0d744..7bc3d082f 100644 --- a/wiki/en/Network-Requirements.md +++ b/wiki/en/Network-Requirements.md @@ -1,38 +1,7 @@ --- -layout: wiki -title: "Quality, Delay and Bandwidth" +layout: redirect +redirect: "/wiki/Running-a-Server" lang: "en" permalink: "/wiki/Network-Requirements" +category: "hidden" --- - -{% include breadcrumb.html root="More" branch1="Running a Server" branch1-url="Running-a-Server" %} - -# Network Requirements - -## Audio bandwidth - -The audio settings have an impact on the required network bandwidth. The table below summarises network requirements with respect to the configuration of: -* Channels : stereo/mono -* Quality : high/medium/low -* Audio buffer duration : 2.67 ms, 5.33 ms, 10.67 ms, 21.33 ms - -With the following units -* ms : milliseconds -* Kbit/s : Kilo-bits per second (Reminder : 1 Mbit/s = 1024 Kbit/s, 1 KByte/s = 8 Kbit/s) -* Mbit/s : Mega-bits per second - -| Channels | Quality | Bandwidth (for buffer : 2.67 ms) | Bandwidth (for buffer : 5.33 ms) | Bandwidth (for buffer : 10.67 ms) | Bandwidth (for buffer : 21.33 ms) | -| --------- | ------ | -------- | -------- | -------- | -------- | -| Stereo | High | 894 Kbit/s | 657 Kbit/s | 541 Kbit/s | 483 Kbit/s | -| Stereo | Medium | 672 Kbit/s | 444 Kbit/s | 328 Kbit/s | 270 Kbit/s | -| Stereo | Low | 606 Kbit/s | 372 Kbit/s | 256 Kbit/s | 198 Kbit/s | -| Mono | High | 672 Kbit/s | 444 Kbit/s | 328 Kbit/s | 270 Kbit/s | -| Mono | Medium | 594 Kbit/s | 366 Kbit/s | 250 Kbit/s | 192 Kbit/s | -| Mono | Low | 534 Kbit/s | 306 Kbit/s | 190 Kbit/s | 132 Kbit/s | - -## Network bandwidth - -There is one upstream (musician sending to the server) and one downstream (server sending back the mix to the musician) -
A diagram of Jamulus network bandwidths from different audio qualities ranging from low to high
- -Note also that mean ADSL2 transfer rate is 10 Mbit/s for downstream and 1 Mbit/s for upstream. The actual performance depends on distance to the provider, which may [theoretically range from 24 Mbit/s at 0.3 km to 1.5 Mbit/s at 5.2 km](https://en.wikipedia.org/wiki/Asymmetric_digital_subscriber_line) for download rate. diff --git a/wiki/en/QOS-Windows.md b/wiki/en/QOS-Windows.md new file mode 100644 index 000000000..ac38f4e36 --- /dev/null +++ b/wiki/en/QOS-Windows.md @@ -0,0 +1,33 @@ + +[comment]: # (This is an include file for use in multiple documents) + +# Quality of Service (QoS) + +Jamulus uses DSCP/CS4 opportunistically to deal with buffer bloat, and uses a default DSCP/CS4 value of 128 (or 0x80). This is compatible with IPv4 and IPv6. Other values can be set using the -Q option, eg -Q [0..255] (where 0 disables QoS). If you want to explore the effect of non-default settings, see RFC4594. However, most people will have no need to do this. + +## Use of QoS on Windows + +Jamulus's QoS settings (including the default) have no effect on Windows because the operating system ignores them. To enable it, you must follow these instructions. Note also that you may need to repeat this procedure every time Jamulus is updated. + +In Search box beside Start menu Type: Local Group Policy Editor (enter)
+In new window, (click) on the menu icon to display the Actions third panel
+Looking at the first panel of the Local Group Policy Editor
+ Local Computer Policy
+  Computer Configuration
+   Windows Settings
+    Policy-based QoS (click)
+Looking at the third panel (Actions) of the Local Group Policy Editor
+ Policy-based QoS
+  More Actions
+   Create new Policy (click)
+    Policy Name: Jamulus
+    Specify DSCP value: 32
+    Next
+    This QoS policy applies Only to applications with name Jamulus.exe
+    Next
+    Next
+    UDP
+    Finish
+ +(Notice Jamulus policy in center panel may be edited) + diff --git a/wiki/en/Running-a-Private-Server.md b/wiki/en/Running-a-Private-Server.md index 9623161fd..535b32da9 100644 --- a/wiki/en/Running-a-Private-Server.md +++ b/wiki/en/Running-a-Private-Server.md @@ -1,56 +1,7 @@ --- -layout: wiki -title: "Running a Private Server" +layout: redirect +redirect: "/wiki/Running-a-Server" lang: "en" permalink: "/wiki/Running-a-Private-Server" +category: "hidden" --- - -{% include breadcrumb.html root="Using Jamulus" branch1="Running a Server" branch1-url="Running-a-Server" %} - -# Running a Private Server - -**_Please ensure you have read the [server overview](Running-a-Server)_** - -This guide assumes you will be running a private server on your home network, but some of the issues here may also apply to those running on cloud hosts (e.g. Amazon EC2). - -It is highly recommended to test your server in **public mode first** so as to narrow down any subsequent problems in private mode. - -## Operating a private server behind a home network router - -### Port forwarding - -To run a private server, you need to set up port forwarding on your router. _(If you are curious about why you need to do this for private but not public servers, see [this footnote](#footnote-for-geeks).)_ - -Normally, people from outside your home network cannot see things inside it. So if you want to operate a Jamulus server at home, you need to open a hole in your router to let Jamulus clients connect to it. - -**The default port for the current version of Jamulus is UDP (not TCP) port 22124.** - -The exact setup of port forwarding differs for every router. Here's an example of the port forwarding settings in a Linksys router: - -
Image of a Linksys router's port forwarding settings
- -For help see [portforward.com](https://portforward.com). - -Once you have your router set up, you can get your external (WAN) IP address e.g. by [using Google](https://www.google.com/search?q=what+is+my+ip). Give this address to your friends so they can connect to your server (_but see also the note on dynamic DNS below_). You yourself have to connect to your own computer instead, since your computer runs the server. Therefore **only you** need to connect to `127.0.0.1`. - -### Points to note - -* You do not need to open a port range as shown in the example above as long as you want to start only one instance of the Jamulus server on the same machine. - -* If using a different port than the default port (22124) you have to enter the port number after the server name or IP address separated by a colon in the Jamulus client (e.g. jamulus.example.org:22120). - -* See also this excellent [guide to running a private server](https://www.facebook.com/notes/jamulus-online-musicianssingers-jamming/how-to-create-a-private-server-for-band-rehearsals/508642543044030/) by [Simon Tomlinson](https://www.facebook.com/simon.james.tomlinson?eid=ARBQoY3KcZAtS3pGdLJuqvQTeRSOo4gHdQZT7nNzOt1oPMGgZ4_3GERe-rOyH5PxsSHVYYXjWwcqd71a) on Facebook. - -## Dynamic DNS and why you will probably need it - -Most domestic Internet connections will change their IP address after a period (hours, days or weeks). To make it easier for people to connect to you, you may therefore also want set up a dynamic DNS address. You can do this on [the machine](https://www.online-tech-tips.com/computer-tips/ddns-dynamic-dns-service/) that you are running the Jamulus server on, or preferably your router [may support it](https://www.noip.com/support/knowledgebase/how-to-configure-ddns-in-router/). - -Note also that your home router may also change the IP address of the machine that you are running your server on. In which case you may need either to give that machine a static IP in the router's DHCP configuration, or simply port forward to all the addresses in your LAN. - -## Footnote for geeks - -One of the many features of Jamulus that make it orgasmically wonderful is the fact that you can set up a server in seconds. But why do public servers not need port forwarding to do this? - -Normally, network address translation (NAT) firewalls prevent incoming requests initiated from outside the local network. Inbound traffic is only possible for packets _relating to an outbound request_ (strictly speaking, "related" and "established" packets to an initial outbound connection). In public mode, when your Jamulus server connects to a Directory Server it of course initiates an outbound connection. From then on, the Directory Server sends (established/related) connection "pings" (not ICMP pings) to your server at regular intervals to keep the relevant NAT port(s) open on your router/firewall. - -However, in private mode clients have to _initiate_ connections into the server's network. NAT firewalls prevent this, so you need to tell them to allow incoming connection requests on the Jamulus port using port forwarding. diff --git a/wiki/en/Running-a-Server.md b/wiki/en/Running-a-Server.md index 17872dc80..9fbfac923 100644 --- a/wiki/en/Running-a-Server.md +++ b/wiki/en/Running-a-Server.md @@ -5,41 +5,40 @@ lang: "en" permalink: "/wiki/Running-a-Server" --- -# Running a Server +# Server Administration Manual + {:.no_toc} -## Do I need to run a server to use Jamulus? +
-NO. - {: .doubletextsize .red } +Table of contents +* TOC + {:toc} -You can just choose somebody else's server from your list and get going. +
-**Don't want strangers interrupting?** Once you and your friends are connected to a public server, press the "solo" buttons on the musicians each of you want to play with. Anyone you don't solo will see a "muted" icon on your fader. And you won't hear them. -## That sounds too easy. -If you really want to run a server, it's **very important** that you read and understand what type of server you want to run. +## Do I need to run a server? -
- Read about server types -
+The short answer is **no**. For various reasons, you should try to use other people's servers, at least at first while getting your sound set up with the Jamulus client. -... then come back here. +Note that you can have a "private" session with other people on a Public Server by simply soloing each other. You will then not be able to hear anyone else if they enter your server. ### Speed and latency -**_The capability of the server itself (and the network it's on) is NOT the main determinant of the quality of a Jamulus session!_** +Many people attribute problems to the server that are in fact problems with the _client_. Much depends on the clients' hard/software setup, the networks that _they_ are on, and whether they are sticking to [Rule Number One](Client-Troubleshooting#you-all-sound-ok-but-its-difficult-to-keep-together). -Many people attribute problems to the server that are in fact problems with the _client_. Much depends on the clients' [hardware](Hardware-Setup), the networks that _they_ are on, and whether they are sticking to [Rule Number One](Getting-Started#having-trouble-cant-keep-in-time). There is therefore no guarantee that you will achieve lower latency or better overall performance by having your own server. +**_The capability of the server itself (and the network it's on) is NOT the main determinant of the quality of a Jamulus session!_** -If you plan to be playing regularly with the same people, **you are strongly advised** to first make sure that each member of the group is set up to use Jamulus properly. Do this by finding a public server with a reasonable ping time for all of you (20 ms or less perhaps), all connect to that and work to fix any individual issues (verifying that they can [follow Rule Number One](Getting-Started#having-trouble-cant-keep-in-time) in particular). Use the solo technique above to prevent being interrupted if needed. +If you plan to be playing regularly with the same people, **you are strongly advised** to first make sure that each member of the group is set up to use Jamulus properly. Do this by finding a Public Server with a reasonable ping time for all of you (20 ms or less perhaps), all connect to that and work to fix any individual issues (verifying that they can [follow Rule Number One](Client-Troubleshooting#you-all-sound-ok-but-its-difficult-to-keep-together) in particular). Use the solo technique above to prevent being interrupted if needed. Once any issues with musicians have been solved in this way, you can then investigate hosting your own server either at home or on a cloud host such as Amazon, which may result in better latency than servers run at home. For example, [see this guide](https://www.facebook.com/notes/jamulus-worldjam/howto-idiots-guide-to-installing-or-upgrading-a-jamulus-server-on-amazon-aws-lig/818091045662521/) for using AWS Lightsail, by Jamulus user [Simon Tomlinson](https://www.facebook.com/simon.james.tomlinson?eid=ARBQoY3KcZAtS3pGdLJuqvQTeRSOo4gHdQZT7nNzOt1oPMGgZ4_3GERe-rOyH5PxsSHVYYXjWwcqd71a) (_Facebook_) ### Bandwidth – do you have enough? -A typical jam might have 4 people, for which you would need 200 Kbit/s * 4 = 800 Kbit/s (0.8 Mbit/s) up and down. So if you have a 10 Mbit/s down and 1 Mbit/s up broadband connection, **you may start running out of bandwidth if a fifth player joins**, particularly if other musicians choose settings that increase their usage. You may want to [check that you have enough speed](https://fast.com) for that. [Read more about bandwidth use](Network-Requirements) at different quality settings. +Unless you plan on hosting more than about 5 players on a slower-speed home connection (eg 10 Mbit/s down and 1 Mbit/s up), then you are unlikely to run out of bandwidth. You can read more about network requirements at different quality settings later in this document. + ### In general @@ -49,22 +48,226 @@ A typical jam might have 4 people, for which you would need 200 Kbit/s * 4 = 800 - Running a server may require you to adjust any firewalls running on or outside of your machine or cloud host. -- Running a **private server at home** (but not a public one) will require you to [port forward](Running-a-Private-Server) on your router. +- Running a Private Server at home will require you to [port forward](#running-a-private-server) on your router. When running a Private Server, port forwarding should not be necessary in most cases, but it's advisable to do so because some networks may not work properly with Jamulus in its default mode. - Jamulus doesn't currently support IPv6 -## All OK? Get set up! +# Server Types + +You can run your server in one of three "modes" (either at home or on a 3rd party host): + +### 1. Public + +Use this mode when you want anyone to join your server, whoever they are. + +Your server will be listed in the Directory that clients use by default. Musicians can then discover and connect to your server. + +
+ Diagram of connections between clients within a Jamulus Public Server +
How Public Servers work
+
+ + + +### 2. Private + +This is the default when starting a server for the first time. Private Servers are not listed by Directories, so only musicians who know your server's address to will be able to connect to it. This is useful because Jamulus does not (in any server mode) let you control who can connect to a server. + + +
+ Diagram of connections between clients within a Jamulus Private Server +
How Private Servers work
+
+ + + +### 3. Directory + +For when you want to run a number of Private Servers, possibly also behind a firewall or on a LAN. Examples include online events, music associations, sectional rehearsals or music lessons for schools. + +To view servers listed by a custom Directory Server, musicians must enter the address in their client’s "Custom Directory Server" settings field. They will then see a Connection Setup list which is generated by your Directory. + +Up to 150 servers can then register with your Directory by setting your Directory address in their `--directoryserver` option at startup. + +To run a server as a Directory, it should be configured with `--directoryserver localhost` (that is, making itself the Directory to query for servers). + +#### Points to note about Directories + +- If you want to control which servers can register with your Directory, you can enable a whitelist with the `--listfilter` command line option. See the section on command line options later in this document. + +- When running a public Directory Server behind a NAT firewall on a private network, use the `--serverpublicip` option to specify the public IP address of the server(s) being listed by your Directory. This is necessary to allow clients on the public Internet to connect to them via NAT. Note that for the servers using this option, you will still need proper port forwarding in your router/firewall. + + +# Bandwidth use + +## Audio bandwidth + +The audio settings have an impact on the required network bandwidth. The table below summarises network requirements with respect to the configuration of: +* Channels : stereo/mono +* Quality : high/medium/low +* Audio buffer duration : 2.67 ms, 5.33 ms, 10.67 ms, 21.33 ms + +With the following units +* ms : milliseconds +* Kbit/s : Kilo-bits per second (Reminder : 1 Mbit/s = 1024 Kbit/s, 1 KByte/s = 8 Kbit/s) +* Mbit/s : Mega-bits per second + +| Channels | Quality | Bandwidth (for buffer : 2.67 ms) | Bandwidth (for buffer : 5.33 ms) | Bandwidth (for buffer : 10.67 ms) | Bandwidth (for buffer : 21.33 ms) | +| --------- | ------ | -------- | -------- | -------- | -------- | +| Stereo | High | 894 Kbit/s | 657 Kbit/s | 541 Kbit/s | 483 Kbit/s | +| Stereo | Medium | 672 Kbit/s | 444 Kbit/s | 328 Kbit/s | 270 Kbit/s | +| Stereo | Low | 606 Kbit/s | 372 Kbit/s | 256 Kbit/s | 198 Kbit/s | +| Mono | High | 672 Kbit/s | 444 Kbit/s | 328 Kbit/s | 270 Kbit/s 8| +| Mono | Medium | 594 Kbit/s | 366 Kbit/s | 250 Kbit/s | 192 Kbit/s | +| Mono | Low | 534 Kbit/s | 306 Kbit/s | 190 Kbit/s | 132 Kbit/s | + +## Network bandwidth + +There is one upstream (musician sending to the server) and one downstream (server sending back the mix to the musician) +
+ A diagram of Jamulus network bandwidths from different audio qualities ranging from low to high +
Calculate bandwidth use
+
+ +Note also that mean ADSL2 transfer rate is 10 Mbit/s for downstream and 1 Mbit/s for upstream. The actual performance depends on distance to the provider, which may [theoretically range from 24 Mbit/s at 0.3 km to 1.5 Mbit/s at 5.2 km](https://en.wikipedia.org/wiki/Asymmetric_digital_subscriber_line) for download rate. + + + +# Starting a server + + +* **Windows users** - Use the "Jamulus Server" icon in the Windows Start menu. + +* **macOS users** - Double-click the "Jamulus Server" icon in Applications (assuming you put the files from the install there as per [these instructions](Installation-for-Macintosh)). + +* **Linux users** + +Open a terminal window (`CTRL+ALT+t` on Ubuntu and related distros) and type `jamulus -s` + +Hit return and you should see the server control window. You can stop the server by closing the server window, or by using `CTRL+C` in the terminal. + + +## Server Setup + +
Image of the Jamulus server setup window
+ +### Make My Server Public + +By default, you will be running a Private Server and need to [read these instructions](#running-a-private-server) to have others connect to you in this mode. + +When making your server public, you should see a confirmation message saying whether your server has registered successfully. If not, and you leave your server running, it will keep trying to register until a free slot becomes available. + + +### Genre + +Because there is a limit of 150 servers per Directory, you need to select which Directory Server you want to advertise your server on. Select a genre if you intend to limit players to that style (players can then see your server in their genre list). This will make your server appear in the relevant server list for clients. + + +### My Server Info + +Type in the name, city and country so that other users can easily identify you. + +### Chat Welcome Message + +The text entered here appears to all users when they join the server (the chat window will open automatically for them). + +## Options + + +
Image of Jamulus server window options
+ +### Recording Directory + +This sets the path to where server's recording will be stored. With this path set, the "Enable Jam Recoder" function in the Server Setup tab will make recording start once the first person connects to the server, and stops when the last person leaves. Use the "New Recording" button to create a new sub-directory in which the recordings will be stored from then on. Note that Recordings are per track in [Audacity](https://www.audacityteam.org/) `.lof` format and [REAPER](https://en.wikipedia.org/wiki/REAPER) `.rpp`. Open the respective files to listen to them in those applications. + +**Note**: When your server is recording, clients will display a message that recording is on. + +### Delay panning + +This option uses small differences in sound arrival time between the two ears. It produces a stereo effect similar to natural human hearing when compared to normal "volume" panning. Note that to achieve the effect, all clients should be set to 'mono in / stereo out' (or to 'stereo', but only if transmitting a stereo signal). + +### Custom Directory Server Address + +Leave this field empty unless you need to list your server on a [private Directory](#3-directory) + + +### Start Minimised + +**Windows users** - If you want the server to start automatically on system start, enable the corresponding check box. + + + +# Running a Private Server + +It is highly recommended to test your server in **public mode first** so as to narrow down any subsequent problems in private mode. + +### Port forwarding + +Normally, people from outside your home network cannot see things inside it. So if you want to operate a Jamulus server at home, you need to open a hole in your router to let Jamulus clients connect to it. + +**The default port for the current version of Jamulus is UDP (not TCP) port 22124.** + +The exact setup of port forwarding differs for every router. For help see [portforward.com](https://portforward.com). + +Once you have your router set up, you can get your external (WAN) IP address e.g. by [using Google](https://www.google.com/search?q=what+is+my+ip). Give this address to your friends so they can connect to your server (_but see also the note on dynamic DNS below_). You yourself have to connect to your own computer instead, since your computer runs the server. Therefore **only you** need to connect to `127.0.0.1`. + +## Dynamic DNS and why you will probably need it + +Most domestic Internet connections will change their IP address after a period (hours, days or weeks). To make it easier for people to connect to you, you may therefore also want set up a dynamic DNS address. You can do this on [the machine](https://www.online-tech-tips.com/computer-tips/ddns-dynamic-dns-service/) that you are running the Jamulus server on, or preferably your router [may support it](https://www.noip.com/support/knowledgebase/how-to-configure-ddns-in-router/). + +Note also that your home router may also change the IP address of the machine that you are running your server on. In which case you may need either to give that machine a static IP in the router's DHCP configuration, or simply port forward to all the addresses in your LAN. + +# Running a headless Linux server + +Those wishing to run a server on a Linux cloud or other third party hosting platform should [read this guide](Server-Linux). + +# Command line options + +Most common functions in Jamulus can be set using the GUI, but these and others can also be set using options given in a terminal window. Exactly how you do this will depend on your operating system. + +For example on Windows, to use a specific settings file, right-click on the Jamulus shortcut and choose "Properties" > Target. Add the necessary arguments to Jamulus.exe: + +```shell +"C:\Program Files\Jamulus\Jamulus.exe" --serverbindip 192.168.0.100 +``` + +For macOS, start a Terminal window and run Jamulus with the desired options like this: + +```shell + /Applications/Jamulus.app/Contents/MacOS/Jamulus --serverbindip 192.168.0.100 +``` + +**Note**: Command-line options will not alter settings made in the GUI. + +- `-d` or `--discononquit` Disconnect all clients on quit. Normally, when a server is stopped or restarted, any clients that have not used their "Disconnect" buttons will re-establish connection when the server comes back up again. Using this option forces clients to manually re-establish their connections to the server. +- `-e` or `--directoryserver` Make the server public and sets its genre (see also `-o`). See [server types](#server-types) for further information. +- `-f` or `--listfilter` Whitelist servers registering on the server list, format `ip address 1[;ip address 2]` Directory Servers only. See [server types](#server-types) +- `-F` or `--fastupdate` Reduces latency if clients connect with "Enable Small Network Buffers" option. Requires faster CPU to avoid dropouts, and more bandwidth to enabled clients. +- `-l` or `--log` Enable logging, set path and file name +- `-L` or `--licence` Show an agreement window before users can connect +- `-m` or `--htmlstatus` Enable HTML status file, set path and file name +- `-o` or `--serverinfo` Location details in the format: `[name];[city];[locale value]` (see [values](https://doc.qt.io/qt-5/qlocale.html#Country-enum)) Public servers only +- `-P` or `--delaypan` Start with delay panning enabled See [notes](#delay-panning)) +- `-R` or `--recording` Include a writeable path where the files should be stored (in quotes if needed). See [Options](#options). +- `--norecord` Disable recording when enabled by default by `-R` +- `-s` or `--server` Start in server mode +- `--serverbindip` Specify the IP address to bind to +- `-T` or `--multithreading` Use multithreading to make better use of multi-core CPUs to support more clients +- `-u` or `--numchannels` Maximum number of channels (clients) +- `-w` or `--welcomemessage` Welcome message on connect +- `-z` or `--startminimized` Start minimizied +- `--serverpublicip` The public IP address of the server if connecting to a Directory behind the same NAT. See [Notes on Directory Servers](#points-to-note-about-directories) + +{% include_relative Shared-Commands.md %} + + +# Troubleshooting -
- For Windows or macOS users - For Linux users -
+Various problems can arise when setting up servers, and we generally ecourage people to use other people's (public) servers at first to isolate any issues that may in fact be due to client configuration. -If you want to run a server on a Raspberry Pi, have a look at the [guide for Raspberry Pi](/kb/2020/03/28/Server-Rpi.html) by fredsiva. +If you are having problems, [see this guide](Server-Troubleshooting). + -Server operators may also be interested in downloading [this set of useful tools](https://github.com/jamulussoftware/jamulus/tree/master/tools) from the Jamulus repository (clone the Git repo and also call `git submodule update --init`). -## Having problems? Got issues? -See the [Server Troubleshooting FAQ](Server-Troubleshooting) diff --git a/wiki/en/Server-Linux.md b/wiki/en/Server-Linux.md index f928e046b..1277287a1 100644 --- a/wiki/en/Server-Linux.md +++ b/wiki/en/Server-Linux.md @@ -1,74 +1,134 @@ --- layout: wiki -title: "Server Installation - Linux" +title: "Headless Linux Server Installation" lang: "en" permalink: "/wiki/Server-Linux" --- -{% include breadcrumb.html root="Using Jamulus" branch1="Running a Server" branch1-url="Running-a-Server" %} +{% include breadcrumb.html root="More" branch1="Server Administration" branch1-url="Running-a-Server" %} -# Server Installation - Linux +# Running a Headless Server -**_Please ensure you have read the [server overview](Running-a-Server)_** +The following is for running Jamulus as a "pure" server on **hardware without audio** (e.g. on a 3rd party/cloud host) and assumes Ubuntu/Debian distributions using systemd. - -## Running a server with a GUI on a desktop machine - -If you have installed the Jamulus client, you can run it in your chosen [server mode](Choosing-a-Server-Type) by running Jamulus with the `-s` option as follows: - -1. Open a terminal window (`CTRL+ALT+t` on Ubuntu and related distros). -1. Assuming Jamulus is in `/usr/local/bin`, type `Jamulus -s` - -Hit return and you should see the server control window. You can stop the server by closing the server window, or by using `CTRL+C` in the terminal. - -**To configure the server**, please refer to [the Windows & macOS instructions](Server-Win-Mac), and [Command Line Options](Command-Line-Options) for other parameters you can set. - -## Running a "headless" server - -The following is for running Jamulus as a "pure" server on **hardware without audio** (e.g. on a 3rd party/cloud host) and assumes Ubuntu/Debian distributions using systemd. We also have instructions for [Raspberry Pi](Server-Rpi). +If you want to run a server on a Raspberry Pi, you will need to [compile from source](https://github.com/jamulussoftware/jamulus/blob/master/COMPILING.md). See also this [guide for Raspberry Pi](/kb/2020/03/28/Server-Rpi.html) maintained by Jamulus user fredsiva. 1. Download the [latest headless .deb file]({{ site.download_root_link }}{{ site.download_file_names.deb-headless }}) 1. Update apt to make sure you have a current list of standard packages: `sudo apt update` 1. Install the Jamulus package: `sudo apt install ./{{ site.download_file_names.deb-headless }}` 1. Enable the headless server process via systemd: `sudo systemctl enable jamulus-headless` -1. Add your desired [command line options](Command-Line-Options) to the `ExecStart` line in the systemd service file in `/lib/systemd/system/jamulus-headless.service` (By default you will be running a private server). +1. Add your desired [command line options](Running-a-Server#command-line-options) to the `ExecStart` line in the systemd service file in `/lib/systemd/system/jamulus-headless.service` (By default you will be running a private server). 1. Reload the systemd files `sudo systemctl daemon-reload` and restart the headless server: `sudo systemctl restart jamulus-headless` -1. Check all is well with `service jamulus-headless status` (hit `q` to get back to the command prompt). +1. Check all is well with `systemctl status jamulus-headless` (hit `q` to get back to the command prompt). -## Notes +You may also be interested in downloading [this set of useful tools](https://github.com/jamulussoftware/jamulus/tree/master/tools) from the Jamulus repository (clone the Git repo and also call `git submodule update --init`). -You can control Jamulus with the `service` command. For example, to stop the server cleanly: +## Notes -`sudo service jamulus-headless stop` +You can control Jamulus with the `systemctl` command. For example, to stop the server cleanly: -### Viewing The Logs +`sudo systemctl stop jamulus-headless` -Jamulus will log to the system file if you left the `StandardOutput=journal` setting in the unit file. Logging to the system log is recommended, as the system will manage the log file for you - no need to come back and purge it later or worry about filling up your disk space. +### Running in public mode -To view the log, use `journalctl` (to exit press Ctrl-C). For example, to read the system log file, filtered for the Jamulus service: +The following minimum setup is required to [run a public server](Running-a-Server#server-types): -`journalctl -u jamulus-headless` +~~~ +jamulus --nogui --server \ + --directoryserver genreServer:port \ + --serverinfo "yourServerName;yourCity;[country ID]" +~~~ -For today’s entries: +**Note**: Semicolon and newline characters are not allowed in `--serverinfo` -`journalctl -u jamulus-headless --since today` +Set your Directory (genre) server using the `--directoryserver` (`-e`) option as follows: -For the last hour: -`journalctl -u jamulus-headless --since "1 hour ago"` +| Genre | Server address | +|-----------|------------------| +|**Any Genre 1** |`anygenre1.jamulus.io:22124`| +|**Any Genre 2** |`anygenre2.jamulus.io:22224`| +|**Any Genre 3** |`anygenre3.jamulus.io:22624`| +|**Genre Rock** |`rock.jamulus.io:22424`| +|**Genre Jazz** |`jazz.jamulus.io:22324`| +|**Genre Classical/Folk** |`classical.jamulus.io:22524`| +|**Genre Choral/Barbershop** |`choral.jamulus.io:22724`| -Filter the log to see connection messages for your Jamulus server: +### Viewing The Logs -`journalctl -u jamulus-headless | grep connected` +Jamulus will log to the system log file if you left the `StandardOutput=journal` setting in the unit file. -Follow (show on screen) Jamulus log messages as they occur: +To view the log, use `journalctl` (to exit press Ctrl-C). For example, to read the system log file, filtered for the Jamulus service: `journalctl -f -u jamulus-headless` + ### Upgrading To upgrade your server to a newer version, simply download a new .deb and re-install as step 3. ### Recording -See [this information](/wiki/Tips-Tricks-More#controlling-recordings-on-linux-headless-servers) on controlling recordings on headless servers. +When using the recording function with the `-R` command line option, if the server receives a SIGUSR1 signal during a re +cording, it will start a new recording in a new directory. SIGUSR2 will toggle recording enabled on/off. + +To send these signals using systemd, create the following two `.service` files in `/etc/systemd/system`, calling them something appropriate (e.g. `newRecording-Jamulus-serv +er.service`). + +**Note:** You will need to save recordings to a path _outside_ of the jamulus home directory, or remove `ProtectHome=true` from your systemd unit file (be aware that doing so is however a potential security risk). + +For turning recording on or off (depending on the current state): + +~~~ + [Unit] + Description=Toggle recording state of Jamulus server + Requisite=Jamulus-Server + + [Service] + Type=oneshot + ExecStart=/bin/systemctl kill -s SIGUSR2 Jamulus-Server +~~~ + +For starting a new recording: + +~~~ + [Unit] + Description=Start a new recording on Jamulus server + Requisite=Jamulus-Server + + [Service] + Type=oneshot + ExecStart=/bin/systemctl kill -s SIGUSR1 Jamulus-Server +~~~ + +_Note: The Jamulus service name in the `ExecStart` line needs to be the same as the `.service` file name you created when setting systemd to control your Jamulus server. So in this example it would be `Jamulus-Server.service`_ + +Run `sudo systemctl daemon-reload` to register them for first use. + +Now you can run these with the `service start` command, for example: + +`sudo service jamulusTogglerec start` (assuming you named your unit file `jamulusTogglerec.service`) + +You can see the result of these commands if you run `service jamulus status`, or by viewing the logs. + +## Making a server status page + +With the `-m` command line argument, server statistics can be generated to be put on a web page. + +Here is an example php script using the server status file to display the current server status on a html page (assuming the following command line argument to be used: `-m /var/www/stat1.dat`): + +~~~ + + +~~~ diff --git a/wiki/en/Server-Troubleshooting.md b/wiki/en/Server-Troubleshooting.md index fd105dccd..cea6178e5 100644 --- a/wiki/en/Server-Troubleshooting.md +++ b/wiki/en/Server-Troubleshooting.md @@ -5,15 +5,25 @@ lang: "en" permalink: "/wiki/Server-Troubleshooting" --- -{% include breadcrumb.html root="Using Jamulus" branch1="Running a Server" branch1-url="Running-a-Server" %} +{% include breadcrumb.html root="More" branch1="Server Administration" branch1-url="Running-a-Server" %} -# Troubleshooting +# Server Troubleshooting + {:.no_toc} + +
+ +Table of contents + +* TOC + {:toc} + +
## Servers - Public ### Why doesn't my server show up in the list? Why isn't it registering? -If you are registered OK (you can [see it here](https://explorer.jamulus.io/)) and you or your friends can't see your server, you may need to wait, or start your client with the `--showallservers` option and try connecting from there ([see this page](Command-Line-Options) on how to start your client with a config option). +If you are registered OK (you can [see it here](https://explorer.jamulus.io/)) and you or your friends can't see your server, you may need to wait, or start your client with the `--showallservers` option and try connecting from there ([see command line options](Software-Manual#command-line-options)) on how to start your client with a config option). If you are seeing a message that says the server is full, please [see this note](Directory-Servers) on Directory Servers. @@ -31,7 +41,7 @@ This should be your **public** IP address (find that with [Google](https://www.g ### What port numbers can I use? -Keep the default UDP ports. The actual default port is documented by the [command line](Command-Line-Options). At the time of writing this documentation, the port number is **22124**. +You can set your server to listen on a custom port with the `--port` option. If you you this, you will need to tell people which port to connect connect on. They will need to append the port number the the address of your server in the format `[serverAddress]:[portNumber]`. ### Is a private server a direct server without contact to the Jamulus Directory Server? diff --git a/wiki/en/Server-Win-Mac.md b/wiki/en/Server-Win-Mac.md index 91a3147ac..4426e79cb 100644 --- a/wiki/en/Server-Win-Mac.md +++ b/wiki/en/Server-Win-Mac.md @@ -1,71 +1,8 @@ --- -layout: wiki -title: "Server Installation - Windows and macOS" +layout: redirect +redirect: "/wiki/Running-a-Server" lang: "en" permalink: "/wiki/Server-Win-Mac" +category: "hidden" --- -{% include breadcrumb.html root="Using Jamulus" branch1="Running a Server" branch1-url="Running-a-Server" %} - -# Installation for Windows and macOS - - -**_Please ensure you have read the [server overview](Running-a-Server)_** - -* **Windows users** - Start the server using the entry for "Jamulus server" in the Windows start menu. - -* **macOS users** - Double-click the "Jamulus server" icon in Applications (assuming you put the files from the install there as per [these instructions](Installation-for-Macintosh)). - -* **Linux users** - Please refer to the [GUI server instructions](Server-Linux#running-a-server-with-the-gui). - -
Image of the Jamulus server setup window
- -### Public server setup - -1. On checking "Make My Server Public" you should see a confirmation message saying whether your server has registered successfully. - -1. Type in the name, city and country so that other users can easily identify you. - -1. Specify a music genre. This will make your server appear in the relevant server list for clients (see more [details on Directory Servers](Directory-Servers)). - -_The Chat Welcome Message appears to all users when they join the server (the chat window will open automatically for them)._ - -### Private server setup - -If you do not check "Make My Server Public", you will be running a private server and need to [read these instructions](Running-a-Private-Server). - -_If you want to **run a client on the same machine** you should **connect the client to `127.0.0.1`** for best performance. (Similarly, if you want to connect a client on another machine on your LAN, use the server's LAN IP address)._ - - -### Other options - -jamulus-server - -### Recording - -Turn on server recording by first setting the Recording Directory in the Options tab. Recording starts once the first person connects to the server, and stops when the last person leaves. Use the "New Recording" button to create a new sub-directory in which the recordings will be stored. Note that Recordings are per track in [Audacity](https://www.audacityteam.org/) `.lof` format and [REAPER](https://en.wikipedia.org/wiki/REAPER) `.rpp`. Open the respective files to listen to them in those applications. - -_Note: When your server is recording, clients will display a message that recording is on._ - -For headless servers: you can control the recording function [using these instructions](Server-Linux#controlling-recordings). - -### Delay panning - -This option uses small differences in sound arrival time between the two ears. It produces a stereo effect similar to natural human hearing when compared to normal "volume" panning. Note that to achieve the effect, all clients should be set to 'mono in / stereo out' (or to 'stereo', but only if transmitting a stereo signal). - -### Custom Central Server Address - - -
Image of Jamulus server window options
- -(Leave this field empty unless you need to list your server on a [private central server](Choosing-a-Server-Type#3-directory)) - - -**Windows users** - If you want the server to start automatically on system start, enable the corresponding check box. - -(Leave the "Custom Directory Server Address" field empty unless you need to list your server on a [private directory server](Choosing-a-Server-Type#3-directory)) - - -*** - -See also [Command Line Options](Command-Line-Options) for other parameters you can set. diff --git a/wiki/en/Shared-Commands.md b/wiki/en/Shared-Commands.md new file mode 100644 index 000000000..84f1128a4 --- /dev/null +++ b/wiki/en/Shared-Commands.md @@ -0,0 +1,11 @@ + +[comment]: # (This is an include file for use in multiple documents) + +- `-h` or `--help` Display help text +- `-i` or `--inifile` Set location of initialization file (overrides default) +- `-n` or `--nogui` Disable GUI (for use in headless mode) +- `-p` or `--port` Sets the local UDP port number. Default is 22124 +- `-Q` or `--qos` Sets the quality of service DSCP value. Default is 128. Disable with 0. QoS is ignored by Windows. To enable it, see +section below +- `-t` or `--notranslation` Disable UI language translations +- `-v` or `--version` Output version information and exit diff --git a/wiki/en/Software-Manual.md b/wiki/en/Software-Manual.md index 4b16f48bc..97d02ef7c 100644 --- a/wiki/en/Software-Manual.md +++ b/wiki/en/Software-Manual.md @@ -16,7 +16,7 @@ This manual documents the Jamulus client application for use by musicians and si * TOC {:toc} - + # Main Window @@ -38,7 +38,7 @@ This manual documents the Jamulus client application for use by musicians and si **Yellow** - A session is still possible but it may be harder to play -
Image of a green red symbol
+
Image of a green red symbol
**Red** - The delay is too large for jamming @@ -52,8 +52,8 @@ This manual documents the Jamulus client application for use by musicians and si ## Input -This shows the level of the two stereo channels for your audio input. -Make sure not to clip the input signal to avoid distortions of the audio signal (the LEDs will indicate clipping when it occurs). +Shows the level of the two stereo channels for your audio input. +Make sure not to clip the input signal to avoid distortions of your sound (the LEDs will indicate clipping when it occurs). ## Mute Myself button @@ -61,7 +61,7 @@ Cuts your audio stream to the server so that you will be able to hear yourself a ## Reverb effect -Reverb can be applied to one local mono audio channel or to both channels in stereo mode. +Adds reverb to your local mono audio channel, or to both channels in stereo mode. The mono channel selection and the reverberation level can be modified. For example, if a microphone signal is fed in to the right audio channel of the sound card and a reverb effect needs to be applied, set the channel selector to the right and move the fader upwards until the desired reverb level is reached. @@ -69,13 +69,13 @@ to the right and move the fader upwards until the desired reverb level is reache ## Chat -The chat text entered in that dialog is sent to -all connected clients. If a new chat message arrives and the Chat dialog is not already open, it will +Opens the chat window. Text entered is sent to +all connected clients. If a new chat message arrives and the Chat dialogue is not already open, it will open automatically for all clients. ## Connect/disconnect button -Opens a dialog where you can select a server to connect to. If you are connected, +Opens a dialogue where you can select a server to connect to. If you are connected, pressing this button will end the session.
Image of a server connection window
@@ -101,9 +101,19 @@ If you have set your Audio Channel to Stereo or Stereo Out in your Settings, you If you see a "mute" icon above a user, it means that person cannot hear you. Either they have muted you, soloed one or more users not including you, or have set your fader in their mix to zero. -Using the **Mute button** prevents users being heard in your local mix. Be aware that when you mute someone, they will see a "muted" icon above your fader to indicate that you cannot hear them. Note also that you will continue to see their VU meters moving if sound from the muted user is reaching the server. Your fader position for them is also unaffected. +### Grp button -The **Solo button** allows you to hear one or more users on their own. Those not soloed will be muted. Note also that those people who are not soloed will see a "muted" icon above your fader. +Defines a group of audio channels. Moving the fader of one member of the group moves the faders of all the others Up to 8 groups can be defined. + +### Mute button + +Prevents users being heard in your local mix. Be aware that when you mute someone, they will see a "muted" icon above your fader to indicate that you cannot hear them. Note also that you will continue to see their VU meters moving if sound from the muted user is reaching the server. Your fader position for them is also unaffected. + +Note that muting your **own** channel simply means you will not hear your signal from the server (and is not advised as it can lead to you becoming out of time with other players). This is therefore not the same as using "[Mute Myself](#mute-myself-button)". + +### Solo button + +Allows you to hear one or more users on their own. Those not soloed will be muted. Note also that those people who are not soloed will see a "muted" icon above your fader. Users are listed left to right in the order that they connect. You can change the sort order using the Edit option in the application menu. @@ -154,10 +164,14 @@ If the selected sound card device offers more than one input or output channel, and Output Channel Mapping_ settings are visible. For each Jamulus input/output channel (left and right channel) a different actual sound card channel can be selected. + ### Audio channels -Selects the number of audio channels to be used for communication between client and server. There are three modes -available: +Selects the number of audio channels to be used for communication between client and server. + +**Note**: It is preferable to run separate client instances per voice/instrument, with each client given its own ini file, rather than using this built-in mono pair to stereo mixer. + +There are three modes available: **Mono** and **Stereo** modes use one and two audio channels respectively. @@ -251,11 +265,48 @@ Increases the gain from your device. Use this if your device delivers a gain tha ### Feedback Protection -Attempts to detect audio feedback loops. Once detected, this feature will activate the "Mute Myself" button and show an explanation message to enable you to fix the problem. - +Attempts to detect audio feedback loops or loud noise in the first three seconds after you connected to a server. Once detected, this feature will show a message and activate the "Mute Myself" button to mute you in your own mix. ### Input Balance Controls the relative levels of the left and right local audio channels. For a mono signal it acts as a pan between the two channels. For example, if a microphone is connected to the right input channel and an instrument is connected to the left input channel which is much louder than the microphone, move the audio fader to increase the relative volume of the mic. + +# Menu commands + +### File > Load/Save Mixer Channels Setup + +You can save and restore the mix you have for your band rehearsals (fader, mute, pan, solo etc.) and load these any time (even while you are playing). Loading can also be done by drag/drop to the mixer window. + + +### Edit > Auto-Adjust All Faders + +Applies a one-off fader setting to each channel depending on its volume. Useful for large ensembles to get a reasonable overall mix, although individual adjustments might still be necessary. Best applied during a warm-up or a uniform part of the music piece. + +# Command Line Options + +Most common functions in Jamulus can be set using the GUI, but these and others can also be set using options given in a terminal window. Exactly how you do this will depend on your operating system. + +For example on Windows, to use a specific settings file, right-click on the Jamulus shortcut and choose "Properties" > Target. Add the necessary arguments to Jamulus.exe: + +```shell + "C:\Program Files\Jamulus\Jamulus.exe" --inifile "C:\path\to\myinifile.ini" +``` + +For macOS, start a Terminal window and run Jamulus with the desired options like this: + +```shell + /Applications/Jamulus.app/Contents/MacOS/Jamulus --inifile "/path/to/myinifile.ini" +``` + +**Note**: Command-line options will not alter settings made in the GUI. + +- `-M` or `--mutestream` Starts Jamulus in muted state +- `--mutemyown` Mute me in my personal mix ("headless" mode only) +- `-c` or `--connect` Connect to given server address on startup, format `address[:port]` +- `-j` or `--nojackconnect` Disable auto JACK connections +- `--ctrlmidich` MIDI controller channel to listen on, control number offset and consecutive CC numbers (channels). Format: `channel[;f*][;p*][;s*][;m*]` See [Tips & Tricks](Tips-Tricks-More#using-ctrlmidich-for-midi-controllers) +- `--clientname` Window title and JACK client name +{% include_relative Shared-Commands.md %} + diff --git a/wiki/en/Tips-Tricks-More.md b/wiki/en/Tips-Tricks-More.md index 55538e347..db3ee9f0e 100644 --- a/wiki/en/Tips-Tricks-More.md +++ b/wiki/en/Tips-Tricks-More.md @@ -6,6 +6,16 @@ permalink: "/wiki/Tips-Tricks-More" --- # Tips & Tricks + {:.no_toc} + +
+ +Table of contents + +* TOC + {:toc} + +
## Learning about remote band rehearsing @@ -27,32 +37,6 @@ Jamulus user [Rob Durkin](https://sourceforge.net/u/bentwrench/profile/) has wri Jamulus user [BTDT](https://sourceforge.net/u/btdt/profile/) has written a system called [305keepers](https://github.com/keepers305/Song-Sheet-Sharing-Web-Pages), a web application that allows a "Jam leader" to push song sheets (in PDF format) to "Jammers" in real time using standard web browsers. -## Making a server status page - -With the `-m` command line argument, server statistic information can be generated to be put on a web page. - -Here is an example php script using the server status file to display the current server status on a html page (assuming the following command line argument to be used: `-m /var/www/stat1.dat`): - -~~~ - - -~~~ - -## Saving and loading client mix states - -You can save and restore the mix you have for your band rehearsals (fader, mute, pan, solo etc.) and load these any time (even while you are playing). Do this with "File > Save Mixer Channels Setup" in your client and load them using "Load Mixer Channels Setup" (or drag/drop them to the mixer window). - ## Converting a public server to a private one on the fly You can run a public server long enough for your band to connect, then go private by simply unchecking the 'Make my server Public' box in the server GUI. Your band mates will still be connected to the server until they disconnect. (Thanks to [David Savinkoff](https://github.com/DavidSavinkoff) for this tip!) @@ -109,75 +93,3 @@ Fader strips in the mixer window are controlled in ascending order from left to Make sure you connect your MIDI device's output port to the Jamulus MIDI in port (QjackCtl (Linux), MIDI Studio (macOS) or whatever you use for managing connections). In Linux you will need to install and launch a2jmidid so your device shows up in the MIDI tab in Qjackctl. - -## Controlling recordings on Linux headless servers - -When using the [recording function](Server-Win-Mac#recording) with the `-R` [command line option](Command-Line-Options), if the server receives a SIGUSR1 signal during a recording, it will start a new recording in a new directory. SIGUSR2 will toggle recording enabled on/off. - -To send these signals using systemd, create the following two `.service` files in `/etc/systemd/system`, calling them something appropriate (e.g. `newRecording-Jamulus-server.service`). - -**Note:** You will need to save recordings to a path _outside_ of the jamulus home directory, or remove `ProtectHome=true` from your systemd unit file (be aware that doing so is however a potential security risk). - -For turning recording on or off (depending on the current state): - -~~~ - [Unit] - Description=Toggle recording state of Jamulus server - Requisite=Jamulus-Server - - [Service] - Type=oneshot - ExecStart=/bin/systemctl kill -s SIGUSR2 Jamulus-Server -~~~ - -For starting a new recording: - -~~~ - [Unit] - Description=Start a new recording on Jamulus server - Requisite=Jamulus-Server - - [Service] - Type=oneshot - ExecStart=/bin/systemctl kill -s SIGUSR1 Jamulus-Server -~~~ - -_Note: The Jamulus service name in the `ExecStart` line needs to be the same as the `.service` file name you created when setting systemd to control your Jamulus server. So in this example it would be `Jamulus-Server.service`_ - -Run `sudo systemctl daemon-reload` to register them for first use. - -Now you can run these with the `service start` command, for example: - -`sudo service jamulusTogglerec start` (assuming you named your unit file `jamulusTogglerec.service`) - -You can see the result of these commands if you run `service jamulus status`, or by viewing the logs. - -## Quality of Service - -Jamulus uses DSCP/CS4 opportunistically to deal with buffer bloat, and uses a default DSCP/CS4 value of 128 (or 0x80). This is compatible with IPv4 and IPv6. Other values can be set using the `-Q` option, eg `-Q [0..255]` (where 0 disables QoS). If you want to explore the effect of non-default settings, see [RFC4594](https://tools.ietf.org/html/rfc4594). However, most people will have no need to do this. - -### Using Quality of Service on Windows - -Jamulus’s QoS settings (including the default) have no effect on Windows because the operating system ignores them. To enable Quality of Service for Jamulus, you must follow these instructions. Note also that you may need to repeat this procedure every time Jamulus is updated. - - -In Search box beside Start menu Type: Local Group Policy Editor (enter)
-In new window, (click) on the menu icon to display the Actions third panel
-Looking at the first panel of the Local Group Policy Editor
- Local Computer Policy
-  Computer Configuration
-   Windows Settings
-    Policy-based QoS (click)
-Looking at the third panel (Actions) of the Local Group Policy Editor
- Policy-based QoS
-  More Actions
-   Create new Policy (click)
-    Policy Name: Jamulus
-    Specify DSCP value: 32
-    Next
-    This QoS policy applies Only to applications with name Jamulus.exe
-    Next
-    Next
-    UDP
-    Finish
-(Notice Jamulus policy in center panel may be edited)