add support for loading controller scripts as JS modules

res/controllers/lib/mididispatcher.mjs

@@ -0,0 +1,89 @@
+/**
+* MidiDispatcher routes incoming MIDI messages to registered callbacks. Register callbacks with
+* the setInputCallback method in your controller script module's init function and call
+* MidiDispatcher's receiveMidiData method in your controller script module's receiveData function.
+*
+* This class is not designed to handle System Exclusive or MIDI Clock messages. For those, implement logic
+* specific to your controller in the controller module's receiveData function before calling
+* MidiDispatcher.receiveData.
+*/
+
+// MIDI messages starting with 0xC (program change) or 0xD (aftertouch) messages are only
+// two bytes long and distinguished by their first byte.
+// https://www.midi.org/specifications-old/item/table-2-expanded-messages-list-status-bytes
+const identifiedByFirstByte = (midiBytes) => {
+    return (midiBytes[0] & 0xF0) == 0xC0 || (midiBytes[0] & 0xF0) === 0xD0;
+}
+
+// JavaScript is broken and believes [1,2] === [1,2] is false, so
+// this function turns an array of MIDI bytes into a unique hashable key.
+// This function does not work for system exclusive messages; that is out of scope.
+const hashMidiBytes = (midiBytes) => {
+    if (identifiedByFirstByte(midiBytes)) {
+        return midiBytes[0];
+    }
+    return midiBytes[0] + (midiBytes[1] << 8);
+}
+
+export class MidiDispatcher {
+    /**
+     * @param {bool} noteOff - When setting the callback for a Note On message, also map the corresponding Note Off
+     * message to the same callback. Defaults to true.
+     */
+    constructor(noteOff) {
+        if (noteOff === undefined) {
+            noteOff = true;
+        }
+        this.noteOff = noteOff;
+        this.inputMap = new Map();
+    }
+    /**
+     * Set the callback for an incoming MIDI message.
+     * @param {Array} midiBytes - Array of numbers indicating the beginning of the MIDI messages. In most cases,
+     * this should be the first two bytes of the MIDI messages, for example [0x93, 0x27]
+     *
+     * Program change (starting with 0xC) and aftertouch (starting with 0xD) messages are distinguished by only
+     * their first byte, so in those cases the Array should only have one number.
+     *
+     * @param {MidiInputHandler} callback - The callback that will be called by the handleMidiInput method
+     * when a MIDI message matching midiBytes is received from the controller.
+     *
+     * @callback MidiInputHandler
+     * @param {Array} data - incoming MIDI data
+     * @param {number} timestamp - The timestamp that Mixxx received the MIDI data at (milliseconds)
+     */
+    setInputCallback(midiBytes, callback) {
+        if (!Array.isArray(midiBytes)) {
+            throw new Error('MidiDispatcher.setInputCallback midiBytes must be an Array, received ' + midiBytes);
+        }
+        if (typeof midiBytes[0] !== 'number') {
+            throw new Error('MidiDispatcher.setInputCallback midiBytes must be an Array of numbers, received ' + midiBytes);
+        }
+        if (typeof callback !== 'function') {
+            throw new Error('MidiDispatcher.setInputCallback callback must be a function, received ' + callback);
+        }
+        const key = hashMidiBytes(midiBytes);
+        this.inputMap.set(key, callback);
+        // If passed a Note On message, also map the corresponding Note Off
+        // message to the same callback.
+        if (this.noteOff === true && ((midiBytes[0] & 0xF0) === 0x90)) {
+            const noteOffBytes = [midiBytes[0] - 0x10, midiBytes[1]];
+            const noteOffKey = hashMidiBytes(noteOffBytes);
+            this.inputMap.set(noteOffKey, callback);
+        }
+    }
+    /**
+     * Receive incoming MIDI data from a controller and execute the callback registered to that
+     * MIDI message.
+     * @param {Array} data - The incoming MIDI data.
+     * @param {number} timestamp - The timestamp that Mixxx received the MIDI data at (milliseconds)
+     */
+    handleMidiInput(data, timestamp) {
+        const key = hashMidiBytes(data);
+        const callback = this.inputMap.get(key);
+        // This assumes a script has not modified this.inputMap directly without this.setInputCallback.
+        if (callback !== undefined && callback !== null) {
+            callback(data, timestamp);
+        }
+    }
+}

res/mixxx.qrc

@@ -1,6 +1,7 @@
 <RCC>
     <qresource prefix="/">
         <file>../LICENSE</file>
+        <file>controllers/lib/mididispatcher.mjs</file>
         <file>images/library/ic_library_drag_and_drop.svg</file>
       <!-- open/closed lock icons for BPM button -->
         <file>images/library/ic_library_locked.svg</file>

src/controllers/controller.cpp

@@ -73,6 +73,10 @@ bool Controller::applyPreset(bool initializeScripts) {
     if (success && initializeScripts) {
         m_pEngine->initializeScripts(scriptFiles);
     }
+
+    if (initializeScripts) {
+        m_pEngine->loadModule(pPreset->moduleFileInfo());
+    }
     return success;
 }
 
@@ -143,4 +147,6 @@ void Controller::receive(const QByteArray data, mixxx::Duration timestamp) {
         QJSValue incomingDataFunction = m_pEngine->wrapFunctionCode(function, 2);
         m_pEngine->executeFunction(incomingDataFunction, data);
     }
+
+    m_pEngine->handleInput(data, timestamp);
 }

src/controllers/controllerpreset.h

@@ -57,6 +57,14 @@ class ControllerPreset {
         return m_scripts;
     }
 
+    void setModuleFileInfo(QFileInfo fileInfo) {
+        m_moduleFileInfo = fileInfo;
+    }
+
+    QFileInfo moduleFileInfo() const {
+        return m_moduleFileInfo;
+    }
+
     inline void setDirty(bool bDirty) {
         m_bDirty = bDirty;
     }
@@ -178,6 +186,7 @@ class ControllerPreset {
     QString m_mixxxVersion;
 
     QList<ScriptFileInfo> m_scripts;
+    QFileInfo m_moduleFileInfo;
 };
 
 typedef QSharedPointer<ControllerPreset> ControllerPresetPointer;

src/controllers/controllerpresetfilehandler.cpp

@@ -144,6 +144,9 @@ void ControllerPresetFileHandler::addScriptFilesToPreset(
         preset->addScriptFile(filename, functionPrefix, file);
         scriptFile = scriptFile.nextSiblingElement("file");
     }
+
+    QString moduleFileName = controller.firstChildElement("module").text();
+    preset->setModuleFileInfo(preset->dirPath().absoluteFilePath(moduleFileName));
 }
 
 bool ControllerPresetFileHandler::writeDocument(

src/controllers/controllerpresetinfoenumerator.cpp

@@ -57,7 +57,7 @@ void PresetInfoEnumerator::loadSupportedPresets() {
     m_bulkPresets.clear();
 
     for (const QString& dirPath : m_controllerDirPaths) {
-        QDirIterator it(dirPath);
+        QDirIterator it(dirPath, QDirIterator::Subdirectories);
         while (it.hasNext()) {
             it.next();
             const QString path = it.filePath();

src/controllers/engine/controllerengine.cpp

@@ -149,6 +149,10 @@ void ControllerEngine::gracefulShutdown() {
     qDebug() << "Invoking shutdown() hook in scripts";
     callFunctionOnObjects(m_scriptFunctionPrefixes, "shutdown");
 
+    if (m_shutdownFunction.isCallable()) {
+        executeFunction(m_shutdownFunction, QJSValueList{});
+    }
+
     // Prevents leaving decks in an unstable state
     //  if the controller is shut down while scratching
     QHashIterator<int, int> i(m_scratchTimers);
@@ -190,6 +194,8 @@ void ControllerEngine::initializeScriptEngine() {
     // Create the Script Engine
     m_pScriptEngine = new QJSEngine(this);
 
+    m_pScriptEngine->installExtensions(QJSEngine::ConsoleExtension);
+
     // Make this ControllerEngine instance available to scripts as 'engine'.
     QJSValue engineGlobalObject = m_pScriptEngine->globalObject();
     ControllerEngineJSProxy* proxy = new ControllerEngineJSProxy(this);
@@ -223,6 +229,53 @@ void ControllerEngine::uninitializeScriptEngine() {
     }
 }
 
+void ControllerEngine::loadModule(QFileInfo moduleFileInfo) {
+#if QT_VERSION >= QT_VERSION_CHECK(5, 12, 0)
+    m_moduleFileInfo = moduleFileInfo;
+
+    QJSValue mod = m_pScriptEngine->importModule(moduleFileInfo.absoluteFilePath());
+    if (mod.isError()) {
+        showScriptExceptionDialog(mod);
+        return;
+    }
+
+    connect(&m_scriptWatcher,
+            &QFileSystemWatcher::fileChanged,
+            this,
+            &ControllerEngine::scriptHasChanged);
+    m_scriptWatcher.addPath(moduleFileInfo.absoluteFilePath());
+
+    QJSValue initFunction = mod.property("init");
+    executeFunction(initFunction, QJSValueList{});
+
+    QJSValue handleInputFunction = mod.property("handleInput");
+    if (handleInputFunction.isCallable()) {
+        m_handleInputFunction = handleInputFunction;
+    } else {
+        scriptErrorDialog(
+                "Controller JavaScript module exports no handleInput function.",
+                QStringLiteral("handleInput"),
+                true);
+    }
+
+    QJSValue shutdownFunction = mod.property("shutdown");
+    if (shutdownFunction.isCallable()) {
+        m_shutdownFunction = shutdownFunction;
+    } else {
+        qDebug() << "Module exports no shutdown function.";
+    }
+#endif
+}
+
+void ControllerEngine::handleInput(QByteArray data, mixxx::Duration timestamp) {
+    if (m_handleInputFunction.isCallable()) {
+        QJSValueList args;
+        args << byteArrayToScriptValue(data);
+        args << timestamp.toDoubleMillis();
+        executeFunction(m_handleInputFunction, args);
+    }
+}
+
 bool ControllerEngine::loadScriptFiles(const QList<ControllerPreset::ScriptFileInfo>& scripts) {
     bool scriptsEvaluatedCorrectly = true;
     for (const auto& script : scripts) {
@@ -263,6 +316,7 @@ void ControllerEngine::reloadScripts() {
 
     qDebug() << "Re-initializing scripts";
     initializeScripts(m_lastScriptFiles);
+    loadModule(m_moduleFileInfo);
 }
 
 void ControllerEngine::initializeScripts(const QList<ControllerPreset::ScriptFileInfo>& scripts) {

src/controllers/engine/controllerengine.h

@@ -26,6 +26,8 @@ class ControllerEngine : public QObject {
     ControllerEngine(Controller* controller);
     virtual ~ControllerEngine();
 
+    void handleInput(QByteArray data, mixxx::Duration timestamp);
+
     bool executeFunction(QJSValue functionObject, QJSValueList arguments);
     bool executeFunction(QJSValue functionObject, const QByteArray& data);
 
@@ -103,6 +105,7 @@ class ControllerEngine : public QObject {
     virtual void timerEvent(QTimerEvent* event);
 
   public slots:
+    void loadModule(QFileInfo moduleFileInfo);
     bool loadScriptFiles(const QList<ControllerPreset::ScriptFileInfo>& scripts);
     void initializeScripts(const QList<ControllerPreset::ScriptFileInfo>& scripts);
     void gracefulShutdown();
@@ -146,6 +149,8 @@ class ControllerEngine : public QObject {
     double getDeckRate(const QString& group);
 
     Controller* m_pController;
+    QJSValue m_handleInputFunction;
+    QJSValue m_shutdownFunction;
     QList<QString> m_scriptFunctionPrefixes;
     QHash<ConfigKey, ControlObjectScript*> m_controlCache;
     struct TimerInfo {
@@ -166,6 +171,7 @@ class ControllerEngine : public QObject {
     QJSValue m_byteArrayToScriptValueJSFunction;
     // Filesystem watcher for script auto-reload
     QFileSystemWatcher m_scriptWatcher;
+    QFileInfo m_moduleFileInfo;
     QList<ControllerPreset::ScriptFileInfo> m_lastScriptFiles;
 
     bool m_bTesting;

src/controllers/midi/midicontroller.cpp

@@ -202,6 +202,17 @@ void MidiController::commitTemporaryInputMappings() {
 
 void MidiController::receive(unsigned char status, unsigned char control,
                              unsigned char value, mixxx::Duration timestamp) {
+    QByteArray byteArray;
+    byteArray.append(status);
+    byteArray.append(control);
+    byteArray.append(value);
+
+    ControllerEngine* pEngine = getEngine();
+    // pEngine is nullptr in tests.
+    if (pEngine) {
+        pEngine->handleInput(byteArray, timestamp);
+    }
+    // legacy stuff below
 
     // The rest of this function is for legacy mappings
     unsigned char channel = MidiUtils::channelFromStatus(status);
@@ -471,6 +482,8 @@ double MidiController::computeValue(
 
 void MidiController::receive(QByteArray data, mixxx::Duration timestamp) {
     controllerDebug(MidiUtils::formatSysexMessage(getName(), data, timestamp));
+    getEngine()->handleInput(data, timestamp);
+    // legacy stuff below
 
     MidiKey mappingKey(data.at(0), 0xFF);