HOWTO Install Attrk
You are expected to know how to install a Linux tar ball, but here are the
Login as the root user.
Copy the source package, attrk-x.x.x.tgz to /usr/local/src.
Unpack the package using
tar zxvf attrk-x.x.x.tgz
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.
HOWTO Start Attrk
Attrk is started from the command prompt by typing
or when running as the root user,
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:
# 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
# Record/Playback session, better started and stopped
# with keystrokes.
# playback_session mysession1.ses
# Real time priority (must be ROOT)
# Real-time clock frequency
# Beat pulse
# 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.
HOWTO Write Your First Song
Start Attrk, as shown above.
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.
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.
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
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).
Give the songchannel (the column) a name: type
ctrl-n MyNew1 enter
as an example, naming the songchannel "MyNew1".
Give this pattern a name: type
ctrl-p Pat1 enter
as an example.
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.
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.
Quit the program by typing
Begin again by starting the program, as shown above. Reload the
song by typing
ctrl-a my_song.attr enter
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.
At any time, save the current song without having to enter the complete
file name by typing
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
after which this note position will be the endnote of the pattern.
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:
and ALSA device names are given as follows:
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.
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.
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
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:
For the Yamaha ES (this is the only synthesizer tested),
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:
for which a line is required in the ~.attrkrc file as
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":
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:
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.
HOWTO Turn on the Record Session Feature
Edit the .attrkrc file in the current directory. Add the following line
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
HOWTO Turn on the Playback Session Feature
Edit the .attrkrc file in the current directory. Add the following line
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
To begin playback and specify the session file, enter
:s p filename
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.
HOWTO Use Extended Commands in Session Files
To send a MIDI control message in a session playback file, use the
||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
|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,
|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.
HOWTO Cut and Paste Song Blocks
In song mode, position the cursor to the upper, left corner of the block
to be cut. Press
which marks the upper-left. Then move the cursor to the lower, right
which marks the lower right. The block will be "cut" (deleted and copied
into the edit buffer) with
Now move the cursor to the upper, left corner of the target location. To
paste the block press
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 number=n1 value=v1 />
<control number=n2 value=v2 />
<control number=nn value=vn />
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 number=91 value=99 />
<control number=93 value=55 />
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).
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
at the prompt. The documentation will sometimes show this operation as
":a 101". The command set is listed in the table below.
|| Primary key
|| Secondary key
| Note velocity
| MIDI control
| MIDI refresh
| MIDI flush
| Mark upper,left
| Mark lower,right
| Copy block
| Cut block
| Paste block
| Delete block
| Copy line
| Session record ON
| Session record OFF
| Session play ON
| Session play OFF
| Session play toggle
| Session play file
|| file name
| Session play reset
| Pattern set
| Set cursor marker
|| letter a-z
| Move to marker
|| letter a-z
| Start Signal from TCP
|| optional parameters
HOWTO Use the Real Time Clock in User Mode
The real time clock is a device controlled by the
operating system which syncronizes the timing of the
sequencer. The real time clock driver (/dev/rtc) will
allow you to use a clock frequency up to 64 Hz if you
are a non-root user. If you log in as root you may set
the real time clock as high as the driver will support.
In the original TekTracker Billy Biggs used a default
of 8192 hz, and attrk will use a default of 1024 hz.
Be warned that the synchronization does not always
improve with a higher frequency. It is possible to set
the frequency so high that the OS services the clock
callback at the expense of the app side. I think 64 hz
works fine for most sequencer, but then I rarely fill
up the sequencer pattern space. Attrk can contain more
notes and patterns than will every be used by human kind,
and the real time clock will get bogged down--even as
root user--long before that circumstance is reached.
Access to the real time clock hardware is through the
Linux driver "rtc0," which is accessed from applications
as the file /dev/rtc0. The easiest way to get
access to the rtc is to just grant global access to
/dev/rtc0 with chmod, which is what I do. If
you feel this would make your computer too vulnerable,
there are more sophisticated methods of control.
The following hint was
contributed by Attrk user Josh Lawrence, which in turn
came from Jeremy Jongepier. You may find this useful
to run Attrk with high real time clock frequencies from
a non-root logon account.
Create an audio group, add yourself to it and create
a new udev rule in /etc/udev/rules.d and
name it something like 40-rtc-permissions.rules
with a single line in it:
After a reboot /dev/rtc0 will have guid audio so any
user in the audio group has access to /dev/rtc0
If you want to get better than 64 hz without having to
log in as root, then you must find a way to run the app
with root privilege from your user account. There is
probably more than one way to do that, but the most common
method would be to use the "sudo" command. You will need
to add a line to your /etc/sudoers file for the
Homer = /usr/local/bin/attrk
will give the user with logon name "david29smith" on the computer
with host name "Homer" the right to run attrk as root. If you
would like to give sudo access to an entire group, say the "audio"
group in the example above, then replace the user name with the
Homer = /usr/local/bin/attrk
HOWTO Set and Use Position Markers
Position markers can be used in song mode. You can mark
the current position of the cursor with a letter from
the alphabet, lower case a-z. Then you can return the
cursor to that position using the letter key. This is
an extended command with the letter "k" for setting the
marker and the letter "n" for moving the cursor back
to that mark. For example, to mark the current cursor
position with the letter "a", type
Now you can return to that position by typing
HOWTO Start the Sequencer from a Network Signal
This is an advanced capability that you will not need
unless you are recording the same tracks repeatedly and
combining the recordings. This would be down to get
studio-only stereo effects such as complex panning,
fading, phasing, etc. For such work to succeed you
need to synchronize the recording application with the
sequencer--at least so that you may avoid a lot of time
queuing the individual recorded files. The capability
was designed for recording on a remote PC in which the
recording PC sends the TCP connect request to the PC
This feature is like pressing the F9 key (start), but from
a remote application making a TCP connection to Attrk.
Attrk merely listens for a TCP connection on port
2999, which serves as the start signal. As soon as the
connection is made Attrk disconnects the port and starts
sequencing. You can test this feature on the remote PC
by using netcat as the TCP tool with a command such as
|echo start || | ||nc ||attrk_host ||2999 || -q 0
where "attrk_host" is the host name (or IP address)
of the machine running Attrk. The next line in your
script would start recording (say, with ecasound or sox).
The effect is that on one computer you start recording,
while on the other computer you start the sequencer
To enable the TCP listen mode on Attrk you use an extended
after which the message line will show "Waiting for
start signal (sock)". The Attrk program will now do
nothing until the TCP connect signal is received. If,
for some reason, the TCP signal is never sent the Attrk
program will be locked out until the listen mode times
out, which is 30 seconds by default. After a timeout
the sequencer will start.
The listen mode command takes 3 optional parameters:
port number, timeout, and silence time. Silence time is
the number of seconds the program waits before starting
the sequencer. It is 1 second by default. This gives
a slight time margin to prevent the first notes from
being cut off on a recording. The silence parameter
can be given as zero. The parameters, when given,
must be on the command line in the correct order,
|:c c || port timeout silence || <return>
If you want to specify the silence parameter you must
also give the port number and timeout parameters--that's
the syntax. If you give zero for the port and timeout
the default values will be used. Here are some examples
Use port 26101 instead of 2999
:c c 26101
Specify a different port AND a different timeout
:c c 26101 10
Specify a timeout but leave the default port
:c c 0 10
Specify a port (4133), timeout (15), and silence of 5 seconds
:c c 4133 15 5
Specify a silence of zero and leave port and timeout unchanged
:c c 0 0 0
The experimental version of this feature is available
and (possibly) allows you more control over the signal
response. Using the ":c b" command (with no parameters)
will cause Attrk to try to run a shell script with
a system() call in which you put your own script for
listening for a port connection. The shell script must
be named "waitnc.sh" and located in the current directory.
An example of what would be in the shell script is
nc -l -p 2999 -w 30 > /dev/null 2> /dev/null
This shell script also provides a glimpse of the analagous
code inside Attrk for triggering on the network signal.
HOWTO Record MIDI Keyboard Input
Beginning with version 1.1.1, Attrk can "record" MIDI
input note On and note OFF messages. Instead of entering
notes manually in pattern mode from the computer keyboard,
you may turn on the MIDI input feature while the song is
playing and record an instrumental track by playing along.
The MIDI note numbers will automatically be entered into
the track and pattern numbers automatically assigned.
Record capability must be turned on with a keyword,
"midiinput", in the .attrkrc file. This just enables the
capability. It does not turn on recording. Recording is
turned on with the
:c r < n >
extended command. Recording
is stopped with
:c r s
The recording session is
:c r c
A typical recording session would
be run with the following sequence of commands.
In song mode, move the cursor (arrow keys) to the track where you
want to record.
Set the MIDI port on this track to match the MIDI port to which your
musical instrument keyboard is connected. For example, if connected
to your second MIDI adapter, enter "ctrl-B 2". Set the MIDI
channel on this track to the output channel on your instrument.
Set the cursor to the row in song mode where you want to begin
Initialize the recording with
:c r c
Turn on recording with
:c r 32
where "32" can be replaced with the desired pattern you want.
Start the sequencer (F9).
Play your MIDI instrument while the song is running.
When finished recording this phrase, enter F11 to stop the sequencer
:c r s
to stop recording.
While you are playing the instrument you will not see
any change on the song mode screen. The screen does not
automatically refresh when recording. When you toggle
the screen mode with the key you will see the new
Note that you execute ":c r c" before the "c r "
command. Doing the clear command (that is, :c r c)
resyncs the MIDI record parameters to the current start
position in the song. The record pointer is aligned
to the "start position" which is the song row that was
marked with the ctrl-F key (and F12 resets the song
position to the start position). The pattern number is
set to the next available, unused pattern.
When starting with a new, blank song you must insert
at least one "click" track. That is, you need an
existing track with notes in the patterns to get the
sequencer running. Also, the looping markers (shown by
the vertical green bar in song mode) might prevent the
sequencer position from moving. Temporarily move the
loop down, out of the way with the ctrl-K and ctrl-L keys.
This is still in an experimental capability. This feature
is disabled by default. In order to turn this feature on
you must put a line in your .attrkrc file
You mau also experiment with the thread priority of the
recording thread by putting a line in the .attrkrc file
input_priority < 0, 1, 2 >
The default value is 0. For example, to increase the
priority to 1, use
However, I do not think you will obtain any difference in
performance. The notes that result from the "recording"
into the song patterns will often be placed slightly off
beat from where you think they should be. This is an
unfortunate side effect of the design approach, which
treats recording events secondary to the playback clock
event. In other words, there is a granularity imposed on
the recording, and input notes may miss a beat depending
on their temporal relation to the clock. Expect to do
some post-recording editing of the new patterns.
HOWTO Use Advanced Loops (Do Loops)
The original TekTracker we designed with the capability to set one loop
which can be set with ctrl-K and ctrl-L. In version 1.1.1 advanced looping
was added. Advanced looping allows multiple loops to be defined, including
loops within loops (nested loops).
From the command line loops can be set with the ":L" extended command
sequence. There must be four arguments, separated by spaces, folloing the
"L". The arguments are
||You give the loop a name with less than 32 characters
||The song pattern row number where the loop begins
||The song pattern row number where the loop ends
||The number of times the loop will be run
For example, to set a loop called "q1" that starts on row 24 and ends
on row 30, to be run three times, you would use the following command,
:L q1 24 30 3
You can define as many loops as you want. To delete all the loops use
When you save your song file the loops will be saved, too. When you
load that song file again your loops will be reloaded as well. You can
set your loops by editing the song file. The loops section is defined
within the tag group. Each loop is defined on a line within
<doloop name=q1 begin=24 end=30 maxloops=3/>
<doloop name=q2 begin=24 end=28 maxloops=2/>
<doloop name=nloop10 begin=40 end=50 maxloops=4/>
If there are no loops defined yet in the song then you must put the opening
and closing "doloop_setup" tags yourself. This group is a top-level group,
that is, not nested inside a channel or pattern group. There is one doloop
tag group per song file. It is easiest to first define a loop on the
command line, save the song file, and then edit the song.
Some comments on loops:
If you create a loop within another loop, the outer loop should
be defined first. If you ignore this the loops might still work.
But if the inner loop and outer loop begin (or end) on the same
row you MUST define the outer loop first.
A loop is designed to run at least once. You must set the number
of times to loop to at least 1. In other words, the maxloops
means the number of time to run, not the number of times to repeat.
During song playback there is only one loop hilighted. A loop
is not hilighted until its execution begins. As each loop is
entered the hilighter moves to that range. Before any of the
defined loops are executed the global loop (which is set with
ctrl-K and ctrl-L) may be hilighted. But after any of the defined
loops are run the "global" loop will be lost (until you set it again).