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)

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

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