266 lines
13 KiB
HTML
266 lines
13 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html><head>
|
|
<meta name="generator" content="Generated by MUP v3.5">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<link type="text/css" rel="stylesheet" href="mup.css">
|
|
<title>Non Session Manager User Manual</title>
|
|
</head>
|
|
<body>
|
|
|
|
<div id=cover>
|
|
<h1>Non Session Manager User Manual</h1>
|
|
<h3></h3>
|
|
<address>
|
|
Jonathan Moore Liles <a href="mailto:male@tuxfamily.org"><male@tuxfamily.org></a><br>
|
|
<br>
|
|
|
|
</address><img src="icon.png" alt="logo"><hr></div>
|
|
<div id=body>
|
|
<div id=toc>
|
|
<h1 id=toc>Table Of Contents</h1>
|
|
<ul>
|
|
<li><a href="#n:1.">1. User Manual</a>
|
|
<ul><li><a href="#n:1.1.">1.1. The Non Session Manager Graphical Interface</a>
|
|
|
|
<ul><li><a href="#n:1.1.1.">1.1.1. Session Operations</a>
|
|
|
|
<ul><li><a href="#n:1.1.1.1.">1.1.1.1. Open</a>
|
|
|
|
<li><a href="#n:1.1.1.2.">1.1.1.2. Close</a>
|
|
|
|
<li><a href="#n:1.1.1.3.">1.1.1.3. Abort</a>
|
|
|
|
<li><a href="#n:1.1.1.4.">1.1.1.4. Save</a>
|
|
|
|
<li><a href="#n:1.1.1.5.">1.1.1.5. New</a>
|
|
|
|
<li><a href="#n:1.1.1.6.">1.1.1.6. Duplicate</a>
|
|
|
|
<li><a href="#n:1.1.1.7.">1.1.1.7. Add Client</a>
|
|
|
|
</ul><li><a href="#n:1.1.2.">1.1.2. Removing a Client From a Session</a>
|
|
|
|
</ul><li><a href="#n:1.2.">1.2. Saving and Restoring Aspects of the Environment</a>
|
|
|
|
<li><a href="#n:1.3.">1.3. The NSM Daemon</a>
|
|
|
|
<ul><li><a href="#n:1.3.1.">1.3.1. Multiple NSMD Instances</a>
|
|
|
|
<ul><li><a href="#n:1.3.1.1.">1.3.1.1. Distributed Session Management</a>
|
|
|
|
<li><a href="#n:1.3.1.2.">1.3.1.2. Multiple Sessions On One Host</a>
|
|
|
|
</ul></ul></ul><li><a href="#u:1.">Distribution</a>
|
|
|
|
</ul></ul><hr></div>
|
|
<h1 id="n:1.">1. User Manual</h1>
|
|
<h2 id="n:1.1.">1.1. The Non Session Manager Graphical Interface</h2>
|
|
<center><div class="fig image"><table id="Fig.1.1" border=1>
|
|
<caption>
|
|
<strong>Fig. 1.1.</strong> Non Session Manager
|
|
</caption>
|
|
|
|
<tr><td><img src="nsm.png" alt="fig. 1.1"></td></tr>
|
|
</table></div></center>
|
|
<p>
|
|
The Non Session Manager is a graphical interface to the NSM Daemon (nsmd). By default, running the command <tt>non-session-manager</tt> will start both the GUI and an instance of the daemon.
|
|
</p>
|
|
<p>
|
|
If a different session root than the default is desired, it may be specified on the command-line as follows:
|
|
</p>
|
|
<div class="fig example"><table width=100%><tr><td><pre>
|
|
non-session-manager -- --session-root path
|
|
</pre></td></tr>
|
|
</table></div>
|
|
<p>
|
|
This command will instruct the instance of nsmd that the GUI starts to use <tt>path</tt> as the session root.
|
|
</p>
|
|
<p>
|
|
All session data is stored in per-session sub-directories of the <i>Session Root</i>.
|
|
</p>
|
|
<h3 id="n:1.1.1.">1.1.1. Session Operations</h3>
|
|
<h4 id="n:1.1.1.1.">1.1.1.1. Open</h4>
|
|
<p>
|
|
There are two ways to open a session.
|
|
</p>
|
|
<p>
|
|
The first is to click the <i>Open</i> button and type in the exact name of an existing session. The second is to click on the desired session name in the session list panel on the left side of the interface.
|
|
</p>
|
|
<p>
|
|
Either way, opening a session saves the current session and switches to the new one. Clients which are capable of switching projects without restarting are instructed to do so, resulting in very fast session open times when such clients are participating in both sessions.
|
|
</p>
|
|
<p>
|
|
Clients cannot be added until a session is open, either by <i>Open</i> or <i>New</i>.
|
|
</p>
|
|
<p>
|
|
As each client launches, a status bar representing it will be added to the client list on the right half the interface. For clients which are capable of reporting their progress, a progress bar will also become active.
|
|
</p>
|
|
<p>
|
|
Only clients supporting the NSM protocol can be told what to open and when to save. Clients not supporting NSM may still be added to the session, but their behavior is undefined other than that NSM can invoke and kill them.
|
|
</p>
|
|
<h4 id="n:1.1.1.2.">1.1.1.2. Close</h4>
|
|
<p>
|
|
This option saves and closes the current session. All clients participating in the session are told to quit. Note that, as mentioned in the preceding section, in NSM it is not necessary to close one session before opening another.
|
|
</p>
|
|
<h4 id="n:1.1.1.3.">1.1.1.3. Abort</h4>
|
|
<p>
|
|
This option closes the current session <b>without saving</b>.
|
|
</p>
|
|
<h4 id="n:1.1.1.4.">1.1.1.4. Save</h4>
|
|
<p>
|
|
This option saves the current session, instructing clients supporting the NSM protocol to save.
|
|
</p>
|
|
<h4 id="n:1.1.1.5.">1.1.1.5. New</h4>
|
|
<p>
|
|
This option saves the current session (if one is open) and creates a new one. The user is prompted for a session name. Session names are paths under the defined <i>Session Root</i>. A session name may include any number of hierarchical elements, which need not be pre-existing.
|
|
</p>
|
|
<p>
|
|
For example, one might name a session as follows:
|
|
</p>
|
|
<div class="fig example"><table width=100%><tr><td><pre>
|
|
Albums/Magnum Opus/The Best Song Ever Produced
|
|
</pre></td></tr>
|
|
</table></div>
|
|
<p>
|
|
When inspecting <i>Session Root</i> in a file manager, the above represents exactly the path you would see.
|
|
</p>
|
|
<p>
|
|
Renaming a session is not currently supported, but one may simply move directories around under <i>Session Root</i> and NSM will detect the new layout upon the next invocation. The session name is not stored anywhere except in its path.
|
|
</p>
|
|
<p>
|
|
<h4 id="n:1.1.1.6.">1.1.1.6. Duplicate</h4>
|
|
<p>
|
|
Templates are supported in by the Non Session Manager via duplication. Clicking on the <i>Duplicate</i> button with a session open will prompt the user for a new session name. The daemon will then perform a recursive file copy of the session and open the copy.
|
|
</p>
|
|
<p>
|
|
Obviously, this should be avoided for sessions containing audio data, as the copy would be very time consuming.
|
|
</p>
|
|
<p>
|
|
To create a template in the first place, simply use <i>New</i> to start a new session (preferably with a name beginning with "Templates/"), add the desired clients to it, and configure them (e.g. add plugins, make JACK connections, etc.) Now, any time you want to start a session from that template, simply switch to the template session and click <i>Duplicate</i> to create a new session based on it.
|
|
</p>
|
|
<h4 id="n:1.1.1.7.">1.1.1.7. Add Client</h4>
|
|
<p>
|
|
This option will prompt the user for the executable name of the client to be added to the session. It is not necessary to type the full path (the PATH environment variable will be searched to find the executable).
|
|
</p>
|
|
<p>
|
|
When controlling an NSM session distributed across multiple machines, the user will also be required to choose which server to invoke the client on.
|
|
</p>
|
|
<h3 id="n:1.1.2.">1.1.2. Removing a Client From a Session</h3>
|
|
<p>
|
|
If a client dies unexpectedly or is closed by the user (e.g. by closing its main window), Non Session Manager will detect this and two buttons will appear on that Client's status bar. One button, the arrow, causes the client to be restarted and to reopen its project file where it left off. The <i>X</i> button causes the client to be permanently removed from the session.
|
|
</p>
|
|
<h2 id="n:1.2.">1.2. Saving and Restoring Aspects of the Environment</h2>
|
|
<p>
|
|
NSM manages clients together in a session. That's it. NSM doesn't know or care what Window Manager or audio subsystem those clients use--nor should it. Specific clients must be written to persist these environmental factors, and added to sessions when required.
|
|
</p>
|
|
<p>
|
|
For saving and restoring the JACK connection graph, a simple headless client named <tt>jackpatch</tt> has been developed and included in the NSM distribution. Simply add <tt>jackpatch</tt> do your basic template session and all the sessions you base on it will have their JACK connection graphs automatically saved and restored.
|
|
</p>
|
|
<h2 id="n:1.3.">1.3. The NSM Daemon</h2>
|
|
<p>
|
|
The NSM Daemon (nsmd) is launched automatically by the Non Session Manager interface whenever one is not found to be already running at the URL specified in the environment.
|
|
</p>
|
|
<p>
|
|
Users who are not attempting to setup advanced modes like shared sessions between machines will not normally need to even know that <tt>nsmd</tt> is running.
|
|
</p>
|
|
<p>
|
|
But for those advanced users, here are the command-line options for launching nsmd separately from the GUI.
|
|
</p>
|
|
<div class="fig example"><table width=100%><tr><td><pre>
|
|
nsmd [--session-root path] [--osc-port port] [--detach]
|
|
</pre></td></tr>
|
|
</table></div>
|
|
<p>
|
|
The <tt>--session-root</tt> option allows one to override where <i>Session Root</i> is, from the default of "$HOME/NSM Sessions" (this option can also be passed to the GUI, which will hand it over to the daemon).
|
|
</p>
|
|
<p>
|
|
<tt>--osc-port</tt> instructs the daemon to bind to a specific UDP port number instead of selecting an available port automatically.
|
|
</p>
|
|
<p>
|
|
<tt>--detach</tt> instructs the daemon to close its standard input and output and go into the background. This is useful for starting the daemon remotely with <tt>rsh</tt>.
|
|
</p>
|
|
<p>
|
|
When nsmd starts, it will print a string of the following form its standard output.
|
|
</p>
|
|
<div class="fig example"><table width=100%><tr><td><pre>
|
|
NSM_URL=osc.udp://foo.bar.net:17551/
|
|
</pre></td></tr>
|
|
</table></div>
|
|
<p>
|
|
This is the OSC URL for the daemon process. If this URL is included in the environment (by either using a fixed port number or starting nsmd early in the initialization process [like in your .xinitrc] extracting the URL from its output) then any NSM capable client will join the current session when started, even if started from outside the Non Session Manager interface (for example, by your Desktop Environment's program launch menu).
|
|
</p>
|
|
<h3 id="n:1.3.1.">1.3.1. Multiple NSMD Instances</h3>
|
|
<p>
|
|
When dealing with multiple instances of nsmd, whether they be on the same host or separate hosts, it is most convenient to use fixed port numbers specified with the <tt>--osc-port</tt> command-line option.
|
|
</p>
|
|
<h4 id="n:1.3.1.1.">1.3.1.1. Distributed Session Management</h4>
|
|
<p>
|
|
In some situations it is necessary to have different audio programs running on different machines, connected by S/PDIF, analog wiring, or over TCP/IP as achieved by <tt>netjack</tt>. Usually the reason for doing this is that neither machine is powerful enough to do all the DSP or synthesis alone.
|
|
</p>
|
|
<p>
|
|
Needless to say, these configurations have historically been extremely difficult to manage--requiring heavy scripting and/or lots of manual setup.
|
|
</p>
|
|
<p>
|
|
NSM is the first--and currently only--system capable of managing these sessions.
|
|
</p>
|
|
<p>
|
|
Let us assume the following conditions for our example:
|
|
</p>
|
|
<ol><li><span>We want to distribute a session across two hosts, Host-A and Host-B, on the local area network.</span>
|
|
<li><span>Each host has a completely independent file system (i.e. not NFS).</span>
|
|
<li><span>We have appropriate access to both hosts.</span>
|
|
</ol><p>
|
|
The first step is to decide what port numbers to use. Let's choose <tt>6661</tt> for Host-A and <tt>6662</tt> for Host-B.
|
|
</p>
|
|
<p>
|
|
If either host is running a firewall, then these ports must be opened explicitly!
|
|
</p>
|
|
<p>
|
|
To start the daemon on host A:
|
|
</p>
|
|
<div class="fig example"><table width=100%><tr><td><pre>
|
|
user@host-a:~$ nsmd --detach --session-root "$HOME/distributed-nsm-sessions" --osc-port 6661
|
|
</pre></td></tr>
|
|
</table></div>
|
|
<p>
|
|
To start the daemon on host B (conveniently from host A, via rsh)
|
|
</p>
|
|
<div class="fig example"><table width=100%><tr><td><pre>
|
|
user@host-a:~$ rsh host-b nsmd --detach --session-root "\$HOME/distributed-nsm-sessions" --osc-port 6662
|
|
</pre></td></tr>
|
|
</table></div>
|
|
<p>
|
|
Note that in the above example, there is a backslash in "$HOME", this is because otherwise the variable would be expanded on the local machine, giving the local value rather than what we intended.
|
|
</p>
|
|
<p>
|
|
Now that both daemons are running, we can start the Non Session Manager interface with the following command:
|
|
</p>
|
|
<div class="fig example"><table width=100%><tr><td><pre>
|
|
user@host-a:~$ non-session-manager --nsm-url osc.udp://host-a:6661 --nsm-url osc.udp://host-b:6662
|
|
</pre></td></tr>
|
|
</table></div>
|
|
<p>
|
|
The Non Session Manager interface will then connect to the daemons on both hosts. Creating a new session will create separate session files on each host. When adding a client, the interface will present the user with a choice of which host to invoke the client on. Aside from that it is just like managing any other session. Sessions can be opened, saved, switched between, etc. and the desired effect will be seen on each host.
|
|
</p>
|
|
<h4 id="n:1.3.1.2.">1.3.1.2. Multiple Sessions On One Host</h4>
|
|
<p>
|
|
Simply starting two (or more) instances of the Non Session Manager interface on the same machine (when the NSM_URL environment variable is unset) will result in the ability to have two different sessions open at the same time on the same host. A lock file prevents the two instances from opening the same session.
|
|
</p>
|
|
<p>
|
|
Imagining a useful application of this feature is left as an exercise for the reader.
|
|
</p>
|
|
<h1 id="u:1.">Distribution</h1>
|
|
<p>
|
|
Development of the Non Session Manager can be followed with Git:
|
|
</p>
|
|
<div class="fig example"><table width=100%><tr><td><pre>
|
|
git clone git://git.tuxfamily.org/gitroot/non/non.git
|
|
</pre></td></tr>
|
|
</table></div>
|
|
<p>
|
|
There are no pre-compiled binaries available.
|
|
</p>
|
|
</div>
|
|
</body>
|
|
</html>
|