kc/doc/notes.txt

CONTENTS:

1) TODO List
2) OSX Install Notes


SPAT LAB SETUP:
+ 1. Stereo
    a. TotalMix - select 'diff. stereo' snapshot
    b. mixer: Recall preset 91 ('stereo diff')
+ 2. Direct - 24 channels - each channel goes in and out on same number.
    a. TotalMix - select 'DTS_24ch'
    b. mixer: Recall preset 96 ('24ch firecac ufx')

LANGUAGE NOTES:
The primary goal of the language is to initialize a dataflow system.
Sub-goals:
1) Avoid describing domain specific computation in the language. As much as possible constrain the 
language to describe initialization tasks (e.g. object allocation, object connection, initialization
parameters, preset grouping, thread/process allocation, UI layout, ...)

2) Network Distrubution
3) UI Layout

Runtime:
+ Extensible data-object system.
+ Library organization (platform independent UI description, application objects, app-independent objects, vector library)
  - Platform independent UI description is a protocol for describing a UI object and a runtime protocol
  for communitcating with the UI which is independent of the UI implementation itself.  The UI should be
  implementable in FLTK, or Javascript.  The UI will always run in separate thread and may run in a 
  separate process.
  - Application objects are plug-ins which follow a similar design to the cmDspProc() objects.
    + xs

NEW DESIGN NOTES:
+ The current designs fundamental weakness is that it uses callbacks to communicate where sequential program 
  flow would produce a more comprehensible program.

+ Dataflow is a natural way to express DSP programs but if it is implemented in a textual, rather than 
  graphical language, then their are some design princles that must be followed in order
  to produce comprehensible programs.
  1) Limit the number of connections as much as possible.
     - There are many simple UI->param connections - these should be made automatically and UI
     objects should not have to be explicitely created - they should be created by the runtime 
     environment.
     - If multiple pieces of data are part of a single message then they should be sent as a unit
     rather than separately. This decreases the number of connections and also removes timing
     dependencies - where the application programmer has to know the order of transmission of the
     individual pieces. (e.g. MIDI messages always contain {status,d0,d1} rather than having to
     send d0 and d1 followed by status to indicate the end of the message {status,d0,d1} should
     be sent as a single record.
  2) Eliminate as many event ordering issues as possible 
     See the example in 1).
  3) Alllow the connections between objects to be made as part of the object allocation.
  4) Allow subprograms to be made. This decreases the complexity of the programs and because
  it allows the programs to be organized hierarchically.  It also allows the subprograms to
     be tested idenpendently.
  5) A natural way to express object multiplicity is required. (e.g. multiple channels).
     This leads to a way to naturally create parallel/fan-in/fan-out connections.
  
+ One way to solve some of the problems of the current program would be to add debugging tools.
  - Generate dataflow diagrams that show execution order and the order of connections.
    The actual sending order of the outputs is not accessible to a static network analyzer because it is
    implementation dependent. 
  - Generate reports of network activity that show the timed order of events.
+  The audio system (cmAudioSys) needs to be able to support multiple parallel DSP chains in separate threads.
+  UI Related Issues:
   - Automatic UI's should be generated by scanning the objects parameters.
   - Custom UI's should be created by explicitily naming object variables along with layout info.
+  Processors should be able to contain their own processing chains - embeddding processors should be possible.
   This naturally leads to a tree address space.  (e.g. fx.filter.param1)
+  Communication between threads should not necessarily require serialization. 
   - Use a blackboard approach where object values are read/written from a blackboard. Objects on the same
     thread use the same physical blackboard. Blackboards on remote processes stream data in the background.
   - This scheme may require double buffering of complex objects to prevent accessing invalid data states.  
+  Objects that send multiple valued messages should use 'record' based data so that only one connection
   is necessary.

STRATEGY:
+ implement highly parallel version - which can take advantage of multiple processors
  to do more - acoustic pitch tracking, source separation based fades

TODO:
+ When a cmMsgList item is selected it should send out the selected index 
  after the individual data items rather than before them - this way the index
  can be used as a definitive signal to perform some action on the previously
  transmitted data items.
+ cmJson and cmLex should report the name of the file when with syntax error messages.
+ Use CSV for mod score file format (to eliminate need for labels)
+ Autoload of default pgm cfg, program, enable audio, sequence, score location.
+ (done) Circuit switcher patch.
+ Review and document the app threading and locking during audio file loading.
+ Remove old performance evaluation code from cmScore.
+ All programs should be able to reload without crashing via enabling/disabling audio.
+ (in new version) Select and save audio devices.
+ (done) Mac Conversion
+ (done) Live MIDI - to test audio/MIDI delay.
+ (done) As threshold increases overall volume decreases - add a compensation algorithm.
+ There are unintialized variable warnings on the release build.
+ Add preset delete.
+ All uses of va_copy() should have a complimentary va_end() 
+ The list boxes do not show the currently selected item.
+ (done)MIDI note messages are sent but do not trigger notes on OSX. 

*** Usage Notes
live     - Disconnects WT cmd input   (WT will not receive an 'on' msg)
           Disconnects TL reset input (TL will not receive a 'reset' msg)
	   Disconnects MFP sel input  (MPF will not receive an 'on' msg)
	   Switches audio input to KR from WT to AIN.
	   Turn the 'meas' checkbox 'on'.
	   
simulate - Turn the 'audio in' checkbox 'on'.
	   Switch MFP output from SF to Nano. 
           (SF MIDI input then comes from the MIDI port.)

audio in - Switch audio input to KR from WT to AIN.
meas     - Instruct the SF to generate measurement outputs for the active meas. unit.
	   Otherwise the measurements must be loaded from the recorded measurment list.
print    - Print a report from the SF.
quiet    - Turn off SF output.

LA Secs  - Fragment recd/play unit look-ahead time in seconds.
Fade DbpSec - Framgent recd/play unit fade out time 
              (time to fade to 0 following a fade msg)	

*** Cross-fade Notes
Cross-fades are initiated by sending any msg to the 'AvailCh.trig' input.
The 'AvailCh' object then  toggles the parameter router channels and xfader gates.
Only after this should the new parameter values be transmitted either from
the 'ActiveMeas' object (through the scale range chains) or directly from the
'ScMod' object.

Sending parameter values prior to triggering the 'AvailCh' will result in the
parameters being sent to the currently active 'Kr'. This will result in two
possibly unintended effects: 
1) The effect of the parameter will be heard immediately - possibly resulting in distortion.
2) If a subsequent trigger is sent to 'AvailCh' the parameters will be routed to
   the fade-out (current) channel rather than the fade-in (next) channel.
 

****  Live Test Score
+ Line 1048 has a red G#5 immediiately following another G#5. Is this correct?
  For now the second G#5 has been marked as a 'skip'.
+ Changed Tempo sections 25,26,27 to 40,47,47a
+ Measurements are taken for sections 51-54 but these sections follow bar 136 and
  are therefore outside the test.  These sections have therefore been redirected
  to the downbeat of 201-204.

*** Testing Notes:
+ Equipment List:
   Four Microphones: Four performance/ Four recording
                     2 inside          2 inside
                     2 overhead        2 overhead

   4 powered speakers
   2 Mixers   (1 performance 1 recording)
   
   Performance Computer (harpo)/ Audio Interface (delta1010) / MIDI interface (Fastlane)
   Recording Computer (crel)   / Audio Interface (delta 1010) / MIDI interface (???)
   Sensor Strip	      

+ Performance Setup
   
                     +------ +
    Mic0 ----------->|       |
    Mic1 ----------->|       | sends  +-----+       +-------+
    Mic2 ----------->|       |------->| A/D |       |       |        +------+      +--------+
    Mic3 ----------->| Mixer |------->|     |------>| harpo |<-------| MIDI |<-----| sensor |    
              aux    |       |        |     |       |       |        +------+      | strip  |
    Spkr0 <----------|       |<-------|     |<------|       |                      +--------+
    Spkr1 <----------|       |<-------|     |       +------ +
              main   |       |        |     |
    Spkr2 <----------|       |<-------| D/A |
    Spkr3 <----------|       |<-------|     |
                     +-------+        +-----+
      
+ Software Development
  - Create Score File

  - Create Recording Program (test with long MIDI playback generating audio - look for drift)
     Record the index of each MIDI event at it's location in an audio channel.

  - Allow all variables and patch connections to be set from the scMod script and have 
     multiple scripts with varynig effects setups. 

  - When scanning past ramping variables in scMod the end value should be
    taken as the next variable(???) - this is not necessarily correct 
    because one never knows where a timed change may end - maybe ramped
    variables should include a 'skip value' giving the next ambient value
    for the ramped variable - experiment with this to figure out what works.

  - Add comb filters tuned according to the current MIDI notes as an additional effect.
  - Add EQ output stage (use mixer).
  - Add an input Compressor.

  - The dry signal should be able to be routed to seperate output channels - around the compressor.
     (Better would be to output a delayed version of the dry signal that was in sync with the transformed
      signal - this might mean simply passing the dry version as separate outputs from KR). 

  - Create a mode in scMod which increments values based on an onset detector. So that
    changes only happen on attacks. This still doesn't help if the pedal is down (or
    if notes are sustained) but otherwise might be a better way to ramp parameters.

  - (DONE) The ability for the measurements to be called at the correct time must be built in.
     (or alternatively to use stored effects).

  - (DONE) Effects applied to the playback fragments.

  - (DONE?) CROSSFADE BUG - This may be fixed by the change to cmDspAvailCh which
     handles the case where no channels are available by sending an error message
     but not actually changing the state of the cross fader.


+ Experiments:
  1) Speaker placement and live/electronics mix.
  2) Sliver mix level
  3) Try varying degree's of effects

   

*** 11/19
+ The recd/play fade should be able to trigger from a capture note as well as 
  playback note.  An offset might also be useful.
  (Should be a default fade for each fragment - keyed to the input. This
  will be the fade that will occur when 
+ Allow setting fade time in the score. 
+ Allow setting fade rate based on 1.0 to 0.0 from fade point to end point.
+ Allow for multiple fades markers per fragment. (what does this mean?)
+ Write code to ignore playback when the score follower is not stable -
  or to throw out fragments where there is a mistake.
+ At the end of each fragment recording the fragment should be truncated by the look-ahead time
  to avoid capturing the attack of the marked note.
+ Part 2 data analysis: analyze the order of notes in counter rhythms.
+ Allow  'evenness' sequences to have non-even relationships.

*** 11/1
+ Change the wavetable to read stereo files or add a second wavetable to play the other channel.
+ The console window is not always updating from the bottom.
+ The 'Dump' button results are not going to the console window.
+ Put dry signal into separate output channels.
+ Add 'adaptive' mode parameters to scale/range mappings.
+ The 'meas'->'parameter' mappings should changable from scMod (mod0.js)
+ The 'adaptive' mode parameters (e.g. offset and invert) need to be connected in the patch.
+ Create a mode in scMod which increments values based on an onset detector. So that
  changes only happen on attacks. This still doesn't help if the pedal is down (or
  if notes are sustained) but otherwise might be a better way to ramp parameters.
+ Mark all notes in the score according to how well they would act as places to transition.
  Notes held while the pedal is down would not be good places to transition.
  These indicators would then be used to determine where a section change can occur
  when the actual section change is missed.
+ (done) All score_loc's and event indexes in meas0.js that beginning with 
  score location 743 must be decremented by two.  (e.g. loc 743 becomes 741 ...)
  (score_loc_1.txt is now the correct score file)
+ When scanning past ramping variables in scMod the end value should be
  taken as the next variable(???) - this is not necessarily correct 
  because one never knows where a timed change may end - maybe ramped
  variables should include a 'skip value' giving the next ambient value
  for the ramped variable - experiment with this to figure out what works.

  

*** 10/17
    Select bar 129.
    Start on F5 before 129.
    Score follower jumps to loc. 978 then backs up to 973.

*** 9/27
* (DONE) Implement live recording for use in part 2.
* Implement a delay between when a new section is set to trigger and when 
it actually does.   This might allow transitions to be set up prior to when they are heard.
* (DONE) OS-X version crashes when the printf("PROCSET ...) is removed from _cmScProcSets().
* Add ability to set mappings and perf. measure settings to scMod.
* The scMod should play through all changes up to the cur starting location so that
  we can mimic the state of playing the piece through but allow starting from any location.
* Experiment with changing settings using the scMod ramping functions.
* Make a source separation based fade using an filter/inverse filter based on the
  spectrum prior to the cross-fade.  As an extra feature notice the state of the pedal
  and decay appropriately.
* The electronic score needs the ability to specify that the output is sent to the audible
cross-fade channel rather than the inactive channel.
* Add a score mode that performs some action (e.g. incr/decr) on each incoming score follower
event.  
* In AvailCh what happens when no available channels are found - this may be the cause 
of the cross-fade cut-out problem.
* Add eq stage to output.

* Setting the upper slope to a negative value is effective.

* Demo Material: Seq 8 Mark 204 (1024-4 2048-4) Fade 10ms Cost->Threshold.
- recd7  Mark 151
- recd8  Mark 145 - same settings a previous take.
- (recd9) Mark 145 - w/ changing xfade switch to mode 4 at 38 
- recd10 Mark 145 - same w/ no mode change
- recd11 Mark 145 - a. 3 different takes w/ score constant - no perf. parameters used - fixed threshold=65 
- recd12 Mark 148   b.(same settings as recd9)
- recd13 Mark 151   c.
- recd14 Mark 161  Section 40 - fixed changes see mod0.js for note 
- Seq 6 Mark 145 M-92 (38,39,39a) (recd16) (recd17) (recd18) (recd19)
- Seq 7 Mark 167 M-100

*** 8/13
* Cross-fade was cutting out during demo.
* Missing takes between seq 7 and seq 8.
* The MIDI is mis-aligned against the audio.
* Are cost / tempo working?  ... test changing mode.
* Add an automatic volume adjustment to prevent parameter changes from causing large volume changes.
* What can we actually do between after a MIDI note is received? Is it already too late to 
  send parameters w/o affecting the attack of the note.

* Live Test material

     Part 1: Meas:76 - (one measure) to get measurments for later sections
     Part 1: Meas:94 (sect 38 (Seq 6)) through Meas:136 (include 136 stop at 137).

     Part 2: ("/Users/kevin/temp/piano score part 2 draft 1 master m 232 - 241 1st 2 bts.sib")
	 	  	 The downbeat of part two aligns with the 3rd beat (in 4/4) of 122 in the first part.
			 Ends on measure 131 at end of beat 3. 
  
     MISSING MIDI for measures 114:126

*** July 10
** (done) Make separate mappings and scale/range controls for left and right.
** Add EQ output stage.
** Work out the speaker setup.
** Add capture/playback.  Analyze notes on capture and do not play if there are
   any wrong notes. (Skipped notes however are acceptable.)
** 

** When a section transition is occurs late - (e.g. due to dropped notes) do not apply
the transformation all at once - instead either ramp it in or step it in on subsequent
attacks.  Section transitions which are positively identified are intended to have 
dramatic changes so applying the updated parameters immediately is acceptable - but
when the parameters are changed mid-section they should be much applied subtely.




** (done) Build a database of measurements and setup the program to be able to
   apply a given measurement at it's assigned section.

** Redevelop spectral distortion algorithm to use a spline as the transform.

** use Log frequency frequency transform instead of FFT.

** Allow for a continous window size via zero padding.

** Add a 'write' preset file button - so the preset file can be saved prior to next crash.

** measurement values can generate MAX_DBL - be sure that are not being sent through to the audio algorithm.
   (see ln:965 cmDspKr.c for a hack to fix this)

** add invert to scale/range  to cause output to go in opposite direction.

** non-grace eveneess are used to generate a measurement value from previous tempo calibration section. 
   (non-grace evenness notes therefore have two scores: 'evenness' and 'overall-duration').

** note that the default setting for dyn and even.

** add dyn,even,tempo,cost number boxes to allow artificial setting of these parameters.
   add dyn,even,tempo,cost as modulator variables to allow them to be set from the modulator
   With these additions we can simulate apply measurements at the 'application' section.

** add begining and ending measure numbers to 'seq' labels

** Gain compensation for mode 4.

** Do IFFT using cos()^c + i * sin()^c - these bases are orthognal but cause harmonic distortion.
   To be efficient this might involve writing an FFT function.

// May 22

** Crashers (Should be tested but are probably already fixed following score follower debugging.)
Seq 2  m24 Mark 36 & 38 
Seq 4: Mark 115
Seq 4: m76-79 Mark 129 (W/ meas: even & dyn -> thresh change min Thresh to 40) - use 4th seq w/ b1
Seq 6: m92 Mark 143
Seq 7: m103 Mark 173
Seq 7: Mark 172 Meas 103 - always crashes on playback.
Seq 4: Mark 76  Meas 40  - crash!
Seq 2: First mark meas 23
  Crash seems to happen in cmProc4.c: _cmScMatchInitMtx() ln:1311.
  It looks like a memory overrun.  Looks like the first line is wrong
  shouldn't:
    if( rn >p->mrn && cn > p->mcn )
  be	
	if(rn*cn > p->mrn*p->mcn)



BUGS:
// Apr 20
The tempo measurement can produce invalid values.  Set score to 22 then play Mark 38.
First tempo measurement is a non-sense value - probably produced by an div by zero.
Also: Mark 8, Meas 10.

Crash on playing Mark 37.

Click on list control outside below list item - crash!

Select Mark 171 (Seq 7) Section 43, m103 crash


// Feb 27
+ Audio seems to preceded MIDI by around 250ms this probably arises
from a delay that was inserted by 'mas'. Can the delay be removed?

// Feb 25
+ Fix the audio file input/output ports 

//
// Feb 6 & 7 
//
+ Performed notes which arrive which about 50ms could be
considered chords.   Extra notes notes which were not part of
the chord are probably common and should be discounted during
the cost analysis.

+ (done) Add alignment cost as a 4th variable along with dyn,even,tempo.

+ (done) In the score print out (score_loc.txt) Section 2 is starting on Bar 5
when it should start inside Bar 7.
 
+ In Take 1 the 2nd dynamics set is not triggered.

+ In Take 3 Eveness 2 the C2 and F#4 are NOT missing althrough they are in the 
evalation.  Also E7 which ends that set is not marked with an 'e'.

+ It is possible to have even-non-grace sets where the note rythm value's are not
all the same (e.g. bar 20 ) 

+ User soft-thresholds for the dynamics categories.

+ Set 39 even measure 25 shows the first note as G#2 when it should be C#1

+ Missig MIDI note sounded: 
C1   score-loc:132
A#2            140
A5             173
C#2            195   Marker 36
E5,G33,A#2,C#1 212-218 Marker 36
E3             185     Marker 37
F5,C#4,G#5     986     Marker 204     

-------------------------------------------------------------------------------
OSX - Install Notes
-------------------------------------------------------------------------------
1. Install macports
2. Install git-core  (sudo port install git-core)
3. sudo port install fftw-3
4. sudo port install fftw-3--single
5. port select --list gcc (which gcc is active)
6. sudo port install gcc47
7. sudo port --set gcc mp-gcc47
8. sudo port install fltk
9. sudo port install xorg-libX11 
10.sudo port install git-core 
11.sudo port install emacs +x11
10 install ~/Library/Preferences/org.larke.kc.txt (is this required?)
11 create ~/Library/Preferences/kc
12 Install ~/Library/Preferences/time_line.js, time_line_preset.js, time_line_preset.csv