SoftWerk

an advanced MIDI pattern
sequencer for Linux

Current FTP Version: 1.99.2
Current CVS Version: 1.99.2

Web: http://softwerk.sourceforge.net/
Email: softwerk-dev@lists.sourceforge.net

Using SoftWerk

This content has been taken from the documentation for the old XForms version of SoftWerk and is not totally correct. Until it is updated, however, it may help to give you an idea of how to do certain things.

Like my other programs, SoftWerk use a configuration file written using Guile, a flexible and powerful dialect of Lisp. You will almost certainly need to edit the one distributed with the source reflect the names of your MIDI device files, and you will probably want to edit the "tagnames" that the ports are known by. Its unlikely that you will need to alter anything else in the file; if you do, I hope that its fairly self-documenting. You must set the environment variable SOFTWERKRC to the name of this file.
  • set the environment variable SOFTWERKRC to the location of your configuration file.
  • Type "softwerk &" at a shell prompt
  • Have fun.

Real Time Priority

Linux supports parts of the POSIX OS standard called "soft real time" scheduling, specifically a scheduling class called SCHED_FIFO. A program that runs as part of this scheduling class has the power to completely take over your machine. If the program gets into a tight loop and you are running on a computer with just one CPU, it will appear that your machine has crashed. So, you should approach this with some caution.

However, if you want rock-steady timing, SCHED_FIFO is a must for SoftWerk. The big problem with a program that wants to run with this kind of scheduling is that on current Linux systems, it be running as root. There are two ways to do this. My preferred one is to make the softwerk executable "setuid root". You need to be root to do this: 

        # chown root /where/i/put/softwerk
	# chmod u+s /where/i/put/softwerk
The other approach, which has some benefits, is to use the nice little program "sudo", which can be configured to allow specific users permission to run specific programs with root permission.

Once you've figured out which method to use (and set it up), you can use the existing settings in the config file, which includes two important variables that control this: 


   ;; should SoftWerk try to run with realtime priority ?
   (set-config-var use-real-time #t)

   ;; if running with RT priority, what priority ?
   (set-config-var real-time-priority 10)
If you don't want to use SCHED_FIFO, then set the first of these two variables to #f (Lisp for "false"). There should rarely be a reason to change the second variable, and if you do, you should know what it means without me having to explain it to you.

Real Time Clock

This version of SoftWerk is able to use the Real Time Clock that exists on almost every kind of computer system on which Linux will run. Using this clock is very desirable, for it allows SoftWerk to have timing resolution far in excess of what it possible just using the regular system timer.

To use the RTC, you should add --enable-rtc as an argument to configure before building SoftWerk. For this to work, you must have a kernel with RTC support, and it must be a version the RTC driver with my simple hack to allow it to support "asynchronous I/O". This became standard with kernel version 2.3.44. If you don't have this in your kernel, you should plan to upgrade to a kernel that does. If you compiled RTC support as a module, you will have to ensure that the module is loaded, or will auto-load when SoftWerk tries to use it.

Aspects of the User Interface

Per-Step Controls

Each step has 3 buttons representing it.

  • The top-most button, often invisible, is an endpoint-marker. Clicking with the left mouse button will set the startpoint for the row that the step belongs to, and clicking with the left sets the endpoint.
  • The value/enable button. This displays the current step value (or "MIDI" if its a MIDI event step), and also functions as an on/off button for the step. The exact meaning of "off" will depend on the row's "skip" setting (see below), but it always prevents the step from causing any MIDI output.
  • The adjuster button, marked with a two-way arrow. This is used to adjust the value of the step.

The adjuster button can be used in a variety of ways:

For sound producing and parameter rows:

  • Right mouse button increases the step value by 1 (typically a MIDI note or control parameter value.
  • Left button decreases the step value by 1
  • Middle button sets value to 63 (middle of MIDI note and parameter range)
  • Ctrl-Right sets value to 127, Ctrl-Left sets value to zero,
  • Shift-Right increases value by 16, Shift-Left decreases value by 16.
  • Alt-Middle puts the step in "Learn" mode: operate a MIDI Controller connected to the sequence's MIDI input port, and the step will subsequently be under control of that controller.

For MIDI event rows (recorded or edited)

The adjuster button pops up a MIDI event editor. An event is represented as a series of byte values, two hexadecimal digits per value.

Sequence-level controls

The "Skip" button
When pressed, steps that are disabled will be completely ignored. When not pressed, steps that are disabled will affect the row's timing, but will produce no sound.
The "Copy" button
When pressed, this row is selected as the row that will used copied from during a paste operation.
The "Paste" button
When pressed, the currently marked "copy" row will be copied into this row. Each step in the "paste" row will be set to the same values as the corresponding step in the "copy" row, and both rows will have the same pattern of step enabled/disabled status.
Mode selector
There are numerous modes for each row:

Off
The row does nothing (surpise, suprise!)
Absolute Pitch
the row generates MIDI Note On and Note Off messages; the step values control the note numbers (on-velocity is controlled by the row volume control and/or relevant On Velocity rows).
Relative Pitch
As above, but incoming MIDI Note On messages on the row's input MIDI port will cause the entire row to be transposed. The root note for all rows starts at MIDI note 60 (Middle C) and transpositions are relative to the current root note.
Single Pitch
As for Absolute Pitch, except that every step has the same value. Changing any of the row's steps changes all of them. Useful for working with MIDI drumkits that use a Note Number -> Drum mapping.
Raw MIDI bytes
The row emits MIDI data entered by you. Click on the adjuster button to edit the message generated by a particular step.
Recorded MIDI
The row first records N MIDI messages (where N is the number of steps in the row), and then emits them. Note that all timing information about the recorded MIDI messages is lost: when they are emitted, the time interval between each message is a function of the rows Gate Interval setting and/or any relevant Gate Interval rows.
Gate Interval
The row controls the gate interval (inter-step timing) for any row whose control button is pushed (in the lower right hand corner of the row controls). Note that if this row is not controlled by itself, it will move out of sync with the controlled rows, and strange effects will result. These are sometimes desirable, sometimes not.
Note Duration
The row controls the note duration (time between Note On and Note Off messages) for any row whose control button is pushed (in the lower right hand corner of the row controls).
On Velocity
The row controls the MIDI On Velocity (in MIDI Note On messages) for any row whose control button is pushed (in the lower right hand corner of the row controls).
Off Velocity
The row controls the MIDI Off Velocity (in MIDI Note Off messages) for any row whose control button is pushed (in the lower right hand corner of the row controls).
Absolute Chord
As Absolute Pitch above, except that all enabled steps sound at the same time.
Relative Chord
As above, but subject to the same kind of transposition as a Relative Pitch row (see above).
Program Change
The row emits MIDI Program Change messages. The step values control which programs are requested.
Controller
The row emits MIDI Controller messages. A counter (labelled "Contr") allows selection of the type of Controller message, and each step value controls the controller value byte of the message.
Pitch Bend
This does not work at this time.
PolyTouch
The row generates polyphonic or "per-note" MIDI pressure messages. This does not work yet.
Aftertouch
The row generates monophonic or "per-channel" MIDI pressure messages. This individual step values control the amount of pressure indicated by the message.

Direction selector
There are four direction modes, each fairly clearly named:
  • Forwards (Left to Right)
  • Backwards (Right to Left)
  • End-to-End (Left to Right and then Right to Left)
  • Random
Gate Interval selector
The gate interval value determines the number of ticks between one step and the next. Note that it can be overridden by another row in "Gate Interval" mode and set to control this row. Why would you want to do this ? Well, the gate interval selector only lets you select a single interval between steps. Using another row to control the intervals allows them to be non-constant, which can be essential to some patterns.
Note Duration selector
The note duration value determines the number of ticks between a MIDI note on message for a step and the corresponding Note Off message. Please note: don't set this value below the gate interval, or you will be challenging the polyphony of your MIDI sound generation device.
MIDI Input Port selector
This allows you to choose which of your system's various MIDI ports will be used for MIDI input by this row.
MIDI Output Port selector
This allows you to choose which of your system's various MIDI ports will be used for MIDI ouput by this row.
MIDI Channel selectors
These allows you to choose which channel will be used for MIDI output and input. Its irrelevant for Raw MIDI rows, since only the MIDI bytes you use for the step messages can determine the channel. Remember that the channel is very important in defining what input events the row might respond to (particularly important for transposition effects).
Trigger
This button pops up a dialog to let you select one of the currently defined triggers for use with this row.

Timing

SoftWerk's timing system exists in 3 layers:

The underlying clock

This is either the system timer, or if configured with --enable-rtc, the RTC clock. It sends SoftWerk an "interrupt" at a fixed rate.

Microseconds per SoftWerk tick

This value tells SoftWerk how much time has to elapse before a "tick" is said to elapse.

Ticks per beat

This value tells SoftWerk how many of its "ticks" correspond to a single beat.

If this seems complicated, don't worry! The only user-visible parts of the timing system are:

BPM

The current tempo in beats-per-minute

ticks-per-beat

A configuration file variable, default value is 16.

To adjust the tempo in SoftWerk, you just modify the BPM setting using the tempo display in the upper right corner.

However, in order to understand the rest of the timing system, you need to understand that the values shown in the "Gate" and "Note" displays for each sequence are in TICKS. That is: if you use 16 ticks per beat, and the gate time says 16, then that sequence will move to the next step every beat. If you reduce the gate time to 8, it moves onto the next step twice every beat. If you increase it to 32, then the sequence will move the next step once every 2 beats.

16 is nice number for many rythmic structures, because of its divisors and fractions (1, 4, 8, 12, 16) correspond to familiar rythmic patterns in the western european tradition. However, other values are equally useful (360 would be a very interesting one, since it has more divisors than almost any other number below 1000, allowing you to set up structures with 1/360th notes as well as 1/12th notes, 1/15th notes, 1/60th notes etc.).

Hopefully, you get the point that by using ticks instead of beats, we end up with a more flexible system. If I were to use beats, I would have to specify which fractions of a beat were possible, and I don't want to limit you in that way. Suppose I allowed just 1/32, 1/16, 1/8, 1/4, 1/2 and single beats (or multiples thereof). What would you do if you wanted to program SoftWerk to have two patterns with non-integral numbers of steps running against each other in relative double time ? Many non-western musics use such complex rythmic patterns, and SoftWerk is specifically designed to accomodate such structures.



Last modified: Tue Nov 28 00:02:19 EST 2000 by Paul Barton-Davis
[Best Viewed with Any Browser]