mirrors
/
non
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

NSM: Update documentation.

This commit is contained in:
Jonathan Moore Liles 2012-02-20 22:19:38 -08:00
parent b9f297bb20
commit 58a4cd1537
1 changed files with 116 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

196
session/doc/NSM.mu
View File

@ -5,36 +5,44 @@
-- Table Of Contents -- Table Of Contents
: Non Session Management API version 0.7 : Non Session Management API version 0.8
The Non Session Management API is an API for session management used The Non Session Management API is used by the various components of
by the various parts of the Non music production suite. It comprises the Non audio production suite to allow any number of independent
a simple OSC based protocol which can easily be implemented by other programs to be managed together as part of a logical session (i.e. a
applications. NSM provides robust session management, including song). Thus, operations such as loading and saving are synchronized.
interactive features.
The Non project contains an implementation of the NSM server API The API comprises a simple Open Sound Control (OSC) based protocol,
called `nsmd` which can be controlled by the `non-session-manager` along with some behavioral guidelines, which can easily be
GUI, but the same server API can easily be implemented by other implemented by various applications.
session managers (such as LADISH).
The only dependency for clients `liblo` (the OSC library), which The Non project contains an program called `nsmd` which is an
several Linux audio applications already link to or plan to link to implementation of the server side of the NSM API. `nsmd` is
in the future. controlled by the `non-session-manager` GUI. However, the same
server-side API can also be implemented by other session managers
(such as LADISH), although consistency and robustness will likely
suffer if non-NSM compliant clients are allowed to participate in a
session.
The only dependency for client implementations `liblo` (the OSC
library), which several Linux audio applications already link to or
plan to link to in the future.
The aim of this project is to thoroughly define the behavior The aim of this project is to thoroughly define the behavior
required of clients. This is an area where other attempts at session required of clients. This is an area where other attempts at session
management (LASH and JACK-Session) have failed. Often the difficulty management (LASH and JACK-Session) have failed. Often the difficulty
with these previous system been, not in implementing support for with these systems has been not in implementing support for them,
them, but in attempting to interpret the confusing and ambiguous API but in attempting to interpret the confusing, ambiguous, or
documentation. For this reason, all LASH support has been removed ill-conceived API documentation. For these reasons and more all
from Non. previous attempts at Linux audio session management protocols are
considered harmful.
You *WILL* see a lot of unambiguous language in this document. These You *WILL* see some unambiguous and emphatic language in this
rules are meant to be followed and are non-negotiable. If an document. For the good of the user, these rules are meant to be
application does not conform to this specification it should be followed and are non-negotiable. If an application does not conform
considered broken. Consistency across applications under session to this specification it should be considered broken. Consistency
management is very important for a good user experience. across applications under session management is very important for a
good user experience.
:: Client Behavior Under Session Management :: Client Behavior Under Session Management
@ -50,7 +58,8 @@
handshake described in the #(ref,NSM OSC Protocol) section). handshake described in the #(ref,NSM OSC Protocol) section).
In order to provide a consistent and predictable user experience, it In order to provide a consistent and predictable user experience, it
is important for applications to adhere to these guidelines. is critically important for applications to adhere to these
guidelines.
::: New ::: New
@ -60,11 +69,11 @@
::: Open ::: Open
This option should be disabled. This option *MUST* be disabled.
The application may, however, elect to implement an option called The application may, however, elect to implement an option called
'Import into Session', creates a copy of a file\/project which is 'Import into Session', creates a copy of a file\/project which is
then saved in the session path provided by NSM. then saved at the session path provided by NSM.
::: Save ::: Save
@ -72,11 +81,11 @@
file\/project as established by the NSM `open` message. file\/project as established by the NSM `open` message.
*UNDER NO CIRCUMSTANCES* should this option present the user with a *UNDER NO CIRCUMSTANCES* should this option present the user with a
choice of where to save the file! choice of where to save the file.
::: Save As ::: Save As
This option should be disabled. This option *MUST* be disabled.
The application may, however, elect to implement an option called The application may, however, elect to implement an option called
'Export from Session', which creates a copy of the current 'Export from Session', which creates a copy of the current
@ -85,7 +94,7 @@
::: Close (as distinguished from Quit or Exit) ::: Close (as distinguished from Quit or Exit)
This option should be disabled, unless its meaning is to disconnect This option *MUST* be disabled unless its meaning is to disconnect
the application from session management. the application from session management.
::: Quit or Exit ::: Quit or Exit
@ -97,14 +106,14 @@
All message parameters are *REQUIRED*. All messages *MUST* be sent All message parameters are *REQUIRED*. All messages *MUST* be sent
from the same socket as the `announce` message, using the from the same socket as the `announce` message, using the
`lo\_send\_from` method of liblo (the server uses the return `lo\_send\_from` method of liblo or its equivalent, as the server uses
addresses to distinguish between clients). the return addresses to distinguish between clients.
::: Establishing a Connection ::: Establishing a Connection
:::: Announce :::: Announce
When started clients *MUST* check the environment for the value of At launch, the client *MUST* check the environment for the value of
`NSM\_URL`. If present, the client *MUST* send the following message `NSM\_URL`. If present, the client *MUST* send the following message
to the provided address as soon as it is ready to respond to the to the provided address as soon as it is ready to respond to the
`\/nsm\/client\/open` event: `\/nsm\/client\/open` event:
@ -114,8 +123,9 @@
If `NSM\_URL` is undefined, invalid, or unreachable, then the client If `NSM\_URL` is undefined, invalid, or unreachable, then the client
should proceed assuming that session management is unavailable. should proceed assuming that session management is unavailable.
`api\_version\_major` and `api\_version\_minor` must be the two parts of `api\_version\_major` and `api\_version\_minor` must be the two
the version number of the NSM API as defined by this document. parts of the version number of the NSM API as defined by this
document.
Note that if the application intends to register JACK clients, Note that if the application intends to register JACK clients,
`application\_name` *MUST* be the same as the name that would `application\_name` *MUST* be the same as the name that would
@ -124,7 +134,10 @@
NOT* register their JACK clients until receiving an `open` message; NOT* register their JACK clients until receiving an `open` message;
the `open` message will provide a unique client name prefix suitable the `open` message will provide a unique client name prefix suitable
for passing to JACK. This is probably the most complex requirement for passing to JACK. This is probably the most complex requirement
of the NSM API, but it isn't difficult to implement. of the NSM API, but it isn't difficult to implement, especially if
the application simply wishes to delay its initialization process
for up to one second while awaiting the `announce` reply and
subsequent `open` message.
`capabilities` *MUST* be a string containing a colon separated list `capabilities` *MUST* be a string containing a colon separated list
of the special capabilities the client of the special capabilities the client
@ -135,19 +148,20 @@
[[ switch, client is capable of responding to multiple `open` messages without restarting [[ switch, client is capable of responding to multiple `open` messages without restarting
[[ dirty, client knows when it has unsaved changes [[ dirty, client knows when it has unsaved changes
[[ progress, client can send progress updates during time-consuming operations [[ progress, client can send progress updates during time-consuming operations
[[ status, client can send textual status updates [[ message, client can send textual status updates
:::: Response :::: Response
The server will respond to the client's `announce` with the following message: The server will respond to the client's `announce` message with the
following message:
> /reply "/nsm/server/announce" s:message s:name_of_session_manager s:capabilities > /reply "/nsm/server/announce" s:message s:name_of_session_manager s:capabilities
`message` is a welcome message. `message` is a welcome message.
The value of `name\_of\_session\_manager` will depend on the The value of `name\_of\_session\_manager` will depend on the
implementation of the NSM server. It might say "Non Session Manager", implementation of the NSM server. It might say "Non Session
or it might say "LADISH". Manager", or it might say "LADISH". This is for display to the user.
`capabilities` will be a string containing a colon separated list of `capabilities` will be a string containing a colon separated list of
special server capabilities. special server capabilities.
@ -159,8 +173,8 @@
[[ server_control, client-to-server control [[ server_control, client-to-server control
A client should not consider itself to be under session management A client should not consider itself to be under session management
until it receives this response (the Non programs activate their until it receives this response. For example, the Non applications
"SM" blinkers at this time.) activate their "SM" blinkers at this time.
If there is an error, a reply of the following form will be sent to If there is an error, a reply of the following form will be sent to
the client: the client:
@ -202,36 +216,39 @@
There is no message for this. Clients will receive the Unix SIGTERM There is no message for this. Clients will receive the Unix SIGTERM
signal and *MUST* close cleanly *IMMEDIATELY*, without displaying signal and *MUST* close cleanly *IMMEDIATELY*, without displaying
any kind of dialog to the user and regardless of whether or not any kind of dialog to the user and regardless of whether or not
unsaved changes would be lost (when a session is closed the unsaved changes would be lost. When a session is closed the
application will receive this signal soon after having responded to application will receive this signal soon after having responded to
a `save` message). a `save` message.
:::: Open :::: Open
> /nsm/client/open s:path_to_instance_specific_project s:client_id > /nsm/client/open s:path_to_instance_specific_project s:display_name s:client_id
The client *MUST* open an existing project, or create new one if one `path\_to\_instance_specific\_project` is a path name assigned to
doesn't already exist, at `path\_to\_instance_specific\_project` the client for storing its project data.
If the path provided doesn't exist, then the client *MUST* The client may append to the path, creating a sub-directory,
immediately create and open a new file\/project at the specified
path (whether that means creating a single file or a project
directory).
No file or directory will be created at the specified path by the
server. It is up to the client to create what it needs.
The client may append to the path, creating a subdirectory,
e.g. '/song.foo' or simply append the client's native file extension e.g. '/song.foo' or simply append the client's native file extension
(e.g. '.non' or '.XML'). The same transformation *MUST* be applied (e.g. '.non' or '.XML'). The same transformation *MUST* be applied
to the name when opening an existing project, as NSM will only to the name when opening an existing project, as NSM will only
provide the instance specific part of the path. provide the instance specific part of the path.
For clients which *HAVE NOT* specified the 'switch' capability, the If a project exists at the path, the client *MUST* immediately open
`open` message will only be delivered once, immediately after the it.
'announce' response.
For client which *HAVE* specified the `:switch:` capability, the If a project does not exist at the path, then the client *MUST*
immediately create and open a new one at the specified path or, for
clients which hold all their state in memory, store the path for
later use when responding to the `save` message.
No file or directory will be created at the specified path by the
server. It is up to the client to create what it needs.
For clients which *HAVE NOT* specified the `:switch:` capability,
the `open` message will only be delivered once, immediately
following the `announce` response.
For clients which *HAVE* specified the `:switch:` capability, the
client *MUST* immediately switch to the specified project or create client *MUST* immediately switch to the specified project or create
a new one if it doesn't exist. a new one if it doesn't exist.
@ -242,9 +259,9 @@
If the user the is allowed to run two or more instances of the If the user the is allowed to run two or more instances of the
application simultaneously (that is to say, there is no technical application simultaneously (that is to say, there is no technical
limitation preventing them from doing so, even if it doesn't make limitation preventing them from doing so, even if it doesn't make
sense to the author), then such an application *MUST* prepend the sense to the author), then such an application *MUST PRE-PEND* the
provided `client\_id` string to any names it registers with common provided `client\_id` string to any names it registers with common
subsystems (e.g. JACK client names). This ensures that the multiple subsystems (e.g. JACK client names). This ensures that multiple
instances of the same application can be restored in any order instances of the same application can be restored in any order
without scrambling the JACK connections or causing other without scrambling the JACK connections or causing other
conflicts. The provided `client\_id` will be a concatenation of the conflicts. The provided `client\_id` will be a concatenation of the
@ -252,7 +269,7 @@
message and a unique identifier. Therefore, applications which message and a unique identifier. Therefore, applications which
create single JACK clients can use the value of `client\_id` directly create single JACK clients can use the value of `client\_id` directly
as their JACK client name. Applications which register multiple JACK as their JACK client name. Applications which register multiple JACK
clients (e.g. Non-Mixer) *MUST* prepend `client_id` value to the clients (e.g. Non-Mixer) *MUST PRE-PEND* `client\_id` value to the
client names they register with JACK and the application determined client names they register with JACK and the application determined
part *MUST* be unique for that (JACK) client. part *MUST* be unique for that (JACK) client.
@ -260,7 +277,15 @@
> $CLIENT_ID/track-1 > $CLIENT_ID/track-1
A response is *REQUIRED* *AFTER* the load\/new operation has been Note that this means that the application *MUST NOT* register with
JACK (or any other subsystem requiring unique names) until it
receives an `open` message from NSM. Likewise, applications with the
`:switch:` capability should close their JACK clients and re-create
them with using the new `client\_id`. Re-registering is necessary
because the JACK API does currently support renaming existing
clients, although this is a sorely needed addition.
A response is *REQUIRED* *AFTER* the open operation has been
completed. Ongoing progress may be indicated by sending messages to completed. Ongoing progress may be indicated by sending messages to
`\/nsm\/client\/progress`. `\/nsm\/client\/progress`.
@ -291,6 +316,10 @@
'open' message. *UNDER NO CIRCUMSTANCES* should a dialog be 'open' message. *UNDER NO CIRCUMSTANCES* should a dialog be
displayed to the user (giving a choice of where to save, etc.) displayed to the user (giving a choice of where to save, etc.)
This message will only be delivered after a previous `open` message,
and may be sent any number of times within the course of a session
(including zero, if the user aborts the session).
::::: Response ::::: Response
The client *MUST* respond to the 'save' message with: The client *MUST* respond to the 'save' message with:
@ -312,7 +341,7 @@
:::: Session is Loaded :::: Session is Loaded
Accepting this message is optional. The intent is to signal to Accepting this message is optional. The intent is to signal to
clients which may have some interdependency (say, peer to peer OSC clients which may have some interdependence (say, peer to peer OSC
connections) that the session is fully loaded and all their peers connections) that the session is fully loaded and all their peers
are available. are available.
@ -341,7 +370,7 @@
The server will not send a response to these messages, but will The server will not send a response to these messages, but will
relay the information to the user. relay the information to the user.
Note that, even when using the `progress` feature, the final Note that even when using the `progress` feature, the final
response to the `save` or `open` message is still *REQUIRED*. response to the `save` or `open` message is still *REQUIRED*.
Clients which intend to send `progress` messages should include Clients which intend to send `progress` messages should include
@ -365,9 +394,9 @@
> /nsm/client/message i:priority s:message > /nsm/client/message i:priority s:message
Clients may send miscellaneous status updates to the server for Clients may send miscellaneous status updates to the server for
possible display to the user. This may simply be chatter that is normally possible display to the user. This may simply be chatter that is
written to the console. `priority` should be a number from 0 to 3, 3 normally written to the console. `priority` should be a number from
being the most important. 0 to 3, 3 being the most important.
Clients which have this capability should include `:message:` in their Clients which have this capability should include `:message:` in their
`announce` capability string. `announce` capability string.
@ -389,7 +418,7 @@
::: Client to Server Control ::: Client to Server Control
If the server publishes the `server\_control` capability, then If the server publishes the `:server\_control:` capability, then
clients can also initiate action by the server. For example, a clients can also initiate action by the server. For example, a
client might implement a 'Save All' option which sends a client might implement a 'Save All' option which sends a
`\/nsm\/server\/save` message to the server, rather than requiring `\/nsm\/server\/save` message to the server, rather than requiring
@ -398,12 +427,12 @@
::: Server Control API ::: Server Control API
The session manager not only manages clients via OSC, but it is itself The session manager not only manages clients via OSC, but it is
controlled via OSC messages. The server responds to the following itself controlled via OSC messages. The server responds to the
messages. following messages.
All of the following messages will be responded to back to the sender's address All of the following messages will be responded to back to the
with one of the two following messages: sender's address with one of the two following messages:
> /reply s:path s:message > /reply s:path s:message
@ -454,12 +483,6 @@
= /nsm/server/list = /nsm/server/list
Lists available projects. One `\/reply` message will be sent for each existing project. Lists available projects. One `\/reply` message will be sent for each existing project.
# = /nsm/server/client/list
# Lists clients in the current session, their client IDs and statuses
# = /nsm/server/ve
:::: Client to Client Communication :::: Client to Client Communication
If the server includes `:broadcast:` in its capability string, then If the server includes `:broadcast:` in its capability string, then
@ -471,11 +494,10 @@
The format of this message is as follows: The format of this message is as follows:
> /nsm/server/broadcast s:path [other parameters...] > /nsm/server/broadcast [any parameters...]
The message will then be relayed to all clients in the session at The message will then be relayed to all clients in the session at
the path given in the `path` parameter and with the other parameters the path `\/nsm\/client\/broadcast`.
shifted forward by one.
For example the message: For example the message:
@ -483,10 +505,12 @@
Would broadcast the following message to all clients in the session Would broadcast the following message to all clients in the session
(except for the sender), some of which might respond to the message (except for the sender), some of which might respond to the message
by updating their own tempo maps. by updating their own tempo maps. Here the string
`\/tempomap\/update` is not an OSC path but merely a name-space
qualifier by which the receivers can filter messages.
> /tempomap/update "0,120,4/4:12351234,240,4/4" > /nsm/client/broadcast /tempomap/update "0,120,4/4:12351234,240,4/4"
Clients may use this feature to establish peer to peer OSC Clients might use this feature to establish peer to peer OSC
communication with symbolic names without having to remember the OSC communication with symbolic names without having to remember the OSC
URLs of peers. ports of peers across sessions.