.\" Manual page for jamulus
.\" Copyright (c) 2021
.\"     mirabilos <tg@debian.org>
.\" Published under the same terms as Jamulus itself.
.\"-
.Dd January 12, 2023
.Dt JAMULUS "1x" "SlackBuilds.org"
.Os jamulus-3.8.1
.Sh NAME
.Nm jamulus
.Nd real-time collaborative music session
.Sh SYNOPSIS
.Nm
.Op Fl 6 | Fl \-enableipv6
.Op Fl c | Fl \-connect Ar address
.Op Fl d | Fl \-discononquit
.Op Fl e | Fl \-directoryserver Ar hostname
.Op Fl F | Fl \-fastupdate
.Op Fl f | Fl \-listfilter Ar filter
.Op Fl h | Fl \&? | Fl \-help
.Op Fl i | Fl \-inifile Ar file
.Op Fl j | Fl \-nojackconnect
.Op Fl L | Fl \-licence
.Op Fl l | Fl \-log Ar file
.Op Fl M | Fl \-mutestream
.Op Fl m | Fl \-htmlstatus Ar file
.Op Fl n | Fl \-nogui
.Op Fl o | Fl \-serverinfo Ar info
.Op Fl P | Fl \-delaypan
.Op Fl p | Fl \-port Ar number
.Op Fl Q | Fl \-qos Ar value
.Op Fl R | Fl \-recording Ar directory
.Op Fl s | Fl \-server
.Op Fl T | Fl \-multithreading
.Op Fl t | Fl \-notranslation
.Op Fl u | Fl \-numchannels
.Op Fl v | Fl \-version
.Op Fl w | Fl \-welcomemessage Ar message
.Op Fl z | Fl \-startminimized
.Op Fl \-centralserver Ar hostname
.Op Fl \-clientname Ar name
.Op Fl \-ctrlmidich Ar MIDISetup
.Op Fl \-directoryfile Ar file
.Op Fl \-mutemyown
.Op Fl \-norecord
.Op Fl \-serverbindip Ar ip
.Op Fl \-serverpublicip Ar ip
.Op Fl \-showallservers
.Op Fl \-showanalyzerconsole
.Sh DESCRIPTION
.Nm Jamulus ,
a low-latency audio client and server, enables musicians to perform real-time
.Dq jam
sessions over the internet.
It is available across multiple platforms, so participants of any field
can communicate without specialist setup requirements.
This is not restricted to music, of course; other use
.Pq perhaps conferencing?
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.
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.
.Pp
Running
.Nm
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
.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
.It Fl e | Fl \-directoryserver Ar hostname
.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
.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
.Dq enable small network buffers
turned on; requires a faster CPU to avoid dropouts and uses more bandwidth to
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 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
override default initialisation file with
.Ar file
.It Fl j | Fl \-nojackconnect
.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 use Fl w No to set the text
before they are allowed joining
.It Fl l | Fl \-log Ar file
.Pq Server mode only
enable logging to
.Ar file
.It Fl M | Fl \-mutestream
.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
.Ar file
periodically
.It Fl n | Fl \-nogui
disable the GUI
.It Fl o | Fl \-serverinfo Ar info
.Pq Registered Servers only
set Server location details, formatted as
.Sm off
.Xo
.Ar name Li \&;
.Ar city Li \&;
.Ar locale
.Xc
.Sm on
where
.Ar locale
is the numeric value of a
.Li QLocale ;
see
.Pa https://doc.qt.io/qt\-5/qlocale.html#Country\-enum
for a list
.It Fl P | Fl \-delaypan
.Pq Server mode only
start with delay panning enabled
.It Fl p | Fl \-port Ar number
set the local UDP port to use to
.Ar number
.Pq default: 22124
.It Fl Q | Fl \-qos Ar value
set QoS
.Ar value
.Pq iptos byte
to use
.Pq default: 128
.It Fl R | Fl \-recording Ar Directory
.Pq Server mode only
enable recording
.Pq but see Fl \-norecord
storing tracks in
.Ar Directory
.It Fl s | Fl \-server
start in Server mode
.It Fl T | Fl \-multithreading
.Pq Server mode only
use multithreading to make better use of multi-core CPUs and
support more Clients
.It Fl t | Fl \-notranslation
disable translations, use built-in English strings
.It Fl u | Fl \-numchannels
.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
show
.Ar message
.Pq may contain HTML and inline CSS
to users on connect
.It Fl z | Fl \-startminimized
.Pq Server mode only
start with minimised window
.It Fl \-centralserver Ar hostname
.Pq Server mode only
deprecated alias for
.Fl \-directoryserver
.It Fl \-clientname Ar name
.Pq Client mode only
set window title and JACK client name
.It Fl \-ctrlmidich Ar MIDISetup
.Pq Client mode only
set MIDI controller channel to listen on, control number offset and
consecutive CC numbers (channels); format:
.Sm off
.Xo
.Ar channel
.Op Li \&;f Ar off Li \&* Ar nchans
.Op Li \&;p Ar off Li \&* Ar nchans
.Op Li \&;s Ar off Li \&* Ar nchans
.Op Li \&;m Ar off Li \&* Ar nchans
.Xc
.Sm on
.Pp
The first semicolon-separated element sets the MIDI channel
.Nm
listens on for control messages.
The other elements specify the items to control by their
first literal letter (f\ =\ volume fader, p\ =\ pan, m\ =\ mute,
s\ =\ solo) directly followed by the offset (CC number) to start from,
a literal asterisk, and the amount of consecutive CC numbers to assign.
Fader strips in the mixer window are controlled in ascending order from
left to right.
.Nm
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 mode only
remember registered Servers even if the Directory is restarted
.It Fl \-mutemyown
.Pq headless Client only
mute my channel in my personal mix
.It Fl \-norecord
.Pq Server mode only
do not automatically start recording even if configured with
.Fl R
.It Fl \-serverbindip Ar ip
.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
.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 debugging command
.It Fl \-showanalyzerconsole
.Pq Client mode only
show analyser console to debug network buffer properties
.Pq debugging command
.El
.Pp
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 Unregistered, Registered, Directory.
A Unregistered Server is unlisted, Clients can only connect if given
the address (IP address and port).
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
.It Pa https://jamulus.io/wiki/Software\-Manual
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\-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
.An mirabilos Aq tg@debian.org
wrote this manual page for the Debian project,
but it may be used elsewhere as well.
.Sh BUGS
This manual page was derived from the source code and summarises
some of the information from the website, but it could be more helpful.
.Pp
Some of the networking code assumes Legacy IP
.Pq IPv4 .