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).