Attrk

Attrk is a MIDI sequencer program based on Billy Bigg's Tektracker. The original Tektracker was published under the terms of the GNU Public License (GPL) for open source software, which allows the source code to be distributed and modified, that is, improved, provided that the new source code is also made freely available for improvement. The Attrk program is a modification of the Tektracker under the privileges granted by the GPL. Attrk uses the algorithm and visual design created by Billy Biggs, but the source code has been rewritten and many additional features added. Attrk is a separate effort from the original Tektracker. For an introduction to the Tektracker you should visit http://vektor.ca/audio/ttrk/.

The Tektracker is a software sequencer. The individual "tracks" are shown in vertical columns, side by side, and in which the notes and patterns in the same row are synchronized. The sequencer runs on your PC, and the MIDI commands are sent out through the PC MIDI adapter (usually the sound card) to your musical instrument synthesizer. Like most sequencers and drum machines, the tektracker was designed with two modes: a pattern mode for entering individual notes into each pattern, and a song mode for arranging patterns into a loop, or "song."

The pattern mode screen can be seen in the screen shot below:

The song mode screen can be seen in the screen shot below:

Although the screen shots show the program running under the X graphics mode, this is merely for ease in getting the screen shot. The Attrk program should be run in console screen mode. The original Tektracker was written for use in console mode so that it could be run on an old computer and run as the root user. The Attrk program keeps this console approach.

The basic operation of the sequencer from the keyboard (there is no mouse control) is the same as the original Tektracker, with additional features. Parts of the text file documentation written by Billy Biggs is supplied below. The original text file (slightly augmented) can be found in the Attrk package as "tektracker_usage.txt". The following text clips were written by Billy Biggs.

The following paragraph explains the top two rows of the screen display, both in pattern mode and in song mode.

The next paragraph is an explanation of how to read the pattern view screen, which is the first screen displayed when you start the program.

The following paragraph shows the song mode view. This is seen by pressing the tab key.

The control of the program with the keyboard is (almost) entirely the same as the original Tektracker. The listing below, again taken from the original documentation, explains the key commands.

• ALSA Support

  The original TekTracker by Billy Biggs has support only for the OSS sound drivers. This is not a severe drawback given that ALSA drivers now provide an interface for compatibility to the OSS API. However, the ALSA mimick for OSS support requires the extra step of a symbolic link between the /dev/midi00 and ALSA's /dev/snd/midiC0D0 device files. Attrk provides a native support for ALSA so that one need only specify the hw:0,0 device file names in the ~.attrkrc file.

• Multiple Sound Adapter Support

  One of the first things I wanted when I first used TekTracker was the ability to play several synthesizer instruments in real time. Attrk has support for multiple sound adapter cards, where each sound card is a MIDI port with 16 channels. Simple insert more than one device line in the ~.attrkrc file. The device lines will be assigned to MIDI ports in the order that they are found in the file: the first adapter will be assigned MIDI port 0, the second adapter will be MIDI port 1, and so on. In the ~.attrkrc file OSS driver adapter lines are given as follows:

  device /dev/midi00
  device /dev/midi01
  .
  .
  

  and ALSA device names are given as follows:

  device hw:0,0
  device hw:1,0
  .
  .
  

  If you are using an ALSA plugin alias for your sound adapter just put the alias in place of the default hardware name.

  Adapters may be specified on the command line using the -d option, but you must not mix methods: either use the ~.attrkrc file or the command line.

• MIDI Program Change Messages

  MIDI program change messages, otherwise known as program patches, change the MIDI instrument's patch, or voice, setting. The original TekTracker provides no capability for initializing or changing the instrument patch, so I added this modification. From the keyboard, a program setting is entered by pressing ctrl-h and entering

  program,bank

  See the Attrk HOWTO for further details.

• MIDI Port Selection

  MIDI ports correspond to the hardware MIDI output ports on your computer. For example, many sound adapter cards that support MIDI have a joystick connector that doubles as a MIDI connector. Each of these adapters corresponds to a MIDI port. Each adapter card in your computer needs a "device" line in your ~.attrkrc file to be identified by Attrk. See the Attrk HOWTO for details on the setup.

• Song File Format in Xml

  The song file format is incompatible with the original TekTracker. The format is now an Xml-like ascii file. The Xml approach makes the file lighter, more flexible, and enables backward compatibility across upgrades. The file parser ignores tags that are not recognized, and options that are not found are filled with defaults. Only channels and patterns that are non-empty are saved, making the file smaller even though it is ascii. The Xml-like format is more flexible because the tag elements do not depend on the order they are found in the file. Channel and pattern tags are given index numbers (attributes) that assign their positions in the song.

  The new file format provides the capability for making adjustments to the song by editing the song file. Certain features of Attrk can only be used by editing the song file. For example, the instrument setup (MIDI control) messages that initialize custom patches on the channel are given by the elements.

• Additional Screen Cursor Keymaps

  A few keyboard commands have been added. The original TekTracker provides cursor movement with the arrow keys. Page left/right, page up/down are mapped as shift-arrow key combinations. The page commands do not work on my computer. I substituted ctrl-u for page up and ctrl-d for page down. I used ctrl-r for page right and ctrly for page left (ctrl-L is already taken).

  Keyboard entry of the instrument patch assignment is done with the ctrl-h key combination. Entry of the MIDI port assignment is performed with ctrl-b.

  The ctrl-g key sequence causes a display of MIDI channel, port and patch assignments for the song channel at the current cursor position.

• Adjustable Pattern Length

  The original TekTracker has the pattern length hard-coded to 32 notes. One of the first things I tried to change was the ability to set the pattern length. Attrk uses an endnote, assigned by the ctrl-z key combination, to set the end of the pattern. A "|" symbol will appear next to the end note in pattern mode. When patterns in the same song position (the same row in song mode) have different pattern lengths, the pattern with the smallest length takes precedence. If the pattern length is not an important feature of your usage, you may simply use the default setting, which is 32.

• Extended Command Set

  The key combinations have been largely used up in the original TekTracker. In order to open the possibility for unlimited future commands I added an extended command feature. Pressing the ":" key causes an entry prompt for further key combinations. At the prompt, enter a string containing ascii tokens separated by space characters that correspond to Attrk commands. See the Attrk HOWTO for the list of extended commands.

• MIDI Control Initialization

  Attrk performs instrument setup when the song file is loaded. MIDI patch settings are sent to each instrument (each port) as found in the song file attributes for each song channel. These are the same parameters that are entered using ctrl-h and ctrl-b. When the MIDI patch is changed using ctrl-h, this new patch will be saved when the song is saved. When the song is loaded, the instrument will be setup with this patch.

  The song file may also contain a list of MIDI control messages (see the MIDI reference for your instrument) that setup the instrument on that song channel with custom effects settings. See the Attrk HOWTO for instructions on how to enter MIDI control into the song file.

• MIDI Control Messages in Real Time

  Each instrument may be sent MIDI control messages in real time using the ":m c " command. The details are in the Attrk HOWTO section.

• Song Mode Cut/Copy and Paste Editing

  It is easy the move around your song pattern assignments in song mode: use the cut and paste feature, which is accomplished with the extended command sequence ":e x", ":e v". See the Attrk HOWTO section.

• Log File

  Attrk automatically generates a log file in the current diretcory called, "logfile.txt." This is used mainly for diagnostics.

• Session Event Recording and Playback

  Attrk has a feature that enables you to log your keystrokes to a "session" file called "session.dat". The session events include most of the song manipulation keys, leaving out those that do not make sense such as start and stop, load and save. The session log feature gives you the ability to catch all the actions you made while twiddling your patterns in real time. You can play back the session and watch the screen cursor moving around changing the settings. Instructions for using session recording are in the Attrk HOWTO.

• Ascore File Format

  The song file may be saved in ASCORE file format using the ":w a" command. ASCORE is music scoring program for Csound and MIDI scores (see also MSCORE). Whereas Attrk is better at real-time sequencer composition, ASCORE offers more control in some features such as note timing, although ASCORE is an entirely non real-time program. In fact, starting with an Attrk session is a good way to setup an ASCORE initial score.

1. HOWTO Install Attrk

2. HOWTO Start Attrk

3. HOWTO Write Your First Song

4. HOWTO Set Up the Sound Adapter

5. HOWTO Set the MIDI port on a Song Channel

6. HOWTO Change the Synthesizer MIDI Patch

7. HOWTO Turn on the Record Session Feature

8. HOWTO Turn on the Playback Session Feature

9. HOWTO Manually Send MIDI Control Messages

10. HOWTO Use Extended Commands in Session Files

11. HOWTO Cut and Paste Song Blocks

12. HOWTO Insert MIDI Instrument Initialization into the Song

13. HOWTO Use the Extended Command Set

1. HOWTO Install Attrk

   You are expected to know how to install a Linux tar ball, but here are the instructions again.

   1. Login as the root user.
   2. Copy the source package, attrk-x.x.x.tgz to /usr/local/src.
   3. Unpack the package using

      tar zxvf attrk-x.x.x.tgz

   4. cd attrk-x.x.x
   5. ./configure
   6. make
   7. make install

   After the make install step, you may run make clean. Leave the source package where it is in /usr/local/src if you later want to run make uninstall.

2. HOWTO Start Attrk

   Attrk is started from the command prompt by typing

   attrk

   or when running as the root user,

   ./attrk

   on the command line. It is recommended that you be logged in with the root user account since this is a real-time program.

   You need to have a config file in the current directory called .attrkrc. The following is an example of a working config file:

   # # .attrkrc # # # MIDI ports (OSS driver) # ports 0,1,2,3 # # device /dev/midi00 # device /dev/midi01 # device /dev/midi02 # device /dev/midi03 # # MIDI ports (ALSA driver) # ports 0,1,2,3 # device hw:0,0 device hw:1,0 device hw:2,0 device hw:3,0,0 # # Record/Playback session, better started and stopped # with keystrokes. # # record_session # playback_session mysession1.ses # # Real time priority (must be ROOT) # realtime # # Real-time clock frequency # rt_clock_frequency 1024 # # Beat pulse # # beatpulse # # Yamaha ES6 Bank settings # (settings for your synthesizer should be possible by consulting # for user's manual) # bank 0 63 32 0 # bank 1 bank 0 63 32 1 # bank 2 bank 0 63 32 2 # bank 3 bank 0 63 32 3 # bank 4 bank 0 63 32 4 # bank 5 bank 0 63 32 5 # bank 6 bank 0 63 32 32 # bank 7 - Drums

   The config file is needed for settting multiple MIDI ports and setting the bank numbers to match your synthesizer. Also, real-time priority and the clock frequency must be set in the config file.

3. HOWTO Write Your First Song

   1. Start Attrk, as shown above.

   2. Enter a note in the first position of the first pattern of the first song channel: the software comes up in pattern mode with the cursor in the upper left corner.

      Type the "e" key. A

      00: E-4 40 -

      should now be shown at the cursor. You have just entered an E in the 4th MIDI register.

   3. Enter another note at 5 beats later:

      Move the cursor down to where the number shows 16: on the left (the the 16th 32nd note).

      Type the "n" key. A

      16: A-3 40 -

      should now appear at the cursor. You have just entered an A in the 3rd MIDI register.

   4. Set this song channel (this column) to send the MIDI notes to the correct instrument on the correct MIDI channel with the correct patch:

      Example: If your instrument is on the first MIDI port you type

      ctrl-b 1 enter

      To set the MIDI channel, use the INSERT and DELETE keys to step the channel up and down. The channel will appear at the top of the column as

      Ch: 01 or Ch: 02 or Ch: 03, etc.

      Let's say that the synthesizer patch you want is on program number 25 in the 5th bank of your instrument (see the section on banks for different instruments), type

      ctrl-h 25,5 enter

      and make sure that there are no spaces between the 25 (program number) and the 5 (bank number).

   5. Give the songchannel (the column) a name: type

      ctrl-n MyNew1 enter

      as an example, naming the songchannel "MyNew1".

   6. Give this pattern a name: type

      ctrl-p Pat1 enter

      as an example.

   7. Start the song playing by pressing the F9 key. Then stop the song by pressing the F11 key. Reset to the starting position by pressing the F12 key.

   8. Save the song by typing

      ctrl-s my_song.attr enter

      where, as an example, the song name is "my_song.attr". The file extension can anything.

   9. Quit the program by typing

      ctrl-q

   10. Begin again by starting the program, as shown above. Reload the song by typing

       ctrl-a my_song.attr enter

   11. Press the tab key to switch to the Song Mode, which shows the song as a list of pattern numbers. Then press the tab key again to switch back to the pattern mode.

   Hints:

   At any time, save the current song without having to enter the complete file name by typing

   :w

   Notice that the pattern sequence repeats after 32 notes. This can be changed by setting a different position as the endnote: Position the cursor over the note to become the new endnote and type

   ctrl-z

   after which this note position will be the endnote of the pattern.

4. HOWTO Set Up the Sound Adapter

   Attrk has support for multiple sound adapter cards, where each sound card is a MIDI port with 16 channels. Simple insert more than one device line in the ~.attrkrc file. The device lines will be assigned to MIDI ports in the order that they are found in the file: the first adapter will be assigned MIDI port 0, the second adapter will be MIDI port 1, and so on. In the ~.attrkrc file OSS driver adapter lines are given as follows:

   device /dev/midi00 device /dev/midi01 . .

   and ALSA device names are given as follows:

   device hw:0,0 device hw:1,0 . .

   If you are using an ALSA plugin alias for your sound adapter just put the alias in place of the default hardware name.

   Adapters may be specified on the command line using the -d option, but you must not mix methods: either use the ~.attrkrc file or the command line.

5. HOWTO Set the MIDI port on a Song Channel

   MIDI ports correspond to the hardware MIDI output ports on your computer. For example, many sound adapter cards that support MIDI have a joystick connector that doubles as a MIDI connector. Each of these adapters corresponds to a MIDI port. Each adapter card in your computer needs a "device" line in your ~.attrkrc file to be identified by Attrk. The order that each MIDI device appears in the ~.attrkrc file will determine which port number will be assigned. The first adapter will be port 1, the second will be port 2, and so on.

   Move the cursor to the song channel for which the MIDI port should be set. Press Ctrl-B. Enter the port number in the range of 1 to N, where N is the number of MIDI adapters (devices) specified at startup of attrk. For example, if /dev/midi01 (OSS driver) was the second MIDI device in the .attrkrc file, then it will be port 2. If hw:2,0 (ALSA driver) was the 5th MIDI device found in the .attrkrc file, then it will be port 5.

6. HOWTO Change the Synthesizer MIDI Patch

   MIDI program change messages, otherwise known as program patches, change the MIDI instrument's patch, or voice, setting. The original TekTracker provides no capability for initializing or changing the instrument patch, so I added this modification. From the keyboard, a program setting is entered by pressing ctrl-h and entering

   program,bank

   where there is no whitespace, just a comma, between program number and bank number. Older synthesizers do not use bank numbers, and so you can enter zero for the bank number.

   The MIDI program setting for each song channel is stored in the song file. When the song file is loaded the instrument will be initialized. Be aware that your synthesizer must be in the correct mode for the program/bank initialization to succeed. Setting different pathes on different song channels will not work unless your instrument has a multi-voice mode (song mode on the Yamaha ES, multimode on the ES Rack).

   The bank setting uses MIDI control message sequences common to musical instrument synthesizer manufacturers such as Yamaha and Roland. This sequence is comprised of two special control messages followed by the program change message:

   control	0	MSB
   control	32	LSB
   program	number

   For the Yamaha ES (this is the only synthesizer tested),

   control	0	63
   control	32	bank_number 0-5
   program	number

   Bank numbers (1 to N) will be assigned by Attrk according to a set of bank specifier statements in your ~.attrkrc file. Bank 1 for the Yamaha ES is obtained with the following control sequence:

   control	0	63
   control	32	0

   for which a line is required in the ~.attrkrc file as

   bank 0 63 32 0

   and for banks 2, 3, 4 ,5, 6,

   bank 0 63 32 1 bank 0 63 32 2 bank 0 63 32 3 bank 0 63 32 4 bank 0 63 32 5

   must be inserted into the ~.attrkrc file. Note that the bank numbers, as you enter them from the keyboard or in the song file correspond to the bank statements in the order they are read from the ~.attrkrc file. Thus, if you were (for whatever reason) to enter the above bank statements in reverse order your bank 1 would be the instrument's bank 6. The two MSB, LSB control messages appear to be common among industry musical instruments. The following bank change messages were taken from the Roland XP-30 manual for banks "USER", "PR-A", "PR-B" and "PR-C":

   USER:

   control	0	80
   control	32	0

   PR-A:

   control	0	81
   control	32	0

   PR-B:

   control	0	81
   control	32	1

   PR-C:

   control	0	81
   control	32	2

   In the ~.attrkrc file the following lines would assign USER to bank 1, PR-A to bank 2, etc:

   bank 0 80 32 0 bank 0 81 32 0 bank 0 81 32 1 bank 0 81 32 2

   The bank statement is comprised of the "bank" keyword followed by any number of number pairs. The bank statements illustrated above each have two number pairs following the bank keyword. The Attrk program will accept any number of pairs. If, for example, you have an instrument that needs only one control message to make a bank change, say, control number 0 with value corresponding to the bank number:

   control

   0

   0,1,2,3...

   then you need only supply bank statements containing one pair:

   bank 0 0 bank 0 1 bank 0 2 bank 0 3

   Similarly, if some instrument were to need three control messages for a bank change, the bank statements in your ~.attrkrc file would each have three number pairs after the bank keyword.

   If you have an old synthesizer that does not use banks, do not try to put a bank statement with no pairs--just enter a 0 for bank number at the keyboard or in the song file.

7. HOWTO Turn on the Record Session Feature

   Edit the .attrkrc file in the current directory. Add the following line

   record_session

   being the only text on the line, all lower case. When you quit (ctrl-q) the session will be automatically saved in the current directory as "session.dat". If there is already a file by that name in the current directory it will be overwritten.

   An alternate, perhaps better, way to turn on a recording session is to use keyboard commands:

   At the keyboard, enter

   :s r 1

   to turn recording on. To turn recording off, enter

   :s r 0

8. HOWTO Turn on the Playback Session Feature

   Edit the .attrkrc file in the current directory. Add the following line

   playback_session

   filename

   where filename is the name of the session file. This can be the session that was just saved, session.dat, or an older session that you renamed for latter use.

   An alternate, perhaps better, way to turn on a playback session is to use keyboard commands:

   At the keyboard, enter

   :s p 1

   to turn playback on. To turn playback off, enter

   :s p 0

   Or, you can toggle playback on and off by successively typing

   :s p

   To begin playback and specify the session file, enter

   :s p filename

9. HOWTO Manually Send MIDI Control Messages

   Use the extended command feature, with the key stroke sequence

   :m c number value

   That is, move the cursor to the song channel for which the MIDI control message is to be sent (send to the instrument assigned to that channel). Enter the key sequence above, where is the control number (see the MIDI reference for your instrument) in the range 1 to 128 (hint: 7 will be the General Midi volume setting). The parameter is the value, 1 to 128, corresponding to the specified control number.

   Hint on the extended commands: pressing ":" opens the input prompt. Then enter the "m c " sequence. Don't expect to enter a ":" after the prompt appears.

10. HOWTO Use Extended Commands in Session Files

    To send a MIDI control message in a session playback file, use the following syntax,

    beat_number

    ext_midi_control

    ctrl_number value channel

    where beat_number> is the beat position in the song. ctrl number is the General MIDI control identifier (7 is volume, 10 is pan, etc). channel is the song channel to change counting from 0. That is, the left-most channel on the screen is channel 0.

    Example: change the volume to 35 on song channel 0 at 2000 beats into the song,

    2000 ext_midi_control 7 35 0

    To set the loop position in a session file, use

    beat_number	ext_loop_position	song_pos_2
    beat_number	ext_loop_destination	song_pos_1

    For example, you want the looping to be between song position 4 and 15 starting at song beat 1600. To smoothly transition, you move the "loop position" (the bottom end of the loop) to 15 a little before beat 1600, say 1580:

    1580 ext_loop_position 15

    then after the song position crosses down to 4 you set the "loop destination" (the top of the loop),

    1610 ext_loop_destination 4

    The last parameter, song position, matches the number on the far left of the song mode screen and starts at 0.

11. HOWTO Cut and Paste Song Blocks

    In song mode, position the cursor to the upper, left corner of the block to be cut. Press

    :e m

    which marks the upper-left. Then move the cursor to the lower, right corner. Press

    :e n

    which marks the lower right. The block will be "cut" (deleted and copied into the edit buffer) with

    :e x

    Now move the cursor to the upper, left corner of the target location. To paste the block press

    :e v

12. HOWTO Insert MIDI Instrument Initialization into the Song

    Attrk performs instrument setup when the song file is loaded. MIDI patch settings are sent to each instrument (each port) as found in the song file attributes for each song channel. These are the same parameters that are entered using ctrl-h and ctrl-b. When the MIDI patch is changed using ctrl-h, this new patch will be saved when the song is saved. When the song is loaded, the instrument will be setup with this patch.

    The song file may also contain a list of MIDI control messages (see the MIDI reference for your instrument) that setup the instrument on that song channel with custom effects settings. These control messages are for initialization only and appear in the song file with the <control_setup> xml tag. There are two different ways to send control messages to the instrument: initialization messages and real-time messages. Whereas you can make real-time control changes on the current song channel by using the ":m c number value" command set, these real-time messages will not be saved in the song file (although they can be recorded in a session). On the other hand, initialization messages cannot be entered from the keyboard. MIDI control initialization messages are inserted into the song file using the following xml-element syntax:

    <control_setup>
    

    <control number=n1 value=v1 />
    <control number=n2 value=v2 />
    .
    .
    .
    <control number=nn value=vn />

    </control_setup>

    where n1, n2, ..., nn are the control numbers (1 = modulation, 7 = volume, etc) in the range 0-127, and v1, v2, ..., vn are their values in the range 0-127. This <control_setup> group must be contained inside the <channel> </channel> element.

    The following example in a song file would set the initial reverb send (control number 91) to 99 and the initial chorus send (control number 93) to 55:

    <control_setup> <control number=91 value=99 /> <control number=93 value=55 /> </control_setup>

    The <control_setup> group of MIDI messages, as well as the MIDI program patch messages, are resent to all instruments with the ":m r" command (MIDI refresh).

13. HOWTO Use the Extended Command Set

    The key combinations have been largely used up in the original TekTracker. In order to open the possibility for unlimited future commands I added an extended command feature. Pressing the ":" key causes an entry prompt for further key combinations. At the prompt, enter a string containing ascii tokens separated by space characters that correspond to Attrk commands. For example, to set the MIDI note velocity for the current note (the note under the cursor in pattern mode) to 101 enter the string

    a 101

    at the prompt. The documentation will sometimes show this operation as ":a 101". The command set is listed in the table below.

    Command	Primary key	Secondary key	values
    Note velocity	a	N/A	0-127
    MIDI control	m	c	0-127
    MIDI refresh	m	r	none
    MIDI flush	m	N/A	none
    Mark upper,left	e	m	none
    Mark lower,right	e	n	none
    Copy block	e	c	none
    Cut block	e	x	none
    Paste block	e	v	none
    Delete block	e	d	none
    Copy line	e	y	none
    Session record ON	s	r	1
    Session record OFF	s	r	0
    Session play ON	s	p	1
    Session play OFF	s	p	0
    Session play toggle	s	p	none
    Session play file	s	p	file name
    Session play reset	s	p	r
    Pattern set	p	N/A	1-N