ableton-js 2.5.4 → 2.7.0

package/CHANGELOG.md

@@ -4,8 +4,23 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### [v2.7.0](https://github.com/leolabs/ableton.js/compare/v2.6.0...v2.7.0)
+
+- :sparkles: Add automatic client-side caching of potentially large props [`68c3edd`](https://github.com/leolabs/ableton.js/commit/68c3edda00918c769afa7c88e54a2a566a0e1f23)
+- :art: Clean up the code a bit [`c183cda`](https://github.com/leolabs/ableton.js/commit/c183cda10deb81e176992ed40624d3f57015a703)
+- :memo: Add some docs for caching [`778da44`](https://github.com/leolabs/ableton.js/commit/778da44ab960cb5074b46e4783abf3d0c57d5a9f)
+
+#### [v2.6.0](https://github.com/leolabs/ableton.js/compare/v2.5.4...v2.6.0)
+
+> 1 November 2022
+
+- :sparkles: Make IDs stable over the lifespan of Live [`0bfcf90`](https://github.com/leolabs/ableton.js/commit/0bfcf904b54d42377877a2e9fab0796986f6aa1a)
+- :sparkles: Add create_track methods [`a7dd6bc`](https://github.com/leolabs/ableton.js/commit/a7dd6bc53e2f49fb133b2eea2a1fe6eb1ff0aac6)
+
 #### [v2.5.4](https://github.com/leolabs/ableton.js/compare/v2.5.3...v2.5.4)
 
+> 19 October 2022
+
 - :sparkles: Restart the socket when a message can't be sent due to a socket error [`91294c3`](https://github.com/leolabs/ableton.js/commit/91294c3cf195afacd22cbf1863e244bc231c9a33)
 - :sparkles: Send the UUID back with the error if a requested namespace handler doesn't exist [`8a96a99`](https://github.com/leolabs/ableton.js/commit/8a96a996b8b65c8485d90ac98293ccd605497784)
 - :memo: Add an example for setting a value [`f334983`](https://github.com/leolabs/ableton.js/commit/f334983a8755eab8415383aae7aff1ecff6e23e2)

package/README.md

@@ -58,7 +58,7 @@ const test = async () => {
   // Get the current tempo
   const tempo = await ableton.song.get("tempo");
   console.log(tempo);
-  
+
   // Set the tempo
   await ableton.song.set("tempo", 85);
 };
@@ -103,6 +103,17 @@ chunk. The last chunk always has the index 0xFF. This indicates to the JS
 library that the previous received messages should be stiched together,
 unzipped, and processed.
 
+### Caching
+
+Certain props are cached on the client to reduce the bandwidth over UDP. To do
+this, the Ableton plugin generates an MD5 hash of the prop, called ETag, and
+sends it to the client along with the data.
+
+The client stores both the ETag and the data in an LRU cache and sends the
+latest stored ETag to the plugin the next time the same prop is requested. If
+the data still matches the ETag, the plugin responds with a placeholder object
+and the client returns the cached data.
+
 ### Commands
 
 A command payload consists of the following properties:
@@ -113,7 +124,9 @@ A command payload consists of the following properties:
   "ns": "song", // The command namespace
   "nsid": null, // The namespace id, for example to address a specific track or device
   "name": "get_prop", // Command name
-  "args": { "prop": "current_song_time" } // Command arguments
+  "args": { "prop": "current_song_time" }, // Command arguments
+  "etag": "4e0794e44c7eb58bdbbbf7268e8237b4", // MD5 hash of the data if it might be cached locally
+  "cache": true // If this is true, the plugin will calculate an etag and return a placeholder if it matches the provided one
 }
 ```
 
@@ -123,7 +136,27 @@ The MIDI Script answers with a JSON object looking like this:
 {
   "data": 0.0, // The command's return value, can be of any JSON-compatible type
   "event": "result", // This can be 'result' or 'error'
-  "uuid": "a20f25a0-83e2-11e9-bbe1-bd3a580ef903"
+  "uuid": "a20f25a0-83e2-11e9-bbe1-bd3a580ef903" // The same UUID that was used to send the command
+}
+```
+
+If you're getting a cached prop, the JSON object could look like this:
+
+```js
+{
+  "data": { "data": 0.0, "etag": "4e0794e44c7eb58bdbbbf7268e8237b4" },
+  "event": "result", // This can be 'result' or 'error'
+  "uuid": "a20f25a0-83e2-11e9-bbe1-bd3a580ef903" // The same UUID that was used to send the command
+}
+```
+
+Or, if the data hasn't changed, it looks like this:
+
+```js
+{
+  "data": { "__cached": true },
+  "event": "result", // This can be 'result' or 'error'
+  "uuid": "a20f25a0-83e2-11e9-bbe1-bd3a580ef903" // The same UUID that was used to send the command
 }
 ```
 

package/index.d.ts

@@ -1,14 +1,18 @@
 /// <reference types="node" />
 import { EventEmitter } from "events";
+import LruCache from "lru-cache";
 import { Song } from "./ns/song";
 import { Internal } from "./ns/internal";
 import { Application } from "./ns/application";
 import { Midi } from "./ns/midi";
+import { Cache } from "./util/cache";
 interface Command {
     uuid: string;
     ns: string;
-    nsid?: number;
+    nsid?: string;
     name: string;
+    etag?: string;
+    cache?: boolean;
     args?: {
         [k: string]: any;
     };
@@ -31,10 +35,14 @@ export declare class TimeoutError extends Error {
     payload: Command;
     constructor(message: string, payload: Command);
 }
+export interface AbletonOptions {
+    host?: string;
+    sendPort?: number;
+    listenPort?: number;
+    heartbeatInterval?: number;
+    cacheOptions?: LruCache.Options<string, any>;
+}
 export declare class Ableton extends EventEmitter implements ConnectionEventEmitter {
-    private host;
-    private sendPort;
-    private listenPort;
     private client;
     private msgMap;
     private eventListeners;
@@ -43,11 +51,15 @@ export declare class Ableton extends EventEmitter implements ConnectionEventEmit
     private cancelConnectionEvent;
     private buffer;
     private latency;
+    private host;
+    private sendPort;
+    private listenPort;
+    cache: Cache;
     song: Song;
     application: Application;
     internal: Internal;
     midi: Midi;
-    constructor(host?: string, sendPort?: number, listenPort?: number, heartbeatInterval?: number);
+    constructor(options?: AbletonOptions);
     close(): void;
     /**
      * Returns the latency between the last command and its response.
@@ -61,11 +73,12 @@ export declare class Ableton extends EventEmitter implements ConnectionEventEmit
      * Sends a raw command to Ableton. Usually, you won't need this.
      * A good starting point in general is the `song` prop.
      */
-    sendCommand(ns: string, nsid: number | undefined, name: string, args?: Record<string, any> | any[], timeout?: number): Promise<any>;
-    getProp(ns: string, nsid: number | undefined, prop: string): Promise<any>;
-    setProp(ns: string, nsid: number | undefined, prop: string, value: any): Promise<any>;
-    addPropListener(ns: string, nsid: number | undefined, prop: string, listener: (data: any) => any): Promise<() => Promise<boolean | undefined>>;
-    removePropListener(ns: string, nsid: number | undefined, prop: string, eventId: string, listener: (data: any) => any): Promise<boolean | undefined>;
+    sendCommand(command: Omit<Command, "uuid">, timeout?: number): Promise<any>;
+    sendCachedCommand(command: Omit<Command, "uuid" | "cache">, timeout?: number): Promise<any>;
+    getProp(ns: string, nsid: string | undefined, prop: string, cache?: boolean): Promise<any>;
+    setProp(ns: string, nsid: string | undefined, prop: string, value: any): Promise<any>;
+    addPropListener(ns: string, nsid: string | undefined, prop: string, listener: (data: any) => any): Promise<() => Promise<boolean | undefined>>;
+    removePropListener(ns: string, nsid: string | undefined, prop: string, eventId: string, listener: (data: any) => any): Promise<boolean | undefined>;
     /**
      * Removes all event listeners that were attached to properties.
      * This is useful for clearing all listeners when Live

package/index.js

@@ -14,6 +14,17 @@ var __extends = (this && this.__extends) || (function () {
         d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
     };
 })();
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -50,6 +61,22 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
         if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
     }
 };
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
 var __spreadArray = (this && this.__spreadArray) || function (to, from) {
     for (var i = 0, il = from.length, j = to.length; i < il; i++, j++)
         to[j] = from[i];
@@ -65,11 +92,13 @@ var events_1 = require("events");
 var uuid_1 = require("uuid");
 var semver_1 = __importDefault(require("semver"));
 var zlib_1 = require("zlib");
+var lru_cache_1 = __importDefault(require("lru-cache"));
 var song_1 = require("./ns/song");
 var internal_1 = require("./ns/internal");
 var application_1 = require("./ns/application");
 var midi_1 = require("./ns/midi");
 var package_version_1 = require("./util/package-version");
+var cache_1 = require("./util/cache");
 var TimeoutError = /** @class */ (function (_super) {
     __extends(TimeoutError, _super);
     function TimeoutError(message, payload) {
@@ -83,15 +112,9 @@ var TimeoutError = /** @class */ (function (_super) {
 exports.TimeoutError = TimeoutError;
 var Ableton = /** @class */ (function (_super) {
     __extends(Ableton, _super);
-    function Ableton(host, sendPort, listenPort, heartbeatInterval) {
-        if (host === void 0) { host = "127.0.0.1"; }
-        if (sendPort === void 0) { sendPort = 39041; }
-        if (listenPort === void 0) { listenPort = 39031; }
-        if (heartbeatInterval === void 0) { heartbeatInterval = 2000; }
+    function Ableton(options) {
+        var _a, _b, _c, _d;
         var _this = _super.call(this) || this;
-        _this.host = host;
-        _this.sendPort = sendPort;
-        _this.listenPort = listenPort;
         _this.msgMap = new Map();
         _this.eventListeners = new Map();
         _this._isConnected = false;
@@ -102,9 +125,13 @@ var Ableton = /** @class */ (function (_super) {
         _this.application = new application_1.Application(_this);
         _this.internal = new internal_1.Internal(_this);
         _this.midi = new midi_1.Midi(_this);
+        _this.host = (_a = options === null || options === void 0 ? void 0 : options.host) !== null && _a !== void 0 ? _a : "127.0.0.1";
+        _this.sendPort = (_b = options === null || options === void 0 ? void 0 : options.sendPort) !== null && _b !== void 0 ? _b : 39041;
+        _this.listenPort = (_c = options === null || options === void 0 ? void 0 : options.listenPort) !== null && _c !== void 0 ? _c : 39031;
         _this.client = dgram_1.default.createSocket({ type: "udp4" });
-        _this.client.bind(_this.listenPort, host);
+        _this.client.bind(_this.listenPort, _this.host);
         _this.client.addListener("message", _this.handleIncoming.bind(_this));
+        _this.cache = new lru_cache_1.default(__assign({ max: 500, ttl: 1000 * 60 * 10 }, options === null || options === void 0 ? void 0 : options.cacheOptions));
         var heartbeat = function () { return __awaiter(_this, void 0, void 0, function () {
             var e_1;
             return __generator(this, function (_a) {
@@ -136,7 +163,7 @@ var Ableton = /** @class */ (function (_super) {
                 }
             });
         }); };
-        _this.heartbeatInterval = setInterval(heartbeat, heartbeatInterval);
+        _this.heartbeatInterval = setInterval(heartbeat, (_d = options === null || options === void 0 ? void 0 : options.heartbeatInterval) !== null && _d !== void 0 ? _d : 2000);
         heartbeat();
         _this.internal
             .get("version")
@@ -225,24 +252,20 @@ var Ableton = /** @class */ (function (_super) {
      * Sends a raw command to Ableton. Usually, you won't need this.
      * A good starting point in general is the `song` prop.
      */
-    Ableton.prototype.sendCommand = function (ns, nsid, name, args, timeout) {
+    Ableton.prototype.sendCommand = function (command, timeout) {
         if (timeout === void 0) { timeout = 2000; }
         return __awaiter(this, void 0, void 0, function () {
             var _this = this;
             return __generator(this, function (_a) {
                 return [2 /*return*/, new Promise(function (res, rej) {
                         var msgId = uuid_1.v4();
-                        var payload = {
-                            uuid: msgId,
-                            ns: ns,
-                            nsid: nsid,
-                            name: name,
-                            args: args,
-                        };
+                        var payload = __assign({ uuid: msgId }, command);
                         var msg = JSON.stringify(payload);
                         var timeoutId = setTimeout(function () {
-                            var arg = JSON.stringify(args);
-                            var cls = nsid ? ns + "(" + nsid + ")" : ns;
+                            var arg = JSON.stringify(command.args);
+                            var cls = command.nsid
+                                ? command.ns + "(" + command.nsid + ")"
+                                : command.ns;
                             rej(new TimeoutError([
                                 "The command " + cls + "." + name + "(" + arg + ") timed out after " + timeout + " ms.",
                                 "Please make sure that Ableton is running and that you have the latest",
@@ -252,10 +275,10 @@ var Ableton = /** @class */ (function (_super) {
                         }, timeout);
                         var currentTimestamp = Date.now();
                         _this.msgMap.set(msgId, {
-                            res: function (data) {
+                            res: function (result) {
                                 _this.setPing(Date.now() - currentTimestamp);
                                 clearTimeout(timeoutId);
-                                res(data);
+                                res(result);
                             },
                             rej: rej,
                             clearTimeout: function () {
@@ -267,17 +290,64 @@ var Ableton = /** @class */ (function (_super) {
             });
         });
     };
-    Ableton.prototype.getProp = function (ns, nsid, prop) {
+    Ableton.prototype.sendCachedCommand = function (command, timeout) {
+        var _a, _b;
         return __awaiter(this, void 0, void 0, function () {
+            var args, cacheKey, cached, result;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0:
+                        args = (_b = (_a = command.args) === null || _a === void 0 ? void 0 : _a.prop) !== null && _b !== void 0 ? _b : JSON.stringify(command.args);
+                        cacheKey = [command.ns, command.nsid, args].filter(Boolean).join("/");
+                        cached = this.cache.get(cacheKey);
+                        return [4 /*yield*/, this.sendCommand(__assign(__assign({}, command), { etag: cached === null || cached === void 0 ? void 0 : cached.etag, cache: true }), timeout)];
+                    case 1:
+                        result = _c.sent();
+                        if (cache_1.isCached(result)) {
+                            if (!cached) {
+                                throw new Error("Tried to get an object that isn't cached.");
+                            }
+                            else {
+                                console.log("Using cached entry:", { cached: cached });
+                                return [2 /*return*/, cached.data];
+                            }
+                        }
+                        else {
+                            if (result.etag) {
+                                console.log("Setting cached entry:", { cacheKey: cacheKey, result: result });
+                                this.cache.set(cacheKey, result);
+                            }
+                            return [2 /*return*/, result.data];
+                        }
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    Ableton.prototype.getProp = function (ns, nsid, prop, cache) {
+        return __awaiter(this, void 0, void 0, function () {
+            var params;
             return __generator(this, function (_a) {
-                return [2 /*return*/, this.sendCommand(ns, nsid, "get_prop", { prop: prop })];
+                params = { ns: ns, nsid: nsid, name: "get_prop", args: { prop: prop } };
+                if (cache) {
+                    return [2 /*return*/, this.sendCachedCommand(params)];
+                }
+                else {
+                    return [2 /*return*/, this.sendCommand(params)];
+                }
+                return [2 /*return*/];
             });
         });
     };
     Ableton.prototype.setProp = function (ns, nsid, prop, value) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
-                return [2 /*return*/, this.sendCommand(ns, nsid, "set_prop", { prop: prop, value: value })];
+                return [2 /*return*/, this.sendCommand({
+                        ns: ns,
+                        nsid: nsid,
+                        name: "set_prop",
+                        args: { prop: prop, value: value },
+                    })];
             });
         });
     };
@@ -289,10 +359,11 @@ var Ableton = /** @class */ (function (_super) {
                 switch (_a.label) {
                     case 0:
                         eventId = uuid_1.v4();
-                        return [4 /*yield*/, this.sendCommand(ns, nsid, "add_listener", {
-                                prop: prop,
+                        return [4 /*yield*/, this.sendCommand({
+                                ns: ns,
                                 nsid: nsid,
-                                eventId: eventId,
+                                name: "add_listener",
+                                args: { prop: prop, nsid: nsid, eventId: eventId },
                             })];
                     case 1:
                         result = _a.sent();
@@ -300,7 +371,7 @@ var Ableton = /** @class */ (function (_super) {
                             this.eventListeners.set(result, [listener]);
                         }
                         else {
-                            this.eventListeners.set(result, __spreadArray(__spreadArray([], this.eventListeners.get(result)), [
+                            this.eventListeners.set(result, __spreadArray(__spreadArray([], __read(this.eventListeners.get(result))), [
                                 listener,
                             ]));
                         }
@@ -325,7 +396,12 @@ var Ableton = /** @class */ (function (_super) {
                         }
                         if (!(listeners.length === 1)) return [3 /*break*/, 2];
                         this.eventListeners.delete(eventId);
-                        return [4 /*yield*/, this.sendCommand(ns, nsid, "remove_listener", { prop: prop, nsid: nsid })];
+                        return [4 /*yield*/, this.sendCommand({
+                                ns: ns,
+                                nsid: nsid,
+                                name: "remove_listener",
+                                args: { prop: prop, nsid: nsid },
+                            })];
                     case 1:
                         _a.sent();
                         return [2 /*return*/, true];

package/midi-script/Interface.py

@@ -1,10 +1,18 @@
+import hashlib
+import json
+
+
 class Interface(object):
     obj_ids = dict()
     listeners = dict()
 
     @staticmethod
     def save_obj(obj):
-        obj_id = id(obj)
+        try:
+            obj_id = "live_" + str(obj._live_ptr)
+        except:
+            obj_id = "id_" + str(id(obj))
+
         Interface.obj_ids[obj_id] = obj
         return obj_id
 
@@ -20,25 +28,43 @@ class Interface(object):
     def get_ns(self, nsid):
         return Interface.obj_ids[nsid]
 
+    def send_result(self, result, uuid, etag, cache):
+        """Sends an empty response if the etag matches the result, or the result together with an etag."""
+        if not cache:
+            return self.socket.send("result", result, uuid)
+
+        def jsonReplace(o):
+            return str(o)
+
+        hash = hashlib.md5(json.dumps(
+            result, default=jsonReplace, ensure_ascii=False).encode()).hexdigest()
+
+        if hash == etag:
+            return self.socket.send("result", {"__cached": True}, uuid)
+        else:
+            return self.socket.send("result", {"data": result, "etag": hash}, uuid)
+
     def handle(self, payload):
         name = payload.get("name")
         uuid = payload.get("uuid")
+        etag = payload.get("etag")
         args = payload.get("args", {})
+        cache = payload.get("cache", False)
         ns = self.get_ns(payload.get("nsid"))
 
         try:
             # Try self-defined functions first
             if hasattr(self, name) and callable(getattr(self, name)):
                 result = getattr(self, name)(ns=ns, **args)
-                self.socket.send("result", result, uuid)
+                self.send_result(result, uuid, etag, cache)
             # Check if the function exists in the Ableton API as fallback
             elif hasattr(ns, name) and callable(getattr(ns, name)):
                 if isinstance(args, dict):
                     result = getattr(ns, name)(**args)
-                    self.socket.send("result", result, uuid)
+                    self.send_result(result, uuid, etag, cache)
                 elif isinstance(args, list):
                     result = getattr(ns, name)(*args)
-                    self.socket.send("result", result, uuid)
+                    self.send_result(result, uuid, etag, cache)
                 else:
                     self.socket.send("error", "Function call failed: " + str(args) +
                                      " are invalid arguments", uuid)

package/midi-script/Internal.py

@@ -10,4 +10,4 @@ class Internal(Interface):
         return self
 
     def get_version(self, ns):
-        return "2.5.4"
+        return "2.7.0"

package/midi-script/Socket.py

@@ -2,6 +2,7 @@ import socket
 import json
 import struct
 import zlib
+import hashlib
 from threading import Timer
 
 

package/midi-script/Song.py

@@ -8,9 +8,19 @@ from .Track import Track
 class Song(Interface):
     def __init__(self, c_instance, socket):
         super(Song, self).__init__(c_instance, socket)
+        self.song = self.ableton.song()
 
     def get_ns(self, nsid):
-        return self.ableton.song()
+        return self.song
+
+    def create_audio_track(self, ns, index):
+        return Track.serialize_track(ns.create_audio_track(index))
+
+    def create_midi_track(self, ns, index):
+        return Track.serialize_track(ns.create_midi_track(index))
+
+    def create_return_track(self, ns):
+        return Track.serialize_track(ns.create_return_track())
 
     def get_clip_trigger_quantization(self, ns):
         return str(ns.clip_trigger_quantization)

package/midi-script/Track.py

@@ -26,7 +26,6 @@ class Track(Interface):
     def get_clip_slots(self, ns):
         return list(map(ClipSlot.serialize_clip_slot, ns.clip_slots))
 
-
     def get_group_track(self, ns):
         return Track.serialize_track(ns.group_track)
 

package/ns/clip-slot.d.ts

@@ -39,7 +39,7 @@ export interface ObservableProperties {
     playing_status: PlayingStatus;
 }
 export interface RawClipSlot {
-    id: number;
+    id: string;
     color: number;
     has_clip: boolean;
     is_playing: boolean;

package/ns/clip-slot.js

@@ -37,6 +37,9 @@ var ClipSlot = /** @class */ (function (_super) {
             clip: function (c) { return (c ? new clip_1.Clip(ableton, c) : null); },
             color: function (c) { return new color_1.Color(c); },
         };
+        _this.cachedProps = {
+            clip: true,
+        };
         return _this;
     }
     /**

package/ns/clip.d.ts

@@ -128,7 +128,7 @@ export interface ObservableProperties {
     warping: boolean;
 }
 export interface RawClip {
-    id: number;
+    id: string;
     name: string;
     color: number;
     is_audio_clip: boolean;

package/ns/cue-point.d.ts

@@ -13,7 +13,7 @@ export interface ObservableProperties {
     time: number;
 }
 export interface RawCuePoint {
-    id: number;
+    id: string;
     name: string;
     time: number;
 }

package/ns/device-parameter.d.ts

@@ -25,7 +25,7 @@ export interface ObservableProperties {
     value: number;
 }
 export interface RawDeviceParameter {
-    id: number;
+    id: string;
     name: string;
     value: number;
     is_quantized: boolean;

package/ns/device.d.ts

@@ -24,7 +24,7 @@ export interface ObservableProperties {
     parameters: string;
 }
 export interface RawDevice {
-    id: number;
+    id: string;
     name: string;
     type: DeviceType;
     class_name: string;

package/ns/device.js

@@ -31,7 +31,10 @@ var Device = /** @class */ (function (_super) {
         var _this = _super.call(this, ableton, "device", raw.id) || this;
         _this.raw = raw;
         _this.transformers = {
-            parameters: function (ps) { return ps.map(function (p) { return new device_parameter_1.DeviceParameter(_this.ableton, p); }); },
+            parameters: function (ps) { return ps.map(function (p) { return new device_parameter_1.DeviceParameter(ableton, p); }); },
+        };
+        _this.cachedProps = {
+            parameters: true,
         };
         return _this;
     }

package/ns/index.d.ts

@@ -2,11 +2,14 @@ import { Ableton } from "..";
 export declare class Namespace<GP, TP, SP, OP> {
     protected ableton: Ableton;
     protected ns: string;
-    protected nsid?: number | undefined;
-    constructor(ableton: Ableton, ns: string, nsid?: number | undefined);
+    protected nsid?: string | undefined;
     protected transformers: Partial<{
         [T in Extract<keyof GP, keyof TP>]: (val: GP[T]) => TP[T];
     }>;
+    protected cachedProps: Partial<{
+        [T in keyof GP]: boolean;
+    }>;
+    constructor(ableton: Ableton, ns: string, nsid?: string | undefined);
     get<T extends keyof GP>(prop: T): Promise<T extends keyof TP ? TP[T] : GP[T]>;
     set<T extends keyof SP>(prop: T, value: SP[T]): Promise<null>;
     addListener<T extends keyof OP>(prop: T, listener: (data: T extends keyof TP ? TP[T] : OP[T]) => any): Promise<() => Promise<boolean | undefined>>;
@@ -16,5 +19,12 @@ export declare class Namespace<GP, TP, SP, OP> {
      */
     sendCommand(name: string, args?: {
         [k: string]: any;
+    }, etag?: string, timeout?: number): Promise<any>;
+    /**
+     * Sends a raw function invocation to Ableton and expects the
+     * result to be a CacheResponse with `data` and an `etag`.
+     */
+    protected sendCachedCommand(name: string, args?: {
+        [k: string]: any;
     }, timeout?: number): Promise<any>;
 }

package/ns/index.js

@@ -43,13 +43,16 @@ var Namespace = /** @class */ (function () {
         this.ns = ns;
         this.nsid = nsid;
         this.transformers = {};
+        this.cachedProps = {};
     }
     Namespace.prototype.get = function (prop) {
         return __awaiter(this, void 0, void 0, function () {
-            var res, transformer;
+            var cache, res, transformer;
             return __generator(this, function (_a) {
                 switch (_a.label) {
-                    case 0: return [4 /*yield*/, this.ableton.getProp(this.ns, this.nsid, String(prop))];
+                    case 0:
+                        cache = !!this.cachedProps[prop];
+                        return [4 /*yield*/, this.ableton.getProp(this.ns, this.nsid, String(prop), cache)];
                     case 1:
                         res = _a.sent();
                         transformer = this.transformers[prop];
@@ -91,10 +94,21 @@ var Namespace = /** @class */ (function () {
      * Sends a raw function invocation to Ableton.
      * This should be used with caution.
      */
-    Namespace.prototype.sendCommand = function (name, args, timeout) {
+    Namespace.prototype.sendCommand = function (name, args, etag, timeout) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
-                return [2 /*return*/, this.ableton.sendCommand(this.ns, this.nsid, name, args, timeout)];
+                return [2 /*return*/, this.ableton.sendCommand({ ns: this.ns, nsid: this.nsid, name: name, args: args, etag: etag }, timeout)];
+            });
+        });
+    };
+    /**
+     * Sends a raw function invocation to Ableton and expects the
+     * result to be a CacheResponse with `data` and an `etag`.
+     */
+    Namespace.prototype.sendCachedCommand = function (name, args, timeout) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                return [2 /*return*/, this.ableton.sendCachedCommand({ ns: this.ns, nsid: this.nsid, name: name, args: args }, timeout)];
             });
         });
     };

package/ns/midi.d.ts

@@ -1,5 +1,5 @@
-import { Namespace } from "./index";
-import { Ableton } from "../index";
+import { Ableton } from "..";
+import { Namespace } from ".";
 export declare enum MidiCommand {
     NoteOn = 128,
     NoteOff = 144,

package/ns/midi.js

@@ -16,7 +16,7 @@ var __extends = (this && this.__extends) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Midi = exports.MidiMessage = exports.MidiCommand = void 0;
-var index_1 = require("./index");
+var _1 = require(".");
 var MidiCommand;
 (function (MidiCommand) {
     MidiCommand[MidiCommand["NoteOn"] = 128] = "NoteOn";
@@ -70,17 +70,18 @@ var MidiMessage = /** @class */ (function () {
         return {
             command: this.command,
             controller: this.parameter1,
-            value: this.parameter2
+            value: this.parameter2,
         };
     };
     MidiMessage.prototype.toNote = function () {
-        if (this.command !== MidiCommand.NoteOn && this.command !== MidiCommand.NoteOff) {
+        if (this.command !== MidiCommand.NoteOn &&
+            this.command !== MidiCommand.NoteOff) {
             throw "not a midi note message";
         }
         return {
             command: this.command,
             key: this.parameter1,
-            velocity: this.parameter2
+            velocity: this.parameter2,
         };
     };
     return MidiMessage;
@@ -91,10 +92,10 @@ var Midi = /** @class */ (function (_super) {
     function Midi(ableton) {
         var _this = _super.call(this, ableton, "midi") || this;
         _this.transformers = {
-            midi: function (msg) { return new MidiMessage(msg); }
+            midi: function (msg) { return new MidiMessage(msg); },
         };
         return _this;
     }
     return Midi;
-}(index_1.Namespace));
+}(_1.Namespace));
 exports.Midi = Midi;

package/ns/scene.d.ts

@@ -29,7 +29,7 @@ export interface ObservableProperties {
 }
 export interface RawScene {
     color: number;
-    id: number;
+    id: string;
     name: string;
 }
 export declare class Scene extends Namespace<GettableProperties, TransformedProperties, SettableProperties, ObservableProperties> {

package/ns/scene.js

@@ -28,6 +28,9 @@ var Scene = /** @class */ (function (_super) {
                 return clip_slots.map(function (c) { return new clip_slot_1.ClipSlot(_this.ableton, c); });
             },
         };
+        _this.cachedProps = {
+            clip_slots: true,
+        };
         return _this;
     }
     return Scene;

package/ns/song-view.js

@@ -62,18 +62,26 @@ var SongView = /** @class */ (function (_super) {
     function SongView(ableton) {
         var _this = _super.call(this, ableton, "song-view") || this;
         _this.transformers = {
-            selected_parameter: function (param) { return new device_parameter_1.DeviceParameter(_this.ableton, param); },
-            selected_track: function (track) { return new track_1.Track(_this.ableton, track); },
-            selected_scene: function (scene) { return new scene_1.Scene(_this.ableton, scene); },
-            highlighted_clip_slot: function (clipSlot) { return new clip_slot_1.ClipSlot(_this.ableton, clipSlot); },
+            selected_parameter: function (param) { return new device_parameter_1.DeviceParameter(ableton, param); },
+            selected_track: function (track) { return new track_1.Track(ableton, track); },
+            selected_scene: function (scene) { return new scene_1.Scene(ableton, scene); },
+            highlighted_clip_slot: function (slot) { return new clip_slot_1.ClipSlot(ableton, slot); },
+        };
+        _this.cachedProps = {
+            selected_parameter: true,
+            selected_track: true,
+            selected_scene: true,
+            highlighted_clip_slot: true,
         };
         return _this;
     }
     SongView.prototype.selectDevice = function (device) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
-                return [2 /*return*/, this.ableton.sendCommand(this.ns, undefined, "select_device", {
-                        device_id: device.raw.id,
+                return [2 /*return*/, this.ableton.sendCommand({
+                        ns: this.ns,
+                        name: "select_device",
+                        args: { device_id: device.raw.id },
                     })];
             });
         });

package/ns/song.js

@@ -101,12 +101,20 @@ var Song = /** @class */ (function (_super) {
         var _this = _super.call(this, ableton, "song") || this;
         _this.view = new song_view_1.SongView(_this.ableton);
         _this.transformers = {
-            cue_points: function (points) { return points.map(function (c) { return new cue_point_1.CuePoint(_this.ableton, c); }); },
-            master_track: function (track) { return new track_1.Track(_this.ableton, track); },
-            return_tracks: function (tracks) { return tracks.map(function (t) { return new track_1.Track(_this.ableton, t); }); },
-            tracks: function (tracks) { return tracks.map(function (t) { return new track_1.Track(_this.ableton, t); }); },
-            visible_tracks: function (tracks) { return tracks.map(function (t) { return new track_1.Track(_this.ableton, t); }); },
-            scenes: function (scenes) { return scenes.map(function (s) { return new scene_1.Scene(_this.ableton, s); }); },
+            cue_points: function (points) { return points.map(function (c) { return new cue_point_1.CuePoint(ableton, c); }); },
+            master_track: function (track) { return new track_1.Track(ableton, track); },
+            return_tracks: function (tracks) { return tracks.map(function (t) { return new track_1.Track(ableton, t); }); },
+            tracks: function (tracks) { return tracks.map(function (t) { return new track_1.Track(ableton, t); }); },
+            visible_tracks: function (tracks) { return tracks.map(function (t) { return new track_1.Track(ableton, t); }); },
+            scenes: function (scenes) { return scenes.map(function (s) { return new scene_1.Scene(ableton, s); }); },
+        };
+        _this.cachedProps = {
+            cue_points: true,
+            master_track: true,
+            return_tracks: true,
+            tracks: true,
+            visible_tracks: true,
+            scenes: true,
         };
         return _this;
     }
@@ -197,7 +205,7 @@ var Song = /** @class */ (function (_super) {
     Song.prototype.getData = function (key) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
-                return [2 /*return*/, this.sendCommand("get_data", { key: key })];
+                return [2 /*return*/, this.sendCachedCommand("get_data", { key: key })];
             });
         });
     };

package/ns/track.d.ts

@@ -111,7 +111,7 @@ export interface ObservableProperties {
     solo: boolean;
 }
 export interface RawTrack {
-    id: number;
+    id: string;
     name: string;
     color: number;
     is_foldable: boolean;

package/ns/track.js

@@ -36,12 +36,17 @@ var Track = /** @class */ (function (_super) {
                 return clip_slots.map(function (c) { return new clip_slot_1.ClipSlot(ableton, c); });
             },
         };
+        _this.cachedProps = {
+            arrangement_clips: true,
+            devices: true,
+            clip_slots: true,
+        };
         return _this;
     }
     Track.prototype.duplicateClipToArrangement = function (clipID, time) {
         return this.sendCommand("duplicate_clip_to_arrangement", {
             clip_id: clipID,
-            time: time
+            time: time,
         });
     };
     return Track;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ableton-js",
-  "version": "2.5.4",
+  "version": "2.7.0",
   "description": "Control Ableton Live from Node",
   "main": "index.js",
   "author": "Leo Bernard <admin@leolabs.org>",
@@ -46,6 +46,7 @@
     "typescript": "^4.3.2"
   },
   "dependencies": {
+    "lru-cache": "^7.14.0",
     "semver": "^7.3.5",
     "uuid": "^8.3.2"
   }

package/util/cache.d.ts

@@ -0,0 +1,14 @@
+import type LruCache from "lru-cache";
+export declare type CachedResponse = {
+    __cached: true;
+};
+export declare type CacheResponse = CachedResponse | {
+    data: any;
+    etag: string;
+};
+export declare const isCached: (obj: CacheResponse) => obj is CachedResponse;
+export interface CacheObject {
+    etag: string;
+    data: any;
+}
+export declare type Cache = LruCache<string, CacheObject>;

package/util/cache.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCached = void 0;
+var isCached = function (obj) {
+    return obj && "__cached" in obj;
+};
+exports.isCached = isCached;