Have ideas to improve npm?Join in the discussion! »

    mixco

    2.0.3 • Public • Published

    mixco

    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.

    Installation

    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.

    Examples

    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
    

    Features

    Write more high level code

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

    No editing XML files

    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.

    No duplicate per-deck code

    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.

    Use external libraries and modularize your code

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

    Automatically test your code

    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.

    Use languages different from JavaScript

    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.

    Generate beautiful documentation

    Documenting a script is hard but important: otherwise your users are clue-less about what each button of the controler 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.

    Usage

    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>
    

    Documentation

    Scripts

    API

    Tests

    Contributing

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

    License

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

    Install

    npm i mixco

    DownloadsWeekly Downloads

    0

    Version

    2.0.3

    License

    GPL-3.0+

    Last publish

    Collaborators

    • avatar