diff --git a/session-manager/doc/API.html b/session-manager/doc/API.html index 71b5837..056347b 100644 --- a/session-manager/doc/API.html +++ b/session-manager/doc/API.html @@ -12,7 +12,7 @@
Jonathan Moore Liles <male@tuxfamily.org>
August 1, 2010
-Version 1.1 +Version 1.2
logo
@@ -21,19 +21,27 @@ Version 1.1
  • 1. Non Session Management API
    • 1.1. Client Behavior Under Session Management -
    • 1.2. NSM OSC Protocol
      • 1.2.1. Establishing a Connection @@ -104,39 +112,54 @@ 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 1.2. NSM OSC Protocol section). In order to provide a consistent and predictable user experience, it is critically important for applications to adhere to these guidelines.

        -

        1.1.1. New

        +

        1.1.1. File Menu

        +

        1.1.1.1. 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.

        -

        1.1.2. Open

        +

        1.1.1.2. Open

        This option MUST 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 at the session path provided by NSM.

        -

        1.1.3. Save

        +

        1.1.1.3. 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.

        -

        1.1.4. Save As

        +

        1.1.1.4. Save As

        This option MUST 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.

        -

        1.1.5. Close (as distinguished from Quit or Exit)

        +

        1.1.1.5. Close (as distinguished from Quit or Exit)

        This option MUST be disabled unless its meaning is to disconnect the application from session management.

        -

        1.1.6. Quit or Exit

        +

        1.1.1.6. Quit or Exit

        This option may behave as normal (possibly asking the user to confirm exiting).

        +

        1.1.2. Data Storage

        +

        1.1.2.1. 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). +

        +

        1.1.2.2. 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
        +

        1.2. 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 or its equivalent, as the server uses the return addresses to distinguish between clients. diff --git a/session-manager/doc/API.mu b/session-manager/doc/API.mu index ffae33b..b5559db 100644 --- a/session-manager/doc/API.mu +++ b/session-manager/doc/API.mu @@ -2,7 +2,7 @@ ! title Non Session Management API ! author Jonathan Moore Liles #(email,male@tuxfamily.org) ! date August 1, 2010 -! revision Version 1.1 +! revision Version 1.2 ! extra #(image,logo,icon.png) -- Table Of Contents @@ -63,13 +63,15 @@ is critically important for applications to adhere to these guidelines. -::: New +::: File Menu + +:::: 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 +:::: Open This option *MUST* be disabled. @@ -77,7 +79,7 @@ 'Import into Session', creates a copy of a file\/project which is then saved at the session path provided by NSM. -::: Save +:::: Save This option should behave as normal, saving the current file\/project as established by the NSM `open` message. @@ -85,7 +87,7 @@ *UNDER NO CIRCUMSTANCES* should this option present the user with a choice of where to save the file. -::: Save As +:::: Save As This option *MUST* be disabled. @@ -94,16 +96,41 @@ 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) +:::: Close (as distinguished from Quit or Exit) This option *MUST* be disabled unless its meaning is to disconnect the application from session management. -::: Quit or Exit +:::: Quit or Exit This option may behave as normal (possibly asking the user to 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 All message parameters are *REQUIRED*. All messages *MUST* be sent