%-------------------------------------------------------------------------------
% seq66-user-manual
%-------------------------------------------------------------------------------
%
% \file        seq66-user-manual.tex
% \library     Documents
% \author      Chris Ahlstrom
% \date        2015-11-01
% \update      2025-02-03
% \version     $Revision$
% \license     $XPC_GPL_LICENSE$
%
%     This document provides LaTeX documentation for Seq66.
%
%-------------------------------------------------------------------------------

% Replacing normal header/footer with a fancier version.  These two symbols of
% document class were showing up as "unused" in the log file.
%
%  headinclude,
%  footinclude,
%
% So we add the fancyhdr package, clear the default layout, and set it up for
% our wider pages.

\documentclass[
 11pt,
 twoside,
 a4paper,
 final                                 % versus draft
]{article}

\input{docs-structure}                 % specifies document structure and layout

\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyhead{}
\fancyfoot{}
\fancyheadoffset{0.005\textwidth}
\lhead{Seq66 Live-Loop MIDI Sequencer and Editor}
\chead{}
\rhead{User Manual}
\lfoot{}
\cfoot{\thepage}
\rfoot{}

% Removes the many "headheight is too small" warnings.

\setlength{\headheight}{14.0pt}

\makeindex

\begin{document}

\title{Seq66 User Manual v. 0.99.18}
\author{Chris Ahlstrom \\
   (\texttt{ahlstromcj@gmail.com})}
\date{\today}
\maketitle

\begin{figure}[H]
   \centering 
   \includegraphics[scale=0.45]{main-window/main-windows-perstfic.png}
   \caption*{Seq66 Windows with Perstfic Style-Sheet}
\end{figure}

\clearpage                             % moves Contents to next page

\tableofcontents
\listoffigures                         % print the list of figures
\listoftables                          % print the list of tables

% Changes the paragraph style to remove indenting and put a line between each
% paragraph.  This could be moved up into the preamble, but then would
% affect the spacing of the TOC and LOF, LOT noted above.
%
% \setlength{\parindent}{2em}
% \setlength{\parskip}{1ex plus 0.5ex minus 0.2ex}

\parindent 0pt
\parskip 9pt

\rhead{\rightmark}         % shows section number and section name

\section{Introduction}
\label{sec:introduction}

   Seq66 is a complete reboot of \textsl{Seq24} and a rewrite of
   \textsl{Sequencer64}.
   The following projects support \textsl{Seq66} and its documentation (see
   the \textbf{Help} menu):

   \begin{itemize}
      \item \url{https://github.com/ahlstromcj/seq66.git}
      \item \url{https://ahlstromcj/github.io/docs/seq66/seq66-user-manual.pdf}
      \item https://ahlstromcj.github.io/
   \end{itemize}

   Feel free to clone or fork it!
   I ain't gonna live forever!
   If you're in a hurry to get going, proceed directly to
   \sectionref{sec:introduction_lets_go}.

\subsection{Seq66: What!?}
\label{subsec:what_is_seq66}

   \textsl{Seq66} is
   a reboot of \textsl{Seq24},
   a live-looping sequencer with an interface similar to a hardware sequencer,
   refactored for newer versions of
   \textsl{C++} for faster and simpler code.
   It drops the
   \textsl{Gtkmm} user-interface in favor of \textsl{Qt 5},
   and has better handling of sets, mute-groups, sessions, configuration files,
   play-lists, and automation control.
   It supports the \textsl{Non/New Session Manager},
   has a metronome function,
   multiple input port recording,
   a modifiable color and brush palette,
   and Qt style-sheets.
   Be prepared to note some significant differences
   between \textsl{Seq66} and our first reboot, \textsl{Sequencer64}.
   The basics are the same, though.

   \textsl{Seq66} is not a synthesizer.
   It requires a hardware or software synthesizer.
   It does not handle audio data, just MIDI.
   It works with \textsl{ALSA}, \textsl{JACK},
   and \textsl{Windows}.

   We have many contributors to acknowledge.
   Please see \sectionref{sec:kudos}.
   If your name is not there, ping us!

\subsection{Seq66: Why!?}
\label{subsec:introduction_vs_others}

   The first reason to refactor \textsl{Sequencer64} is to take advantage of
   things learned in responding to user reports.  The second reason is to use
   the new code as an opportunity to add new functionality such as
   \textsl{Non Session Manager} support.  The third reason is to tighten the
   code by using newer features of \textsl{C++11} and later.
   The fourth reason is to make the innumerable minor improvements that come to
   attention with time and testing.

\subsection{Improvements}
\label{subsec:improvements}

   The following improvements are some that have been made in
   \textsl{Seq66} versus \textsl{Sequencer64}.

   \begin{itemize}
      \item \textbf{Qt} 5 as the standard user-interface offers many benefits:
         \begin{itemize}
            \item A better live frame using Qt push-buttons.
            \item The main window's size can be change, at start up or
               by dragging the corners.
            \item Palette files to support the colors used for drawing
               grid, circles, rectangles, and text.
            \item Qt style-sheets for control of colors and fonts for many
               user-interface items.
            \item A Qt linear-gradient default style for painting the
               progress boxes, notes, and triggers.
            \item Drag-and-drop support for opening a MIDI file in
               \textsl{Seq66}. Open a file explorer to find and load a
               MIDI file.
         \end{itemize}
      \item Improved the \textbf{song editor} for laying out patterns
         into a song.
         It includes transposable triggers, and
         can be opened in a tab or window.
      \item The \textbf{mutes editor} tab, improves mute-group handling
         and control.
      \item A \textbf{playlist editor} tab with improved flexibility.
      \item A \textbf{sets editor} tab examine each set.
      \item A \textbf{events editor} tab examine each event.
         Useful to trouble-shoot and fix minor event issues and
         add meta text events.
      \item A \textbf{session} tab (and Edit / Preference pages) to see that
         \textsl{Seq66} is running in the desired environment and configuation.
      \item \textbf{New/Non Session Manager} support.
         The sessions tab shows the
         locations of configuration files for the session.
      \item \textbf{MIDI control/display automation}.
         Control by "launchpad" devices, and display of statuses.
      \item Repartitioning of \textbf{configuration files} into separate files
         for flexibility; added a \textbf{color palette} file,
         Qt \textbf{style-sheets} (\texttt{*.qss});
         an enhanced keystroke and \textbf{MIDI 'ctrl'} file, with
         support for displaying pattern and action statuses.
         The main file is \texttt{qseq66.rc}.
      \item Improved \textbf{alternate} keyboard layout support, with
         some support for international keyboards.
      \item \textbf{Mapping} of port numbers to a consistent set of port names.
      \item Providing for \textbf{routing of MIDI input} events to
         patterns based on port number or output-channel number.
      \item \textbf{Export songs} to SMF 0 and 1 formats in various ways.
      \item \textbf{Internals}:
         More efficient lookups for using control maps and lambda functions.
      \item Configurable as a \textbf{command-line} application
         with the option to run as a headless \textsl{daemon}.
   \end{itemize}

   For developers, a \textsl{Seq66} build is customizable via C macros and by
   enabling/disabling options at 'configure' time.
   Distro maintainers may create their own build configurations.
   We cannot show all permutations of settings in this document,
   so don't be surprised if some screenshots don't quite match one's setup.

\subsection{Document Structure}
\label{subsec:introduction_document_structure}

   The structure of this document follows the user-interface of
   \textsl{Seq66}.
   To help the reader jump around this document, it provides
   multiple links, references, and index entries.

\subsection{Building Seq66}
\label{subsec:introduction_building_seq66}

   There are a number of ways of building Seq66.

   \begin{itemize}
      \item \textbf{Autotools Build and Install}.
         Configure, make, and install.
      \item \textbf{Bootstrap Install}.
         Generate autotools files and build.
      \item \textbf{OpenSUSE and Fedora}.
         Specifics for that Linux distro.
      \item \textbf{Qmake-based Install}.
         Optional on Linux, mandatory for Windows.
      \item \textbf{Arch Linux}.
         There is a nice \textsl{AUR} package and some
         other packages noted at (\cite{repositories}).
   \end{itemize}

   The \texttt{INSTALL} file included with the source code and
   documentation goes into great detail about these methods.
   Also see \texttt{data/readme.windows} and \texttt{contrib/notes/git.txt}
   for supplemental information.

% First Start

\input{first_start}

% The main window and live grid.

\input{live_grid}

% Menu

\input{menu}

% Patterns Panel

\input{patterns_panel}

% Pattern Editor

\input{pattern_editor}

% Song Editor

\input{song_editor}

% Event Editor

\input{event_editor}

% Session Management

\input{sessions}

% Import/Export

\input{midi_export}

% Recording

\input{recording}

% Configuration files are now consolidated into one file

\input{configuration}

% Playlists

\input{playlist}

% Set Master

\input{setmaster}

% Mutes and mute-groups

\input{mutes}

% Palettes

\input{palettes}

% Tables of keyboard and mouse actions

\input{kbd_mouse}

% Meta-event support

%%% \input{meta_events}

% Windows

\input{windows}

% Discussion of ALSA support

\input{alsa}

% Discussion of JACK support

\input{jack}

% Port-Mapping

\input{port_mapping}

% Headless version

\input{headless}

% Setup for Launchpad Mini

\input{launchpad_mini}

% Important Concepts

\input{concepts}

% Discussion of MIDI formats related to Seq24 and Seq66

\input{midi_formats}

% Acknowledgments

\input{kudos}

\section{Summary}
\label{sec:summary}

   Contact: If you have ideas about \textsl{Seq66} or a bug report,
   please email us (at \url{mailto:ahlstromcj@gmail.com}).
   If it's a bug report, please add \textbf{[BUG]} to the Subject, or use the
   GitHub bug-reporting interface.

% References

\input{references}

\printindex

\end{document}

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