Jamulus: 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.