Notes for RaySession and Agordejo Session Managers
Chris Ahlstrom
2025-01-15 to 2025-01-18

This document provides a brief, startup description of using raysession
and agordejo. Both use the Non/New Session Manager (NSM) protocol, more
or less. Descriptions of session control via signals, a JACK session,
or NSM can be found in the *Session Management* section of the Seq66
user manual.

Note that these two session managers, raysession and agordejo, can
be started, along with JACK, via the contrib/scripts/jackctl script.

Also included is our steps to get a new setup without a session manager,
and then run Seq66 with one.

=============
 Ray Session
=============

 1. Start JACK server.
 2. RaySession includes its own implementation of the NSM server.
 3. Run this command to use a more hidden session directory instead of
    "~/Ray Network Sessions":

    $ raysession --session-root /home/$USER/.local/share/ray &

    Note: After exit, the configuration files for RaySession itself are in

        /home/$USER/.config/RaySession/RaySession.conf etc.

    Also, the /home/$USER/.local/share/ray/... session directories do not
    quite follow NSM convention.

 4. Use "With JACK patch memory". Ok. This yields a session with the "JACK
    Connections" client running.
 5. Add Seq66 (qseq66), qsynth, etc. using the "+ Application" button.

    [ We see Jack Connections twice, agordejo, Qtractor, Seq66, but not
      Qsynth.  WHY?  Can add our jackctl script, but it comes up as a
      Ray-Hack with need to configure ]

=============
 Agordejo
=============

 1. Start JACK server. Might be able to do some minimal work with ALSA.
 2. Agordejo includes an implementation of the NSM server.
 3. No need to set --session-root; the default is
    /home/$USER/.local/share/nsm, but we can do it anyway.

The next section shows how to start from scratch by running Seq66
without a session manager and getting the basic setup to work.

=============
 First Run
=============

 1. Make sure NO session manager is running. Make sure JACK is not
    active.
 2. Remove or move aside all qseq66.* files in ~/.config/seq66.
 3. Plug in devices: AKAI MPK Mini Play, Korg nanoKEY2, Alesis Q25,
    Launchpad Mini, etc.
 4. Start software synthesizers such as Yoshimi in ALSA mode.
 5. $ jackctl --start --a2j

    Seq66 provides this script in contrib/scripts/jackctl.
    This starts JACK and a2jmidi. See the script for details.

 6. Start software synthesizers such as Qsynth in JACK mode.
 7. Optional: Start QjackCtl
    1. Setup / Misc / Start JACK audio...  Disable
    1. Setup / Misc / Stop JACK audio...   Disable
    1. xxx
    1. xxx
    1. xxx
    1. Optionally the Graph view.
 8. $ qseq66 --jack
 9. Verify the setup. See the "Setup" section below.
10. Make the following additional settings:

    1. Clock tab: enable "MIDI Ctrl Out" and select the Launchpad Mini.
    2. Input tab: Enable all inputs except "Midi Through Port-0".
    3. Click the "Restart Seq66!" button.
    4. Input tab: enable "MIDI Ctrl In" and select the Launchpad Mini.
    5. JACK tab: Disable "JACK auto-connect". We need the session
       manager to set up the connections.
    5. Session tab: Change the name of the 'ctrl' file to
       "launchpad.ctrl".
    6. Click the "Restart Seq66!" button.

    Verify by stopping qseq66 and restarting it. Fix any wrong settings
    and try again.
11. Copy "data/linux/qseq66-lp-mini-alt.ctrl" to
    "~/.config/seq66/launchpad.ctrl".
12. Edit all the configuration files to see that they are correct.
    Keep fixing and rerunning qseq66 until it all works.

    Note that qseq66 can be run with or without the option to
    "auto-connect" qseq66 to existing JACK ports.

=============
 NSM Run
=============

Once all the setup issues are complete, one can run a session manager.
We will use Agordejo here. Also, we will use the script jackctl,
found in contrib/scripts, to set up JACK, start the a2jmidid daemon
to expose hardware USB MIDI devices to JACK, and start the session
manager. (It can also start up a software synthesizer, but we want
the session manager to do that.) The steps might differ slighly depending
on the host computer setup. The script requires that jackdbus be running
in order to use the jack_control command. We assume the session
configuration directory (step 1.4 below) is not yet present.

    1. Run the following command (assuming jackctl is in the PATH); it
       performs the following steps, with short sleeps to ensure startup:

       $ jackctl --start --a2j --session

       1. jack_control start
       2. jack_control dps period 128
       3. a2jmidid --export-hw -u &
       4. agordejo --session-root /home/$USER/.local/share/nsm &

    2. Make sure that any MIDI applications (e.g. Qsynth) are set up for
       JACK. Close them once set up.
    3. 

   xx. To close out the session:

       1. Save and Close the session, then quit Agordejo. This should
          also close qseq66 and qsynth.
       2. Run the following command.

          $ jackctl --stop --a2j

=============
 Setup
=============

    Clock:

        Midi Through Port-0
        Launchpad Mini MIDI 1
        nanoKEY2 nanoKEY2 _ CTRL
        Q25 MIDI 1
        MPK mini Play mk3 MIDI 1
        a2j:yoshimi input
        fluidsynth-midi:midi_00

        x MIDI I/O Port Maps

    Input:

        Midi Through Port-0
        Launchpad Mini MIDI 1
        nanoKEY2 nanoKEY2 _ CTRL
        Q25 MIDI 1
        MPK mini Play mk3 MIDI 1


# vim: sw=4 ts=4 wm=8 et ft=sh
