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

[gilgongo]

@vocobox Just noticed that the minimum bandwidth in that statement we put on the wiki was 600Kbps. We used to have 200Kbps. Was there a reason why we put it higher?

https://github.com/corrados/jamulus/wiki/Quality,-delay-and-network-bandwidth/_compare/41bcae58ccc34021ceeff3dca7b4170b18f2c148...039f769274edf47fec0b934fe4c145c9639b5443

[vocobox]

yep, I changed it after a comment of Volker saying "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.", so I took an higher example value.

Note that when I ran iftop on a server, I noticed that actual kbps are slightly lower than the one displayed by the application, but it is not large enough to be mentioned in the doc.

One thing that surprised me is why the stereo bandwidth is not 2x the mono bandwidth...

[gilgongo]

@vocobox Oh OK. I guess it's what we want to say as the theoretical mininum vs the actual minimum that people might want. See Volker's comment here . So maybe it's still accurate to say "An Internet connection speed of at least 200Kbps (0.2Mbps) up and down, with 800Kbps recommended" ?

[vocobox]

yes :)

[WolfganP]

Just for reference for the discussion of producing better materials, I'll like to add the following from https://github.com/corrados/jamulus/issues/148#issuecomment-629679659 (by @matzix) which I like due to clear relationship between client controls and the audio/data path betwenn clients and server:

[gilgongo]

@WolfganP Thanks for this. I'm not sure if you intend for this to be included in the docs, but while it's true that over 60% of Jamulus users who have filled out our usage survey say they have "advanced" computer skills, I'd be somewhat cautious in doing that. One of the problems I think Jamulus has is being seen as rather technical and perhaps difficult to use.

[streaps]

which is probably clearer with this kind of schema

https://github.com/corrados/jamulus/issues/64#issuecomment-613543425

@vocobox, I don't understand this infographic. It's either not obvious what it wants to tell me or it is just wrong.

[gene96817]

@gilgongo is this diagram (https://github.com/corrados/jamulus/issues/64#issuecomment-633309575) 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 https://github.com/corrados/jamulus/issues/64#issuecomment-613875648

[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 https://github.com/corrados/jamulus/issues/64#issuecomment-633309575 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 :-)