|
|
|
@@ -1,6 +1,9 @@ |
|
|
|
//// |
|
|
|
This is "asciidoctor", not plain "asciidoc". |
|
|
|
https://asciidoctor.org/docs/user-manual/ |
|
|
|
|
|
|
|
100 characters per line (soft limit). |
|
|
|
|
|
|
|
//// |
|
|
|
|
|
|
|
|
|
|
|
@@ -12,8 +15,12 @@ A copy of the license has been provided in the file documentation/API/LICENSE. |
|
|
|
//// |
|
|
|
|
|
|
|
|
|
|
|
//// |
|
|
|
The revnumber API 1.1.1 below is autogenerated. Please do not touch this line. |
|
|
|
//// |
|
|
|
|
|
|
|
:authors: Jonathan Moore Liles, Nils Hilbricht |
|
|
|
:revnumber: API 1.1.1 |
|
|
|
:revnumber: API 1.1.2 |
|
|
|
:revremark: License CC-By-SA v2.5 |
|
|
|
:iconfont-remote!: |
|
|
|
:!webfonts: |
|
|
|
@@ -161,6 +168,23 @@ to. Some unique component may be required to prevent collisions. |
|
|
|
|
|
|
|
==== Session Root and Session Directories |
|
|
|
|
|
|
|
Client programs MUST NOT handle the following themselves. This section is background-information. |
|
|
|
|
|
|
|
NSM follows the link:https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG Base Directory Specifications] |
|
|
|
|
|
|
|
All existing and new sessions are directories below the session-root, which defaults to |
|
|
|
`$XDG_DATA_HOME/nsm/`, which usually results in `$HOME/.local/share/nsm/`. |
|
|
|
|
|
|
|
Each session directory contains a file `session.nsm` with one client per line `name:executable:UID\n` |
|
|
|
For example: |
|
|
|
``` |
|
|
|
JACKPatch:jackpatch:nBEIQ |
|
|
|
jack_mixer:jack_mixer:nTXHV |
|
|
|
Carla-Rack:carla-rack:nFAOD |
|
|
|
``` |
|
|
|
`nsmd` loads and saves this file, client names are their self-reported names. |
|
|
|
The file format is final and frozen. Additions or changes SHALL NOT be made. |
|
|
|
|
|
|
|
===== Subdirectories / Hierarchical Structure |
|
|
|
|
|
|
|
Subdirectories MAY be made to organize sessions into meaningful structures, such as album/track or |
|
|
|
@@ -177,6 +201,32 @@ Any session itself MUST be a "leaf" in this directory tree. A session MUST NOT c |
|
|
|
session subdirectories: any directory that contains a file `session.nsm` is the final |
|
|
|
element in the hierarchy. |
|
|
|
|
|
|
|
===== Lockfiles |
|
|
|
|
|
|
|
Because multiple `nsmd` can run at the same time we need to prevent accidental write-access to the |
|
|
|
same session by different nsm-daemons, and subsequently GUIs. |
|
|
|
|
|
|
|
Therefore each currently open session creates a lockfile under `$XDG_RUNTIME_DIR/nsm/` (usually |
|
|
|
`/run/user/XXXX/nsm/`) that tells `nsmd` to not open such a locked session. This directory gets |
|
|
|
cleaned by the operating system, preventing sessions to stay locked after e.g. a power failure. |
|
|
|
|
|
|
|
The lockfile is named after the simple session name combined with a numeric ID for the session |
|
|
|
root. It is possible that two `nsmd` opened two different session roots, both with the same simple |
|
|
|
session name, e.g. "my song". Lockfiles are able to distinguish between those and will not prevent |
|
|
|
access in this scenario. The numeric ID is a djb2 hash modulo (%) 65521 of the session root directory |
|
|
|
(see `src/file.cpp` function `simple_hash()`). |
|
|
|
|
|
|
|
|
|
|
|
The lockfile contains, on separate lines: |
|
|
|
|
|
|
|
* The absolute path to the session, including the root-dir, which could be overriden by `nsmd --session-root`, allowing two sessions of the same basic name in different roots. |
|
|
|
* the OSC URL of the server that runs this session, the same as `$NSM_URL`. |
|
|
|
|
|
|
|
Example: |
|
|
|
``` |
|
|
|
/home/johann/.local/share/nsm/cantatas/easter1751 |
|
|
|
osc.udp://myuser.localdomain:11287/ |
|
|
|
|
|
|
|
|
|
|
|
== NSM OSC Protocol |
|
|
|
|
|
|
|
@@ -751,8 +801,8 @@ PATCH version when you make backwards compatible bug fixes. |
|
|
|
|Non Session Manager at moment of fork | 1.2 (June 2020) |
|
|
|
|Non Session Manager API | 1.0 link:https://github.com/original-male/non/blob/master/session-manager/src/nsmd.C[NON nsmd.C] |
|
|
|
|Original API Document | 1.0 link:http://non.tuxfamily.org/nsm/API.html[non.tuxfamily.org/nsm/API.html] |
|
|
|
|New Session Manager | 1.5.0 |
|
|
|
|New Session Manager API | 1.1.1 link:https://github.com/jackaudio/new-session-manager/blob/master/src/nsmd.cpp[NEW nsmd.cpp] |
|
|
|
|New Session Manager | 1.6.0 |
|
|
|
|New Session Manager API | 1.1.2 link:https://github.com/jackaudio/new-session-manager/blob/master/src/nsmd.cpp[NEW nsmd.cpp] |
|
|
|
|New API Document | 1.5.0 link:#[Here] |
|
|
|
|
|
|
|
|=== |
|
|
|
@@ -851,3 +901,9 @@ patch-level from 1.1.0 to 1.1.1 |
|
|
|
* Add API-section "Subdirectories / Hierarchical Structure" that explains the session directory. |
|
|
|
This behaviour was already the case for nsm-legacy-gui and nsmd 1.5.0 was patched to adhere to this |
|
|
|
behaviour more strictly as well, removing false session entries in 3rd party clients such as Agordejo. |
|
|
|
|
|
|
|
=== Changes in API Version 1.1.2 |
|
|
|
|
|
|
|
* nsmd now follows the XDG Base Directory Specifications for it's session root and lock files. This |
|
|
|
if of no consequence to clients but required documentation nevertheless, which was described as |
|
|
|
"background information" in the new section. |
Nils
3 years ago