Mixco is a framework for creating hardware controller scripts for the amazing Mixxx DJ software. It makes the process easier and faster, and resulting scripts are often more robust, ready to be rock big parties.
And remember, this is Free Software.
Mixco is based on the NodeJS JavaScript development environment so, first, you need to install it. Then, just run in the command line:
npm install -g mixco
You can also browse the code on Github.
Mixco comes with a series of factory controller scripts. They are well documented and their code serves as good tutorial on how to use the framework.
To install these, run on the command line:
mixco --factory
The programming interface is very fluent and declarative, allowing you to write more high level code. For example, imagine this feature: when the sync button aligns the phase or not depending on whether the shift button is pressed. While normally this would involve quite a few lines of code detecting whether shift is pressed, controlling the lights of the buttons, and so on, With Mixco this can be written simply as:
var mixco = require('mixco')
var c = mixco.controls
var b = mixco.behaviours
// ... in your script constructor ...
var shift = b.modifier()
c.control(c.noteIds(0x01, 0))
.does (shift)
c.control(c.noteIds(0x02, 0))
.when (shift, "[Channel1]", "beatsync_tempo")
.else_( "[Channel1]", "beatsync")Normally, Mixxx requires that you describe every MIDI message that your controller can receive in a verbose XML file. Mixco generates this file for you from your JavaScript file, so you can focus on adding cool features to your mapping.
Most DJ oriented MIDI controllers are mostly symmetric, with controls
duplicated per deck. Since we don't need a XML mapping, you can avoid
duplicating the code: just write a function that defines the
functionality for one deck, and call it several times. For an
example, look at the addDeck() function of
this tutorial script.
If your script is big and complicated, you can split it into multiple
files to make it easier to maintain, by using the require()
function. Even cooler, most libraries installed with npm, the
NodeJS package manager, work out of the box. Mixco will
compile your script into a single bundle that Mixxx can use and is
easy to redistribute. For example:
// file: my-utils.js
exports.doSomething = function() { ... }// file: my-script.mixco.js
// importing the framework
var mixco = require('mixco')
// using a external library: https://www.npmjs.com/package/underscore
var _ = require('underscore')
// Using custom module
var utils = require('./my-utils')
utils.doSomething()In JavaScript, it is easy to make tiny mistake that break your code. Mixco can run some basic tests on your scripts, so some simple problems can be found before even loading it into Mixxx.
Also, Mixco be run in watch mode: whenever you change your script, it will re-run the tests and, when successful, recompile the script so it's reloaded inside Mixxx.
If you are like me, you don't like JavaScript so much. Mixco supports CoffeeScript, a nice language with syntax inspired by Python and Ruby that polishes some of the rough corners of JavaScript. Mixco can automatically compile CoffeeScript script to JavaScript and, in the future, other languages too.
Documenting a script is hard but important: otherwise your users are clue-less about what each button of the controller does. Mixco encourages a style of programming known as literate programming, which mixes code with documentation about what it does. If you code in that style, it can generate beautiful web pages like this, that teach your users not only what the script does, but also what code they should is creating that functionality, encouraging people to improve the scripts and create their own mods.
Mixco comes with a program called, ehem, mixco, that compiles all
the scripts in the current directory to a form that can be used inside
Mixxx. Try this by creating a file my_script.mixco.js and run this
in the same folder:
mixco
info: inputs: . info: output directory: mixco-output info: generated: <...>/mixco-output/my_script.mixco.output.js info: generated: <...>/mixco-output/my_script.mixco.output.midi.xml
Mixco can watch the filesystem so you don't need to re-run the
command whenever you change the script. It can also automatically run
tests on it and copy the script to some location, so Mixxx can see it.
For example, if you are on Linux, you might want to run the command
like this:
mixco --watch --test -o /usr/share/mixxx/controllers
The mixco command can do much more:
mixco --help Usage: mixco [options] [<input>...] Mixco is a framework for making DJ controller scripts for Mixxx. This program can compile all the <input> Mixco scripts into .js and .xml files that can be used inside Mixxx. Mixco scripts have one of the following extensions: *.mixco.js, *.mixco.coffee, *.mixco.litcoffee. When no <input> is passed, it will compile all scripts in the current directory. When an <input> is a directory, all scripts found in it will be compiled. Options: -o, --output=PATH Directory where to put the generated files Default: mixco-output -r, --recursive Recursively look for scripts in input directories -w, --watch Watch scripts for changes and recompile them -T, --self-test Test the framework before compilation -t, --test Test the input scripts before compilation --factory Compile the scripts that come with Mixco -h, --help Display this help message and exit -V, --verbose Print more output -v, --version Output version information and exit More info and bug reports at: <http://sinusoid.es/mixco>
- mixco.behaviour
- mixco.cli
- mixco.control
- mixco.console
- mixco.script
- mixco.transform
- mixco.util
- mixco.value
Please, log bugs, questions or feature requests in the Github issue tracker.
We are also happy to accept contributions, either improvements to the frameworks, new factory scripts or documentation enhancements. Fork us on GitHub or by running:
git clone https://github.com/arximboldi/mixco.git
You can also contact me by email at: raskolnikov@gnu.org.
Copyright (C) 2013, 2015 Juan Pedro Bolívar Puente
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 3 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, see http://www.gnu.org/licenses/.
