====== Jack-Session v2.0 - brainstorm ======

===== jack-session v1.0 =====

Links and references to the current 1.0 API.

  * [[http://trac.jackaudio.org/wiki/WalkThrough/Dev/JackSession|Developer Walk-through]] - the JACK-Session API
  * [[http://trac.jackaudio.org/wiki/WalkThrough/User/jack_session|Basic Usage info]]
  * [[http://hochstrom.endofinternet.org/files/pyjacksm-cast01.ogv|Example-usage Screencast]]
  * [[http://jackaudio.org/files/docs/html/session_8h.html|Session API documentation]] - doxygen
  * [[http://jackaudio.org/files/docs/html/group__SessionClientFunctions.html|Session Client Function API]] - doxygen
  * [[http://tangostudio.tuxfamily.org/jacksession?lang=en|End-User documentation]] by TangoStudio.

===== Brainstorm =====

Be welcome, to add your opinion and idea below.

\\

Having tried to use jack-session for a while,
my conclusion is:

\\
  * It needs Session **Load without application-quit**, thus I'm distinguishing here \\ between **"quit" =>** exit application and **"close" =>** close documents without application-exit.
\\
  * It needs Session **Close without Save** (this won't exit (most) applications)
\\
  * Beeing able to load multiple sessions (at once) appears bad, is an error-source
\\
  * Conditions where connection-restoration fails - must be known (e.g. apps are not allowed to auto-connect jack-ports)
\\
  * sometimes eventually you don't want a JS-capable app to be part of the current session, although you're running it at the same time. JS should offer a flag for this (set by jack-client-app on user request): <code>session_client->part_of_active_session = false;  //(default is true, of course) </code>
\\

===== Introduce new events =====

<code C>

// extend EventType:
enum JackSessionEventType {
	...
    JackSessionCloseAndLoadNew = 4,    // load a new session, without quitting applications (if possible)
    JackSessionCloseWithoutQuit = 5,   // close session-document without quitting applications
    JackSessionCloseWithQuit = 6       // close the session and quit everything
}

</code>

<code C>
// extend jack-session-client implementations:
//
if( ev->type == JackSessionCloseAndLoadNew ){

	// close current document(s), eventually ask the user, if he/she
	//      would like to save first (but **don't quit** the application)
	
	// then load new session-document(s)
}


if( ev->type == JackSessionClose ){

	// close current document(s), eventually ask the user, if he/she
	//      would like to save first
	
}


</code>


===== Replace the command_line with an appID (cross-platform) =====

- **saving a command line with the session is a very bad idea.**

My suggestion:

The jack-session-commander (e.g. qjackctl) has a small (operating system specific)
database. 
\\
The contained **entries would overwrite the command_line, if existend**. Thus backwards compatible.

The database would be queried by appID:

It would have the **fields: appID, executable, generic_parameters **
\\
The database can be processed with simple split(),trim() operations. One entry per line.
\\
\\
One single entry would look like:
(fist word is the appID, **not** the executable name, although it may be equal.

<code>

appID==amSynth; exe==/usr/bin/amSynth; param:loadFile==-f $arg:loadFile; param:uuid==-u $arg:uuid ; param:autoconnect==-A $arg:autoconnect; param:with_gui==-w $arg:with_gui;

</code>
\\
On windows, the entry might look like:
<code>

appID==amSynth; exe==c:\programs\amSynth; param:loadFile==/f $arg:loadFile; param:uuid==/u $arg:uuid ; param:autoconnect==/A $arg:autoconnect; param:with_gui==/w $arg:with_gui;

</code>

\\

jack_session_event would be filled by the JS-client as:

<code C>

jsEvent->appID = "amSynth";
jsEvent->appParams = " loadFile1==%s; autoconnect==%s " %( sessionFile, false );
jsEvent->loadFile = sessionFile;

</code>


The jack-session-manager would search the database for
the appID and generate an appropriate (os-specific) command_line.
\\

This would also allow different command lines, by
assigning different appIDs to a single application (amSynthWithoutGui, amSynthWithGui, amSynthInGreen,...)

\\

<code C>

// in 
struct _jack_session_event {

	// make the command_line member deprecated
	
	// introduce the following members instead
	
	
	// AppID : usually equal to application name, without path info
	char *appID;	
	
	char *appParams;	// additional prefered Application Parameters (abstracted, to be OS-independent)
	
	char loadFile;	// file to load (with extension, without path info, could contain a simple string, with more files to load.)
	
}

</code>

\\

\\

===== (Multi) Session Handling ===== 
\\

\\
Can multi-session handling work reliably ? \\
Is it too complicated ? \\
Can a single-session be open multiple times ? \\
\\
The current behavior, to me, feels strange and unexpected:
Opening a running session (twice) opens another set of windows.
What's that ? Do I have a "doubled" session now ?
It is very opaque, unclear, which window belongs to which session. 
Is that how it should be, is that what we'd want ?
\\
\\
An idea:\\
Add a sessionID. \\
The client would allow selecting the session it belongs to (with a drop-down-box). This would allow multiple sessions to be open.
Every session should have an associated color (light, water-color) and a short description string (user-assigned), the applications can use to visualize dependency to a particular session.\\
\\
For example I could have a "light-green" session with hydrogen and qsynth and a "light-orange" session with audacity and lv2host running at the same time. \\
\\
In qjackctl, there would be an option "create new session" with a dialog, where I would be able to select a color, enter a string, for a new session.

\\
\\
**Store connections:**
\\
  * Every saved sessions stores all connections currently active (when hitting save).
\\
**Restoration of connections** in a multi-session environment.
\\
  * Start with no connections, nothing connected (keep existing connections ? rather not - they could conflict ?)
  * Load first session    => connections of __applications belonging to__ that particular session __are restored__ (only)
  * Load a second session => the same
  * __Restore additionally__ saved connections __if the user requests__, from an already loaded session.
\\
Every app has a drop-down-box, where one of the loaded sessions can be selected, i.o. to become a member.
\\
\\

===== Jack-Session - Best Practice Section ===== 
\\

\\

We need a **jack-session-api best-practice** section. This would contain hints as:
\\
  * dont's use paths in the command_line (amSynth   vs.  /usr/bin/amSynth )
\\
  * don't use single character parameters in the command_line  ==>  bad:\\ params -a=yes and -A=no is the same on some platforms, rather --autoconnect=yes, --artefacts=no
\\
  * with the session, applications should **restore their window position** and state (maximized, curled up, minimized, etc.) 
\\
  * apps are not allowed to auto-connect jack-ports, when using jack-session (user option)
\\
  * apps are allowed to save to another folder **additionally** (for backup purposes)
\\

\\

===== Comments and additional ideas ===== 


  * Qjackctl - sesssion: save, works as 'save as' now. It would be nice if it would be possible to have also the opportunity to hit just 'save'.
  * Qjackctl should support infra clients, like pyjacksm does atm.
  * It would be nice if you could load a JackSession Manager (like pyjacksm) with different configuration files (now only .pyjacksmrc)
  * It will be valuable if you could load a session via the command line / BASH script.
  * It would be nice to be able to load more then one session at once...