Documentation incomplete

General
1

Hello,

when reading the documentation and looking through the source code, it looks like, that some important key items are missing.
I try now since several days, to understand, how mopidy is working and how things are tied together, but it all still looks like a big plate of spaghetti.

I miss a very small example, just playing a lokal mp3-file, where the name is given either in the code or in a configuration file. Just to see all the steps needed to get one track playing.
This example should have a bare minimal frontend, backend and all whats needed, that one track can be played, stopped, repeated and volume can be changed.

This should be followed with an description, what all gets started, where is the starting point in the sources, as I can see between 20 and 30 threads from os perspective, most called mopidy, but others are typefind:sync, id3demux10:sink, mpegaudioparse1, source:src, aqueue:src, queue0:src, queue1:src, queue2-0:src, dconf worker, …
From that perspective pykka makes sense, which I found out is a kind of thread-management-library.

So the next example could be an addition to the first example, by adding another backend, which provides some streams as audio sources, and another frontend, which can change the current running track between the mp3 file and one of the streams.

Even spending hours in investigation, I have not found the place, where the content of a file, an stream or an socket gets tied to a function, which will make this audible.

It took me hours, to find out, that mopidy seems to be just a frontend to GStreamer, however this assumption comes only from what I see in internal/gi.py. Nothing about that in the architecture diagrams.

Can anyone provide me more information, links I might have missed or other sources of information?

2

I don’t think I can provide the answer you are looking for. A detailed understanding of how Mopidy core works should not be necessary for writing an extension to provide a new music source (backend) or a new way to control Mopidy (frontend). The core API is fully documented and should provide ways to do everything you’ve listed. Examples of using it can be found in existing extensions. Mopidy-File backend might be a good place to start with a simple Backend. For a simple frontend, you could look at Mopidy-Raspberry-GPIO.

How about we start from the top: what are you trying to do? If you just want to play some local files on your computer then Mopidy-File and Mopiyd-Local do this, you don’t need to reinvent them.

3

Its not about reinvention, its about understanding. For me its important, to understand, how things work, not only using APIs and forget about the rest. This approach is one of the top sources of most security issues, as people have no idea, what will happen with their code.
One easy example: Given my assumption, that GStreamer is handling all the codecs and other stuff, people using mopidy or developing frontends/backends should know about. Unfortunately I found nothing about this in the documentation.
When a security issue pops up, that tells, that devices using GStreamer are at risk, when playing from malicious streaming sources, you could think: “Oh, i am fine, I use mopidy for streaming!”
Many projects are starting to include a SBOM (software bill of materials) for those reasons.

The next and also important thing is: If I understand, whats going on below a used API, I can use this API much more efficient and I am able to recognize, where and why my code may fail.

I can first use an API, if I understand, how this is working.

From other software projects, I made also the experience, that when developers started documenting their stuff in a way, that others could be able within hours.

If you know more details, why you can’t provide me with some documentation, how the things in mopidy-file and mopidy-local exactly work in detail?
mopidy-raspberry-gpio is useless, as i can’t see any information, about which track is played or the possibility to decide which of the available tracks should be played in my second example.

4

The documentation is relatively clear about the dependency on GStreamer: It is said in the “Audio” section of the page devoted to the architecture, cf. Architecture — Mopidy 3.4.2 documentation.

Hopefully, Mopidy and its documentation have open sources and you can submit improvements via a merge request…

I’d like to take advantage of your message to say that, as a Mopidy user, client developer and modest contributor to extensions, I find the documentation neat and, without being perfect, it is clearly superior to many open source projects! Many thanks to maintainers!

2 Likes
5

Sorry, that is far from being clear. Looks like, I have overseen this small hint. When a large part of the functionality comes from a third party library this, I would expect, to see this in the diagrams above.
I really think, that explaining the relationship to such a big third party piece, should have a own chapter in the documentation.

And before submitting improvements, I need to understand how things are working.
Currently, I can only ask questions and point out, what is missing from my point of view.
If someone would be willing, to answer some of my questions or give me some directions, this thread could be the source of some improvements, and yes: If I finally will be able to understand, I would be glad, to submit changes.

Especially in current times of distributed software development, I would expect in the very first chapter of the documentation the verbal equivalent of a SBOM.

6

People will answer specific questions, if they have time and interest in doing so. We’ve tried to provide the most useful documentation we can, with the time and resources we have.

I’m going to stop there. Thanks for your feedback.