NSM: update API document.
This commit is contained in:
Jonathan Moore Liles
parent
9cebe116d1
commit
5cc6136f9c
|
|
@ -12,7 +12,7 @@
|
||||||
<address>
|
<address>
|
||||||
Jonathan Moore Liles <a href="mailto:male@tuxfamily.org"><male@tuxfamily.org></a><br>
|
Jonathan Moore Liles <a href="mailto:male@tuxfamily.org"><male@tuxfamily.org></a><br>
|
||||||
August 1, 2010<br>
|
August 1, 2010<br>
|
||||||
Version 1.1
|
Version 1.2
|
||||||
</address><img src="icon.png" alt="logo"><hr></div>
|
</address><img src="icon.png" alt="logo"><hr></div>
|
||||||
<div id=body>
|
<div id=body>
|
||||||
<div id=toc>
|
<div id=toc>
|
||||||
|
|
@ -21,19 +21,27 @@ Version 1.1
|
||||||
<li><a href="#n:1.">1. Non Session Management API</a>
|
<li><a href="#n:1.">1. Non Session Management API</a>
|
||||||
<ul><li><a href="#n:1.1.">1.1. Client Behavior Under Session Management</a>
|
<ul><li><a href="#n:1.1.">1.1. Client Behavior Under Session Management</a>
|
||||||
|
|
||||||
<ul><li><a href="#n:1.1.1.">1.1.1. New</a>
|
<ul><li><a href="#n:1.1.1.">1.1.1. File Menu</a>
|
||||||
|
|
||||||
<li><a href="#n:1.1.2.">1.1.2. Open</a>
|
<ul><li><a href="#n:1.1.1.1.">1.1.1.1. New</a>
|
||||||
|
|
||||||
<li><a href="#n:1.1.3.">1.1.3. Save</a>
|
<li><a href="#n:1.1.1.2.">1.1.1.2. Open</a>
|
||||||
|
|
||||||
<li><a href="#n:1.1.4.">1.1.4. Save As</a>
|
<li><a href="#n:1.1.1.3.">1.1.1.3. Save</a>
|
||||||
|
|
||||||
<li><a href="#n:1.1.5.">1.1.5. Close (as distinguished from Quit or Exit)</a>
|
<li><a href="#n:1.1.1.4.">1.1.1.4. Save As</a>
|
||||||
|
|
||||||
<li><a href="#n:1.1.6.">1.1.6. Quit or Exit</a>
|
<li><a href="#n:1.1.1.5.">1.1.1.5. Close (as distinguished from Quit or Exit)</a>
|
||||||
|
|
||||||
</ul><li><a href="#n:1.2.">1.2. NSM OSC Protocol</a>
|
<li><a href="#n:1.1.1.6.">1.1.1.6. Quit or Exit</a>
|
||||||
|
|
||||||
|
</ul><li><a href="#n:1.1.2.">1.1.2. Data Storage</a>
|
||||||
|
|
||||||
|
<ul><li><a href="#n:1.1.2.1.">1.1.2.1. Internal Files</a>
|
||||||
|
|
||||||
|
<li><a href="#n:1.1.2.2.">1.1.2.2. External Files</a>
|
||||||
|
|
||||||
|
</ul></ul><li><a href="#n:1.2.">1.2. NSM OSC Protocol</a>
|
||||||
|
|
||||||
<ul><li><a href="#n:1.2.1.">1.2.1. Establishing a Connection</a>
|
<ul><li><a href="#n:1.2.1.">1.2.1. Establishing a Connection</a>
|
||||||
|
|
||||||
|
|
@ -104,39 +112,54 @@ These are: New, Open, Save, Save As, Close and Quit or Exit.
|
||||||
<p>
|
<p>
|
||||||
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 <tt>announce</tt> handshake described in the <a class=int href="#n:1.2.">1.2. NSM OSC Protocol</a> section). In order to provide a consistent and predictable user experience, it is critically important for applications to adhere to these guidelines.
|
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 <tt>announce</tt> handshake described in the <a class=int href="#n:1.2.">1.2. NSM OSC Protocol</a> section). In order to provide a consistent and predictable user experience, it is critically important for applications to adhere to these guidelines.
|
||||||
</p>
|
</p>
|
||||||
<h3 id="n:1.1.1.">1.1.1. New</h3>
|
<h3 id="n:1.1.1.">1.1.1. File Menu</h3>
|
||||||
|
<h4 id="n:1.1.1.1.">1.1.1.1. New</h4>
|
||||||
<p>
|
<p>
|
||||||
This option may empty/reset the current file or project (possibly after user confirmation). <b>UNDER NO CIRCUMSTANCES</b> should it allow the user to create a new project/file in another location.
|
This option may empty/reset the current file or project (possibly after user confirmation). <b>UNDER NO CIRCUMSTANCES</b> should it allow the user to create a new project/file in another location.
|
||||||
</p>
|
</p>
|
||||||
<h3 id="n:1.1.2.">1.1.2. Open</h3>
|
<h4 id="n:1.1.1.2.">1.1.1.2. Open</h4>
|
||||||
<p>
|
<p>
|
||||||
This option <b>MUST</b> be disabled.
|
This option <b>MUST</b> be disabled.
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
The application may, however, elect to implement an option called 'Import into Session', creates a copy of a file/project which is then saved at the session path provided by NSM.
|
The application may, however, elect to implement an option called 'Import into Session', creates a copy of a file/project which is then saved at the session path provided by NSM.
|
||||||
</p>
|
</p>
|
||||||
<h3 id="n:1.1.3.">1.1.3. Save</h3>
|
<h4 id="n:1.1.1.3.">1.1.1.3. Save</h4>
|
||||||
<p>
|
<p>
|
||||||
This option should behave as normal, saving the current file/project as established by the NSM <tt>open</tt> message.
|
This option should behave as normal, saving the current file/project as established by the NSM <tt>open</tt> message.
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
<b>UNDER NO CIRCUMSTANCES</b> should this option present the user with a choice of where to save the file.
|
<b>UNDER NO CIRCUMSTANCES</b> should this option present the user with a choice of where to save the file.
|
||||||
</p>
|
</p>
|
||||||
<h3 id="n:1.1.4.">1.1.4. Save As</h3>
|
<h4 id="n:1.1.1.4.">1.1.1.4. Save As</h4>
|
||||||
<p>
|
<p>
|
||||||
This option <b>MUST</b> be disabled.
|
This option <b>MUST</b> be disabled.
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
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.
|
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.
|
||||||
</p>
|
</p>
|
||||||
<h3 id="n:1.1.5.">1.1.5. Close (as distinguished from Quit or Exit)</h3>
|
<h4 id="n:1.1.1.5.">1.1.1.5. Close (as distinguished from Quit or Exit)</h4>
|
||||||
<p>
|
<p>
|
||||||
This option <b>MUST</b> be disabled unless its meaning is to disconnect the application from session management.
|
This option <b>MUST</b> be disabled unless its meaning is to disconnect the application from session management.
|
||||||
</p>
|
</p>
|
||||||
<h3 id="n:1.1.6.">1.1.6. Quit or Exit</h3>
|
<h4 id="n:1.1.1.6.">1.1.1.6. Quit or Exit</h4>
|
||||||
<p>
|
<p>
|
||||||
This option may behave as normal (possibly asking the user to confirm exiting).
|
This option may behave as normal (possibly asking the user to confirm exiting).
|
||||||
</p>
|
</p>
|
||||||
|
<h3 id="n:1.1.2.">1.1.2. Data Storage</h3>
|
||||||
|
<h4 id="n:1.1.2.1.">1.1.2.1. Internal Files</h4>
|
||||||
|
<p>
|
||||||
|
All project specific data created by a client <b>MUST</b> be stored in the per-client storage area provided by NSM. This includes all recorded audio and MIDI files, snapshots, etc. Only global configuration items, exports, and renders of the project may be stored elsewhere (wherever the user specifies).
|
||||||
|
</p>
|
||||||
|
<h4 id="n:1.1.2.2.">1.1.2.2. External Files</h4>
|
||||||
|
<p>
|
||||||
|
Files required by the project but external to it (typically read-only data such as audio samples) <b>SHOULD</b> be referenced by creating a symbolic link within the assigned session area, and then referring to the symlink. This allows sessions to be archived and transported simply (e.g. with "tar -h") by tools that have no knowledge of the project formats of the various clients in the session. The symlinks thus created should, at the very least, be named after the files they refer to (some unique component may be required to prevent collisions)
|
||||||
|
</p>
|
||||||
|
<div class="fig example"><table width=100%><tr><td><pre>
|
||||||
|
samples/drumbeat-1.wav
|
||||||
|
samples/drumbeat-2.wav
|
||||||
|
</pre></td></tr>
|
||||||
|
</table></div>
|
||||||
<h2 id="n:1.2.">1.2. NSM OSC Protocol</h2>
|
<h2 id="n:1.2.">1.2. NSM OSC Protocol</h2>
|
||||||
<p>
|
<p>
|
||||||
All message parameters are <b>REQUIRED</b>. All messages <b>MUST</b> be sent from the same socket as the <tt>announce</tt> message, using the <tt>lo_send_from</tt> method of liblo or its equivalent, as the server uses the return addresses to distinguish between clients.
|
All message parameters are <b>REQUIRED</b>. All messages <b>MUST</b> be sent from the same socket as the <tt>announce</tt> message, using the <tt>lo_send_from</tt> method of liblo or its equivalent, as the server uses the return addresses to distinguish between clients.
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,7 @@
|
||||||
! title Non Session Management API
|
! title Non Session Management API
|
||||||
! author Jonathan Moore Liles #(email,male@tuxfamily.org)
|
! author Jonathan Moore Liles #(email,male@tuxfamily.org)
|
||||||
! date August 1, 2010
|
! date August 1, 2010
|
||||||
! revision Version 1.1
|
! revision Version 1.2
|
||||||
! extra #(image,logo,icon.png)
|
! extra #(image,logo,icon.png)
|
||||||
|
|
||||||
-- Table Of Contents
|
-- Table Of Contents
|
||||||
|
|
@ -63,13 +63,15 @@
|
||||||
is critically important for applications to adhere to these
|
is critically important for applications to adhere to these
|
||||||
guidelines.
|
guidelines.
|
||||||
|
|
||||||
::: New
|
::: File Menu
|
||||||
|
|
||||||
|
:::: New
|
||||||
|
|
||||||
This option may empty\/reset the current file or project (possibly
|
This option may empty\/reset the current file or project (possibly
|
||||||
after user confirmation). *UNDER NO CIRCUMSTANCES* should it allow
|
after user confirmation). *UNDER NO CIRCUMSTANCES* should it allow
|
||||||
the user to create a new project\/file in another location.
|
the user to create a new project\/file in another location.
|
||||||
|
|
||||||
::: Open
|
:::: Open
|
||||||
|
|
||||||
This option *MUST* be disabled.
|
This option *MUST* be disabled.
|
||||||
|
|
||||||
|
|
@ -77,7 +79,7 @@
|
||||||
'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 at the session path provided by NSM.
|
then saved at the session path provided by NSM.
|
||||||
|
|
||||||
::: Save
|
:::: Save
|
||||||
|
|
||||||
This option should behave as normal, saving the current
|
This option should behave as normal, saving the current
|
||||||
file\/project as established by the NSM `open` message.
|
file\/project as established by the NSM `open` message.
|
||||||
|
|
@ -85,7 +87,7 @@
|
||||||
*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 *MUST* be disabled.
|
This option *MUST* be disabled.
|
||||||
|
|
||||||
|
|
@ -94,16 +96,41 @@
|
||||||
file\/project which is then saved in a user-specified location
|
file\/project which is then saved in a user-specified location
|
||||||
outside of the session path provided by NSM.
|
outside of the session path provided by NSM.
|
||||||
|
|
||||||
::: Close (as distinguished from Quit or Exit)
|
:::: Close (as distinguished from Quit or Exit)
|
||||||
|
|
||||||
This option *MUST* 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
|
||||||
|
|
||||||
This option may behave as normal (possibly asking the user to
|
This option may behave as normal (possibly asking the user to
|
||||||
confirm exiting).
|
confirm exiting).
|
||||||
|
|
||||||
|
::: Data Storage
|
||||||
|
|
||||||
|
:::: Internal Files
|
||||||
|
|
||||||
|
All project specific data created by a client *MUST* be stored in
|
||||||
|
the per-client storage area provided by NSM. This includes all
|
||||||
|
recorded audio and MIDI files, snapshots, etc. Only global
|
||||||
|
configuration items, exports, and renders of the project may be
|
||||||
|
stored elsewhere (wherever the user specifies).
|
||||||
|
|
||||||
|
:::: External Files
|
||||||
|
|
||||||
|
Files required by the project but external to it (typically
|
||||||
|
read-only data such as audio samples) *SHOULD* be referenced by
|
||||||
|
creating a symbolic link within the assigned session area, and then
|
||||||
|
referring to the symlink. This allows sessions to be archived and
|
||||||
|
transported simply (e.g. with "tar -h") by tools that have no
|
||||||
|
knowledge of the project formats of the various clients in the
|
||||||
|
session. The symlinks thus created should, at the very least, be
|
||||||
|
named after the files they refer to (some unique component may be
|
||||||
|
required to prevent collisions)
|
||||||
|
|
||||||
|
> samples/drumbeat-1.wav
|
||||||
|
> samples/drumbeat-2.wav
|
||||||
|
|
||||||
:: NSM OSC Protocol
|
:: NSM OSC Protocol
|
||||||
|
|
||||||
All message parameters are *REQUIRED*. All messages *MUST* be sent
|
All message parameters are *REQUIRED*. All messages *MUST* be sent
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue