readme.windows for Seq66 0.99.18
Chris Ahlstrom
2018-05-13 to 2025-02-03

This README file tells you how to run the native Windows implmentation of
seq66, an executable named qpseq66.exe.  It provides some notes on Seq66 and
Windows.  We mostly use Windows 10; some features might differ in Windows 7 or
Windows 2012 Server. Note that Seq66 is a 64-bit application for Windows.
This release fixes known issues and adds other work as noted in NEWS and
RELNOTES.

There is a portable 7z package for qpseq66; an NSIS-based installer is
available (read "0.99.8" as the latest version number) as part of the
latest GitHub release. An example:

    https://github.com/ahlstromcj/seq66/releases/download/0.99.8/seq66_setup_x64-0.99.8.exe

For full documentation (PDF user manual), also see

    https://github.com/ahlstromcj/seq66/doc

or the install directory. Or use the Help menu to access the tutorial and user
manual. Some minor features are missing from the Windows version, such as
virtual ports. Sample configuration files are provided.

Why the name qpseq66.exe instead of seq66.exe? The "q" stands for the Qt user
interface, and the "p" stands for the PortMidi-based engine used for Windows.

Once installed, go to "C:/Program Files/Seq66" and create a desktop shortcut
for qpseq66.exe, with the following command line (for a default Windows 10
setup having only the MIDI Mapper and the Microsoft wave-table synthesizer
installed):

    C:\Program Files\Seq66\qpseq66.exe

(Other files are available in the 'data' directory.  For example, the user
manual is a PDF file stored in:

    C:\Program Files\Seq66\data\doc\seq66-user-manual.pdf

and sample Seq66 MIDI files are stored in

    C:\Program Files\Seq66\data\midi

for demonstration of various Seq66 features.)

Run the 'qpseq66.exe' shortcut and load a tune from the MIDI directory.  If
there application seems frozen, exit it (which saves the initial set of
configuration files), and run it again.

If an error appears, click out and run it again, and there should be a "MIDI
Mapper" present on buss 0.  Load a song, and select the "0" device from the
buss dropdown ("None") at the top of the main page.  The file should play.
You can save the file to preserve the new buss number; songs can be set to
play on multiple busses.

Note that the configuration files for Seq66 get created at first exit.  They
reside in 

        C:/Users/myname/AppData/Local/seq66/

Palette files, style sheets, and sample 'ctrl' files can be copied from

    C:\Program Files\Seq66\data\windows     and
    C:\Program Files\Seq66\data\samples

Try the incrypt-66 and perstfic-66 palette and qss (style-sheet) files!  They
can be set up by editing the 'rc' and 'usr' file, or in UI (followed by a
complete restart of Seq66).

Inaccessible Devices:

    When first starting qpseq66 on Windows 10, one might experience some
    issues.  One issue is that the Microsoft MIDI Mapper, rumored to be
    removed in Windows 8 and beyond, is still detected by the PortMidi library
    used in qpseq66.  Another issue is that the built-in Microsoft wave-table
    synthesizer is not accessible, because the MIDI Mapper grabs it.  So Seq66
    detects this situation and disables the wave-table synthesizer, instead
    using the MIDI Mapper (device 0) to access the synthesizer, and it shows a
    warning dialog.  To make the disabling change permanent, exit Seq66 and
    restart it.  Then, for the basic setup on Windows, only output bus 0 is
    available.  And no input bus is available, so Seq66 ignores that, so that
    one can at least do MIDI playback.

    Furthermore...

    ...We installed the CoolSoft MIDIMapper and VirtualMIDISynth to try to get
    around these issues, and tried to turn off the system setup of "Allow
    applications to restrict access to this device."  But we still had
    inaccessible devices, and the resulting errors would cause qpseq66 to
    abort.  So we had to spend a lot of time supporting the disabling of
    inaccessible ports, and saving and restoring the "rc" setup properly.
    Here is the latest output on our Windows, generated using the option "-o
    log=virtualmidi.log":

        qpseq66 
        C:/Users/myname/AppData/Local/seq66/virtualmidi.log 
        2019-09-13 09:09:59 
        [MIDIMAPPER] 'mapper in : midiInGetDevCaps() error for device
            'MIDIMAPPER': 'The specified device identifier is out of range' '
        pm_winmm_general_inputs(): no input devices
        PortMidi MMSystem 0: Microsoft MIDI Mapper output opened
        PortMidi MMSystem 1: CoolSoft MIDIMapper output closed
        PortMidi MMSystem 2: Microsoft GS Wavetable Synth output opened
        PortMidi MMSystem 3: VirtualMIDISynth #1 output closed
        [Opened MIDI file,
    'C:\Users\myname\Documents\Home\seq66\data\b4uacuse-gm-patchless.midi']
        [Writing rc configuration
            C:\Users\myname\AppData\Local\seq66\qpseq66.rc]
        PortMidi call failed: [-1] 'Bad pointer'
        PortMidi call failed: [-1] 'Bad pointer'
        Begin closing open devices...
        Warning: devices were left open. They have been closed.

    We still have some minor issues at start up and at exit, but are now able
    to play a tune on the wavetable synthesizer using the "-b 0" option.
    Bus (port) 0 accesses the Windows MIDI Mapper.

    When you first run qpseq66 on Windows, it will create new configuration
    files:

        C:\Users\username\AppData\Local\seq66\qpseq66.rc
        C:\Users\username\AppData\Local\seq66\qpseq66.usr
        C:\Users\username\AppData\Local\seq66\qpseq66.ctrl
        C:\Users\username\AppData\Local\seq66\qpseq66.drums
        C:\Users\username\AppData\Local\seq66\qpseq66.mutes
        C:\Users\username\AppData\Local\seq66\qpseq66.palette
        C:\Users\username\AppData\Local\seq66\qpseq66.playlist
    
    Inaccessible devices are noted in the "[midi-clock]" or
    "[midi-clock-map]" sections of
    "C:\Users\username\AppData\Local\seq66\qpseq66.rc" by a "-1" (disabled)
    or "-2" (unavailable) value.
    Similar for the "[midi-input]" or "[midi-input-map]" sections.

Configuration Files:

    On Linux, the normal directory location of the Seq66 configuration
    files is "/home/username/.config/seq66".  Various confignames:

        qseq66.rc, .usr     The RtMidi Native ALSA/JACK version.
        qpseq66.rc, .usr    The PortMidi Qt 5 version.

    On Windows, the conventional location is different, and the location used
    is "C:\Users\username\AppData\Local\seq66".  The file is:

        qpseq66.rc          The PortMidi Qt 5 version for Windows.
        qpseq66.usr         Ditto.

    To access AppData, highlight the username directory, then append
    "AppData" to the end of "C:\Users\username".  It is a Windows thang.

Building the Application:

    To build, see the instructions in the "nsis\build_release_package.bat"
    file.  Basically, install Qt Creator to use the mingw compiler, and
    double-click on that batch file and let it do its thing.

    After a build, one can change to the shadow-build directory
    "seq66-release" and run
    
        Seq66qt5\release\qpseq66.exe
        
    If it does not come up after a few seconds (Windows is *slow*), then
    run:

        windeployqt Seq66qt5\release

    and try again.  Immedidately quit the application, go to your
    "AppData" directory and verify the presence of:

        qpseq66.rc
        qpseq66.usr
        qpseq66.ctrl
        qpseq66.drums
        qpseq66.mutes
        qpseq66.playlist
        seq66.log

    Now plug in a MIDI device, and do the same exercise.  Open
    qpseq66.rc and see what is in it:

    [midi-clock]

    2    # number of MIDI clocks/busses

    # Output buss name: [0] 0:0 PortMidi:Microsoft MIDI Mapper
    0 0  # buss number, clock status

    # Output buss name: [2] 1:1 PortMidi:Microsoft GS Wavetable Synth (virtual)
    1 0  # buss number, clock status

    # Output buss name: [3] 1:1 PortMidi:nanoKEY2
    2 0  # buss number, clock status
    
    [midi-input]
    
    1    # number of input MIDI busses

	# The first number is the port number, and the second number
	# indicates whether it is disabled (0), or enabled (1).

	# [1] 0:1 PortMidi:nanoKEY2
	0 0

    We still have some minor issues at start up and at exit, but are now able
    to play a tune on the wavetable synthesizer using the "-b <n>" option.

    When you first run qpseq66 on Windows, it will create two new
    configuration files:

    When you first run qpseq66 on Windows, it will create a new configuration
    file, with inaccessible devices noted in the "[midi-clock]" section of
    "C:\Users\username\AppData\Local\seq66\qpseq66.rc" by a "-1" value.

Configuration Files For Windows:

    On Windows, the conventional location is

    "C:\Users\username\AppData\Local\seq66".
    
    The files are:

        qpseq66.rc          The main usage parameters for Seq66.
        qpseq66.usr         Supplemental options, not all supported in
                            Windows yet.
        qpseq66.ctrl        Provides the MIDI input controls and output controls
                            that let one control Seq66 via MIDI and display some
                            status items to LaunchPad-like devices.
        qpseq66.drums       Provides the ability to remap drum notes.
        qpseq66.mutes       Offloads the mute settings to a separate file.
        qpseq66.palette     Provides a way to change the coloring of most
                            of Seq66.  Qt themes can also be applied.

    The log-file also goes into the AppData\Local\seq66 directory.  To access
    AppData, highlight the username directory, then append "AppData" to the
    end of "C:\Users\username".  It is a Windows thang.

    These settings are one way to alter the ports accessed.  Another way is to
    make a command-line Shortcut like the following:

        qpseq66 --buss 1 --option log=filename.out 

    It is also possible to alter the MIDI tune to use a particular buss by
    using the global buss-selection dropdown in the main window.

Keystroke Support:

    Some keystrokes are hardwired, but a number of them can be configured by
    editing the "ctrl" file directly.  This file is well-documented enough
    that it can be edited with care, so no Qt 5 keystroke editor will be
    provided.  If you are afraid to edit, find a Linux user of Seq66 and get
    them to edit one for you.

Other Information:

   http://donyaquick.com/midi-on-windows/#x1-120004.1

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