# Caviio Custom Bitwig Devices — Read This First This folder contains custom Bitwig devices/modulators and two different ways to make their identities available to Bitwig. Read this document completely and choose **one** method before saving real projects. This is an unofficial, experimental package. It is not made, supported, or endorsed by Bitwig GmbH. ## What the UUID actually does Every Bitwig device or modulator document has an identity UUID embedded in the document itself. Native Bitwig identities are also known to internal registries and catalogs inside `bitwig.jar`. Giving a custom document a new UUID is therefore only half of the job: Bitwig must either be taught that identity (**Option A**) or the custom document must use an identity Bitwig already knows (**Option B**). Grid modules also have identities, but the two tools supplied in this folder currently handle only `.bwdevice` and `.bwmodulator` documents. They do **not** currently install arbitrary `.bwmodule` files. ## Install the custom documents Copy or merge the two folders found under `devices/` into your Bitwig user library: - macOS / Windows: `Documents/Bitwig Studio/Library/` - Linux: `~/Bitwig Studio/Library/` The final locations are: - `Library/My Devices/*.bwdevice` - `Library/My Modulators/*.bwmodulator` The supplied tools can also create/verify the required `My Devices` and `My Modulators` links inside a selected Bitwig installation. The included documents should be treated as **Bitwig Studio 6.1 documents**. Older Bitwig versions may reject files saved by a newer release even if a tool contains a technical profile for that older version. ## Choose exactly one identity method Do not apply both methods to the same working copies of the documents. Option A keeps the supplied custom UUIDs; Option B rewrites them to native donor UUIDs. That means the same device has a different identity under the two methods. Projects saved with one method are not automatically compatible with the other method. Keep an untouched copy of the original `devices/` folder. ## Option A — Register the custom UUIDs by patching Bitwig Tool: `OPTION A/uuid-tool.zip` This is the best option when the same stable custom identity must be used on several computers or inside shared projects. The tool: 1. Keeps or assigns a stable, unique UUID to each custom device/modulator. 2. Registers that UUID in the selected Bitwig installation. 3. Adds the required category, Browser/search, and availability handling. 4. Handles Bitwig's integrity/tamper response for the modified JAR. 5. Creates backups and verifies the result before completing the installation. The supplied Option A tool has launchers for macOS, Windows, and Linux. Its current verified profiles cover Bitwig Studio 6.0.6, 6.0.11, 6.1 Beta 6, 6.1 Beta 7, and 6.1 stable. This device pack itself is intended for Bitwig 6.1. ### After a Bitwig update A Bitwig update normally replaces `bitwig.jar`, so the registration patch is removed. The UUID embedded in each custom document does **not** need to change. Run a tool version that explicitly supports the new Bitwig build and register the same UUIDs again. Never force a profile intended for another build. ### Requirements and consequences - Bitwig and all Bitwig audio/plugin processes must be closed first. - The selected Bitwig installation is modified. - macOS and Linux require Python 3; Windows includes its own Python runtime. - Keep the generated local backup, but never redistribute it. Read the README inside `uuid-tool.zip` before running it. ## Option B — Use a compatible native donor UUID without patching the JAR Tool: `OPTION B ( only for mac for the moment )/Bitwig UUID Donor Tool macOS 2026-08-29.zip` This method does not patch `bitwig.jar`. Instead, every custom device or modulator receives the UUID of one compatible native Bitwig donor. It is **not** enough to rewrite the UUID and simply delete the native donor. Reliable cold project recall requires the donor's expected core-library path to remain present. The tool therefore: 1. Checks that device and donor have the same signal type. A modulator can only use a modulator donor. 2. Backs up the custom document, native donor document, and exact UUID-scoped factory support files. 3. Rewrites only the custom document's exact UUID fields. 4. Replaces the native donor's core slot with an exact copy of the rewritten custom document. 5. Removes conflicting UUID-scoped factory defaults/remote controls. 6. Verifies name, UUID, file hashes, and both document locations. The selected native donor is no longer available as its original device until the operation is restored. Do not choose a native device you still need. ### Project portability with Option B Every computer that must open the same project needs the **same mapping**: `custom device -> native donor UUID` If two users choose different donors, their rewritten custom devices have different identities and the project is not portable between them. Record the mapping and use it consistently on every machine. ### After a Bitwig update An update can restore the original native donor, its support files, and the internal library layout. Close Bitwig and run the donor operation again for the new installation, choosing the same donor mapping. Do not restore native files from an older Bitwig build into a newer build. Option B is currently packaged and verified for macOS. Read the README and `SHARING-NOTICE.txt` inside its ZIP before use. ## Which option should I use? - Choose **Option A** when stable identities and project sharing across several installations matter most, and you accept patching each supported Bitwig build. - Choose **Option B** when avoiding a `bitwig.jar` patch matters most, and you accept sacrificing one compatible native donor per custom identity and maintaining the exact same donor mapping everywhere. ## Safety and sharing - Back up important projects and the original custom documents first. - Never run either tool while Bitwig or its audio/plugin processes are active. - Never distribute a generated `Backups` folder. It may contain copies of native Bitwig application resources and machine-specific paths. - Do not distribute a modified `bitwig.jar` or backed-up native donor files. - Share only the clean tool ZIPs and custom documents included here. Bitwig's published terms state that its digital products may not be modified, reproduced, distributed, or made publicly accessible unless expressly permitted or legally permissible. Each user is responsible for their license and local law. This document is not legal advice. Official terms: https://www.bitwig.com/terms-conditions/ ## Package contents - `devices/` — Caviio custom devices and modulator - `OPTION A/` — cross-platform custom UUID registry patch tool - `OPTION B ( only for mac for the moment )/` — macOS native UUID donor tool