Diagramming Jamulus

[gilgongo]

I've had a go at trying to explain the basic Jamulus configuration in diagram form with a view to putting this on the wiki for non-technical users.

EDIT: Following discussions below, here's the latest versions

BTW I'm using this to make the diagrams the basic version of which is free for non-commercial use and lets you save the files externally. There might be a better one though. It was just the first I found on Google.

Overview

For people who just need to get the general idea:

Public Server At Home

(I was trying to keep the diagrams wide rather than deep so they wouldn't need too much scrolling on the page, but I might move the central server down a bit so the signal path can be straight like it is in the diagram below)

Private Server At Home

[corrados]

Overview: If the jam is on "Your chosen server" than it is misleading that the signal path goes through the Central Server. The Central Server just manages the server list in that case. The actual audio data goes directly from the clients to "Your chosen server".

[corrados]

The same applies to Public Server At Home.

[gilgongo]

Hehe - this is why I'm always a bit wary of diagrams :-)

The line is supposed to be a "conceptual" connection rather than a strict signal path. So the Central Server is represented as the thing that "connects" the clients to the chosen server.

I'll see if I can re-think it so that the role of the central server is clear while the path to/from the server is correctly represented (and without it all looking too complicated).

[dcocharro]

I think the diagram is a great addition. Thank you.
Occurred to me that maybe by having two styles of arrows connecting the elements would allow to clear some ambiguities (or not :P ).
One arrow representing "network management data" and another for the actual audio signal data between clients. Another alternative would be to create a diagram for each separate process, 1) entering the network and connect to a server and 2) exchanging audio signal data.
But I have to say also, I don't dislike the current diagram, maybe some accompanying text would help to avoid any ambiguities.

[gilgongo]

BTW I envisage this to be on the home page of the wiki, mainly for the benefit of non-technical people so that they can "orientate" a bit. It's not supposed to an overview of the technical architecture. If people want that, we have a link to Volker's paper there.

[vocobox]

Great work @gilgongo ! Shall I suggest you add the source file of your schema so that schemas could extended and drawn with the same style & software (at my job wiki I usually add a "schema source" URL just under the diagram so that one can easily retrieve it for modification).

I would suggest to add the technical flow diagram in Volker diagram, which clarify the jitter/buffering. It also makes clear that mixing occurs on server side, which was not clear for me at the beginning.

[gilgongo]

Hi @vocobox Sure, I can add the source file on the ticket (edit: Oh, Google Drive support seems to be broken). Although for those of a technical mind (perhaps less than 5% of the intended audience!) there is a link to the paper that includes the diagram you refer to on the wiki home page already. I'm only trying to describe Jamulus to non-technical users who just need to get some kind of general idea. Perhaps I'm not being abstract enough! :-)

Meanwhile, here's a version that puts the Central Server into a sort of "position of influence". Starts to feel a bit obscure though...

[ZoomRmc]

The last one is much better, although:

1. "People Running Jamulus Servers" should be changed to simply "Other Servers" (they are the same servers as the purple one, not People).
2. The data flow arrows shouldn't really merge. They have separate paths to the server and carry different signals (client inputs).

[gilgongo]

Maybe just "Jamulus servers" then?

But just to be clear: this is intended as a diagram for non-technical users. They just need to grasp three basic concepts:

1. That they run Jamulus on their PCs (ie it's not some web-based or phone app thing)
2. That lots of people can run servers.
3. That they can use the "Central Server" to connect to those servers.

Once they have those concepts in mind, it then makes it possible to explain how they can set up their own public or private servers.

I very much doubt they will care about the details beyond that: how the actual signal paths run or whether they are separate or not :-) This is why I was favouring the initial attempt at portraying the central server as "controlling" the servers and the clients, and just leaving it there.

[vocobox]

Not sure the following table would be relevant for the overview section you propose, but I made it to think about the bandwidth requirement involved by buffer size/channel number/sound quality :

It is based on the "adutio stream rate" field value displayed on the setting page.

I however wasn't really able to explain why I could not properly send sound fast enough for proper synchronisation when using my home Wifi which provides me the following figures with fast.com (sorry I know this is off-topic, and I also know Ethernet is better :/ ).

[sehe]

@vocobox The problem with WiFi connections is usually the increased jitter (latency variation). A "sure-fire" way to remedy drop-outs here is to manually increase the jitter buffers but this also increases total delay. You will have to strike a balance between delay and acceptable quality.

The best investment you can probably do to improve the situation is to switch to a cabled network connection.

It's unlikely that you run into actual bandwidth issues, although I've heard anecdotal evidence that general network congestion (e.g. family members streaming video) also increased dropouts.

PS. I almost forget: Nice table. I found that useful (I've made my own table before)

[gilgongo]

OK how about this for a compromise?

This makes Public Server Mode look like:

[vocobox]

The first one is great. Maybe you can add a legend indicating "coordination links" for the doted line and "sound transfer" for plain line.

[vocobox]

@sehe thank you. I moved the bandwidth table here if you want to review/edit feel free : https://github.com/corrados/jamulus/wiki/Quality,-delay-and-network-bandwidth

[gilgongo]

@vocobox Are those speeds (kbps) KiloBits per second or KiloBytes? I always get confused...

[vocobox]

@gilgongo I assumed that the application UI follows the convention which is Kb : Kilobit, KB : KiloBytes. @corrados am I wright?

[gilgongo]

@vocobox OK so if those figures are Kilobits/s then I've added that to the minimum bandwidth requirement in the docs as "200Kbps (0.2Mbps)" since most domestic broadband speeds are reported in Mbps I think. So for the majority of people, Jamulus will not use much of bandwidth.

[corrados]

Please note that in the current Git code, I have changed a lot towards support for 64 samples frame size. The Buffer Delay will look like this:

[vocobox]

@gilgongo For transposing audio bandwidth requirements (which is what Jamulus displays in the Settings UI) to network requirements (which is what system admin would want to know), we should clarify that network requirements are

• for upstream (single musician to server)
• for downstream (server mix to every musician), hence should be multiplied by number of musicians

which is probably clearer with this kind of schema

Can @corrados validate this is correct before I add it to the wiki?

And yes, having another table in Mbps would be useful for this purpose!

[gilgongo]

@vocobox Do you mean there should be one bandwidth minimum for client users and another guide for server operators (eg if the average number of people in a jam is 4, then it's 200Kbps * 4?)

[vocobox]

@gilgongo my first schema was wrong, I fixed, sorry. But yes, as far as I understand, the server should be able to handle M x 2 streams (where M is number of musicians), while each individual musician should only deal with 2 streams.

[gilgongo]

@vocobox OK so if I was to put that into practical terms (I can sort out the exact wording later):

If you are just connecting to servers with Jamulus, you need (roughly) a minimum of 200Kbps up and downstream (so if you have a 10Mbits down and 1Mbps up broadband connection, you're unlikely to run into any issues of bandwidth, depending on who else is using the line).

If you are running a server, you will need to multiply a minimum of 200Kbps by the number of people (external to your network) using your server. So if a jam has 4 people, then you will need 200Kbps * 4 = 800Kbs up and down (so if you have a 10Mbits down and 1Mbps up broadband connection, you may start running out of bandwidth if a fifth player joins, or the other musicians choose settings that increase their usage).

Is that right?

[vocobox]

Yes, that is what I understood - but I would prefer to have @corrados confirmation.

@gilgongo I think that the server bandwidth is enslaved by the client setting. If I suddenly send 1GB/s, the server has to deal with it.

One question to @corrados : do you confirm the server send me back sound with the same quality as I use to send? If Musician1 send with High quality, will (s)he receive with High quality. If Musician2 send with Low quality on the same server, will (s)he receive with Low quality? Would any musician be able to affect the downstream compression of the other musician?

[corrados]

I can confirm this. But the 200 kbps is with Mono Low quality. I guess nobody is actually using this. With my Stereo High quality setting, I am more like in the 800 kbps range.
And yes, the server returns the audio in exactly the same quality setting as the client transmits to the server. A musician can only affect his own compression, not the compression of any other client stream.

[vocobox]

@gilgongo I reused your phrasing in the wiki. Feel free to revise.

https://github.com/corrados/jamulus/wiki/Quality,-delay-and-network-bandwidth

[gilgongo]

@vocobox I moved those two descriptions into the Client and Server overview pages respectively, and linked both back to your details page to avoid duplication.

BTW unless anyone has any further suggestions about the diagrams, I'll put those into the relevant areas as well.

[gilgongo]

OK I've done that now here and here. The diagramming tool made it too hard to do exactly what I wanted with the public server diagram, but it's good enough.

The source file is here if anyone wants it (use https://online.visual-paradigm.com to edit):
Jamulus Diagrams.zip

[gene96817]

@gilgongo is this diagram (#64 (comment)) still valid? This diagram really helps my understanding and eliminates the need for just twiddling knobs to see what happens. I know is too technical for a lot of musicians. It would be good to have these kinds of diagrams in an appendix for technical users. Thanks.

[gilgongo]

Yes, from a high level it's still valid. I'd forgotten about that diagram.

[ann0see]

OK I've done that now here and here. The diagramming tool made it too hard to do exactly what I wanted with the public server diagram, but it's good enough.

The source file is here if anyone wants it (use https://online.visual-paradigm.com to edit):
Jamulus Diagrams.zip

Can we change them to use the new logo and somewhere link them on the website repo?

[drummer1154]

This is identical to the version previously posted to
#64 (comment)

[ann0see]

Yes. I'm currently working on newer ones. I couldn't really get them to the new design. Currently only the first diagram:

Jamulus Diagrams_edited.zip

[ann0see]

And yes, I think there are multiple changes which could and should be made (@drummer1154 you already mentioned a few) https://github.com/jamulussoftware/jamuluswebsite/issues/174

1. Do we include some kind of clarification how the server mixes audio (one mix per client. Should we add it here?)
2. We should move away from the "The central server" concept. There are multiple "central servers" now.
3. Should we add the jitter buffers or similar?

[gilgongo]

Should we add the jitter buffers or similar?

Since jitter buffers are in the UI, it might make sense to attempt to illustrate them. However, you're going to rapidly descend into the rabbit hole on all this (should you show "mute myself" vs "mute"? What about local panning? The local mix?) unless you have a clear idea of why you're diagramming. When I did these, I just wanted to show somebody what some of the common vocabulary referred to ("client", "server", "central server" etc.). You may of course be able to elegantly draw more than that :-)

Perhaps a useful rule would be "If somebody didn't understand this, would it matter?" If so, then knowing that there are multiple central servers would be "no", since all the user sees is a drop-down menu.

[ann0see]

Perhaps a useful rule would be "If somebody didn't understand this, would it matter?"

Does somebody need to understand jitter buffers? We have the "auto" setting in Jamulus.

Tagging
@drummer1154 here. You suggested some changes to this (I think there was some confusion about the fact that Jamulus uses one mix per user). (How) would you visualize it? We might also just change the subtitle on jamulus.io

[drummer1154]

I dunno about "the subtitle on jamulus.io". I still think that several "layers" of diagrams are needed - top layer for the average newbee user who doesn't care about the underlying technology and just wants to play together with other musicians so they know about the Jamulus client-server principle - if it works immediately - fine. But what if not - then troubleshooting is required, and I strongly believe that more deep down "techie" diagrams could help, including the sampling rate issue. I would visualize the mixes as "stacked" rectangles - I hope I can find time soon to start the drawing.

If somebody didn't understand this, would it matter?
We have the "auto" setting in Jamulus.

From my experience: I manually set both buffers 1 tick higher than the value found by the automatic as audio dropouts or distortions occur if I don't.

[ann0see]

subtitle

It's currently:

Jamulus works on the client server principle. Everybody’s audio is sent to a server, mixed and processed there. Afterwards the audio is sent to every client. If a server is made public and registered on a central server, its information will be broadcasted to all clients.

So you'll make some more in depth diagrams?

[drummer1154]

Yes, as soon as possible.

[drummer1154]

Finally finished the first version. I tried to keep as close to Volker's "Simplified Jamulus block diagram" in his 2015 Case Study.
Please review and let me know what you think - is it comprehensible?
Jamulus_hg_2021-01-04.pdf

[gene96817]

Thanks for working on this. Can client2 be a non-Windows client (does not have ASIO). Also it is possible to add a label for the two jitter buffers (client and server) to the UI indicators?

[ann0see]

Looks good for me although I would prefer the design of the private/public server diagrams since that looks more visually appealing to me.

[drummer1154]

@gene96817 Good point regarding the audio drivers, renamed to be more generic. I added a number to the Server jitter buffers so as to show the relationship to the Clients (and capitalized both Server and Client). In the GUI the Jitter Buffer sliders are named "Local" and "Server" and the context help refers to "local client" so I think the correlation should be clear, OK?

I also added an icon for the actual "User" so as to distinguish "User" (as a person) and "Client" (as a computer) - even if in some discussions/descriptions both nouns are used synonymously, and added "IP" to the network cloud to be more specific.

@ann0see This is meant more like a circuit diagram or audio block diagram of a mixing console (similar to above #64 (comment) by @Matzix) which shall be "correct" from a technical PoV - be it "visually appealing" or not.

@corrados and @gilgongo Please do me the favor to review the diagram, thanks.

JamulusABDv103.pdf

[gilgongo]

@drummer1154 Thanks - I'm not familiar with the conventions of such diagrams, or what questions would be asked so that it would need to be consulted exactly. So it's hard to know how to comment (do you have an example for a similar application, eg Zoom or something?).

As I mentioned before, one test for a useful diagram would be to answer the question "If I didn't know this, would it matter?" (or perhaps, "If I did know this, would it help me use Jamulus?"). One thing I wonder about is how "personal mix" works. If my client is receiving a stereo mix of all the clients on the server including me, then how is it that I can adjust individual channel levels that only I can hear? I don't know if sometimes people are reluctant to adjust levels because they think that will adjust them for all (possibly using the "control" line in the diagram?). Would explaining that in the diagram be useful? What about the distinction between "mute" and "mute myself", and that of the relationship between the client and the audio driver (I see both seem to be one thing in the diagram)?

But again, its hard for me to know what the scope or ultimate purpose of this is :-)

[ann0see]

I think this diagram would go somewhere where more experienced users could find out more about how Jamulus works technically (e.g. a specific page in the community KB which describes how jamulus works in a more detailed way.)

[drummer1154]

@gilgongo What I am referring to is e.g. this: http://behringerwiki.music-group.com/images/1/11/X18-XR18_block_diagram.pdf

As to your question "... would it matter" - I agree that this is a valid question. The reason I came across the block diagram was when I started using Jamulus with our band, nothing worked and - as engineers - we started troubleshooting by trying to understand how the service is supposed to work. Volker's 2015 "case study" was a good starting point, and besides the text describing the principle, it contains "Figure 2: Simplified Jamulus block diagram", which, however, does not show how the "Personal Mix" feature is supposed to work. So I was completely mislead by "This mix is again compressed with OPUS and transmited [sic] to all connected clients ..." suggesting that there is only ONE mix - where in reality there are as many as clients are connected. So it mattered to me and this was the main reason why I considered updating Volker's diagram.

One thing I wonder about is how "personal mix" works.

Are you kidding? But if you are seriously putting this question then I am even more convinced that the documentation needs to be enhanced.

What I am saying now is pure guessing, taken from the information read in several discussions and needs to be confirmed by the Jamulus architects (mainly @corrados). But for me it is obvious that - as in a "real" mixing console - in the server there are attenuator and pan functions which are controlled by each client's GUI elements and transferred via the "Control" channel. I did not yet take up any such function in the diagram as from my PoV it is a more deep down detail which is, however, not really required to understand the overall principle. I would like to continue with the diagram on a next page giving something like an "exploded view" of those functions (as well as the "real" audio routing in the client so as to show how "Mute Myself" is working and that it violates the "golden principle" "ONLY. LISTEN. TO. THE. SIGNAL. FROM. THE. SERVER!", maybe a bit better than the drawing above :-).

As to where to finally make such a diagram available to the public - this should be left to the people who are currently doing most of the valuable documentation on jamulus.io - in so far I absolutely agree to @ann0see above.

But what I would strongly request is a quick guide to "where to find what" and where to enter contributions, maybe kind of a "tree view". When I (of course in a state of frustration because nothing worked as expected) documented https://github.com/jamulussoftware/jamuluswebsite/issues/174 - which then was commented to be in the wrong repository - I blindly followed the advice given in #778 (comment) ...

[WolfganP]

I would change the "audio compression / decompression" labels on server side as it may imply a compressor effect on audio which is not what's happening. Probably "audio encode / decode" may fit better.

[drummer1154]

@WolfganP 100% agreed, thanks, taken over thoughtlessly from Volker's paper. Will be changed on Client also in the next edition. !!CoDec!!

[gilgongo]

@drummer1154

What I am saying now is pure guessing

OK so when you ask if I'm kidding (I wasn't, BTW) you mean you can't answer that yet, or that it's too low-level a question for the diagram as it currently stands? I'm a bit unclear.

when I started using Jamulus with our band, nothing worked

I think you've said that before and I've been meaning to ask: to what extent was that "not working" due to the fact that the Jamulus client's UI presents itself as a mixing desk? I have wondered whether it might be the case that the more familiar somebody is with real-world mixing desks and sound engineering, the greater the likelihood of them becoming confused with Jamulus when it doesn't behave in exactly the same way. It's just a hypothesis, but your statement about being an engineer and "nothing worked" seems to support the idea so I'm curious.

[drummer1154]

@gilgongo Please don't get me wrong - I do not want to express any emotions towards any other person.

[is it] too low-level a question for the diagram as it currently stands?

Absolutely not - I only want to say that I do not have all the knowledge which the creators of the SW have, and I am absolutely not able (and also not willing) to reverse-engineer the source code to gain the information required to create a complete and accurate diagram. Therefore I need help from these experts - at least review.

As it stands now my diagram is e.g. missing the stereo signal capability, but I believe this is again a next deeper down level of information (which I cannot add because I do not understand the mechanism behind Settings - Misc - Audio Cannels (Mono; Mono-in/Stereo-out; Stereo) - according to my tests documented in https://github.com/jamulussoftware/jamuluswebsite/issues/174#issue-765437110 a lot of unexpected things happen when you change this setting).

to what extent was that "not working" due to the fact that the Jamulus client's UI presents itself as a mixing desk?

To none. The GUI is OK for me (with an open gap for some small changes which could remove unnecessary inconsitencies as e.g. discussed in #778 (from my PoV just the relationship between L/R channel and slider up/down movement should be consolidated to a "natural" feeling - but especially there you see that excessive expectations from some users may not meet the developer intentions at all - leading to the developer apparently going into fold-back).

My initial problem was that key facts are not stated prominently in the documentation (e.g. Jamulus only supports 48 kHz sample rate (prio 1), it only supports IPv4 (prio 2) etc. - one of the reasons why I supported creating the table in #763) so that after having removed the primary obstacles I still was unable to hear my vDrums via Jamulus - just because I was not aware of the fact that I need to connect to a server or else I will not be able to hear myself. I do not want to copy/paste my input from #712 here but I want to state: would there be a sound audio block diagram covering all technical aspects, a lot of problems could be solved without the need to call for help from any of the Jamulus support/development platforms (I believe that in 90% of the cases the root cause is on the user side - or it cannot be resolved due to technical reasons - but please also see in #712 the fact that my interface tells me that something in the "application" (as the manual says it, i.e. Jamulus) has not set up the interface correctly - and the difference in mindsets is that even if it is working somehow, I can hardly accept this, while someone else would certainly say: it's working so why worry).

Latest version:
JamulusABDv104.pdf
Edit: Sampling rate added.
JamulusABDv105.pdf

[ann0see]

My initial problem was that key facts are not stated prominently in the documentation (e.g. Jamulus only supports 48 kHz sample rate

The sample rate problem will be documented in the upcoming version of the documentation. So this will be fixed.

it only supports IPv4

This is already documented on the server setup page. You can nevertheless open an issue to make this fact clearer in the documentation repo. (Use the bug report or feature request template).

[drummer1154]

I have taken up the sample rate into the diagram v105. Sorry to be late - it came to my mind in the very moment when I uploaded v104 :-). I want to have the important things in the diagram - a picture is worth a thousand words - and I am rather going to create the next drawing for the client audio than initiating a discussion how and where to put the according verbal description - other people are able to do this better than me.

[ann0see]

I just found this: http://www.aesmelbourne.org.au/wp-content/media/Nov2020_slides.pdf

Maybe we can ask FABIO MARRACCINI if he allows us to use some of his slides?