class:: SpaceTracker 
summary:: A plain-text human-writable musical performance description format
related:: PlayBufS, RecordBufS, SpaceTrackerGuide
categories:: File

description:

The SpaceTracker SuperCollider class converts SpaceTracker formatted files to and from timed buffer formatted audio files or buffers, which can be played back and recorded using the TimedBufferUGens PlayBufS and RecordBufS.

classmethods::

method:: new

argument:: treefile

A String or PathName to a SpaceTracker file that should be read from or written to.

Alternatively, SpaceTracker code may be provided directly as a string, if you prefer have it inline in your SuperCollider code.

argument:: soundfile

A string or PathName to a sound file in timed format (first channel is the time the other values of the frame should be held, in seconds) that should be read from or written to. If this is omitted, a temporary path is generated. 

methods::

method:: toBuffer

Read from the treefile and allocate and write to an array of timed buffers that may be played back with PlayBufS.

argument:: server

The server the buffer should be created on. Server.default is used if omitted.

method:: fromBuffer

Read from an array of timed buffers that can be recorded with RecordBufS and write to the treefile, creating it if it does not exist.

Warning: treefile will be overwritten without confirmation.

method:: toSoundFile

Read from the treefile and write to the sound file. If the treefile is polyphonic, a seperate indexed sound file is created for each channel of polyphony,

Warning: soundfile and related indexed soundfiles will be overwritten without confirmation.

method:: fromSoundFile

Read from the soundfile, and related indexed soundfiles for polyphony, and generate a treefile.

Warning: tree will be overwritten without confirmation.

examples::

Please place the following example SpaceTracker file into groove.note to run this example.

code::
1 16 c2 96
1 16
1 16 c2 64
1 16
1 16 c3 64
1 16
1 16 b2b 64
1 16
1 16 c3 96
1 16
1 16 f2 64
1 16 g2 64
1 16
1 16 b2b 64
1 16 c3 64
::

code::
s.boot;
b=SpaceTracker("groove.note").toBuffer(s);
(
  // playback monophonic file with two controls
  x={
    var note, velocity;
    #note, velocity = PlayBufT.ar(2, b, 120/60);
    Saw.ar(note.midicps, (velocity/128).lag);
  };
  x.play;
)
::

Please place the following example SpaceTracker file into chords.note to run this example.

code::
1 4
 0
  3 16 c4 64
  5 16 c4 64
 0
  3 16 b3b 64
  5 16 a3 64
 0
  3 16 g3 64
  5 16 g3 64
1 4
::

code::
s.boot;
c=SpaceTracker("chords.note").toBuffer(s);
(
  // playback polyphonic file with two controls
  y={
    // polyphony of file is 3
    PlayBufT.ar(2, c, 120/60).collect{|c|
      var n,v;
      #n,v=c;
      SinOsc.ar(n.midicps.lag,0,(v/128).lag*0.2);
    }.sum!2;
  };
  y.play
)
::


Now play both together

code::
(
  x.play;
  y.play;
)
::

You may also run the example above by providing the SpaceTracker code inline instead of a file name. Note that indenting the SpaceTracker code will result in an error. You may however add empty lines for readability.


code::
(
  b = SpaceTracker("
1 16 c2 96
1 16
1 16 c2 64
1 16
1 16 c3 64
1 16
1 16 b2b 64
1 16
1 16 c3 96
1 16
1 16 f2 64
1 16 g2 64
1 16
1 16 b2b 64
1 16 c3 64
").toBuffer(s);
)
::

code::
(
  c = SpaceTracker("
1 4
 0
  3 16 c4 64
  5 16 c4 64
 0
  3 16 b3b 64
  5 16 a3 64
 0
  3 16 g3 64
  5 16 g3 64
1 4
").toBuffer(s);
)
::


Record monophonic MIDI in

Please refer to the monophonic example in the RecordBufT help file to record MIDI to a timed buffer.

code::
  // Save timed buffer to SpaceTracker format
  SpaceTracker("target.note").fromBuffer(b);
::

Record polyphonic MIDI in

Please refer to the polyphonic example in the RecordBufT help file to record MIDI to a timed buffer.

code::
  // Save timed buffer to SpaceTracker format
  SpaceTracker("target.note").fromBuffer(b);
::

When converting recorded polyphonic timed buffer data to a single polyphonic SpaceTracker file, it is guaranteed that every note will play back just as recorded, but not that each note will be on the same channel as during recording. If this is a requirement, you may convert each channel to its own SpaceTracker file.

code::
  b.do{|b,i| SpaceTracker("target"++i++".note").fromBuffer(b) };
::

discussion::

A human-readable plain text file is the most universal way to express data, as is recognized by the Unix Philosophy and is used in most modern technologies today, for example HTML. The most natural way to express a sequence of events in a text file is one event per line, as was recognized as early as the 80s in the "Tracker" tradition of music software. There are degrees to the human readability of text, and making a very simple subset even more readable vastly improves the usability of the format, as recognized in the early 2000s by the "markdown" format for writing a subset of HTML by hand.

SpaceTracker intends to accomplish for musical performance data such as notes and control data what markdown accomplished for HTML- a simple, human readable non-distracting visually appealing yet very powerful syntax for quickly jotting down and playing back some notes, for serious composition, and for serious recording, editing and playing back musical performances.