1 files changed, 283 insertions, 0 deletions
diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts
new file mode 100644
index 0000000000..f74096e480
--- /dev/null
+++ b/res/controllers/engine-api.d.ts
@@ -0,0 +1,283 @@
+
+/** ScriptConnectionJSProxy */
+
+declare interface ScriptConnection {
+    /**
+     * Disconnect the script connection,
+     * established by {@link engine.makeConnection} or {@link engine.makeUnbufferedConnection}
+     *
+     * @returns Returns true if the connection has been disconnected successfully
+     */
+    disconnect(): boolean;
+
+    /**
+     * Triggers the execution of the callback function of the script connection,
+     * established by {@link engine.makeConnection} or {@link engine.makeUnbufferedConnection}
+     * with the actual value of a control.
+     *
+     * Note: To execute all callback functions connected to a ControlObject at once, use {@link engine.trigger} instead
+     */
+    trigger(): void;
+}
+
+
+/** ControllerScriptInterfaceLegacy */
+
+declare namespace engine {
+    /**
+     * Gets the control value
+     *
+     * @param group Group of the control e.g. "[Channel1]"
+     * @param name Name of the control e.g. "play_indicator"
+     * @returns Value of the control (within it's range according Mixxx Controls manual page:
+     *          https://manual.mixxx.org/latest/chapters/appendix/mixxx_controls.html)
+     */
+    function getValue(group: string, name: string): number;
+
+    /**
+     * Sets a control value
+     *
+     * @param group Group of the control e.g. "[Channel1]"
+     * @param name Name of the control e.g. "play_indicator"
+     * @param newValue Value to be set (within it's range according Mixxx Controls manual page:
+     *                 https://manual.mixxx.org/latest/chapters/appendix/mixxx_controls.html)
+     */
+    function setValue(group: string, name: string, newValue: number): void;
+
+    /**
+     * Gets the control value normalized to a range of 0..1
+     *
+     * @param group Group of the control e.g. "[Channel1]"
+     * @param name Name of the control e.g. "play_indicator"
+     * @returns Value of the control normalized to range of 0..1
+     */
+    function getParameter(group: string, name: string): number;
+
+    /**
+     * Sets the control value specified with normalized range of 0..1
+     *
+     * @param group Group of the control e.g. "[Channel1]"
+     * @param name Name of the control e.g. "play_indicator"
+     * @param newValue Value to be set, normalized to a range of 0..1
+     */
+    function setParameter(group: string, name: string, newValue: number): void;
+
+    /**
+     * Normalizes a specified value using the range of the given control,
+     * to the range of 0..1
+     *
+     * @param group Group of the control e.g. "[Channel1]"
+     * @param name Name of the control e.g. "play_indicator"
+     * @param value Value with the controls range according Mixxx Controls manual page:
+     *              https://manual.mixxx.org/latest/chapters/appendix/mixxx_controls.html
+     * @returns Value normalized to range of 0..1
+     */
+    function getParameterForValue(group: string, name: string, value: number): number;
+
+    /**
+     * Resets the control to its default value
+     *
+     * @param group Group of the control e.g. "[Channel1]"
+     * @param name Name of the control e.g. "play_indicator"
+     */
+    function reset(group: string, name: string): void;
+
+    /**
+     * Returns the default value of a control
+     *
+     * @param group Group of the control e.g. "[Channel1]"
+     * @param name Name of the control e.g. "play_indicator"
+     * @returns Default value with the controls range according Mixxx Controls manual page:
+     *          https://manual.mixxx.org/latest/chapters/appendix/mixxx_controls.html
+     */
+    function getDefaultValue(group: string, name: string): number;
+
+    /**
+     * Returns the default value of a control, normalized to a range of 0..1
+     *
+     * @param group Group of the control e.g. "[Channel1]"
+     * @param name Name of the control e.g. "play_indicator"
+     * @returns Default value of the specified control normalized to range of 0..1
+     */
+    function getDefaultParameter(group: string, name: string): number;
+
+    type CoCallback = (value: number, group: string, name: string) => void
+
+    /**
+     * Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes
+     *
+     * This connection has a FIFO buffer - all value change events are processed in serial order.
+     *
+     * @param group Group of the control e.g. "[Channel1]"
+     * @param name Name of the control e.g. "play_indicator"
+     * @param callback JS function, which will be called every time, the value of the connected control changes.
+     * @returns Returns script connection object on success, otherwise 'undefined''
+     */
+    function makeConnection(group: string, name: string, callback: CoCallback): ScriptConnection |undefined;
+
+    /**
+     * Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes
+     *
+     * This connection is unbuffered - when value change events occur faster, than the mapping can process them,
+     * only the last value set for the control is processed.
+     *
+     * @param group Group of the control e.g. "[Channel1]"
+     * @param name Name of the control e.g. "VuMeter"
+     * @param callback JS function, which will be called every time, the value of the connected control changes.
+     * @returns Returns script connection object on success, otherwise 'undefined''
+     */
+    function makeUnbufferedConnection(group: string, name: string, callback: CoCallback): ScriptConnection | undefined;
+
+    /**
+     * This function is a legacy version of makeConnection with several alternate
+     * ways of invoking it. The callback function can be passed either as a string of
+     * JavaScript code that evaluates to a function or an actual JavaScript function.
+     *
+     * @param group Group of the control e.g. "[Channel1]"
+     * @param name Name of the control e.g. "VuMeter"
+     * @param callback JS function, which will be called every time, the value of the connected control changes.
+     * @param disconnect If "true", all connections to the ControlObject are removed. [default = false]
+     * @returns Returns script connection object on success, otherwise 'undefined' or 'false' depending on the error cause.
+     * @deprecated Use {@link makeConnection} instead
+     */
+    function connectControl(group: string, name: string, callback: CoCallback, disconnect?: boolean): ScriptConnection | boolean | undefined;
+
+
+    /**
+     * Triggers the execution of all connected callback functions, with the actual value of a control.
+     * Note: To trigger a single connection, use {@link ScriptConnection.trigger} instead
+     *
+     * @param group Group of the control e.g. "[Channel1]"
+     * @param name Name of the control e.g. "play_indicator"
+     */
+    function trigger(group: string, name: string): void;
+
+    /** @deprecated Use {@link console.log} instead */
+    function log(message: string): void;
+
+    type TimerID = number;
+
+    /**
+     * Starts a timer that will call the specified script function
+     *
+     * @param interval Time in milliseconds until the function is executed.
+     *                 Intervals below 20ms are not allowed.
+     * @param scriptCode Function to be executed,
+     *                   you can also use closures as:
+     *                   function() { print("Executed Timer") }
+     * @param oneShot If true the function is only once,
+     *                if false the function is executed repeatedly  [default = false]
+     * @returns timerId which is needed to stop a timer.
+     *          In case of an error, 0 is returned.
+     */
+    function beginTimer(interval: number, scriptCode: () => any, oneShot?: boolean): TimerID;
+
+    /**
+     * Stops the specified timer
+     *
+     * @param timerId ID of the timer
+     */
+    function stopTimer(timerId: TimerID): void;
+
+    /**
+     * Jogwheel function to be called when scratching starts (usually when the wheel is touched)
+     * This function contains an parametrizeable alpha-beta filter, which influences the
+     * responsiveness and looseness of the imaginary slip mat
+     *
+     * @param deck The deck number to use, e.g: 1
+     * @param intervalsPerRev The resolution of the MIDI control (in intervals per revolution)
+     * @param rpm The speed of the imaginary record at 0% pitch (in revolutions per minute (RPM) typically 33+1/3, adjust for comfort)
+     * @param alpha The alpha coefficient of the filter (start with 1/8 (0.125) and tune from there)
+     * @param beta The beta coefficient of the filter (start with alpha/32 and tune from there)
+     * @param ramp Set true to ramp the deck speed down. Set false to stop instantly [default = true]
+     */
+    function scratchEnable(deck: number, intervalsPerRev: number, rpm: number, alpha: number, beta: number, ramp?: boolean): void;
+
+    /**
+     * Function to be called each time the jogwheel is moved during scratching
+     *
+     * @param deck The deck number to use, e.g: 1
+     * @param interval The movement value (typically 1 for one "tick" forwards, -1 for one "tick" backwards)
+     */
+    function scratchTick(deck: number, interval: number): void;
+
+    /**
+     * Jogwheel function to be called when scratching ends (usually when the wheel is released)
+     *
+     * @param deck The deck number to use, e.g: 1
+     * @param ramp  Set true to ramp the deck speed up. Set false to jump to normal play speed instantly [default = true]
+     */
+    function scratchDisable(deck: number, ramp?: boolean): void;
+
+    /**
+     * Returns true if scratching is enabled
+     *
+     * @param deck The deck number to use, e.g: 1
+     * @returns True if scratching is enabled
+     */
+    function isScratching(deck: number): boolean;
+
+    /**
+     * If enabled, soft-takeover prevents sudden wide parameter changes,
+     * when on-screen control and hardware control divert.
+     * With soft-takeover you need to turn a hardware knob, until it reaches
+     * the position of the on-screen knob - than it takes over control.
+     *
+     * @param group Group of the control e.g. "[Channel1]"
+     * @param name Name of the control e.g. "pregain"
+     * @param enable Set true to enable soft-takeover for the specified control
+     */
+    function softTakeover(group: string, name: string, enable: boolean): void;
+
+    /**
+     * Inhibits a sudden value change from the hardware control.
+     * Should be called when receiving input for the knob/fader,
+     * that switches its behavior (e.g. Shift-Button pressed)
+     *
+     * @param group Group of the control e.g. "[Channel1]"
+     * @param name Name of the control e.g. "pregain"
+     */
+    function softTakeoverIgnoreNextValue(group: string, name: string): void;
+
+    /**
+     * To achieve a brake effect of the playback speed
+     * Both engine.softStart() and engine.brake()/engine.spinback() can interrupt each other.
+     *
+     * @param deck The deck number to use, e.g: 1
+     * @param activate Set true to activate, or false to disable
+     * @param factor Defines how quickly the deck should come to a stop.
+     *               Start with a value of 1 and increase to increase the acceleration.
+     *               Be aware that brake called with low factors (about 0.5 and lower),
+     *               would keep the deck running although the resulting very low sounds are not audible anymore. [default = 1.0]
+     * @param rate The initial speed of the deck when enabled. "1" (default) means 10x speed in forward.
+     *             Negative values like "-1" also work, though then it's spinning reverse obviously. [default = 1.0]
+     */
+    function brake(deck: number, activate: boolean, factor?: number, rate?: number): void;
+
+    /**
+     * To achieve a spinback effect of the playback speed
+     * Both engine.softStart() and engine.brake()/engine.spinback() can interrupt each other.
+     *
+     * @param deck The deck number to use, e.g: 1
+     * @param activate Set true to activate, or false to disable
+     * @param factor Defines how quickly the deck should come to normal playback rate.
+     *               Start with a value of 1 and increase to increase the acceleration.
+     *               Be aware that spinback called with low factors (about 0.5 and lower),
+     *               would keep the deck running although the resulting very low sounds are not audible anymore. [default = 1.8]
+     * @param rate The initial speed of the deck when enabled. "-10" (default) means 10x speed in reverse.
+     *             Positive values like "10" also work, though then it's spinning forward obviously. [default = -10.0]
+     */
+    function spinback(deck: number, activate: boolean, factor?: number, rate?: number): void;
+
+    /**
+     * To achieve a forward acceleration effect from standstill to normal speed.
+     * Both engine.softStart() and engine.brake()/engine.spinback() can interrupt each other.
+     *
+     * @param deck The deck number to use, e.g: 1
+     * @param activate Set true to activate, or false to disable
+     * @param factor Defines how quickly the deck should come to normal playback rate.
+     *               Start with a value of 1 and increase to increase the acceleration.
+     *               SoftStart with low factors would take a while until sound is audible. [default = 1.0]
+     */
+    function softStart(deck: number, activate: boolean, factor?: number): void;
+}