~daschuer/mixxx/features_banshee

This is the documentation for the preliminary support for recording and
playing back macros.

0. What is this?
At the moment it allows basic recording, editing and playback of macros.

The most impressive thing it can do at the moment is basic auto-crossfading.
See 4.4 for an example script that implements this.

Key features:
	- Record basic control sequences
	- Automatically simplifies recordings so they can be edited by hand
	- Write macros from scratch
	- Play back macros
	- Macros automatically stored as xml on disk

Although it's missing some key features for recording whole performances, it's
already reasonably powerful for automation of control sequences.

It can record macros controlling:

	- The crossfader
	- Channel volumes
	- Channel low, mid and high pass filters
	- Master volume and balance
	- Channel rates

1. Prerequisites

You need lua and tolua installed. They provide the interpreter for the macros.

On gentoo you can:

	emerge lua tolua

No particular version is required as far as I know, but if you run into problems
then I'm using:

 	lua-5.0.2
	tolua-5.0

2. Compiling

Do a:

cd src/
./configure --enable-script

You should see "script => yes" go past at some point. If you see "script => no"
then it means the configure script couldn't find your tolua headers. If this
happens (and tolua is installed), post on mixxx-devel and let me know.

Then do a:

make clean
make

Everything should work.

3. Using

When you run mixxx, an extra "Macro" menu should be available in the menu bar.

Selecting the Macro menu and Show Studio brings up the macro editor window.

In the new window which appears, the Macro menu allows you to perform actions:
	- New Macro -- Creates a new macro
	- Record -- Start recording a new macro
	- Stop Record -- Finish recording and add recorded macro to library
	- Play -- Plays the macro selected in the list
	- Delete -- Delete the selected macro (with confirmation)

Macros can be selected in the list on the left and their code appears in the
main editor pane.

4. Writing Macros

4.1 Creating a basic macro by hand

In the macro editor window, select Macro->New Macro. A macro named "New Macro"
appears in the list on the left. Select it. You can rename the macro by
clicking again on the name in the list. Then you can type in the main editor
to the right. Enter the following code:

	mixxx:startFade("[Master]", "crossfader");
		mixxx:fadePoint(2000, -1.0);
		mixxx:fadePoint(4000, 1.0);
	mixxx:endFade();

Select Macro->Play. Move back to the main mixxx window. 2 seconds (2000 ms)
after you clicked play, the crossfader should jump to the left and then slide
across to the right, finishing 4 seconds (4000 ms) after you clicked play.

4.2 Recording a macro

Select Macro->Record. Move to the main mixxx window, perform a crossfade or
twiddle some high/mid/low knobs. When you are done, select Macro->Stop Record.
A macro should appear in the list called "Recorded Macro". This can be renamed
as before by clicking on the name in the list on the left once it is selected.
Select Macro->Play with the macro selected and then switch back to the main
window, you should see your actions replayed. You can also examine the script
produced in the macro editor pane.

4.3 A bit about the API

The basic element is setting up a list of time/value pairs for a control.
You specify a list of values for a control and times to apply the values and
the scripting engine automatically interpolates between them linearly.

You start a list of points with:

	mixxx:startFade(group, name);

And end it with:

	mixxx:endFade();

Points are specified with:
	
	mixxx:fadePoint(time in ms, value);

Most controls have values in the range -1.0 to 1.0 or similar.

Controls to try are (in group:name format):
	- [Master]:crossfader
	- [Master]:balance
	- [Master]:volume
	- [Channel1]:volume
	- [Channel1]:pregain
	- [Channel1]:rate
	- [Channel1]:filterLow
	- [Channel1]:filterMid
	- [Channel1]:filterHigh

Where each [Channel1] can be replaced by [Channel2] with obvious effects.

In addition, there is also the command:

	mixxx:getValue(group, name);

Which can be used to retrieve the value of a control. One usage of this is shown
below in 4.4.

4.4 A good example, a basic auto-crossfader

You can do more complicated things with a bit of lua knowledge. Lua is very
simple, anyone who has programmed in just about any language should pick it up
straight away.

The following script implements a very basic auto-crossfader:

	time = 4000;

	s = mixxx:getValue("[Master]", "crossfader");
	e = -1.0;
	if s < 0.0 then
		e = 1.0;
	end

	mixxx:startFade("[Master]", "crossfader");
		mixxx:fadePoint(0, s);
		mixxx:fadePoint(time, e);
	mixxx:endFade();

First the script stores the number of ms to take crossfading for convenience.
Next, the current position of the crossfader is retrieved and stored in s.
Next, the end point of the fade is determined, if the crossfader is currently
on the left, the end point is all the way to the right (1.0). If the crossfader
is already on the right, then the end point is all the way to the left (-1.0).

Then the script sets up a linear crossfade from where the crossfader is now, to
the other end, taking the number of ms stored in time to complete.

Copy this script into a new macro in the macro editor and use Macro->Play to
test it out. You can tweak the speed and make it more complex in the editor.

5. Problems/Feedback

I'd appreciate any feedback at all. Especially information about what sort
of things people would like to use this for and what sort of user interface
they'd like to see.

There probably will be problems and segfaults. All stack traces and reports are
gratefully received.

Any of the above should be either posted on mixxx-devel or e-mail to:

	MYUSERNAME@users.sourceforge.net

My user name is adam_d

Hopefully I will be able to fix your problem(s).