
Copyright (C) 2004 by Predrag Viceic                                  
viceic@net2000.ch                                            

This program is free software; you can redistribute it and/or modify  
it under the terms of the GNU General Public License as published by  
the Free Software Foundation; either version 2 of the License, or     
(at your option) any later version.                                   

This program is distributed in the hope that it will be useful,       
but WITHOUT ANY WARRANTY; without even the implied warranty of        
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         
GNU General Public License for more details.                          

You should have received a copy of the GNU General Public License     
along with this program; if not, write to the                         
Free Software Foundation, Inc.,                                       
59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             
 
----------------------------------------------------------------------------------------------

INSTALLATION:

*In order to generate makefiles and compile you should execute

  qmake freecycle.pro
  make

 in the freecycle dir.

*Before compiling Aubio, you should edit pitchdetection.h and rename 'bin' to 
'abin' to prevent a conflict with Qt's bin function. This will soon be fixed in Aubio.

* You should install Soundtouch 1.3.0 or you will have namespace problems when compiling Freecycle.


----------------------------------------------------------------------------------------------

MANUAL:

* In the wave part of the wave display:
	- left mouse button operates on selection (move, resize)
	- right mouse button operates on lines (loop markers, beatlines), depending on the context:
		- middle of the beatline : move
		- bottom of the beatline: delete
		- top of the beatline: lock/unlock
		- any part of the  loop marker: move

* In the ruler part of the wave display:
	- right mouse buttons plays segment between two beatlines
	- left mouse button plays from the position till released
	
* Ctrl+right : brings right loop marker to the mouse position
* Ctrl+left : brings left  loop marker to the mouse position


* The viewed area can be adjusted also in the preview frame (the bottom one, with the full wave)

* The audio chnuks are  saved in the original major format (wav, aiff, ..), you can only adjust the minor format (16bit, 32bit fp,..).

If you find this manual too sparse, you are welcome to write a better one :)

----------------------------------------------------------------------------------------------

COMMAND LINE SWITCHES

	--ueber  : Launches Freecycle with UeberStyle



----------------------------------------------------------------------------------------------

KNOWN BUGS:

* Many, but works pretty well with small waves (~30 sec)
* >1 LASPA audio outputs can not be routed to the same audio channel

----------------------------------------------------------------------------------------------

ISSUES:

Mandrake10 users which experience compile problems with ueberstyle.cpp should either:

a) activate QMotifStyle support in their qt install
or
b) disable Ueberstyle in Freecycle by removing it in main.cpp and src.pro

----------------------------------------------------------------------------------------------


FAQ:

Q: Could You tell me what is this popup menu with this kind of time signatures 
for? How to use it.

A: When the sound signal gets analysed, the bpm computation starts based on 
beatline positions. If there are at least 4 locked beatlines, only the locked 
beatlines serve as the basis for the bpm computation, If there are less than 
4 beatlines locked, the unlocked (green) beatlines are used. The value 
obtained is then multiplied by the values in the combo. That gives you the 
possibilitiy to change the detected 75BPM to i.e. 150 BPM. The computed value 
is then used for:

a) Time stretching
b) measure marker computation (the bar between two loop points, when dragged)
c) bpm lines computation (activated by the clock icon and at least one locked 
beatline)
c) midi file generation


Q: I would like to know what is the purpose of the clock button and why and 
when it becomes "active"

A: This icon gets enabled when there is at least one locked beatline. It draws 
what I call the bpmlines, i.e. the measures based on the BPM and synchronised 
with the first locked beatline.


Q: I guess that the time stretch amount is in percent, but why is the initial 
value 30 and not 100?

A: it is the BPM and not the percent.



Q: Does the beatlines and loop markers affect the bpm?

A: Beatlines are the basis for the BPM computation. Loop markers doesn't 
affect the BPM.



Q: How does the "time signature" pop up menu affect the bpm?

A:The detected bpm value is multiplied by the value in the combo.
i.e. 150BPM x 1/2 =75BPM


Q: Is it possible to stretch one beat in a whole loop?

A: For now, time stretching works on the whole sound file.



Q: What are the different analisys methods best for?

A: Well that's a short question with a huge answer. :)

The first (default) algorithm (time domain) detects beats by comparing the 
instant energy (nb of samples configured as instant energy buffer size in 
Configuration->Configure Amplitude Domain) with the average energy (nb of 
samples configured as avergage energy buffer size in Configuration->Configure 
Amplitude Domain). If the difference exceeds some treshold computed internaly 
and based on the variance of the signal, then the beatline is put at that 
position (well it's a little bit more complicated because Freecycle then does 
zero-crossing, but you should have got the point..)

The second algorithm (frequency domain) does the same thing but the signal is 
splitted in multiple bands and the algorithms compare the instant energy of 
each frequency band with the average energy of that band. That gives you the 
positibility to beatmatch the signal with continuous amplitude but varying 
frequency (flute playing legato notes). Configuration->Configure FFT-> 
Beatmatching FFT gives you the parameters for this algorithm. Window is 
equivalent to the [instant energy buffer size]. Average energy is hardcoded 
as 44032 frames.

If you want to know more about the above two algorithms please read the 
following [http://www.yov408.com/beat/BeatDetectionAlgorithms.pdf] as it 
served as the basis for these two algorithms.

The aubio algorithms are well known among DSP experts, which I'm not. Please 
search on the web if you want some precisions about those. Feel free to post 
your findings on freecycle-users :)




Q: What is the fft configuration and configure amplitude domain menus for and 
how to set it for the best (depending on cpu and memory) program performance?

A: Generaly speaking slower->better and faster->less precise. Experiment! The 
default values are ok on a 2Ghz  CPU and 1Gb RAM. But this depends on the 
size of your soundfile, so if you keep those relatively small it should be ok 
even on less recent computers.

You can see the effect of fft configuration parameters in the spectrogram view 
(View->Spectrum). Spectrogram FFT parameters are used for drawing the 
spectrum. If you link those parameters to the Beatmnatching FFT, you cans see 
what the Frequency domain analysis algorithm "sees".

----------------------------------------------------------------------------------------------



Enjoy,
Predrag Viceic

 
