Create a .desktop entry specification to make NSM-client-support discovery reliable and fast

[diovudau]

At the moment there is no programmatic way parse a system for installed NSM-capable clients.
Internal and IRC discussions about this have been going on for some time, hereby transferred to the public eye.

A proposed solution is a new entry in clients XDG .desktop files. It specifies the command that nsmd should call.
This will be added as a SHOULD-rule in the API docs and it is in the clients best interest.

Support in existent clients will be gained by spreading the word, asking nicely and submitting code-patches.

A GUI can also supplement the list of discovered programs through an internal database. However, this can only be a fallback because it is based on human knowledge.

This has interaction with a potential list of marketing-information on our potential website/documenation. If it is very easy and convenient for the public to inform us of nsm-capable clients, that we are unaware of, we can establish contact with the clients developers and lend a helping hand. (Same goes for an "official" NSM Wishlist)

[falkTX]

A few applications are already using X-NSM-Capable=true in desktop files.
If the same application has several ways to start within NSM (like carla does) it can have NoDisplay=true in multiple separate files so these extra ones don't show up as menu entry.

It is important that this is a boolean value, so that it can be manually set to off if needed. (for example, user override of this value via local files as a way to filter specific entries; could be used also as post-install step in some projects where NSM/liblo is optional at build-time)
So applications scanning the desktop files need to make sure to read the value and it be "true".

I wonder if it is useful to also have some string dedicated to NSM servers.
If not, then X-NSM-Capable=true seems good enough for me already.

[falkTX]

Regarding custom values in desktop files, see https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#extending

If one particular party wishes to add a field for personal use, they should prefix the key with the string X-PRODUCT, e.g. X-NewDesktop-Foo,

[diovudau]

A boolean for easy maintenance and packaging is fine. However, it must be ensured that the binary in the desktop file is actually the name that nsmd must use to start the program. By ensured I mean described in the NSM-specs so that programs can use the correct format.
I believe, when I wrote the issue in July 2020, there was at least one example where this was not the case.

[Houston4444]

All things said here seems good to me. It's a good idea to take the key Carla already use.
Boolean takes sense for build reasons indeed.

I wonder if it is useful to also have some string dedicated to NSM servers.

Humm, I don't see any interest to that... I am not opposite, but I don't see.

[diovudau]

Can we have an example of a proper .desktop file here? Ideally with a more complex or problematic usecase.

[falkTX]

You can see the carla ones at https://github.com/falkTX/Carla/tree/main/data/desktop
Only carla.desktop and carla-control.desktop are visible on the desktop environment, and these do not have NSM capable keys.

This is intentional, because the main carla will have its engine mode based on the last used settings. Which can lead to issues when used on a session manager, as the next-loading behaviour will depend on inconsistent prior settings.
So the 4 desktop files in there that have the NSM capable key are the ones that are not visible on the desktop environment (if this is a good decision or not is debatable)
But it works best this way IMO, since then the behaviour is consistent - carla-jack-multi will always start carla with JACK driver in multi-client mode. Similarly, carla-rack will always start carla in its rack mode. You get the idea.

[diovudau]

I would like to propose a coordinated effort on getting the desktop file situation in all known nsm-clients, supplemented by me writing this in the API document (as mentioned above). Maybe we choose a week or two to help all clients, writing pull requests etc.

Before that I want to mention once more the possibility that the exec=... line in the desktop file may not be the binary used as an nsm client. Honestly, I forgot in which program that happened, or if it happened at all. Any ideas?

[Houston4444]

It is implemented in Hydrogen: Houston4444/hydrogen#1
Guitarix: https://github.com/brummer10/guitarix/releases/tag/V0.43.0
I'am pretty sure there is another one, but I can't remember and find which one...

Note (minor): In Carla desktop files, the used key is X-NSM-capable=true, where for others it is X-NSM-Capable=true ("Capable" capitalized). RaySession checks the lowercase, so it doesn't matters, I suggest to make the same.

[Houston4444]

Which programs are still missing this key ?

• AmSynth,
• Ardour,
• ZynAddSubFx,
• Vee One Suite,
• QTractor,
• Mamba
• others ?

[diovudau]

We have a list of NSM programs here:
https://github.com/jackaudio/new-session-manager/wiki

[diovudau]

/usr/share/applications/zynaddsubfx-jack.desktop does not have that added yet. But let's imagine it has. Then this is the executable that nsm should start:
Exec=zynaddsubfx -I jack -O jack

As we know it is impossible for nsmd to have command line arguments. Now should all starter applications parse the exec string to find out the actual name? That is not trivial. While uncommon spaces are allowed in file names, even executables. This makes it impossible to distinguish them fro a program that e.g. does not use -- or - as parameters.
A bit milder carla, and others, use exec "carla-rack %u" as their command. So that needs filtering out as well. % is a valid char for a filename as well, btw.

So, we need the explicit exec name that can be used with nsmd. My suggestion is to have that as .desktop entry. Since @falkTX absolutely wants the x-nsm-capable entry to be a bool that would be a second entry x-nsm-exec .
Is there another way to find that exec?

[diovudau]

sidenote: amsynth Exec entry is a full path /usr/bin/amsynth. That is standard-conform:
https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#exec-variables

[falkTX]

Nice catch. Using X-NSM-Exec seems the best approach to me, I can add this for carla 2.4.3

[diovudau]

Ok, this takes care of problematic chars in the executable name and makes separating by space possible to find the exec name.

[...] Arguments are separated by a space. Arguments may be quoted in whole. If an argument contains a reserved character the argument must be quoted. The rules for quoting of arguments is also applicable to the executable name or path of the executable program as provided.

But that doesn't solve the absolute path option. And who knows what else is lurking in the XDG specs...

So: Explicit is better than implicit. x-nsm-exec sounds robust. On my arch system, with all pro-audio installed, only carla, lupp and guitarix are using the x-nsm-capable key so far. That means for most of the clients the next request, after this all is in the API docs, will be the first request. And not a repeated "change again please!" one.

[falkTX]

The x-nsm-exec entry must be a non-absolute and non-relative path, simply the filename as per NSM requirements.
That ensures we can use the value as-is.

[diovudau]

Regarding case sensitivity. It MUST be spelled only one way. I've had a look at some XDG libraries, and at least some of them are case sensitive.

X-NSM-Capable=true
X-NSM-Exec=jackpatch
NoDisplay=true

NoDisplay is useful for tools that only work with nsm, like jackpatch and nsm-data in Agordejo.

NoDisplay | NoDisplay means "this application exists, but don't display it in the menus". This can be useful to e.g. associate this application with MIME types, so that it gets launched from a file manager (or other apps), without having a menu entry for it (there are tons of good reasons for this, including e.g. the netscape -remote, or kfmclient openURL kind of stuff). | boolean