@soundor/vst3-host 0.0.0-stage → 0.1.0

package/native/src/Session.h

@@ -0,0 +1,82 @@
+// Requests, one at a time and in order, on the main thread. A process request
+// runs on the audio worker while the main thread keeps running its loop (and
+// an open editor); the next request waits until it is done.
+#pragma once
+
+#include "EventLoop.h"
+#include "HostInterface.h"
+#include "Ipc.h"
+#include "LiveAudio.h"
+#include "Plugin.h"
+#include "Settings.h"
+
+#include <condition_variable>
+#include <deque>
+#include <functional>
+#include <mutex>
+#include <thread>
+
+namespace soundor::vst3host
+{
+    /** The thread process() runs on. */
+    class AudioWorker
+    {
+    public:
+        AudioWorker();
+        ~AudioWorker();
+        AudioWorker(const AudioWorker&) = delete;
+        AudioWorker& operator=(const AudioWorker&) = delete;
+        /** Runs `work` on the worker thread; one job at a time. */
+        void run(std::function<void()> work);
+
+    private:
+        std::mutex mutex_;
+        std::condition_variable wake_;
+        std::function<void()> job_;
+        bool stop_ = false;
+        std::thread thread_;
+    };
+
+    class Session
+    {
+    public:
+        Session(EventLoop& loop, FrameWriter& writer, bool ui);
+        ~Session();
+
+        /** The handshake: the first frame the client sees. */
+        void hello(size_t maxPayload);
+        void onFrame(Frame frame);
+        /** The client closed the request stream. */
+        void onInputClosed();
+        /** The request stream is corrupt and cannot continue. */
+        void onProtocolError(const std::string& message);
+        int exitCode() const { return exitCode_; }
+
+    private:
+        void pump();
+        void handle(Frame& frame);
+        void respond(const Json& id, Json result, std::span<const uint8_t> payload = {});
+        void respondError(const Json& id, const std::string& code, const std::string& message,
+                          const Json& details = {});
+        void emit(const std::string& event, Json params);
+        void finish(int code);
+        std::unique_ptr<EditorWindow> createWindow(const std::string& title, int width, int height,
+                                                   EditorWindow::Callbacks callbacks, std::string& error);
+        Json openEditor(const Json& params, const std::string& where);
+        void applyAudio(const Json& params, const std::string& where);
+
+        EventLoop& loop_;
+        FrameWriter& writer_;
+        bool ui_;
+        Settings settings_;
+        /** The presentation of the next editor: "editor" or "host". */
+        std::string presentation_;
+        Plugin plugin_;
+        LiveAudio audio_;
+        HostModel model_;
+        AudioWorker worker_;
+        std::deque<Frame> queue_;
+        bool closing_ = false;
+        int exitCode_ = 0;
+    };
+} // namespace soundor::vst3host

package/native/src/Settings.cpp

@@ -0,0 +1,93 @@
+#include "Settings.h"
+
+#include "Json.h"
+#include "Paths.h"
+
+#include <cstdlib>
+#include <filesystem>
+#include <fstream>
+#include <sstream>
+
+namespace soundor::vst3host
+{
+    namespace
+    {
+#if ! defined(_WIN32)
+        std::string environment(const char* name)
+        {
+            const char* value = std::getenv(name); // NOLINT(concurrency-mt-unsafe): read on the main thread
+            return value != nullptr ? value : "";
+        }
+#endif
+
+        std::filesystem::path settingsPath()
+        {
+#if defined(_WIN32)
+            // Windows' environment is UTF-16.
+            if (const wchar_t* path = _wgetenv(L"SOUNDOR_VST3_HOST_SETTINGS"); path != nullptr && *path != L'\0')
+                return path;
+            const wchar_t* base = _wgetenv(L"APPDATA");
+            return base == nullptr || *base == L'\0' ? std::filesystem::path()
+                                                     : std::filesystem::path(base) / "Soundor" / "vst3-host.json";
+#else
+            if (const std::string path = environment("SOUNDOR_VST3_HOST_SETTINGS"); ! path.empty())
+                return toPath(path);
+#endif
+#if defined(_WIN32)
+#elif defined(__APPLE__)
+            const std::string home = environment("HOME");
+            return home.empty() ? std::filesystem::path()
+                                : toPath(home) / "Library" / "Application Support" / "Soundor" / "vst3-host.json";
+#else
+            if (const std::string config = environment("XDG_CONFIG_HOME"); ! config.empty())
+                return toPath(config) / "soundor" / "vst3-host.json";
+            const std::string home = environment("HOME");
+            return home.empty() ? std::filesystem::path() : toPath(home) / ".config" / "soundor" / "vst3-host.json";
+#endif
+        }
+    } // namespace
+
+    Settings Settings::load()
+    {
+        Settings settings;
+        const auto path = settingsPath();
+        if (path.empty())
+            return settings;
+        std::ifstream input(path, std::ios::binary);
+        if (! input)
+            return settings;
+        std::stringstream text;
+        text << input.rdbuf();
+        try
+        {
+            const Json json = Json::parse(text.str());
+            if (const Json* value = json.find("presentation");
+                value != nullptr && value->isString() && (value->asString() == "host" || value->asString() == "editor"))
+                settings.presentation = value->asString();
+            if (const Json* value = json.find("panelOpen"); value != nullptr && value->isBool())
+                settings.panelOpen = value->asBool();
+            if (const Json* value = json.find("volume");
+                value != nullptr && value->isNumber() && value->asNumber() >= 0 && value->asNumber() <= 1)
+                settings.volume = value->asNumber();
+        }
+        catch (const std::exception&) // NOLINT(bugprone-empty-catch): a damaged file means the defaults
+        {
+        }
+        return settings;
+    }
+
+    void Settings::save() const
+    {
+        const auto path = settingsPath();
+        if (path.empty())
+            return;
+        std::error_code error;
+        std::filesystem::create_directories(path.parent_path(), error);
+        Json json = Json::object();
+        json.set("presentation", presentation);
+        json.set("panelOpen", panelOpen);
+        json.set("volume", volume);
+        std::ofstream output(path, std::ios::binary | std::ios::trunc);
+        output << json.dump() << "\n";
+    }
+} // namespace soundor::vst3host

package/native/src/Settings.h

@@ -0,0 +1,23 @@
+// The host interface's settings, kept between runs in a JSON file:
+// $XDG_CONFIG_HOME/soundor/vst3-host.json (~/.config), ~/Library/Application
+// Support/Soundor/vst3-host.json or %APPDATA%\Soundor\vst3-host.json;
+// SOUNDOR_VST3_HOST_SETTINGS names another file. What a launch asks for
+// explicitly always wins over them.
+#pragma once
+
+#include <string>
+
+namespace soundor::vst3host
+{
+    struct Settings
+    {
+        /** Open editors with the host interface ("host") or without ("editor"). */
+        std::string presentation = "host";
+        bool panelOpen = false;
+        double volume = 0.8;
+
+        static Settings load();
+        /** Best effort: a settings file that cannot be written is not an error. */
+        void save() const;
+    };
+} // namespace soundor::vst3host

package/native/src/Version.h.in

@@ -0,0 +1,11 @@
+// Generated by CMakeLists.txt from package.json and protocol.json.
+#pragma once
+
+namespace soundor::vst3host
+{
+    inline constexpr const char* hostVersion = "@SOUNDOR_VST3_HOST_VERSION@";
+    inline constexpr int protocolVersion = @SOUNDOR_VST3_HOST_PROTOCOL@;
+    inline constexpr unsigned long long defaultMaxPayload = @SOUNDOR_VST3_HOST_MAX_PAYLOAD@ULL;
+    inline constexpr unsigned long long maxHeader = @SOUNDOR_VST3_HOST_MAX_HEADER@ULL;
+    inline constexpr const char* sdkVersion = "@SOUNDOR_VST3_SDK_VERSION@";
+} // namespace soundor::vst3host

package/native/src/X11Library.cpp

@@ -0,0 +1,127 @@
+#include "X11Library.h"
+
+#include <dlfcn.h>
+
+#include <cstdio>
+#include <type_traits>
+
+namespace soundor::vst3host
+{
+    namespace
+    {
+        const Xlib* loadedXlib = nullptr;
+        Display* quietDisplay = nullptr;
+
+        int logError(Display* display, XErrorEvent* event)
+        {
+            if (display == quietDisplay)
+                return 0;
+            char text[256] = {};
+            loadedXlib->getErrorText(display, event->error_code, text, sizeof text);
+            std::fprintf(stderr, "X error (ignored): %s, request %d.%d, resource 0x%lx\n", text, event->request_code,
+                         event->minor_code, event->resourceid);
+            return 0;
+        }
+    } // namespace
+
+    const Xlib* loadXlib(std::string& error)
+    {
+        static Xlib xlib;
+        static bool loaded = false;
+        if (loaded)
+            return &xlib;
+        void* library = dlopen("libX11.so.6", RTLD_NOW | RTLD_LOCAL);
+        if (library == nullptr)
+        {
+            error = "the editor needs libX11.so.6, which could not be loaded";
+            return nullptr;
+        }
+        bool complete = true;
+        auto bind = [&](auto& function, const char* name)
+        {
+            function = reinterpret_cast<std::remove_reference_t<decltype(function)>>(dlsym(library, name));
+            complete = complete && function != nullptr;
+        };
+        bind(xlib.openDisplay, "XOpenDisplay");
+        bind(xlib.closeDisplay, "XCloseDisplay");
+        bind(xlib.defaultScreen, "XDefaultScreen");
+        bind(xlib.rootWindow, "XRootWindow");
+        bind(xlib.blackPixel, "XBlackPixel");
+        bind(xlib.createSimpleWindow, "XCreateSimpleWindow");
+        bind(xlib.destroyWindow, "XDestroyWindow");
+        bind(xlib.mapWindow, "XMapWindow");
+        bind(xlib.storeName, "XStoreName");
+        bind(xlib.internAtom, "XInternAtom");
+        bind(xlib.changeProperty, "XChangeProperty");
+        bind(xlib.setWMProtocols, "XSetWMProtocols");
+        bind(xlib.selectInput, "XSelectInput");
+        bind(xlib.pending, "XPending");
+        bind(xlib.nextEvent, "XNextEvent");
+        bind(xlib.resizeWindow, "XResizeWindow");
+        bind(xlib.getWindowAttributes, "XGetWindowAttributes");
+        bind(xlib.flush, "XFlush");
+        bind(xlib.connectionNumber, "XConnectionNumber");
+        bind(xlib.allocSizeHints, "XAllocSizeHints");
+        bind(xlib.setWMNormalHints, "XSetWMNormalHints");
+        bind(xlib.free, "XFree");
+        bind(xlib.moveResizeWindow, "XMoveResizeWindow");
+        bind(xlib.setErrorHandler, "XSetErrorHandler");
+        bind(xlib.getErrorText, "XGetErrorText");
+        bind(xlib.displayString, "XDisplayString");
+        bind(xlib.queryTree, "XQueryTree");
+        bind(xlib.sync, "XSync");
+        bind(xlib.getImage, "XGetImage");
+        bind(xlib.freePixmap, "XFreePixmap");
+        bind(xlib.setWindowBackgroundPixmap, "XSetWindowBackgroundPixmap");
+        bind(xlib.sendEvent, "XSendEvent");
+        bind(xlib.setWindowBackground, "XSetWindowBackground");
+        bind(xlib.changeWindowAttributes, "XChangeWindowAttributes");
+        bind(xlib.translateCoordinates, "XTranslateCoordinates");
+        if (! complete)
+        {
+            error = "libX11.so.6 lacks a required function";
+            return nullptr;
+        }
+        loaded = true;
+        loadedXlib = &xlib;
+        xlib.setErrorHandler(&logError);
+        return &xlib;
+    }
+
+    const XLive* loadXLive()
+    {
+        static const XLive* const loaded = []() -> const XLive*
+        {
+            static XLive live;
+            void* composite = dlopen("libXcomposite.so.1", RTLD_NOW | RTLD_LOCAL);
+            void* damage = dlopen("libXdamage.so.1", RTLD_NOW | RTLD_LOCAL);
+            void* extensions = dlopen("libXext.so.6", RTLD_NOW | RTLD_LOCAL);
+            if (composite == nullptr || damage == nullptr || extensions == nullptr)
+                return nullptr;
+            bool complete = true;
+            auto bind = [&](void* library, auto& function, const char* name)
+            {
+                function = reinterpret_cast<std::remove_reference_t<decltype(function)>>(dlsym(library, name));
+                complete = complete && function != nullptr;
+            };
+            bind(composite, live.compositeQueryExtension, "XCompositeQueryExtension");
+            bind(composite, live.redirectSubwindows, "XCompositeRedirectSubwindows");
+            bind(composite, live.unredirectSubwindows, "XCompositeUnredirectSubwindows");
+            bind(composite, live.nameWindowPixmap, "XCompositeNameWindowPixmap");
+            bind(damage, live.damageQueryExtension, "XDamageQueryExtension");
+            bind(damage, live.damageCreate, "XDamageCreate");
+            bind(damage, live.damageDestroy, "XDamageDestroy");
+            bind(damage, live.damageSubtract, "XDamageSubtract");
+            bind(extensions, live.shapeQueryExtension, "XShapeQueryExtension");
+            bind(extensions, live.shapeCombineRectangles, "XShapeCombineRectangles");
+            bind(extensions, live.shapeCombineMask, "XShapeCombineMask");
+            return complete ? &live : nullptr;
+        }();
+        return loaded;
+    }
+
+    void setQuietDisplay(Display* display)
+    {
+        quietDisplay = display;
+    }
+} // namespace soundor::vst3host

package/native/src/X11Library.h

@@ -0,0 +1,83 @@
+// Xlib, loaded when a window is first needed and never linked: headless mode
+// runs on machines without X11 libraries or a display.
+#pragma once
+
+#include <X11/Xlib.h>
+#include <X11/Xutil.h>
+#include <X11/extensions/Xcomposite.h>
+#include <X11/extensions/Xdamage.h>
+#include <X11/extensions/shape.h>
+
+#include <string>
+
+namespace soundor::vst3host
+{
+    struct Xlib
+    {
+        decltype(&XOpenDisplay) openDisplay = nullptr;
+        decltype(&XCloseDisplay) closeDisplay = nullptr;
+        decltype(&XDefaultScreen) defaultScreen = nullptr;
+        decltype(&XRootWindow) rootWindow = nullptr;
+        decltype(&XBlackPixel) blackPixel = nullptr;
+        decltype(&XCreateSimpleWindow) createSimpleWindow = nullptr;
+        decltype(&XDestroyWindow) destroyWindow = nullptr;
+        decltype(&XMapWindow) mapWindow = nullptr;
+        decltype(&XStoreName) storeName = nullptr;
+        decltype(&XInternAtom) internAtom = nullptr;
+        decltype(&XChangeProperty) changeProperty = nullptr;
+        decltype(&XSetWMProtocols) setWMProtocols = nullptr;
+        decltype(&XSelectInput) selectInput = nullptr;
+        decltype(&XPending) pending = nullptr;
+        decltype(&XNextEvent) nextEvent = nullptr;
+        decltype(&XResizeWindow) resizeWindow = nullptr;
+        decltype(&XGetWindowAttributes) getWindowAttributes = nullptr;
+        decltype(&XFlush) flush = nullptr;
+        decltype(&XConnectionNumber) connectionNumber = nullptr;
+        decltype(&XAllocSizeHints) allocSizeHints = nullptr;
+        decltype(&XSetWMNormalHints) setWMNormalHints = nullptr;
+        decltype(&XFree) free = nullptr;
+        decltype(&XMoveResizeWindow) moveResizeWindow = nullptr;
+        decltype(&XSetErrorHandler) setErrorHandler = nullptr;
+        decltype(&XGetErrorText) getErrorText = nullptr;
+        decltype(&XDisplayString) displayString = nullptr;
+        decltype(&XQueryTree) queryTree = nullptr;
+        decltype(&XSync) sync = nullptr;
+        decltype(&XGetImage) getImage = nullptr;
+        decltype(&XFreePixmap) freePixmap = nullptr;
+        decltype(&XSetWindowBackgroundPixmap) setWindowBackgroundPixmap = nullptr;
+        decltype(&XSendEvent) sendEvent = nullptr;
+        decltype(&XSetWindowBackground) setWindowBackground = nullptr;
+        decltype(&XChangeWindowAttributes) changeWindowAttributes = nullptr;
+        decltype(&XTranslateCoordinates) translateCoordinates = nullptr;
+    };
+
+    /** What live presentation needs (EditorArea) besides Xlib. */
+    struct XLive
+    {
+        decltype(&XCompositeQueryExtension) compositeQueryExtension = nullptr;
+        decltype(&XCompositeRedirectSubwindows) redirectSubwindows = nullptr;
+        decltype(&XCompositeUnredirectSubwindows) unredirectSubwindows = nullptr;
+        decltype(&XCompositeNameWindowPixmap) nameWindowPixmap = nullptr;
+        decltype(&XDamageQueryExtension) damageQueryExtension = nullptr;
+        decltype(&XDamageCreate) damageCreate = nullptr;
+        decltype(&XDamageDestroy) damageDestroy = nullptr;
+        decltype(&XDamageSubtract) damageSubtract = nullptr;
+        decltype(&XShapeQueryExtension) shapeQueryExtension = nullptr;
+        decltype(&XShapeCombineRectangles) shapeCombineRectangles = nullptr;
+        decltype(&XShapeCombineMask) shapeCombineMask = nullptr;
+    };
+
+    /** The functions the host uses, loaded once; nullptr and `error` without
+        libX11. Loading also replaces Xlib's default error handler, which
+        ends the process, with one that logs: a plugin's failed X request
+        is the plugin's problem, not the host's end. */
+    const Xlib* loadXlib(std::string& error);
+
+    /** Loaded once; nullptr without libXcomposite, libXdamage or libXext, where the
+        editor's view stays on the screen while it is resized. */
+    const XLive* loadXLive();
+
+    /** Errors on this connection are not logged: its requests may name a
+        plugin's window, which the plugin destroys when it likes. */
+    void setQuietDisplay(Display* display);
+} // namespace soundor::vst3host

package/native/tools/Embed.cpp

@@ -0,0 +1,49 @@
+// Writes files into a C++ source as byte arrays:
+//
+//   soundor_vst3_host_embed <output.cpp> <namespace> (<name> <file>)...
+//
+// Each <name> becomes `extern const unsigned char name[]` and
+// `extern const std::size_t nameSize` in <namespace>.
+#include <cstdio>
+#include <fstream>
+#include <iterator>
+#include <string>
+#include <vector>
+
+int main(int argc, char** argv)
+{
+    if (argc < 3 || (argc - 3) % 2 != 0)
+    {
+        std::fputs("usage: soundor_vst3_host_embed <output.cpp> <namespace> (<name> <file>)...\n", stderr);
+        return 2;
+    }
+    std::string code = "// Generated by soundor_vst3_host_embed.\n#include <cstddef>\n\nnamespace ";
+    code += argv[2];
+    code += "\n{\n";
+    for (int index = 3; index < argc; index += 2)
+    {
+        std::ifstream input(argv[index + 1], std::ios::binary);
+        if (! input)
+        {
+            std::fprintf(stderr, "cannot read %s\n", argv[index + 1]);
+            return 1;
+        }
+        const std::vector<unsigned char> bytes { std::istreambuf_iterator<char>(input),
+                                                 std::istreambuf_iterator<char>() };
+        const std::string name = argv[index];
+        code += "    extern const unsigned char " + name + "[];\n";
+        code += "    extern const std::size_t " + name + "Size;\n";
+        code += "    alignas(16) const unsigned char " + name + "[] = {";
+        for (size_t at = 0; at < bytes.size(); ++at)
+        {
+            if (at % 24 == 0)
+                code += "\n        ";
+            code += std::to_string(bytes[at]) + ",";
+        }
+        code += "\n    };\n    const std::size_t " + name + "Size = " + std::to_string(bytes.size()) + ";\n";
+    }
+    code += "} // namespace " + std::string(argv[2]) + "\n";
+    std::ofstream output(argv[1], std::ios::binary);
+    output << code;
+    return output ? 0 : 1;
+}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@soundor/vst3-host",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "A standalone VST3 host for tests and development: a native executable driven from Node.js, with or without the plugin's editor.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/soundor/soundor.git",
+    "directory": "hosts/vst3-host"
+  },
+  "bin": {
+    "soundor-vst3-host": "./dist/cli.mjs"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "NOTICE.md",
+    "CMakeLists.txt",
+    "CMakePresets.json",
+    "protocol.json",
+    "targets.json",
+    "cmake",
+    "native/src",
+    "native/tools",
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@soundor/tsdown-config": "^0.0.0",
+    "@soundor/typescript-config": "^0.0.0",
+    "@types/node": "^24.19.2",
+    "tsdown": "^0.23.4",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  },
+  "engines": {
+    "node": "^22.18.0 || >=24.11.0"
+  },
+  "optionalDependencies": {
+    "@soundor/vst3-host-linux-x64-gnu": "0.1.0",
+    "@soundor/vst3-host-darwin-universal": "0.1.0",
+    "@soundor/vst3-host-win32-x64": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b && tsdown --clean",
+    "test": "vitest run",
+    "build:native": "node src/cli.ts prepare --mode source",
+    "test:native": "node scripts/native.ts test",
+    "tidy:native": "cmake --workflow --preset tidy",
+    "format:native": "node ../../scripts/clang-format.mjs --check native",
+    "format:native:fix": "node ../../scripts/clang-format.mjs --fix native"
+  }
 }

package/protocol.json

@@ -0,0 +1,7 @@
+{
+  "$comment": "The host's IPC protocol identity, read by the native build (CMakeLists.txt) and the Node client (src/protocol.ts). Bump `version` for any incompatible change to frames or messages.",
+  "version": 1,
+  "magic": "SVH1",
+  "maxHeaderBytes": 1048576,
+  "defaultMaxPayloadBytes": 268435456
+}

package/targets.json

@@ -0,0 +1,33 @@
+{
+  "$comment": "The platform packages the release generates (scripts/release.ts). Each carries one executable; npm or pnpm installs the one matching `os`, `cpu` and `libc`. Not workspace packages: they are generated, versioned as @soundor/vst3-host, and never committed.",
+  "targets": [
+    {
+      "target": "linux-x64-gnu",
+      "package": "@soundor/vst3-host-linux-x64-gnu",
+      "os": ["linux"],
+      "cpu": ["x64"],
+      "libc": ["glibc"],
+      "runner": "ubuntu-24.04",
+      "architectures": ["x64"],
+      "executable": "bin/soundor-vst3-host"
+    },
+    {
+      "target": "darwin-universal",
+      "package": "@soundor/vst3-host-darwin-universal",
+      "os": ["darwin"],
+      "cpu": ["arm64", "x64"],
+      "runner": "macos-15",
+      "architectures": ["arm64", "x64"],
+      "executable": "bin/soundor-vst3-host"
+    },
+    {
+      "target": "win32-x64",
+      "package": "@soundor/vst3-host-win32-x64",
+      "os": ["win32"],
+      "cpu": ["x64"],
+      "runner": "windows-2025",
+      "architectures": ["x64"],
+      "executable": "bin/soundor-vst3-host.exe"
+    }
+  ]
+}