SEQ32

SEQ32 - Midi Sequencer
======================

-----------------------------------------------------------
[1] What & Why
[2] Who 
[3] Interface
[4] Contact / Bugs / Ideas
[5] License

-----------------------------------------------------------

[1] What & Why

Seq32 is a real-time midi sequencer. It was created to 
provide a very simple interface for editing and playing 
midi 'loops'. 

-----------------------------------------------------------

[2] Who 

Written by Rob C. Buse.  I wrote this program to fill a
hole.  I figure it would be a waste if I was the only one
using it.  So, I released it under the GPL.

-----------------------------------------------------------

[3] Interface

The program is basically a loop playing machine with a 
simple interface.


[3a] Main Window

	* File. 

        The File menu is used to save and load standard 
	MIDI files.  It should be able to handle any 
	Format 1 standard files, Any other sequencer 
	should be capable of exporting.  

	* Options

	Used to configure what bus midi clock gets dumped to.

	* Help.
	
	Shows the About box.
	
	* Boxes

	Each box represents a loop. By right clicking 
	on an empty box you bring up a menu to create
	a new loop, or edit a existing one.

	Left clicking on a box will change its state
	from muted (Dark blue) to playing (Light Blue) when
	the sequencer is running.

	By clicking and holding the left button on a sequence,
	you can drag it to a new location on the grid.

        Dragging to an already existing sequence will swap locations.

        Dragging with the ALT key pressed to an in-active location will
        copy to the landing location.

        Right Clicking will bring up a menu of available options
        for the sequence.  Here you can select the midi bus/channel.
        You can also clear all performance data (on/off) see section
        [3d] for more info.

	* 'Screen Sets'

	You only see 32 loops in the main window.  This
	is a screen set.  You can switch between sets
	by using the '[' and ']' keys on your keyboard or
	the spin widget labeled set.  
	There are a total of 32 sets, for a total of 
	1024 loops. 

	* BPM

	The ; and ' keys will increase/decrease tempo as
	will the bpm spinner.	

	* Muting and Unmuting Tracks.

	Left clicking on a Tracks will toggle its playing
	status.  Hitting its assigned keyboard key will
	also toggle its status.  Below is the grid thats
	mapped to the loops on the screen set.

	[1    ][2    ][3    ][4    ][5    ][6    ][7    ][8    ]
	[q    ][w    ][e    ][r    ][t    ][y    ][u    ][i    ]
	[a    ][s    ][d    ][f    ][g    ][h    ][j    ][k    ]
	[z    ][x    ][c    ][v    ][b    ][n    ][m    ][,    ]

     	* Mute/Unmute patterns (Groups)

	You can toggle the playing status of up to 32 previously 
	defined mute/unmute patterns (groups) in the active screen 
	set, similar to hardware sequencers. 
	This is done either by one of the 'group toggle' keys 
	or by a MIDI controller, both assigned in the .seq32rc file. 
	A Mute/Unmute pattern (group) is stored by holding a 
	'group learn' key while pressing the corresponding 
	'group toggle' key. 
	There are also keys assigned to turn on/off the group 
	functionality.
    
    	* Replace

	Holding down 'Left Ctrl' while selecting a sequence 
	will mute all other sequences and turn on the selected
	sequences.

        * Restore

	Holding 'Alt' will save the state of playing sequences
	and restore them when 'Alt' is lifted.

	Holding 'Left Ctrl' and 'Alt' at the same time will enable
	you to flip over to new sequences briefly and then
	flip right back upon lifting 'Alt'.

        * Queue

	Holding 'Right Ctrl' will queue a on/off toggle for a 
	sequence when the loop ends. Queue also works for mute/unmute 
	patterns (groups), in this case every sequence will toggle 
	its status after its individual loop end. 

        * keep queue

	Pressing the 'keep queue' key assigned in the .seq32rc file 
	activates permanent queue mode until you use the temporary 
	Queue function again pressing 'Right Ctrl'. 


[3b] Options Window

	This window allows us to select which sequence gets midi
        clock, and which incoming midi events control the sequencer.


[3c] Edit Window

	Right clicking on the main window then selecting
	New/Edit will bring up the edit window.	

	The top bar of the sequence editor lets you 
	change the name of the sequence, the time 
        signature of the piece, and how long the loop
        is.

	Snap selects where the notes will be drawn. Note
	Length determines what size they will be.  Scale 
        is the relation between midi ticks and pixels. 
        1:4 = 4 ticks per pixel.  The Bus button selects
        which ALSA device to use, and which midi channel.          

        The 3rd line contains the Undo button, which will roll
        back any changes to the sequence from this session.
        You can select which Scale and Key the piece is in
        and it will grey out those keys on the roll not in 
        the key.  You can select a sequence to draw on the 
        background to help with writing corresponding parts.

	Holding the mouse over any button for a short period
	will let you view what it does.

	While the sequencer is playing, you can mute/unmute
	the sequence by toggling the [Play] button.  The 
	[Thru] button will relay any ALSA midi input
	to the sequences Bus and midi channel.  [Record] 
	will capture and ALSA midi input and save it in the
	sequence.

        Midi record supports simultaneous multi-sequence record, channel specific, up to 16 channels at once.

        Midi recording types. Recording button 'Merge' to select type:
            Legacy merged looped (notes are added upon looping of sequence).
            Overwrite looped record (notes will be cleared upon looping after
            the first note played and overwrite previous pass).
            Expand sequence length to fit recording (sequence does not loop and
            will expand after reaching last 1/4 measure).
            Expand and replace recording. 

        Midi step edit is added on record(seq42 not playing), starting at transport line.
        Sequence editor Ctrl-right arrow and Ctrl-left arrow key moves transport line by snap.
        Home key moves transport line to start.

	On both the grid window and the event window, HOLDING
	down the right mouse button will change your cursor
	to a pencil and put you in 'draw' mode.  Then while
        still HOLDING the right mouse button, click the left
        mouse button to insert new notes.  Many people find 
        this combination strange at first, but once you get
        used to it, it becomes a very fast method of note
        manipulation.

        Pressing  the middle mouse button will let you change 
	the length of the note.

        Chord note selection will draw notes based on the
        chord selection (Thanks to LMMS for the lookup table).

        Mute and solo individual notes on sequence editor.
            Right mouse button click on piano roll will mute,
            middle mouse button to solo. Muted keys will change color to red,
            and solo to green. These settings will NOT be saved to file.

        To display the MIDI number instead of the letter value of the note.
            Right mouse button + CTRL to toggle between letter and MIDI number
            when on the piano roll.

	The left mouse button lets you select multiple events 
        which can then be clicked and moved, cut (Ctrl-X), 
        copy (Ctrl-C), or pasted (Ctrl-V).  When the notes are 
        selected, you can delete them with the Delete key.

        You can use cursor keys to move selected notes up/down
        in pitch or left/right in time.
        Up and down move by one semitone.
        Hold down Shift to move up or down by octave.
        Right and left move the selected notes by the current snap amount.
        (Note that it does not automatically snap the notes to the grid.
        If you want that, use the quantize function first.)
        Nudge the selected notes by individual ticks by holding down the
        Shift key with left or right arrows.

        Notes will send MIDI play when added to the sequence or moved.

        Mouse scroll >> scroll vertically.
        Shift + mouse scroll >> scroll horizontally.
        CTRL + mouse scroll >> zoom-in, zoom-out horizontally.
        ALT + mouse scroll >> zoom-in, zoom-out vertically.

        Key z >> horizontal zoom-out.
        Shift z >> horizontal zoom-in.
        Key 0 >> reset horizontal zoom to default.

        Key v >> vertical zoom-out.
        Shift v >> vertical zoom-in.
        Key 9 >> reset vertical zoom to default.

	Right clicking on the event strip ( directly under
	the paino roll grid ) will allow you to add/select/move 
	midi events (not note on/off messages) somewhat like the 
	piano grid.

	The data editor ( directly under the event strip ) is used 
	to change note velocities, channel pressure, control codes,
	patch select, etc.  Just click + drag the mouse across 
	the window to draw a line.  The values will match that line.
        Any events that are selected in the paino roll or event
        strip can have their values modified with the mouse 
        wheel.

	The [Event] button allows you to select which type of data
	the event strip and data editor are currently displaying.


[3d] Performance Edit

        NAVIGATION FROM THE SONG EDITOR:

        EDITING GRID:

        Mouse scroll >> scroll vertically.
        Shift + mouse scroll >> scroll horizontally.
        CTRL + mouse scroll >> zoom-in, zoom-out horizontally.
        ALT + mouse scroll >> zoom-in, zoom-out vertically.

        Key z >> horizontal zoom-out.
        Shift z >> horizontal zoom-in.
        Key 0 >> reset horizontal zoom to default.

        Key v >> vertical zoom-out.
        Shift v >> vertical zoom-in.
        Key 9 >> reset vertical zoom to default.

        CTRL + c >> copy selected trigger to clipboard.
        CTRL + v >> paste clipboard trigger after selected trigger.
        CTRL + x >> cut selected trigger and copy to clipboard.
        Delete, backspace >> delete selected trigger.
        Middle mouse button >> paste clipboard trigger to mouse location.

        Home key >> reposition the progress line to the L marker.
        End key >> reposition the progress line to the R marker.
        's' key >> reposition the L marker to the progress line.
        Shift + 's' key >> reposition the R marker to the progress line.

        'p' key reposition song editor play location. With mouse focus on song editor(tracks),
        press 'p' to move play position to mouse location.

        --------------------

        TRACK NAME AREA:

        Left mouse button >> mute track.
        Middle mouse button >> solo track.
        Right mouse button >> show menu.

        Left mouse button - hold and drag >> to inactive track, will move to the new location.
        Left mouse button - hold and drag >> to active track, will swap locations.

        ALT + Left mouse button - hold and drag >> to inactive track, copy track to landing location.

        Mouse scroll >> scroll vertically.
        ALT + mouse scroll >> zoom-in, zoom-out vertically.

        'L' and 'R' EDIT LOOP TRACK:

        Left mouse button and drag >> move 'L' marker to pointer location.
        Right mouse button and drag >> move 'R' marker to pointer location.

        CTRL + left mouse button and drag >> A green vertical location line will appear.
            Release the CTRL button to expand insert/paste all track triggers between the 'L' and 'R'
            markers to the location line.

        ALT + left mouse button and drag >> A green vertical location line will appear.
            Release the ALT button to overwrite/paste all track triggers between the 'L' and 'R'
            markers to the location line.


        Use the collapse and expand button to modify events.

        Tempo Changes:

        To add a tempo change marker, left click on the Tempo grid in the song editor.
        A BPM pop up window will appear in which you can type, use the spin button, use the bpm key-binding
        or use tap button to set the BPM value. Press enter or return to accept the value. Press escape to abandon
        the value. Upon acceptance, a blue tempo mark will be set at the location of the left click
        location, grid snapped. Also, to the right of the marker, the tempo value will be indicated.
        Tempo values range from 1 to 600. You can move a created marker by placing the mouse pointer
        above an existing marker. The pointer will change to an up arrow, then left click and drag
        the marker to the desired location. The markers will move based on the grid snapping that
        is selected. You cannot move the first start marker and any attempt to move to the beginning
        start location will be ignored. Use the BPM spinner to the left of the first marker to
        adjust the starting BPM.

        To delete a tempo marker, right click above the marker.

        During play, when the progress line reaches the tempo mark, the BPM value will change
        to the indicated amount. Also, the main bpm spin button will indicate the current
        tempo being played. Upon stop, the main spin button will revert back to the original 
        starting value.

        The first marker at the start of the song cannot be deleted. Use the main window BPM spin
        buttons as used in previous releases to adjust the starting marker.

        STOP Markers:
        When setting the marker BPM, a value of 0 (zero) can be used to set a stop marker.
        Stop markers are indicated by red color, and the bpm value will indicate "[stop]".
        When playing, as the progress mark encounters a stop marker, the transport will stop.
        Stop markers can be used for editing purposes, or at the end of a song to stop the transport.
        When in Playlist mode, if stopped by a stop marker, the set list will automatically increment
        to the next file on the set list after stopping.

        Live mode:
        In live mode, only the starting bpm will be used. No subsequent tempo marks or stop marks
        will have any effect. Please note that when starting the transport from the song editor, it is
        assumed that song mode is in effect even if the main window Song/Live button is set to 'Live'.

        For the tempo map, special thanks to:
        Jonathan Moore Liles    (non-timeline)
        http://non.tuxfamily.org

[3e] .seq32rc File 

        After you run seq32 for the first time, it will generate 
        a .seq32rc file in your home directory.

        It contains the the data for remote midi control, keyboard
        control, and midi clock.

        * [midi-control]

        For each sequence, we can set up midi events to turn a 
	sequence on, off, or toggle it.  We see the following
	lines in the [midi-control] section:

        0  [0 0 0 0 0 0]   [0 0 0 0 0 0]   [0 0 0 0 0 0]            
        1  [0 0 0 0 0 0]   [0 0 0 0 0 0]   [0 0 0 0 0 0]          
        2  [0 0 0 0 0 0]   [0 0 0 0 0 0]   [0 0 0 0 0 0]   
        ...

        The first number is the sequence in the main window.  Each set 
        of brackets corresponds to a midi filter.  If the incoming midi 
        event matches the filter, it will either [toggle],[on],or[off] 
   	the sequence  respectivaly.

        The layout of each filter inside the bracket is as follows:

        [(on/off) (inverse) (midi status byte (channel ignored)) 
                                     (data1) (data2 min) (data2 max)]

	If the on/off is set to 1, it will match the incoming midi 
        to the pattern and perfrom the 	action (on/off/toggle) 
        if the data falls in the range specified.  All values 
	are in decimal.

	The last three is the range of data that will match.

	The following is an example of responding to note on events, 
        note 0, with any velocity to turn the sequence on, and note 
        off events, note 0, and any velocity to turn the sequence off.

	  Toggle                 On                         Off
        1 [0 0 0 0 0 0]         [1 0  144 0 0 127]          [1 0 128 0 0 127]

	the inverse field will make the sequence perform the opposite 
        action (off for on, on for off) if the data falls outside the 
        specified range.  This is cool because you can map several 
        sequences to a knob or fader.

	The following example would map a row of sequences to one knob 
        sending out changes for Control Code 1:

	Toggle            On                    Off
        
        0  [0 0 0 0 0 0]  [1 1 176 1   0   15]  [0 0 0 0 0 0]
        1  [0 0 0 0 0 0]  [1 1 176 1  16   31]  [0 0 0 0 0 0]
        2  [0 0 0 0 0 0]  [1 1 176 1  32   47]  [0 0 0 0 0 0]
        3  [0 0 0 0 0 0]  [1 1 176 1  48   63]  [0 0 0 0 0 0]
        4  [0 0 0 0 0 0]  [1 1 176 1  64   79]  [0 0 0 0 0 0]
        5  [0 0 0 0 0 0]  [1 1 176 1  80   95]  [0 0 0 0 0 0]
        6  [0 0 0 0 0 0]  [1 1 176 1  96  111]  [0 0 0 0 0 0]
        7  [0 0 0 0 0 0]  [1 1 176 1 112  127]  [0 0 0 0 0 0]

        Midi Transport Control:

        Midi control had been extended for transport control, recording, set and 
        playlist adjustment. The implementation follows the original seq24 method with some
        minor modification.  For transport control, start, stop, fast forward, rewind
        and beginning of song are supported. To implement the midi control for existing
        users, start seq32 then quit to generate the midi control grid for existing .seq32rc
        files. For new users, the file will be created after quitting the program for the 
        first time. All transport controls are channel specific. 

        For midi specifications, the channels are numbered from 0 to 15 and for seq32, 
        the channels are displayed from 1 to 16 (remember to offset by -1 when setting).

        Note On              = 144 + channel (0 to 15)
        Note Off             = 128 + channel (0 to 15)
        Control Code (CC)    = 178 + channel (0 to 15)

        For screen set adjustment, ability to adjust by CC value has been added to
        the screen set up group section. Use the toggle section to adjust by value.
        The following will allow value adjustment using CC (176); number 4; and also
        allow single up adjustment using A0 (note 21), channel 2.
        # screen set up (value, up, up)
        66 [1 0 176   4   0 127] [1 0 145  21   0 127] [0 0   0   0   0   0]

        The following would set play to toggle start/stop with note press C8 (midi note 108)
        on channel 1; to start only with A#7 (note 106); to stop only with A7 (note 105):
            # start playing (toggle, start, stop)
            0 [1 0 144 108   0 127] [1 0 144 106   0 127] [1 0 144 105   0 127]

        The record group will toggle recording on/off for all sequences in which
        the sequence editor is open. When recording, the only midi controls that
        are available are start/stop and record. Also, the midi events used by these
        controls will not be passed thru or used by recording.
        Example to set record to toggle with A0 (note 21). The toggle group and off
        group work for record and can also be used and will always toggle:
            # record
            2 [0 0   0   0   0   0] [1 0 144  21   0 127] [0 0   0   0   0   0]

        Example to set Fast forward with note-on (144) B7 (note 107) when pressed, and to stop when
        the key is released note-off (128):
            # fast forward (forward, forward, stop)
            3 [0 0   0   0   0   0] [1 0 144 107   0 127] [1 0 128 107   0 127]

        Rewind works similar to fast forward.

        Beginning of song will move the transport to the beginning of the song or the 
        left (L) grid marker. Each section can be used and will only set to the marker.
        Following will use A#7 (note 106) to set:
            # beginning of song 
            5 [0 0   0   0   0   0] [1 0 144 106   0 127] [0 0   0   0   0   0]

        Midi control for playlist will only be active when seq32 transport is stopped. You
        can set the playlist value while running but the selected file will not be loaded
        until the sequencer stops. If the sequencer is stopped by a stop marker, then
        the playlist will set the file at the next file past the selected value. The program
        will range check for validity, and the file list starts at 1.
        For playlist, the toggle group can be used to send by CC value, the on group for next, 
        and off group for previous.
        Example to set playlist to adjust by value, CC (178), CC number 7. Playlist Next is set
        to note A0 (21) and previous is set to A#0 (22):

            6 [1 0 178   7   1 127] [1 0 144  21   0 127] [1 0 144  22   0 127]
   
        # mute in group
       
        This section controls 32 groups of mutes in the same way as 
	defined for [midi-control]. A group is a set of sequences 
	that can toggle their playing state together.
        Every group contains all 32 sequences in the active screen 
	set (see after).

        [mute-group]

        Here there are the definitions of the state of the 32 sequences
        in the playing screen set when a group is selected.
        group [state of the first 8 sequences] [second 8] [third 8] [fourth 8]

        After the list of sequences and their midi events, you can 
        set seq32 to handle midi events and change the following: 


        * [midi-clock]

        The midi clock fields will contain the clocking state from the last 
        time seq32 was run.  Turn off clock with a 0, or on with a 1.

        * [manual-alsa-ports]

        Set this to 1 if you want to expose alsa ports to Jack.
        Set to 0 if you want manual alsa connections from seq32.

        * [vertical-zoom-sequence]

        Sets the vertical zoom default for the sequence editor.

        * [vertical-zoom-song]

        Sets the vertical zoom default for the song editor tracks.

        * [horizontal-zoom-song]

        Sets the horizontal zoom default for the song editor tracks.

        * [keyboard-control]      
        
        The keyboard control is a dump of the keys that seq32 
        recognises and its corresponding sequence number.
	Note that the first number corresponds to the number of sequences in
	the active screen set.

        * [keyboard-group]

        Same as keyboard-control, but to control groups.

   	#bpm up and down					
	-> keys to control bpm
	#screen set up and down					
	-> keys for changing the active screenset
	#group functionality on, group functionality off, group learn
	-> note that the group learn key is a modifier key to be held while 
	   pressing a group toggle key
        #replace, queue, snapshot_1, snapshot_2, keep queue
	-> These are the other modifier keys explained in section 3a.

     *NOTES*: 
	To see the required key codes when pressed, run seq32 with --show_keys.

	Seq32 will overwrite the .seq32rc file on quit. You should therefore
	quit seq32 before doing modifications to the .seq32rc file.

	Some keys should not be assigned to control sequences in seq32 as they
	are already assigned in the seq32 menu (with ctrl). 
	

[3f] JACK Transport

        In order to run seq32 with JACK Tranport Sync, you need 
        to enable it at the command line with the following flags:

        --jack_transport : seq32 will sync to JACK transport 
                           if the JACK server is available.
        
        --jack_master : seq32 will try to be JACK master
        
        --jack_master_cond : The attempt to be JACK master will 
                             fail if there is already a master,
                             otherwise it will just take over.

        --jack_start_mode <x> : When seq32 is synced to JACK,  
                                The playback command comes 
                                from the JACK server.  seq32 will 
                                play in performance mode
                                by default (section [3d]).  
                                If you want live mode, set 
                                --jack_start_mode 0.

        From the performance editor you can connect and disconnect from
        JACK using the Jack button.

        You can not change the BPM of seq32 while rolling in JACK sync mode.


-----------------------------------------------------------

[4] Playlist mode:

        A playlist is a text file containing multiple seq32 files (midi), that can be quickly loaded
        for use and accompaniment with a live performance. The playlist file should list on each line the
        full path to the midi file and name, ex:

        /home/username/seq32dir/file1.midi
        /home/username/seq32dir/file2.midi
        /home/username/seq32dir/file3.midi

        There should be no blank lines before, after, or between the files listed. Do not use
        place holders, full path only.

        Playlist mode can be invoked from the command line with the -X <path to playlist file> option.
        The playlist can also be selected from the main menu, File, Open playlist...

        When the playlist mode is first invoked, you will be prompted with a dialog pop-up asking
        if you wish to verify the playlist. For a new playlist, or if a playlist is modified, selecting 'Yes'
        would be beneficial to check for errors.  The verification will attempt to load all the files
        on the list, in order, and if errors are encountered, will stop and indicate the offending file.
        Select 'No' or escape key if the playlist has previously been verified. If the verification is
        successful, no pop-up errors will occur, and the first file on the list will be loaded.

        When playlist mode is in effect, the main window SEQ32 logo will turn blue with a red "PLAYLIST" overlay.
        In addition, the main window title and song editor title will indicate "Playlist" and
        the current song and numeric value listed in the playlist file ex:

            "seq32 - Playlist, Song 03 - [/home/username/seq32dir/file3.midi]"

        To cycle through the playlist, use the right arrow key to go down the list, and the left
        arrow key to go up the list, from the main window or song editor only. The key binding
        can be changed in the File/Options/Keyboard tab.

        The sequencer must be stopped in order to cycle up or down the playlist.

        ALERT!! - the key binding may need to be reset if a previous .seq32rc file is present 
        in your home directory. Go to File/Options/Keyboard to set the 'Playlist next' and
        'Playlist previous' keys. The default is the left(previous) and right(next) arrow keys.

        During playlist play, when the transport is stopped by a Stop marker, the playlist song will 
        automatically be incremented down by one song. (See STOP markers above).

        To shut off playlist mode, simply load a new file from the main menu, File/New or
        File/Open. You could also quit and restart. The main window title will no longer
        show the "Playlist, Song XX" listing, and the main window SEQ32 logo will reset to black.

        If editing while in playlist mode, you will NOT be prompted to save changes when moving
        to a new song on the list. If unsaved, all editing will be lost! So if editing in playlist
        mode, be sure to save before right arrow, or left arrow!

        Special thanks for the playlist idea, and some code (modified) go to:
        Simon Hickinbotham - seq24plus.
        https://github.com/franticspider/seq24plus

[5] Contact

	https://stazed@github.com/Stazed/seq32.git

-----------------------------------------------------------

[6] License

Released under the Terms of the GPL.  See the COPYING file
for a full readout.