{"id":27942878,"url":"https://github.com/tonalflex/tonalflex-template-plugin","last_synced_at":"2025-05-07T11:58:43.454Z","repository":{"id":283542146,"uuid":"951150294","full_name":"tonalflex/tonalflex-template-plugin","owner":"tonalflex","description":"JUCE Template for creating new plugins for Tonalflex (ElkOS aarch64)","archived":false,"fork":false,"pushed_at":"2025-05-02T23:33:08.000Z","size":179,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-05-07T11:58:34.285Z","etag":null,"topics":["audio-processing","cpp","dsp","juce-framework","micro-frontend","vst"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tonalflex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-19T08:35:31.000Z","updated_at":"2025-05-02T23:33:12.000Z","dependencies_parsed_at":"2025-03-20T20:13:16.911Z","dependency_job_id":"07cefd0f-36dd-4e97-947a-fab8aca2c01f","html_url":"https://github.com/tonalflex/tonalflex-template-plugin","commit_stats":null,"previous_names":["tonalflex/tonalflex-template-plugin"],"tags_count":7,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tonalflex%2Ftonalflex-template-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tonalflex%2Ftonalflex-template-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tonalflex%2Ftonalflex-template-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tonalflex%2Ftonalflex-template-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tonalflex","download_url":"https://codeload.github.com/tonalflex/tonalflex-template-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252873975,"owners_count":21817711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio-processing","cpp","dsp","juce-framework","micro-frontend","vst"],"created_at":"2025-05-07T11:58:42.797Z","updated_at":"2025-05-07T11:58:43.443Z","avatar_url":"https://github.com/tonalflex.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TonalFlex Template Plugin\n\n---\n\n## **📖 Introduction**\n\n**TonalFlex Template Plugin** provides a starting point for creating **Audio DSP Plugins** using **[JUCE](https://juce.com)** framework.\n\nThis template is designed to **simplify development** and ensure **cross-platform compatibility**, including **desktop environments** _(Linux/MacOS/Windows)_ and embedded systems such as _**[ElkOS](https://www.elk.audio/)**_.\n\nIt includes:\n\n- **CMake presets** for standardized builds.\n- **Prebuilt Docker image** to cross-compile for **[ElkOS](https://www.elk.audio/)**.\n- **Support for Windows, macOS, and Linux** desktop builds.\n- **Example CMake structure** for easy integration with JUCE.\n\nUse this template to **kickstart plugin development** with minimal setup.\n\n---\n\n## **⚡ Prerequisites**\n\nBefore you begin, ensure you have the following installed:\n\n✅ **Development Tools**:\n\n- [VS Code](https://code.visualstudio.com/) (Recommended IDE)\n- [CMake](https://cmake.org/download/) (Build system)\n- [Docker](https://www.docker.com/) (For cross-compilation)\n\n✅ **Additional Dependencies**:\n\n- [JUCE Framework](https://juce.com/) (Automatically fetched via CMake)\n- [Git](https://git-scm.com/) (Version control)\n\n💡 **Tip**: Use the **CMake Presets** included in this project for an easy, consistent setup!\n\n---\n\n## **🎛️ Getting Started**\n\nWhen opening this template for the first time:\n\n1. **Select a CMake Preset** in your IDE.\n2. The available presets are defined in [`CMakePresets.json`](./CMakePresets.json).\n3. This ensures a **consistent build setup** across different environments.\n4. Set your plugin name and information in the following files:\n   - `plugin/CMakeLists.txt`\n   - `plugin/src/plugin_processor.cpp`\n   - `ui/package.json`\n   - `ui/public/metadata.json`\n\n---\n\n## **📦 Embedded Cross-Compilation** _(ElkOS)_\n\nBuild the plugin for ElkOS using the prebuilt docker image specified in `docker-compose.yml`.\n\n```sh\ndocker-compose up\n```\n\nOnce the compilation completes, a compressed headless VST3 plugin for ElkOS running on ARM64 is accessible in the workspace `bin` directory.\n\n_Note! You may need to add exectuable permission to the build script first time._\n\n```\nchmod +x ./script/build-arm64-headless.sh\n```\n\n---\n\n## 📦 Native WebView UI Build _(Linux/MacOS/Windows)_\n\nFrom the root of the project, run:\n\n```sh\ncd ui\nnpm install\nnpm run build\ncd ..\n```\n\nThis compiles the frontend and places the output in the correct directory for the plugin to include.\n\n💡 This step is required for all platforms (Linux, macOS, Windows).\n\nAlternatively, you can automate this step inside a wrapper script or CI pipeline.\n\n---\n\n## 🔨 Native Build Instructions _(Linux/MacOS/Windows)_\n\nIf you want to build the plugin for desktop, use:\n\n```sh\n# Option 1 - Debug Mode\ncmake -B build -S . -DHEADLESS=OFF -DCMAKE_BUILD_TYPE=Debug\n\n# Option 2 - Release Mode\ncmake -B build -S . -DHEADLESS=OFF -DCMAKE_BUILD_TYPE=Release\n\n# Note! For linux, you also need to specify the toolchain\n-DCMAKE_TOOLCHAIN_FILE=cmake/linux-toolchain.cmake \\\n\n# Build Plugin\ncmake --build build\n```\n\n_Note! Make sure you have selected a CMake Preset before first build, otherwise you may need to delete the build directory, choose preset and build again!_\n\n### Run Desktop Standalone Plugin\n\nAfter building, run:\n\n```sh\n# Debug\ncd build/plugin/plugin_artefacts/Debug/Standalone\n\n# Release\ncd build/plugin/plugin_artefacts/Release/Standalone\n```\n\n```sh\n# MacOS\nopen ./plugin.app\n\n# Linux\nchmod +x plugin\n./plugin\n\n# Windows (PowerShell)\n./plugin.exe\n```\n\n### Run Desktop VST3 Plugin\n\nTo load and run the **VST3 version** of the plugin, you will need a **plugin host** such as a DAW (**Logic Pro, Reaper, Studio One, Cubase, Ableton Live, etc.**) or a standalone **VST3 plugin host** like **JUCE Audio Plugin Host** (can be built from the [JUCE library](https://juce.com)).\n\nAfter building, the compiled **VST3 plugin** will be located at:\n\n```sh\n# Debug\nbuild/plugin/plugin_artefacts/Debug/VST3/plugin.vst3\n\n# Release\nbuild/plugin/plugin_artefacts/Release/VST3/plugin.vst3\n```\n\n### Native Install the Plugin\n\nCopy the **VST3 plugin** to the appropriate directory for your OS so that your DAW can detect it:\n\n- **MacOS:** `~/Library/Audio/Plug-Ins/VST3/`\n- **Windows:** `C:\\Program Files\\Common Files\\VST3\\`\n- **Linux:** `~/.vst3/`\n\nAfter copying, **rescan your plugins** in your DAW's settings and load the plugin.\n\n---\n\n## 🚀 CI/CD (Release) Instructions\n\n### Release VST3 for Embedded System\n\n_This is the headless VST3 plugin (DSP processor) that runs on the target embedded device._\n\n```sh\n# Replace v0.0.0 with actual version!\ngit tag v0.0.0\ngit push origin v0.0.0\n```\n\n_This triggers an NPM publish workflow, which builds the UI package and publishes it to the public `Tonalflex` NPM registry._\n\n### Deploy WebUI to NPM\n\n_This is the frontend bundle used in the embedded system’s remote UI._\n\n```sh\n# Replace ui-v0.0.0 with actual version!\ngit tag ui-v0.0.0\ngit push origin ui-v0.0.0\n```\n\n_This triggers a build workflow, which builds the plugin inside a Docker container and uploads the ZIP file to a GitHub release._\n\n---\n\n## 🔓 Licensing \u0026 JUCE Attribution\n\nThis project is licensed under the **GNU AGPLv3**.\nIt uses the **JUCE framework**, which is dual-licensed under AGPLv3 and the JUCE Proprietary License.\n\nFor more information, see [JUCE Licensing](https://juce.com/juce-6-licence).\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftonalflex%2Ftonalflex-template-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftonalflex%2Ftonalflex-template-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftonalflex%2Ftonalflex-template-plugin/lists"}