From 56092960981a979ec0b73244f13c90b5d55d9695 Mon Sep 17 00:00:00 2001 From: Jonathan <4561747+gilgongo@users.noreply.github.com> Date: Thu, 24 Mar 2022 17:13:28 +0000 Subject: [PATCH] Update -h and man page as per jamuluswebsite/pull/714 (#2448) --- distributions/Jamulus.1 | 154 +++++++++++++++++++++++----------------- src/main.cpp | 30 ++++---- 2 files changed, 102 insertions(+), 82 deletions(-) diff --git a/distributions/Jamulus.1 b/distributions/Jamulus.1 index f62093ea01..e2c61aa291 100644 --- a/distributions/Jamulus.1 +++ b/distributions/Jamulus.1 @@ -60,82 +60,99 @@ is also possible. .Pp One participant starts .Nm -in server mode, ideally on a dedicated server (virtual) machine; -all participants start the (graphical) client which transmits audio -to the server, receiving back a mixed stream. +in Server mode, ideally on a dedicated server (virtual) machine; +all participants start the (graphical) Client which transmits audio +to the Server, receiving back a mixed stream. Use of a metronome is recommended. Clients should be connected using ethernet, not wireless, and use proper headphone and microphone connections, not Bluetooth. -The server should run on a low-latency system, ideally not a VM. +The Server should run on a low-latency system, ideally not a VM. .Pp Running .Nm -without any extra options launches the full graphical client. +without any extra options launches the full graphical Client. .Pp The options are as follows: .Bl -tag -width Ds .It Fl 6 | Fl \-enableipv6 enable IPv6 support .It Fl c | Fl \-connect Ar address -.Pq client mode only -connect to the given server +.Pq Client mode only +connect to the given Server .Ar address .Pq Ar hostname Ns Op Ar :port at startup .It Fl d | Fl \-discononquit -.Pq server mode only -disconnect all clients on quit +.Pq Server mode only +disconnect all Clients on quit .It Fl e | Fl \-directoryserver Ar hostname -.Pq server mode only -make the server public and set its genre by setting the address -of the directory server (formerly central server) to use to +.Pq Server mode only +Register the Server with the given Directory by setting the Directory Server Address to use to .Ar hostname ; see also .Fl o ; -to be a directory server, use +to be a Directory Server, use .Dq Li localhost .It Fl F | Fl \-fastupdate -.Pq server mode only -use 64 samples frame size mode, which reduces latency if clients connect with +.Pq Server mode only +use 64 samples frame size mode, which reduces latency if Clients connect with .Dq enable small network buffers turned on; requires a faster CPU to avoid dropouts and uses more bandwidth to -connected clients +connected Clients +.It Fl \-jsonrpcsecretfile Ar file +(Server mode only) +Set the path to a text +.Ar file +containing an authentication string for obtaining access to the JSON-RPC API. +This option is required when +.Fl \-jsonrpcport +is used. +.It Fl \-jsonrpcport Ar port +(Server mode only) +Enables JSON-RPC API server to control the application, set the TCP +.Ar port +number. +This API is +.Em experimental +and may change. +It is only accessible from localhost. +Please refer to the JSON-RPC API Documentation. .It Fl f | Fl \-listfilter Ar filter -.Pq directory server mode only -whitelist which servers are allowed to register on the server list; +.Pq Directory mode only +whitelist which Servers are allowed to register on the server list; .Ar filter must consist of semicolon-separated IP addresses .It Fl h | Fl \&? | Fl \-help display a short help text and exit immediately .It Fl i | Fl \-inifile Ar file -.Pq client and non-headless server mode only +.Pq Client and non-headless Server mode only override default initialisation file with .Ar file .It Fl j | Fl \-nojackconnect -.Pq client mode only +.Pq Client mode only do not automatically connect to JACK .It Fl L | Fl \-licence -.Pq server mode only -require clients to accept the agreement shown in the welcome message +.Pq Server mode only +require Clients to accept the agreement shown in the welcome message .Pq use Fl w No to set the text before they are allowed joining .It Fl l | Fl \-log Ar file -.Pq server mode only +.Pq Server mode only enable logging to .Ar file .It Fl M | Fl \-mutestream -.Pq client mode only +.Pq Client mode only start in muted state .It Fl m | Fl \-htmlstatus Ar file -.Pq server mode only -write server status and list of connected clients, in HTML format, to +.Pq Server mode only +write Server status and list of connected Clients, in HTML format, to .Ar file periodically .It Fl n | Fl \-nogui disable the GUI .It Fl o | Fl \-serverinfo Ar info -.Pq public servers only -set server location details, formatted as +.Pq Registered Servers only +set Server location details, formatted as .Sm off .Xo .Ar name Li \&; @@ -151,7 +168,7 @@ see .Pa https://doc.qt.io/qt\-5/qlocale.html#Country\-enum for a list .It Fl P | Fl \-delaypan -.Pq server mode only +.Pq Server mode only start with delay panning enabled .It Fl p | Fl \-port Ar number set the local UDP port to use to @@ -163,45 +180,45 @@ set QoS .Pq iptos byte to use .Pq default: 128 -.It Fl R | Fl \-recording Ar directory -.Pq server mode only +.It Fl R | Fl \-recording Ar Directory +.Pq Server mode only enable recording .Pq but see Fl \-norecord storing tracks in -.Ar directory +.Ar Directory .It Fl s | Fl \-server -start in server mode +start in Server mode .It Fl T | Fl \-multithreading -.Pq server mode only +.Pq Server mode only use multithreading to make better use of multi-core CPUs and -support more clients +support more Clients .It Fl t | Fl \-notranslation disable translations, use built-in English strings .It Fl u | Fl \-numchannels -.Pq server mode only +.Pq Server mode only set maximum number of channels .Pq and , therefore , users ; default is 10, maximum is 150 .It Fl v | Fl \-version display version information and exit immediately .It Fl w | Fl \-welcomemessage Ar message -.Pq server mode only +.Pq Server mode only show .Ar message .Pq may contain HTML and inline CSS to users on connect .It Fl z | Fl \-startminimized -.Pq server mode only +.Pq Server mode only start with minimised window .It Fl \-centralserver Ar hostname -.Pq server mode only +.Pq Server mode only deprecated alias for .Fl \-directoryserver .It Fl \-clientname Ar name -.Pq client mode only +.Pq Client mode only set window title and JACK client name .It Fl \-ctrlmidich Ar MIDISetup -.Pq client mode only +.Pq Client mode only set MIDI controller channel to listen on, control number offset and consecutive CC numbers (channels); format: .Sm off @@ -227,31 +244,30 @@ left to right. does not provide feedback as to the current state of the Solo and Mute buttons so the controller must track and signal their state locally. .It Fl \-directoryfile Ar file -.Pq directory server mode only -enable server list persistence, storing to and loading from -.Ar file +.Pq Directory mode only +remember registered Servers even if the Directory is restarted .It Fl \-mutemyown -.Pq headless client only +.Pq headless Client only mute my channel in my personal mix .It Fl \-norecord -.Pq server mode only +.Pq Server mode only do not automatically start recording even if configured with .Fl R .It Fl \-serverbindip Ar ip -.Pq server mode only +.Pq Server mode only configure Legacy IP address to bind to .It Fl \-serverpublicip Ar ip -.Pq server mode only -configure public Legacy IP address when both the directory server -and the actual server are situated behind the same NAT, so that -clients can connect +.Pq Server mode only +configure public legacy IP address when both the Directory Server +and the actual Server are situated behind the same NAT, so that +Clients can connect .It Fl \-showallservers -.Pq client mode only -show all registered servers in the serverlist regardless whether a ping -to the server is possible or not +.Pq Client mode only +show all registered Servers in the serverlist regardless whether a ping +to the Server is possible or not .Pq debugging command .It Fl \-showanalyzerconsole -.Pq client mode only +.Pq Client mode only show analyser console to debug network buffer properties .Pq debugging command .El @@ -259,16 +275,16 @@ show analyser console to debug network buffer properties Note that the debugging commands are not intended for general use. .Pp .Nm Jamulus -knows four modes of operation: client mode and three kinds of server -.Pq private , public , directory . -A private server is unlisted, clients can only connect if given +knows four modes of operation: Client mode and three kinds of Server +.Pq Unregistered, Registered, Directory. +A Unregistered Server is unlisted, Clients can only connect if given the address (IP address and port). -A public server will contact a directory server (whose address must be -given at server startup) and show up in that server's list; clients -can retrieve a list of public servers from the directory server. -Several public directory servers are operated by the Jamulus project; -there is a directory server for each genre, which is how public Jamulus -servers are categorised into genres. +A Registered Server will contact a Directory (whose address must be +given at Server startup) and show up in that Server's list; Clients +can retrieve a list of Registered Servers from the Directory Server. +Several Registered Directories are operated by the Jamulus project; +there is a Directory for each genre, which is how Registered Jamulus +Servers are categorised into genres. .Sh SEE ALSO .Xr qjackctl 1 .Bl -tag -width Ds @@ -277,15 +293,19 @@ online handbook .It Pa https://jamulus.io/wiki/FAQ frequently asked questions .It Pa https://jamulus.io/wiki/Running\-a\-Server -documentation on server configuration and types -.It Pa https://jamulus.io/wiki/Server\-Linux#running\-in\-public\-mode -current list of directory servers operated by the Jamulus project, +documentation on Server configuration and types +.It Pa https://jamulus.io/wiki/Server\-Linux#running\-in\-registered\-mode +current list of Directory Servers operated by the Jamulus project, controlling the .Dq genre .It Pa https://jamulus.io/wiki/Tips\-Tricks\-More verbose .Fl \-ctrlmidich documentation and other more or less useful information +.It Pa https://github.com/jamulussoftware/jamulus/blob/master/docs/JSON\-RPC.md +JSON-RPC API Documentation (see +.Fl \-jsonrpcport +above) .El .Sh AUTHORS .An -nosplit diff --git a/src/main.cpp b/src/main.cpp index 888be6778d..5164cad9d1 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -1014,7 +1014,7 @@ QString UsageArguments ( char** argv ) "\n" "Common options:\n" " -i, --inifile initialization file name\n" - " (not supported for headless server mode)\n" + " (not supported for headless Server mode)\n" " -n, --nogui disable GUI (\"headless\")\n" " -p, --port set the local port number\n" " --jsonrpcport enable JSON-RPC server, set TCP port number\n" @@ -1029,39 +1029,39 @@ QString UsageArguments ( char** argv ) " -6, --enableipv6 enable IPv6 addressing (IPv4 is always enabled)\n" "\n" "Server only:\n" - " -d, --discononquit disconnect all clients on quit\n" - " -e, --directoryserver address of the directory server with which to register\n" - " (or 'localhost' to host a server list on this server)\n" - " --directoryfile enable server list persistence, set file name\n" - " -f, --listfilter server list whitelist filter. Format:\n" + " -d, --discononquit disconnect all Clients on quit\n" + " -e, --directoryserver address of the directory Server with which to register\n" + " (or 'localhost' to host a server list on this Server)\n" + " --directoryfile Remember registered Servers even if the Directory is restarted. Directory Servers only.\n" + " -f, --listfilter Server list whitelist filter. Format:\n" " [IP address 1];[IP address 2];[IP address 3]; ...\n" " -F, --fastupdate use 64 samples frame size mode\n" " -l, --log enable logging, set file name\n" " -L, --licence show an agreement window before users can connect\n" " -m, --htmlstatus enable HTML status file, set file name\n" - " -o, --serverinfo registration info for this server. Format:\n" + " -o, --serverinfo registration info for this Server. Format:\n" " [name];[city];[country as QLocale ID]\n" - " --serverpublicip public IP address for this server. Needed when\n" + " --serverpublicip public IP address for this Server. Needed when\n" " registering with a server list hosted\n" " behind the same NAT\n" " -P, --delaypan start with delay panning enabled\n" " -R, --recording sets directory to contain recorded jams\n" " --norecord disables recording (when enabled by default by -R)\n" - " -s, --server start server\n" - " --serverbindip IP address the server will bind to (rather than all)\n" + " -s, --server start Server\n" + " --serverbindip IP address the Server will bind to (rather than all)\n" " -T, --multithreading use multithreading to make better use of\n" - " multi-core CPUs and support more clients\n" + " multi-core CPUs and support more Clients\n" " -u, --numchannels maximum number of channels\n" " -w, --welcomemessage welcome message to display on connect\n" - " (string or filename)\n" + " (string or filename, HTML supported)\n" " -z, --startminimized start minimizied\n" "\n" "Client only:\n" - " -c, --connect connect to given server address on startup\n" - " -j, --nojackconnect disable auto Jack connections\n" + " -c, --connect connect to given Server address on startup\n" + " -j, --nojackconnect disable auto JACK connections\n" " -M, --mutestream starts the application in muted state\n" " --mutemyown mute me in my personal mix (headless only)\n" - " --clientname client name (window title and jack client name)\n" + " --clientname Client name (window title and JACK client name)\n" " --ctrlmidich MIDI controller channel to listen\n" "\n" "Example: %1 -s --inifile myinifile.ini\n"