2 ! title Non Session Management API
3 ! author Jonathan Moore Liles #(email,male@tuxfamily.org)
8 : Non Session Management API version 0.8
10 The Non Session Management API is used by the various components of
11 the Non audio production suite to allow any number of independent
12 programs to be managed together as part of a logical session (i.e. a
13 song). Thus, operations such as loading and saving are synchronized.
15 The API comprises a simple Open Sound Control (OSC) based protocol,
16 along with some behavioral guidelines, which can easily be
17 implemented by various applications.
19 The Non project contains an program called `nsmd` which is an
20 implementation of the server side of the NSM API. `nsmd` is
21 controlled by the `non-session-manager` GUI. However, the same
22 server-side API can also be implemented by other session managers
23 (such as LADISH), although consistency and robustness will likely
24 suffer if non-NSM compliant clients are allowed to participate in a
27 The only dependency for client implementations `liblo` (the OSC
28 library), which several Linux audio applications already link to or
29 plan to link to in the future.
31 The aim of this project is to thoroughly define the behavior
32 required of clients. This is an area where other attempts at session
33 management (LASH and JACK-Session) have failed. Often the difficulty
34 with these systems has been not in implementing support for them,
35 but in attempting to interpret the confusing, ambiguous, or
36 ill-conceived API documentation. For these reasons and more all
37 previous attempts at Linux audio session management protocols are
40 You *WILL* see some unambiguous and emphatic language in this
41 document. For the good of the user, these rules are meant to be
42 followed and are non-negotiable. If an application does not conform
43 to this specification it should be considered broken. Consistency
44 across applications under session management is very important for a
47 :: Client Behavior Under Session Management
49 Most graphical applications make available to the user a common set
50 of file operations, typically presented under a File or Project
53 These are: New, Open, Save, Save As, Close and Quit or Exit.
55 The following sub-sections describe how these options should behave when
56 the application is part of an NSM session. These rules only apply
57 when session management is active (that is, after the `announce`
58 handshake described in the #(ref,NSM OSC Protocol) section).
60 In order to provide a consistent and predictable user experience, it
61 is critically important for applications to adhere to these
66 This option may empty\/reset the current file or project (possibly
67 after user confirmation). *UNDER NO CIRCUMSTANCES* should it allow
68 the user to create a new project\/file in another location.
72 This option *MUST* be disabled.
74 The application may, however, elect to implement an option called
75 'Import into Session', creates a copy of a file\/project which is
76 then saved at the session path provided by NSM.
80 This option should behave as normal, saving the current
81 file\/project as established by the NSM `open` message.
83 *UNDER NO CIRCUMSTANCES* should this option present the user with a
84 choice of where to save the file.
88 This option *MUST* be disabled.
90 The application may, however, elect to implement an option called
91 'Export from Session', which creates a copy of the current
92 file\/project which is then saved in a user-specified location
93 outside of the session path provided by NSM.
95 ::: Close (as distinguished from Quit or Exit)
97 This option *MUST* be disabled unless its meaning is to disconnect
98 the application from session management.
102 This option may behave as normal (even possibly asking the user to
107 All message parameters are *REQUIRED*. All messages *MUST* be sent
108 from the same socket as the `announce` message, using the
109 `lo\_send\_from` method of liblo or its equivalent, as the server uses
110 the return addresses to distinguish between clients.
112 ::: Establishing a Connection
116 At launch, the client *MUST* check the environment for the value of
117 `NSM\_URL`. If present, the client *MUST* send the following message
118 to the provided address as soon as it is ready to respond to the
119 `\/nsm\/client\/open` event:
121 > /nsm/server/announce s:application_name s:capabilities i:api_version_major i:api_version_minor i:pid
123 If `NSM\_URL` is undefined, invalid, or unreachable, then the client
124 should proceed assuming that session management is unavailable.
126 `api\_version\_major` and `api\_version\_minor` must be the two
127 parts of the version number of the NSM API as defined by this
130 Note that if the application intends to register JACK clients,
131 `application\_name` *MUST* be the same as the name that would
132 normally by passed to `jack\_client\_open`. For example, Non-Mixer
133 sends "Non-Mixer" as its `application\_name`. Applications *MUST
134 NOT* register their JACK clients until receiving an `open` message;
135 the `open` message will provide a unique client name prefix suitable
136 for passing to JACK. This is probably the most complex requirement
137 of the NSM API, but it isn't difficult to implement, especially if
138 the application simply wishes to delay its initialization process
139 for up to one second while awaiting the `announce` reply and
140 subsequent `open` message.
142 `capabilities` *MUST* be a string containing a colon separated list
143 of the special capabilities the client
144 possesses. e.g. ":dirty:switch:progress:"
146 // Available Client Capabilities
148 [[ switch, client is capable of responding to multiple `open` messages without restarting
149 [[ dirty, client knows when it has unsaved changes
150 [[ progress, client can send progress updates during time-consuming operations
151 [[ message, client can send textual status updates
155 The server will respond to the client's `announce` message with the
158 > /reply "/nsm/server/announce" s:message s:name_of_session_manager s:capabilities
160 `message` is a welcome message.
162 The value of `name\_of\_session\_manager` will depend on the
163 implementation of the NSM server. It might say "Non Session
164 Manager", or it might say "LADISH". This is for display to the user.
166 `capabilities` will be a string containing a colon separated list of
167 special server capabilities.
169 Presently, the server `capabilities` are:
171 // Available Server Capabilities
173 [[ server_control, client-to-server control
175 A client should not consider itself to be under session management
176 until it receives this response. For example, the Non applications
177 activate their "SM" blinkers at this time.
179 If there is an error, a reply of the following form will be sent to
182 > /error "/nsm/server/announce" i:error_code s:error_message
184 The following table defines possible values of `error\_code`:
188 [[ ERR_GENERAL, General Error
189 [[ ERR_INCOMPATIBLE_API, Incompatible API version
190 [[ ERR_BLACKLISTED, Client has been blacklisted.
192 ::: Server to Client Control Messages
194 Compliant clients *MUST* accept the client control messages
195 described in this section. All client control messages *REQUIRE* a
196 response. Responses *MUST* be delivered back to the sender (NSM)
197 from the same socket used by the client in its `announce` message
198 (by using `lo\_send\_from`) *AFTER* the action has been completed or
199 if an error is encountered. The required response is described in
200 the subsection for each message.
202 If there is an error and the action cannot be completed, then
203 `error\_code` *MUST* be set to a valid error code (see #(fig,Error Code Definitions))
204 and `message` to a string describing the problem (suitable
205 for display to the user).
207 The reply can take one of the following two forms, where `path` *MUST* be
208 the path of the message being replied to (e.g. "/nsm\/client\/save"):
210 > /reply s:path s:message
212 > /error s:path i:error_code s:message
216 There is no message for this. Clients will receive the Unix SIGTERM
217 signal and *MUST* close cleanly *IMMEDIATELY*, without displaying
218 any kind of dialog to the user and regardless of whether or not
219 unsaved changes would be lost. When a session is closed the
220 application will receive this signal soon after having responded to
225 > /nsm/client/open s:path_to_instance_specific_project s:display_name s:client_id
227 `path\_to\_instance_specific\_project` is a path name assigned to
228 the client for storing its project data.
230 The client may append to the path, creating a sub-directory,
231 e.g. '/song.foo' or simply append the client's native file extension
232 (e.g. '.non' or '.XML'). The same transformation *MUST* be applied
233 to the name when opening an existing project, as NSM will only
234 provide the instance specific part of the path.
236 If a project exists at the path, the client *MUST* immediately open
239 If a project does not exist at the path, then the client *MUST*
240 immediately create and open a new one at the specified path or, for
241 clients which hold all their state in memory, store the path for
242 later use when responding to the `save` message.
244 No file or directory will be created at the specified path by the
245 server. It is up to the client to create what it needs.
247 For clients which *HAVE NOT* specified the `:switch:` capability,
248 the `open` message will only be delivered once, immediately
249 following the `announce` response.
251 For clients which *HAVE* specified the `:switch:` capability, the
252 client *MUST* immediately switch to the specified project or create
253 a new one if it doesn't exist.
255 Clients which are incapable of switching projects or are prone to
256 crashing upon switching *MUST NOT* include `:switch:` in their
259 If the user the is allowed to run two or more instances of the
260 application simultaneously (that is to say, there is no technical
261 limitation preventing them from doing so, even if it doesn't make
262 sense to the author), then such an application *MUST PRE-PEND* the
263 provided `client\_id` string to any names it registers with common
264 subsystems (e.g. JACK client names). This ensures that multiple
265 instances of the same application can be restored in any order
266 without scrambling the JACK connections or causing other
267 conflicts. The provided `client\_id` will be a concatenation of the
268 value of `application\_name` sent by the client in its `announce`
269 message and a unique identifier. Therefore, applications which
270 create single JACK clients can use the value of `client\_id` directly
271 as their JACK client name. Applications which register multiple JACK
272 clients (e.g. Non-Mixer) *MUST PRE-PEND* `client\_id` value to the
273 client names they register with JACK and the application determined
274 part *MUST* be unique for that (JACK) client.
276 For example, a suitable JACK client name would be:
280 Note that this means that the application *MUST NOT* register with
281 JACK (or any other subsystem requiring unique names) until it
282 receives an `open` message from NSM. Likewise, applications with the
283 `:switch:` capability should close their JACK clients and re-create
284 them with using the new `client\_id`. Re-registering is necessary
285 because the JACK API does currently support renaming existing
286 clients, although this is a sorely needed addition.
288 A response is *REQUIRED* *AFTER* the open operation has been
289 completed. Ongoing progress may be indicated by sending messages to
290 `\/nsm\/client\/progress`.
294 The client *MUST* respond to the 'open' message with:
296 > /reply "/nsm/client/open" s:message
300 > /error "/nsm/client/open" i:error_code s:message
304 [[ ERR, General Error
305 [[ ERR_BAD_PROJECT, An existing project file was found to be corrupt
306 [[ ERR_CREATE_FAILED, A new project could not be created
307 [[ ERR_UNSAVED_CHANGES, Unsaved changes would be lost
308 [[ ERR_NOT_NOW, Operation cannot be completed at this time
314 The client *MUST* immediately save the current application specific
315 project data to the project path previously established in the
316 'open' message. *UNDER NO CIRCUMSTANCES* should a dialog be
317 displayed to the user (giving a choice of where to save, etc.)
319 This message will only be delivered after a previous `open` message,
320 and may be sent any number of times within the course of a session
321 (including zero, if the user aborts the session).
325 The client *MUST* respond to the 'save' message with:
327 > /reply "/nsm/client/save" s:message
331 > /error "/nsm/client/save" i:error_code s:message
335 [[ ERR, General Error
336 [[ ERR_SAVE_FAILED, Project could not be saved
337 [[ ERR_NOT_NOW, Operation cannot be completed at this time
339 ::: Server to Client Informational Messages
341 :::: Session is Loaded
343 Accepting this message is optional. The intent is to signal to
344 clients which may have some interdependence (say, peer to peer OSC
345 connections) that the session is fully loaded and all their peers
348 > /nsm/client/session_is_loaded
350 This message does not require a response.
352 ::: Client to Server Informational Messages
354 These are optional messages which a client can send to the NSM
355 server to inform it about the client's status. The client should not
356 expect any reply to these messages. If a client intends to send a
357 message described in this section, then it *MUST* add the
358 appropriate value to its `capabilities` string when composing the
363 > /nsm/client/progress f:progress
365 For potentially time-consuming operations, such as `save` and
366 `open`, progress updates may be indicated throughout the duration by
367 sending a floating point value between 0.0 and 1.0, 1.0 indicating
368 completion, to the NSM server.
370 The server will not send a response to these messages, but will
371 relay the information to the user.
373 Note that even when using the `progress` feature, the final
374 response to the `save` or `open` message is still *REQUIRED*.
376 Clients which intend to send `progress` messages should include
377 `:progress:` in their `announce` capability string.
381 > /nsm/client/is_dirty
383 > /nsm/client/is_clean
385 Some clients may be able to inform the server when they have unsaved
386 changes pending. Such clients may optionally send `is\_dirty` and `is\_clean`
389 Clients which have this capability should include `:dirty:` in their
390 `announce` capability string.
394 > /nsm/client/message i:priority s:message
396 Clients may send miscellaneous status updates to the server for
397 possible display to the user. This may simply be chatter that is
398 normally written to the console. `priority` should be a number from
399 0 to 3, 3 being the most important.
401 Clients which have this capability should include `:message:` in their
402 `announce` capability string.
404 ::: Error Code Definitions
406 // Error Code Definitions
407 [[ Symbolic Name, Integer Value
409 [[ ERR_INCOMPATIBLE_API, -2
410 [[ ERR_BLACKLISTED, -3
411 [[ ERR_LAUNCH_FAILED, -4
412 [[ ERR_NO_SUCH_FILE, -5
413 [[ ERR_NO_SESSION_OPEN, -6
414 [[ ERR_UNSAVED_CHANGES, -7
416 [[ ERR_BAD_PROJECT, -9
417 [[ ERR_CREATE_FAILED, -10
419 ::: Client to Server Control
421 If the server publishes the `:server\_control:` capability, then
422 clients can also initiate action by the server. For example, a
423 client might implement a 'Save All' option which sends a
424 `\/nsm\/server\/save` message to the server, rather than requiring
425 the user to switch to the session management interface to effect the
428 ::: Server Control API
430 The session manager not only manages clients via OSC, but it is
431 itself controlled via OSC messages. The server responds to the
434 All of the following messages will be responded to back to the
435 sender's address with one of the two following messages:
437 > /reply s:path s:message
439 > /error s:path i:error_code s:message
441 The first parameter of the reply is the path to the message being
442 replied to. The `\/error` reply includes an integer error code
443 (non-zero indicates error). `message` will be a description of the
446 The possible errors are:
450 [[ ERR_GENERAL, General Error
451 [[ ERR_LAUNCH_FAILED, Launch failed
452 [[ ERR_NO_SUCH_FILE, No such file
453 [[ ERR_NO_SESSION, No session is open
454 [[ ERR_UNSAVED_CHANGES, Unsaved changes would be lost
456 = /nsm/server/add s:path_to_executable
457 Adds a client to the current session.
460 Saves the current session.
462 = /nsm/server/load s:project_name
463 Saves the current session and loads a new session.
465 = /nsm/server/new s:project_name
466 Saves the current session and creates a new session.
469 Saves and closes the current session.
472 Closes the current session *WITHOUT SAVING*
475 Saves and closes the current session and terminates the server.
477 = /nsm/server/duplicate s:new_project
478 Saves and closes the current session, creates a complete copy of
479 it as `new_project` and opens it. The existing project should ideally be
480 a lightweight template, as copying any audio data could be very time
484 Lists available projects. One `\/reply` message will be sent for each existing project.
486 :::: Client to Client Communication
488 If the server includes `:broadcast:` in its capability string, then
489 clients may send broadcast messages to each other through the NSM
492 Clients may send messages to the server at the path
495 The format of this message is as follows:
497 > /nsm/server/broadcast [any parameters...]
499 The message will then be relayed to all clients in the session at
500 the path `\/nsm\/client\/broadcast`.
502 For example the message:
504 > /nsm/server/broadcast /tempomap/update "0,120,4/4:12351234,240,4/4"
506 Would broadcast the following message to all clients in the session
507 (except for the sender), some of which might respond to the message
508 by updating their own tempo maps. Here the string
509 `\/tempomap\/update` is not an OSC path but merely a name-space
510 qualifier by which the receivers can filter messages.
512 > /nsm/client/broadcast /tempomap/update "0,120,4/4:12351234,240,4/4"
514 Clients might use this feature to establish peer to peer OSC
515 communication with symbolic names without having to remember the OSC
516 ports of peers across sessions.