493 lines
17 KiB
Plaintext
493 lines
17 KiB
Plaintext
|
|
! title Non Session Management API
|
|
! author Jonathan Moore Liles #(email,male@tuxfamily.org)
|
|
! date August 1, 2010
|
|
|
|
-- Table Of Contents
|
|
|
|
: Non Session Management API version 0.7
|
|
|
|
The Non Session Management API is an API for session management used
|
|
by the various parts of the Non music production suite. It comprises
|
|
a simple OSC based protocol which can easily be implemented by other
|
|
applications. NSM provides robust session management, including
|
|
interactive features.
|
|
|
|
The Non project contains an implementation of the NSM server API
|
|
called `nsmd` which can be controlled by the `non-session-manager`
|
|
GUI, but the same server API can easily be implemented by other
|
|
session managers (such as LADISH).
|
|
|
|
The only dependency for clients `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
|
|
required of clients. This is an area where other attempts at session
|
|
management (LASH and JACK-Session) have failed. Often the difficulty
|
|
with these previous system been, not in implementing support for
|
|
them, but in attempting to interpret the confusing and ambiguous API
|
|
documentation. For this reason, all LASH support has been removed
|
|
from Non.
|
|
|
|
You *WILL* see a lot of unambiguous language in this document. These
|
|
rules are meant to be followed and are non-negotiable. If an
|
|
application does not conform to this specification it should be
|
|
considered broken. Consistency across applications under session
|
|
management is very important for a good user experience.
|
|
|
|
:: Client Behavior Under Session Management
|
|
|
|
Most graphical applications make available to the user a common set
|
|
of file operations, typically presented under a File or Project
|
|
menu.
|
|
|
|
These are: New, Open, Save, Save As, Close and Quit or Exit.
|
|
|
|
The following sub-sections describe how these options should behave when
|
|
the application is part of an NSM session. These rules only apply
|
|
when session management is active (that is, after the `announce`
|
|
handshake described in the #(ref,NSM OSC Protocol) section).
|
|
|
|
In order to provide a consistent and predictable user experience, it
|
|
is important for applications to adhere to these guidelines.
|
|
|
|
::: New
|
|
|
|
This option may empty\/reset the current file or project (possibly
|
|
after user confirmation). *UNDER NO CIRCUMSTANCES* should it allow
|
|
the user to create a new project\/file in another location.
|
|
|
|
::: Open
|
|
|
|
This option should be disabled.
|
|
|
|
The application may, however, elect to implement an option called
|
|
'Import into Session', creates a copy of a file\/project which is
|
|
then saved in the session path provided by NSM.
|
|
|
|
::: Save
|
|
|
|
This option should behave as normal, saving the current
|
|
file\/project as established by the NSM `open` message.
|
|
|
|
*UNDER NO CIRCUMSTANCES* should this option present the user with a
|
|
choice of where to save the file!
|
|
|
|
::: Save As
|
|
|
|
This option should be disabled.
|
|
|
|
The application may, however, elect to implement an option called
|
|
'Export from Session', which creates a copy of the current
|
|
file\/project which is then saved in a user-specified location
|
|
outside of the session path provided by NSM.
|
|
|
|
::: Close (as distinguished from Quit or Exit)
|
|
|
|
This option should be disabled, unless its meaning is to disconnect
|
|
the application from session management.
|
|
|
|
::: Quit or Exit
|
|
|
|
This option may behave as normal (even possibly asking the user to
|
|
confirm exiting).
|
|
|
|
:: NSM OSC Protocol
|
|
|
|
All message parameters are *REQUIRED*. All messages *MUST* be sent
|
|
from the same socket as the `announce` message, using the
|
|
`lo\_send\_from` method of liblo (the server uses the return
|
|
addresses to distinguish between clients).
|
|
|
|
::: Establishing a Connection
|
|
|
|
:::: Announce
|
|
|
|
When started clients *MUST* check the environment for the value of
|
|
`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
|
|
`\/nsm\/client\/open` event:
|
|
|
|
> /nsm/server/announce s:application_name s:capabilities i:api_version_major i:api_version_minor i:pid
|
|
|
|
If `NSM\_URL` is undefined, invalid, or unreachable, then the client
|
|
should proceed assuming that session management is unavailable.
|
|
|
|
`api\_version\_major` and `api\_version\_minor` must be the two parts of
|
|
the version number of the NSM API as defined by this document.
|
|
|
|
Note that if the application intends to register JACK clients,
|
|
`application\_name` *MUST* be the same as the name that would
|
|
normally by passed to `jack\_client\_open`. For example, Non-Mixer
|
|
sends "Non-Mixer" as its `application\_name`. Applications *MUST
|
|
NOT* register their JACK clients until receiving an `open` message;
|
|
the `open` message will provide a unique client name prefix suitable
|
|
for passing to JACK. This is probably the most complex requirement
|
|
of the NSM API, but it isn't difficult to implement.
|
|
|
|
`capabilities` *MUST* be a string containing a colon separated list
|
|
of the special capabilities the client
|
|
possesses. e.g. ":dirty:switch:progress:"
|
|
|
|
// Available Client Capabilities
|
|
[[ Name, Description
|
|
[[ switch, client is capable of responding to multiple `open` messages without restarting
|
|
[[ dirty, client knows when it has unsaved changes
|
|
[[ progress, client can send progress updates during time-consuming operations
|
|
[[ status, client can send textual status updates
|
|
|
|
:::: Response
|
|
|
|
The server will respond to the client's `announce` with the following message:
|
|
|
|
> /reply "/nsm/server/announce" s:message s:name_of_session_manager s:capabilities
|
|
|
|
`message` is a welcome message.
|
|
|
|
The value of `name\_of\_session\_manager` will depend on the
|
|
implementation of the NSM server. It might say "Non Session Manager",
|
|
or it might say "LADISH".
|
|
|
|
`capabilities` will be a string containing a colon separated list of
|
|
special server capabilities.
|
|
|
|
Presently, the server `capabilities` are:
|
|
|
|
// Available Server Capabilities
|
|
[[ Name, Description
|
|
[[ server_control, client-to-server control
|
|
|
|
A client should not consider itself to be under session management
|
|
until it receives this response (the Non programs activate their
|
|
"SM" blinkers at this time.)
|
|
|
|
If there is an error, a reply of the following form will be sent to
|
|
the client:
|
|
|
|
> /error "/nsm/server/announce" i:error_code s:error_message
|
|
|
|
The following table defines possible values of `error\_code`:
|
|
|
|
// Response codes
|
|
[[ Code, Meaning
|
|
[[ ERR_GENERAL, General Error
|
|
[[ ERR_INCOMPATIBLE_API, Incompatible API version
|
|
[[ ERR_BLACKLISTED, Client has been blacklisted.
|
|
|
|
::: Server to Client Control Messages
|
|
|
|
Compliant clients *MUST* accept the client control messages
|
|
described in this section. All client control messages *REQUIRE* a
|
|
response. Responses *MUST* be delivered back to the sender (NSM)
|
|
from the same socket used by the client in its `announce` message
|
|
(by using `lo\_send\_from`) *AFTER* the action has been completed or
|
|
if an error is encountered. The required response is described in
|
|
the subsection for each message.
|
|
|
|
If there is an error and the action cannot be completed, then
|
|
`error\_code` *MUST* be set to a valid error code (see #(fig,Error Code Definitions))
|
|
and `message` to a string describing the problem (suitable
|
|
for display to the user).
|
|
|
|
The reply can take one of the following two forms, where `path` *MUST* be
|
|
the path of the message being replied to (e.g. "/nsm\/client\/save"):
|
|
|
|
> /reply s:path s:message
|
|
|
|
> /error s:path i:error_code s:message
|
|
|
|
:::: Quit
|
|
|
|
There is no message for this. Clients will receive the Unix SIGTERM
|
|
signal and *MUST* close cleanly *IMMEDIATELY*, without displaying
|
|
any kind of dialog to the user and regardless of whether or not
|
|
unsaved changes would be lost (when a session is closed the
|
|
application will receive this signal soon after having responded to
|
|
a `save` message).
|
|
|
|
:::: Open
|
|
|
|
> /nsm/client/open s:path_to_instance_specific_project s:client_id
|
|
|
|
The client *MUST* open an existing project, or create new one if one
|
|
doesn't already exist, at `path\_to\_instance_specific\_project`
|
|
|
|
If the path provided doesn't exist, then the client *MUST*
|
|
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. '.non' or '.XML'). The same transformation *MUST* be applied
|
|
to the name when opening an existing project, as NSM will only
|
|
provide the instance specific part of the path.
|
|
|
|
For clients which *HAVE NOT* specified the 'switch' capability, the
|
|
`open` message will only be delivered once, immediately after the
|
|
'announce' response.
|
|
|
|
For client which *HAVE* specified the `:switch:` capability, the
|
|
client *MUST* immediately switch to the specified project or create
|
|
a new one if it doesn't exist.
|
|
|
|
Clients which are incapable of switching projects or are prone to
|
|
crashing upon switching *MUST NOT* include `:switch:` in their
|
|
capability string.
|
|
|
|
If the user the is allowed to run two or more instances of the
|
|
application simultaneously (that is to say, there is no technical
|
|
limitation preventing them from doing so, even if it doesn't make
|
|
sense to the author), then such an application *MUST* prepend the
|
|
provided `client\_id` string to any names it registers with common
|
|
subsystems (e.g. JACK client names). This ensures that the multiple
|
|
instances of the same application can be restored in any order
|
|
without scrambling the JACK connections or causing other
|
|
conflicts. The provided `client\_id` will be a concatenation of the
|
|
value of `application\_name` sent by the client in its `announce`
|
|
message and a unique identifier. Therefore, applications which
|
|
create single JACK clients can use the value of `client\_id` directly
|
|
as their JACK client name. Applications which register multiple JACK
|
|
clients (e.g. Non-Mixer) *MUST* prepend `client_id` value to the
|
|
client names they register with JACK and the application determined
|
|
part *MUST* be unique for that (JACK) client.
|
|
|
|
For example, a suitable JACK client name would be:
|
|
|
|
> $CLIENT_ID/track-1
|
|
|
|
A response is *REQUIRED* *AFTER* the load\/new operation has been
|
|
completed. Ongoing progress may be indicated by sending messages to
|
|
`\/nsm\/client\/progress`.
|
|
|
|
::::: Response
|
|
|
|
The client *MUST* respond to the 'open' message with:
|
|
|
|
> /reply "/nsm/client/open" s:message
|
|
|
|
Or
|
|
|
|
> /error "/nsm/client/open" i:error_code s:message
|
|
|
|
// Response Codes
|
|
[[ Code, Meaning
|
|
[[ ERR, General Error
|
|
[[ ERR_BAD_PROJECT, An existing project file was found to be corrupt
|
|
[[ ERR_CREATE_FAILED, A new project could not be created
|
|
[[ ERR_UNSAVED_CHANGES, Unsaved changes would be lost
|
|
[[ ERR_NOT_NOW, Operation cannot be completed at this time
|
|
|
|
:::: Save
|
|
|
|
> /nsm/client/save
|
|
|
|
The client *MUST* immediately save the current application specific
|
|
project data to the project path previously established in the
|
|
'open' message. *UNDER NO CIRCUMSTANCES* should a dialog be
|
|
displayed to the user (giving a choice of where to save, etc.)
|
|
|
|
::::: Response
|
|
|
|
The client *MUST* respond to the 'save' message with:
|
|
|
|
> /reply "/nsm/client/save" s:message
|
|
|
|
Or
|
|
|
|
> /error "/nsm/client/save" i:error_code s:message
|
|
|
|
// Response Codes
|
|
[[ Code, Meaning
|
|
[[ ERR, General Error
|
|
[[ ERR_SAVE_FAILED, Project could not be saved
|
|
[[ ERR_NOT_NOW, Operation cannot be completed at this time
|
|
|
|
::: Server to Client Informational Messages
|
|
|
|
:::: Session is Loaded
|
|
|
|
Accepting this message is optional. The intent is to signal to
|
|
clients which may have some interdependency (say, peer to peer OSC
|
|
connections) that the session is fully loaded and all their peers
|
|
are available.
|
|
|
|
> /nsm/client/session_is_loaded
|
|
|
|
This message does not require a response.
|
|
|
|
::: Client to Server Informational Messages
|
|
|
|
These are optional messages which a client can send to the NSM
|
|
server to inform it about the client's status. The client should not
|
|
expect any reply to these messages. If a client intends to send a
|
|
message described in this section, then it *MUST* add the
|
|
appropriate value to its `capabilities` string when composing the
|
|
`announce` message.
|
|
|
|
:::: Progress
|
|
|
|
> /nsm/client/progress f:progress
|
|
|
|
For potentially time-consuming operations, such as `save` and
|
|
`open`, progress updates may be indicated throughout the duration by
|
|
sending a floating point value between 0.0 and 1.0, 1.0 indicating
|
|
completion, to the NSM server.
|
|
|
|
The server will not send a response to these messages, but will
|
|
relay the information to the user.
|
|
|
|
Note that, even when using the `progress` feature, the final
|
|
response to the `save` or `open` message is still *REQUIRED*.
|
|
|
|
Clients which intend to send `progress` messages should include
|
|
`:progress:` in their `announce` capability string.
|
|
|
|
:::: Dirtiness
|
|
|
|
> /nsm/client/is_dirty
|
|
|
|
> /nsm/client/is_clean
|
|
|
|
Some clients may be able to inform the server when they have unsaved
|
|
changes pending. Such clients may optionally send `is\_dirty` and `is\_clean`
|
|
messages.
|
|
|
|
Clients which have this capability should include `:dirty:` in their
|
|
`announce` capability string.
|
|
|
|
:::: Status Messages
|
|
|
|
> /nsm/client/message i:priority s:message
|
|
|
|
Clients may send miscellaneous status updates to the server for
|
|
possible display to the user. This may simply be chatter that is normally
|
|
written to the console. `priority` should be a number from 0 to 3, 3
|
|
being the most important.
|
|
|
|
Clients which have this capability should include `:message:` in their
|
|
`announce` capability string.
|
|
|
|
::: Error Code Definitions
|
|
|
|
// Error Code Definitions
|
|
[[ Symbolic Name, Integer Value
|
|
[[ ERR_GENERAL, -1
|
|
[[ ERR_INCOMPATIBLE_API, -2
|
|
[[ ERR_BLACKLISTED, -3
|
|
[[ ERR_LAUNCH_FAILED, -4
|
|
[[ ERR_NO_SUCH_FILE, -5
|
|
[[ ERR_NO_SESSION_OPEN, -6
|
|
[[ ERR_UNSAVED_CHANGES, -7
|
|
[[ ERR_NOT_NOW, -8
|
|
[[ ERR_BAD_PROJECT, -9
|
|
[[ ERR_CREATE_FAILED, -10
|
|
|
|
::: Client to Server Control
|
|
|
|
If the server publishes the `server\_control` capability, then
|
|
clients can also initiate action by the server. For example, a
|
|
client might implement a 'Save All' option which sends a
|
|
`\/nsm\/server\/save` message to the server, rather than requiring
|
|
the user to switch to the session management interface to effect the
|
|
save.
|
|
|
|
::: Server Control API
|
|
|
|
The session manager not only manages clients via OSC, but it is itself
|
|
controlled via OSC messages. The server responds to the following
|
|
messages.
|
|
|
|
All of the following messages will be responded to back to the sender's address
|
|
with one of the two following messages:
|
|
|
|
> /reply s:path s:message
|
|
|
|
> /error s:path i:error_code s:message
|
|
|
|
The first parameter of the reply is the path to the message being
|
|
replied to. The `\/error` reply includes an integer error code
|
|
(non-zero indicates error). `message` will be a description of the
|
|
error.
|
|
|
|
The possible errors are:
|
|
|
|
// Responses
|
|
[[ Code, Meaning
|
|
[[ ERR_GENERAL, General Error
|
|
[[ ERR_LAUNCH_FAILED, Launch failed
|
|
[[ ERR_NO_SUCH_FILE, No such file
|
|
[[ ERR_NO_SESSION, No session is open
|
|
[[ ERR_UNSAVED_CHANGES, Unsaved changes would be lost
|
|
|
|
= /nsm/server/add s:path_to_executable
|
|
Adds a client to the current session.
|
|
|
|
= /nsm/server/save
|
|
Saves the current session.
|
|
|
|
= /nsm/server/load s:project_name
|
|
Saves the current session and loads a new session.
|
|
|
|
= /nsm/server/new s:project_name
|
|
Saves the current session and creates a new session.
|
|
|
|
= /nsm/server/close
|
|
Saves and closes the current session.
|
|
|
|
= /nsm/server/abort
|
|
Closes the current session *WITHOUT SAVING*
|
|
|
|
= /nsm/server/quit
|
|
Saves and closes the current session and terminates the server.
|
|
|
|
= /nsm/server/duplicate s:new_project
|
|
Saves and closes the current session, creates a complete copy of
|
|
it as `new_project` and opens it. The existing project should ideally be
|
|
a lightweight template, as copying any audio data could be very time
|
|
consuming.
|
|
|
|
= /nsm/server/list
|
|
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
|
|
|
|
If the server includes `:broadcast:` in its capability string, then
|
|
clients may send broadcast messages to each other through the NSM
|
|
server.
|
|
|
|
Clients may send messages to the server at the path
|
|
`\/broadcast`.
|
|
|
|
The format of this message is as follows:
|
|
|
|
> /nsm/server/broadcast s:path [other parameters...]
|
|
|
|
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
|
|
shifted forward by one.
|
|
|
|
For example the message:
|
|
|
|
> /nsm/server/broadcast /tempomap/update "0,120,4/4:12351234,240,4/4"
|
|
|
|
Would broadcast the following message to all clients in the session
|
|
(except for the sender), some of which might respond to the message
|
|
by updating their own tempo maps.
|
|
|
|
> /tempomap/update "0,120,4/4:12351234,240,4/4"
|
|
|
|
Clients may use this feature to establish peer to peer OSC
|
|
communication with symbolic names without having to remember the OSC
|
|
URLs of peers.
|