%-------------------------------------------------------------------------------
% alsa
%-------------------------------------------------------------------------------
%
% \file        alsa.tex
% \library     Documents
% \author      Chris Ahlstrom
% \date        2021-06-16
% \update      2024-11-13
% \version     $Revision$
% \license     $XPC_GPL_LICENSE$
%
%     Provides the ALSA page section of seq66-user-manual.tex.
%
%-------------------------------------------------------------------------------

\section{ALSA}
\label{sec:alsa}

   This section describes some details concerning the ALSA support of
   \textsl{Seq66}.
   Currently, it just includes some tricks that might be useful, plus some
   clarification.

\subsection{ALSA / Through Ports}
\label{subsec:alsa_through_ports}

   When running the commands \texttt{aplaymidi -l} or \texttt{arecordmidi -l},
   one sees something like the following.
   Notice that there is only one Thru port.
   The MIDI Through port is useful for...?
   They are virtualized hardware MIDI loopbacks that make it so
   programs that only output to "hardware" ports can use them
   to control and sequence other programs in an ALSA or JACK session.
   Also see how to increase the number of ALSA MIDI Thru ports in
   \cite{alsathru}.

   \begin{verbatim}
    Port    Client name                      Port name
    14:0    Midi Through                     Midi Through Port-0
    28:0    nanoKEY2                         nanoKEY2 MIDI 1
     . . .
   \end{verbatim}

   Note that "14:0" consists of the ALSA client ID, 14, and the port ID of the
   Midi Through pseudo-device, 0.

   \index{linux!system MIDI Thru}
   \index{MIDI Thru}
   One minor issue with the system MIDI Thru port is that, if it and another
   input port (e.g. VMPK) are both enabled, then each note emitted by VMPK is
   doubled. Be aware.

   \begin{quote}
      "ALSA always creates 1 MIDI through port. Since I work with Windows music
      applications via Wine, and because MIDI through ports are
      everything-proof, how can I increase the amount of MIDI through ports
      created by ALSA?"
   \end{quote}

   To add more Thru ports, first use \texttt{modinfo} to see information about
   the kernel module \texttt{snd-seq-dummy}.  Part of the output is shown here:

   \begin{verbatim}
      $ /sbin/modinfo snd-seq-dummy
      filename:    /lib/modules/5.7-amd64/kernel/sound/core/seq/snd-seq-dummy.ko
      alias:       snd-seq-client-14
      description: ALSA sequencer MIDI-through client
      author:      Takashi Iwai <tiwai@suse.de>
      name:        snd_seq_dummy
      parm:        ports:number of ports to be created (int)
      parm:        duplex:create DUPLEX ports (bool)
   \end{verbatim}

   Edit the following file (create it if necessary)
   to add a line to change the number
   of Thru ports.  We use the '\#' prompt to indicate root access or usage of
   \texttt{sudo}.
   Save it.
   No need to reboot, this \textsl{Linux}.
   just remove and reinsert the module with the
   "mod" commands, as root:

   \begin{verbatim}
      # vi /etc/modprobe.d/alsa-base.conf
      options snd-seq-dummy ports=2
      # rmmod snd_seq_dummy
      # modprobe snd_seq_dummy
   \end{verbatim}

   Then listing the ports will show:

   \begin{verbatim}
    Port    Client name                      Port name
    14:0    Midi Through                     Midi Through Port-0
    14:1    Midi Through                     Midi Through Port-1
    28:0    nanoKEY2                         nanoKEY2 MIDI 1
     . . .
   \end{verbatim}

   This will, of course, throw off the \textsl{Seq66} port numbering, unless
   one has implemented port-mapping (\sectionref{sec:port_mapping}).
   (But remember that using virtual ports will disable port-mapping.)

\subsection{ALSA / Virtual MIDI Devices}
\label{subsec:alsa_virtual_midi_devices}

   The "manual" ports of \textsl{Seq66} are "virtual" ports.
   From \textsl{The Linux MIDI-HOWTO} \cite{midihowto}:

   \begin{quote}
   MIDI sequencers like to output their notes to MIDI devices that normally
   route their events to the outside world, i.e., to hardware synths and
   samplers. With virtual MIDI devices one can keep the MIDI data inside the
   computer and let it control other software running on the same machine. This
   HOWTO describes all that is necessary to achieve this goal.
   \end{quote}

   To use ALSA's virtual MIDI the
   \texttt{snd-card-virmidi} module must be present. 

   \begin{verbatim}
   # Configure support for OSS /dev/sequencer and /dev/music (/dev/sequencer2)
   # (Takashi Iwai: unnecessary to alias beyond the first card, i.e., card 0)
   alias sound-service-0-1 snd-seq-oss
   alias sound-service-0-8 snd-seq-oss
   # Configure card 1 (second card) as a virtual MIDI card
   sound-slot-1 snd-card-1
   alias snd-card-1 snd-virmidi
   \end{verbatim}

   More to come, such as an explanation of \texttt{aconnectgui}....
   Also see the article about ALSA and JACK MIDI \cite{midilinux}.

\subsection{ALSA / Trouble-Shooting}
\label{subsec:alsa_testing}

   This section describes some trouble-shooting that can be done with ALSA.

\subsubsection{ALSA / Trouble-Shooting / ALSA Breakage}
\label{subsubsec:alsa_testing_alsa_breakage}

   We have seen ALSA MIDI support break, perhaps due to a system update, on
   \textsl{Arch Linux}..
   The first symptom is a prompt when \textsl{Seq66} starts:

   \begin{verbatim}
      Internal error.  Creating master bus failed; check MIDI drivers or reboot
   \end{verbatim}

   One can verify that it is not a \textsl{Seq66} issue by running
   \texttt{aplaymidi} or \texttt{arecordmidi}:

   \begin{verbatim}
      $ aplaymidi -l
      ALSA lib seq_hw.c:529:(snd_seq_hw_open) open /dev/snd/seq failed: No
      such device
      Cannot open sequencer - No such device
   \end{verbatim}

   If the command \texttt{modprobe snd\_seq} run as \texttt{root} does
   not work, a reboot will.

\subsubsection{ALSA / Trouble-Shooting / MIDI Clock}
\label{subsubsec:alsa_testing_midi_clock}

   MIDI clock is a signal broadcast to ensure
   several MIDI-enabled synthesizers or sequencer stay in
   synchronization. Clock events are sent at a rate of 24 pulses per quarter
   note.  THey maintain a synchronized tempo for synthesizers
   that have BPM-dependent voices, and for arpeggiator synchronization.

\paragraph{ALSA MIDI Clock Send}
\label{paragraph:alsa_testing_midi_clock_send}

   To verify that \textsl{Seq66} sends MIDI clock, the easiest way in
   ALSA is to run the following command and set \textsl{Seq66} to send
   MIDI Clock to the \texttt{aseqdump} port that appears after restarting
   \textsl{Seq66}:

   \begin{verbatim}
      $ aseqdump
      Waiting for data at port 129:0. Press Ctrl+C to end.
      Source  Event                  Ch  Data
        0:1   Port subscribed            128:0 -> 129:0
   \end{verbatim}

   Once set up, start playback on \textsl{Seq66}.
   The result should be a never-ending stream of rapid MIDI clock messages.

\paragraph{ALSA MIDI Clock Receive}
\label{paragraph:alsa_testing_midi_clock_receive}

   To verify that \textsl{Seq66} receives MIDI clock in ALSA, use a sequencer
   that can emit MIDI Clock in ALSA.  The precursor to \textsl{Seq66},
   \textsl{Seq24}, can be used, as well as \textsl{Seq66}.
   First, run one of the following commands:

   \begin{verbatim}
      $ seq24 -m
      $ qseq66 --alsa --manual --verbose
   \end{verbatim}

   This creates a bunch of virtual ALSA MIDI ports.
   In the \textbf{MIDI Clock} for either application,
   select the \textbf{On} option for the first port.
   Then run \textsl{a debug version of Seq66} in a terminal window
   with the following options:

   \begin{verbatim}
      $ qseq66 --alsa --auto-ports --verbose --client-name seq66debug
   \end{verbatim}

   This sets up to auto-connect ALSA MIDI ports.  In
   \textbf{Edit / Preferences / MIDI Input}, check-mark the first
   "seq24" port.  There should be no need to restart.
   Then start playback in \textsl{Seq24}.
   \textsl{Seq66} should display a rapid stream of MIDI Clock messages.
   If not, check the setup and, if correct, report a bug!

\paragraph{VMPK Issues}
\label{paragraph:alsa_testing_vmpk_issues}

   \index{VMPK}
   On our \textsl{Ubuntu 18} system, the \textsl{VMPK} virtual keyboard
   (version to be determined) has issues:

   \begin{verbatim}
        Seq66:  input FIFO overrun
        VMPK:   RtMidiOut::sendMessage: error sending MIDI message to port.
                RtMidiIn::alsaMidiHandler: unknown MIDI input error!
   \end{verbatim}

   In addition, we find a massive spewage of events in the pattern.
   This does not occur on our \textsl{Ubuntu 20} system with
   \textsl{VMPK v. 0.7.2}.
   However, with that version, one must go to its \textbf{Edit / Preferences}
   dialog and make sure that MIDI I/O is enabled and that both input
   and output are set to ALSA.

   Another issue occurred when we tried testing with multiple instances
   of VMPK. Both would appear in the MIDI Inputs list, with the same name but
   different client numbers.  However, input would come in on the same buss
   number, no matter which VMPK instance was played.
   Thus, it's basically useless to run more than one VMPK instance.

   See the \textsl{VMPK} website \cite{vmpk}.

%-------------------------------------------------------------------------------
% vim: ts=3 sw=3 et ft=tex
%-------------------------------------------------------------------------------
