%-------------------------------------------------------------------------------
% concepts
%-------------------------------------------------------------------------------
%
% \file        concepts.tex
% \library     Documents
% \author      Chris Ahlstrom
% \date        2015-11-01
% \update      2023-10-25
% \version     $Revision$
% \license     $XPC_GPL_LICENSE$
%
%     Provides some concepts and terms needed to understand Seq66.
%
%-------------------------------------------------------------------------------

\section{Concepts}
\label{sec:concepts}

   The \textsl{Seq66} program is a loop-player machine with a 
   number of interfaces.  This section is useful
   to present some concepts and definitions of terms as
   they are used in \textsl{Seq66}.  Various terms have been used over
   the years to mean the same thing (e.g. "sequence", "pattern", "loop",
   "track", and "slot"), so it is good to clarify the terminology.

\subsection{Concepts / Reload Session}
\label{subsec:concepts_reload_session}

   While \textsl{Seq66} is flexible, changes in devices setups and other
   settings generally required the user to \textsl{reload session}.
   This reload can be done in two ways.

   \begin{itemize}
      \item \textbf{Manual Restart}
         Once a setting is changed, or a new arrangement of devices occurs,
         exit \textsl{Seq66}, examine or edit the various configuration files
         (if desired), and start \textsl{Seq66} again.
      \item \textbf{Edit / Preferences / Restart Seq66}.
         When settings in \textbf{Edit / Preferences} are changed, the
         \textbf{Reload Session} button becomes enabled.
         Click it, and the result is basically like restarting \textsl{Seq66}.
   \end{itemize}

   Note that some changes in settings will not take effect on this restart.
   For example, a style-sheet, if specified, is loaded when the application is
   created, not in the restartable loop.
   The solution is to exit \textsl{Seq66} manually and then start it again.

   In the future (version 2?), we will make \textsl{Seq66}
   able to better detect and
   reconfigure for system changes and preferences changes.

\subsection{Concepts / Terms}
\label{subsec:concepts_terms}

   This section doesn't provide comprehensive coverage of terms.  It
   covers terms that might be puzzling.

\subsubsection{Concepts / Terms / loop, pattern, track, sequence}
\label{subsubsec:concepts_terms_loop}

   \index{loop}
   \index{pattern}
   \index{sequence}
   \textsl{Loop} is a synonym for \textsl{pattern}, \textsl{track},
   or \textsl{sequence}; the terms are used interchangeably.
   Each loop is represented by a box (pattern slot) in the Pattern (main)
   window, also known as the "Patterns Panel" or "Live Grid"..

   A loop is a unit of melody or rhythm
   extending for a small number of measures (in most cases).
   Each loop is represented by a box in the patterns panel.
   Each loop is editable.  All patterns can be layed out in
   a particular arrangement to generate a more complex song.
   \index{slot}
   A \textsl{slot} is a box in a pattern grid that holds a loop.
   Note that other sequencer applications use the term "sequence"
   to apply to the complete song, and not just to one track or pattern in the
   entire song.

\subsubsection{Concepts / Terms / armed, muted}
\label{subsubsec:concepts_terms_armed}

   \index{armed}
   An armed sequence is a MIDI pattern that will be heard.
   "Armed" is the opposite of "muted", and the same as "unmuted".
   An unarmed sequence will not be heard, and it has a normal background.
   Performing an \textsl{arm} operation in \textsl{Seq66}
   means clicking on an "unarmed" sequence in the patterns panel (the main
   window of \textsl{Seq66}).
   When the sequence is \textsl{armed}, it will be heard, and it has a
   more noticeable background.
   A sequence can be armed or unarmed in many ways:

   \begin{itemize}
      \item Clicking on a sequence/pattern box.
      \item Pressing the hot-key for that sequence/pattern box.
      \item Setting up a mute-group containing that pattern, and then
         activating it with its hot-key.
      \item Opening up the Song Editor and starting playback; the
         sequences arm/unarm depending on the layout of the
         sequences and triggers in the piano roll of the Song Editor.
      \item Using a MIDI control, as configured in a 'ctrl' file, to
         toggle the armed status of a pattern or select a mute-group.
   \end{itemize}

\subsubsection{Concepts / Terms / bank, screenset, play-screen}
\label{subsubsec:concepts_terms_bank}

   \index{screenset}
   A \textsl{screenset}
   is a set of patterns that fit within the \textbf{4 x 8}
   grid of loops/patterns in the patterns panel.
   \textsl{Seq66} supports multiple screens sets, up to 32 of them,
   and a name can be given to each for clarity.
   Some other sizes, such as \textbf{8 x 8} and \textbf{12 x 8}, are
   partly supported.
   \index{bank}
   The term "bank" is \textsl{Kepler34}'s name for "screenset".
   The term "scenes" from \textsl{Ableton Live} is very similar as well.
   \index{play screen}
   By default, only one set is active and playing at a time.  This set is
   informally termed the "play screen".  There are options to let more than one
   set play at once.

\subsubsection{Concepts / Terms / buss, bus, port}
\label{subsubsec:concepts_terms_buss}

   \index{bus}
   \index{buss}
   A \textsl{buss} (also spelled "bus" these days, see
   \url{https://en.wikipedia.org/wiki/Busbar}) is an entity onto which
   MIDI events can be placed, in order to be heard or to affect the
   playback, or into which MIDI events can be received, for recording.
   A \textsl{buss} is just another name for port.
   \textsl{Seq66} can also perform some mapping of I/O ports
   for a more flexible studio setup.

\subsubsection{Concepts / Terms / performance, song, trigger}
\label{subsubsec:concepts_terms_performance}

   In the jargon of \textsl{Seq66}, a
   \index{performance}
   \index{song}
   \textsl{performance} or
   \textsl{song} is an organized collection of patterns that play a full tune
   automatically.
   This layout of patterns is created using the song editor, sometimes
   called the "performance editor".
   This window controls the song playback in "Song Mode"
   (as opposed to "Live Mode").

   \index{trigger}
   The playback of each track is controlled by a set of triggers created for
   that track.
   A \textsl{trigger} is indicates when a sequence/pattern/loop
   should be played, and how much of the sequence (including repeats) should be
   played.  A song performance consists of a number of sequences, each
   triggered as the musician laid them out.

\subsubsection{Concepts / Terms / Auto-step, Step-Edit}
\label{subsubsec:concepts_terms_auto_step}

   \index{auto-step}
   \index{step-edit}
   Auto-step (step-edit) provides a way to add notes easily when a pattern is
   not playing.  It works in two ways.  In the first way, when drawing notes on
   the pattern-editor's piano roll, dragging the mouse automatically inserts
   notes of the configured length at intervals of the configured snap.
   In the second way, incoming MIDI notes (including chords)
   are automatically logged at the given snap interval, with a length a little
   less than the configured snap interval.
   There is also a one-shot step-edit mode that is useful for recording a drum
   pattern emitted by a machine.

\subsubsection{Concepts / Terms / export}
\label{subsubsec:concepts_terms_export}

   \index{export}
   A \textsl{export} in \textsl{Seq66} is a way of writing a
   song-performance to a more standard MIDI file, so that it can be played
   exactly by other sequencers.
   An export collects all of the unmuted tracks that have
   performance information (triggers) associated with them, and creates one
   larger trigger for each track, repeating the events as indicated by the
   original performance.
   MIDI can also be exported to SMF 0 format.

\subsubsection{Concepts / Terms / group, mute-group}
\label{subsubsec:concepts_terms_group}

   \index{group}
   A \textsl{group} in \textsl{Seq66} is a
   set of patterns, that can arm/disarm all together.
   Every group contains all sequences in the active screen set. 
   This concept is similar to mute/unmute groups in hardware
   sequencers.
   \index{mute-group}
   Also known as a "mute-group".
   Mute-groups can be stored in the MIDI file or in a 'mutes' file.
   Each mute-group is associated with a keystroke or a MIDI control.

\subsubsection{Concepts / Terms / play-set}
\label{subsubsec:concepts_terms_playset}

   \index{play-set}
   A \textsl{play-set} is the current set of patterns that are available for
   playing.  Normally, this is the patterns in the current bank (play-screen),
   but \textsl{Seq66} can be configured
   (see \sectionref{subsec:configuration_rc})
   to include patterns from other sets.
   For example, one can have each newly selected set get added to the play-set
   without removing the previous set's patterns from the play-set.

\subsubsection{Concepts / Terms / PPQN, pulses, ticks, clocks, divisions}
\label{subsubsec:concepts_terms_pulses}

   \index{pulses}
   The concept of "pulses per quarter note", or PPQN, is very important for
   MIDI timing.  To make it a bit more confusing, sometimes these pulses are
   referred to as "ticks", "clocks", and "divisions".
   To make it even more confusing, there are separate timing concepts to
   understand, such as "tempo", "beats per measure", "beats per minute", and
   "MIDI clocks".
   And, when JACK is involved, one must remember that JACK "ticks" come at 10
   times the rate of MIDI ticks.
   A full description of all these terms, and how they are calculated, is
   beyond the scope of this document.

\subsubsection{Concepts / Terms / queue, keep queue, snapshot, oneshot}
\label{subsubsec:concepts_terms_queue_mode}

   The concepts here refer to playback, not recording.  The term "one-shot" in
   playback is differnt from the same term in "recording".

   To "queue" a pattern means to ready it for playback on the next repeat of
   a pattern.  A pattern can be armed immediately, or it can be queued to
   play back the next time the pattern restarts.
   Pattern toggle occurs at the next play of the pattern,
   rather than being set immediately.

   A set of queued patterns can be temporarily stored, so that a different
   set of playbacks can occur, before the original set of playbacks is
   restored.

   \index{keep queue}
   \index{queue!keep}
   The "keep queue" functionality allows the queue to be held without
   holding down a button the whole time.  Once this key is pressed,
   then the hot-keys for any pattern can be pressed, over and over,
   to queue each pattern.

   \index{snapshot}
   A \textsl{Seq66} \textsl{snapshot} is a briefly preserved
   state of the patterns.  One can press a snapshot key, change the state of
   the patterns for live playback, and then release the snapshot key to
   revert to the state when it was first pressed.  (One might call it a
   "revert" key.)

   \index{oneshot}
   \index{oneshot!playback}
   \index{one-shot}
   \index{one-shot!playback}
   \index{playback!one-shot}
   \textsl{Seq66} \textsl{one-shot playback} is a way to enable a pattern to be
   queued and then played only once.
   For recording, 
   \index{oneshot}
   \index{oneshot!recording}
   \index{one-shot}
   \index{one-shot!recording}
   \index{recording!one-shot}
   \textsl{Seq66} \textsl{one-shot recording} is a way to record notes from a
   MIDI device with automatic stepping and snapping, which terminates at the
   end of the specified length of the pattern.

\subsection{Concepts / Sound Subsystems}
\label{subsec:concepts_sound_subsystems}

\subsubsection{Concepts / Sound Subsystems / ALSA}
\label{subsubsec:concepts_sound_alsa}

   \textsl{ALSA} is a audio/MIDI system for \textsl{Linux}, with components built
   into the \textsl{Linux} kernel. It is the main subsystem used by
   \textsl{Seq66}.
   It supports virtual port connections via the \texttt{aconnect} program.
   The name of the library used to build
   \textsl{ALSA} projects is \texttt{libasound} \cite{alsa}.

\subsubsection{Concepts / Sound Subsystems / PortMIDI}
\label{subsubsec:concepts_sound_portmidi}

   \textsl{PortMIDI} is a cross-platform API (applications programming
   interface) for MIDI refactored for \textsl{Seq66}.
   It is used in the "portmidi" C++ modules, and provides support for
   \textsl{Seq66} in \textsl{Microsoft Windows} (and potentially
   \textsl{Mac OSX}).
   See reference \cite{portmidi} for the PortMIDI home page; our version
   cuts out code that requires \textsl{Java}.

\subsubsection{Concepts / Sound Subsystems / JACK}
\label{subsubsec:concepts_sound_jack}

   \textsl{JACK} is a cross-platform
   API and infrastructure
   (with an emphasis on \textsl{Linux})
   to make it easier to connect and reroute MIDI
   and audio event between various applications and hardware ports.
   It should be preferred over \textsl{ALSA}, and is selected automatically if
   running.
   It supports virtual port connections via the \texttt{qjackctl} program or
   the \textsl{Non Session Manager}.
   See reference \textsl{JACK Audio Connection Kit} \cite{jack}.

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