From afa03fcb15a59d651be38a254fcd12878aa7fbe8 Mon Sep 17 00:00:00 2001 From: eimexdev <130890337+eimexdev@users.noreply.github.com> Date: Thu, 21 May 2026 18:45:08 -0700 Subject: [PATCH 01/13] Add end-user install guide --- docs/install.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 docs/install.md diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..fbc4d8a --- /dev/null +++ b/docs/install.md @@ -0,0 +1,57 @@ +# Install OpenBeat + +Use the installer package for normal editing work. The installers include the OpenBeat runtime, so you do not need to install Python or project dependencies separately. + +## Download + +1. Open the latest GitHub release: https://github.com/eimexdev/OpenBeat/releases/latest +2. Download the installer for your operating system: + - macOS: `OpenBeat-macos-.pkg` + - Windows: `OpenBeat-windows--installer.exe` +3. Close DaVinci Resolve before running the installer. + +## macOS + +1. Run the `.pkg` installer. +2. If macOS Gatekeeper blocks the package, open System Settings > Privacy & Security and allow the package, then run it again. +3. Restart DaVinci Resolve. +4. Confirm the scripts appear under `Workspace > Scripts > OpenBeat`. + +The installer copies OpenBeat into: + +- Scripts: `~/Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Scripts/Utility/OpenBeat` +- Modules: `~/Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Modules/OpenBeat` + +## Windows + +1. Run `OpenBeat-windows--installer.exe`. +2. Accept the default Resolve Fusion support folder unless you have moved Resolve's scripting support files. +3. Restart DaVinci Resolve. +4. Confirm the scripts appear under `Workspace > Scripts > OpenBeat`. + +The installer copies OpenBeat into: + +- Scripts: `%APPDATA%\Blackmagic Design\DaVinci Resolve\Support\Fusion\Scripts\Utility\OpenBeat` +- Modules: `%APPDATA%\Blackmagic Design\DaVinci Resolve\Support\Fusion\Modules\OpenBeat` + +## Update + +Install the newer package over the old one, then restart Resolve. The installer replaces the OpenBeat script and module folders, but it does not remove your project markers, generated click tracks, generated subtitle files, or analysis cache. + +## Uninstall + +Delete the OpenBeat script and module folders listed above, then restart Resolve. + +## Verify The Install + +1. Open a Resolve project and timeline. +2. Select a timeline audio clip, or place the playhead over an audio clip. +3. Run `Workspace > Scripts > OpenBeat > Create Timeline Markers (Quantized)`. + +If the script runs but cannot identify the clip, place the playhead over the target audio clip and run it again. + +## Current Compatibility + +OpenBeat is designed for the non-Studio version of DaVinci Resolve by avoiding custom `UIManager` windows. Local testing has confirmed the core workflow in DaVinci Resolve 20.3.2. Studio builds may work too, but the release target is the free/non-Studio workflow. + +OpenBeat is an independent community project. It is not an official Resolve component and is not distributed or endorsed by Blackmagic Design. From aa73e9094fff9d3e7b501320bc007381d463f3d9 Mon Sep 17 00:00:00 2001 From: eimexdev <130890337+eimexdev@users.noreply.github.com> Date: Thu, 21 May 2026 18:45:21 -0700 Subject: [PATCH 02/13] Add release checklist --- docs/release-checklist.md | 73 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/release-checklist.md diff --git a/docs/release-checklist.md b/docs/release-checklist.md new file mode 100644 index 0000000..11ebf71 --- /dev/null +++ b/docs/release-checklist.md @@ -0,0 +1,73 @@ +# Release Checklist + +Use this checklist before publishing an OpenBeat release. + +## Version + +- Choose the next version number. +- Update `version` in `pyproject.toml`. +- Update `__version__` in `openbeat/__init__.py`. +- Confirm the release tag will be `v`. + +## Local Checks + +Run from the repository root: + +```bash +python -m compileall openbeat scripts tests +python -m unittest discover -s tests -v +``` + +If `lua` is available locally, also run: + +```bash +lua -e 'assert(loadfile("resolve/Fusion/Modules/OpenBeat/OpenBeatCommon.lua"))' +``` + +## Installer Build + +- Run the `Build Installers` workflow on the target commit. +- Confirm the macOS artifact is named `OpenBeat-macos-.pkg`. +- Confirm the Windows artifact is named `OpenBeat-windows--installer.exe`. +- Download both artifacts and verify they are not stale local files. + +## Smoke Test + +On macOS: + +- Run the `.pkg` installer. +- Restart Resolve. +- Confirm `Workspace > Scripts > OpenBeat` appears. +- Run `Create Timeline Markers (Quantized)` on a known test clip. + +On Windows: + +- Run the installer executable. +- Restart Resolve. +- Confirm `Workspace > Scripts > OpenBeat` appears. +- Run `Create Timeline Markers (Quantized)` on a known test clip. + +For both platforms: + +- Verify timeline marker creation. +- Verify clip marker creation. +- Verify click-track WAV generation. +- Verify subtitle SRT generation. +- Treat automatic click-track and subtitle timeline placement as best-effort only. + +## Publish + +- Trigger the `Release` workflow with tag `v`. +- Keep `draft` enabled for the first run. +- Check the generated release notes. +- Check both installer assets are attached to the draft release. +- Replace or supplement generated notes with concise install and known-limit notes. +- Publish the release. + +## Site And Announcement + +- Update the landing page download link to the published GitHub release or exact release assets. +- Confirm the GitHub repository is public before launch. +- Confirm the chosen license is present before using open-source wording publicly. +- Publish the landing page. +- Post the launch announcement after the download link and release assets are live. From 207d6a652d00951d50c7c776b0817446973d4855 Mon Sep 17 00:00:00 2001 From: eimexdev <130890337+eimexdev@users.noreply.github.com> Date: Thu, 21 May 2026 18:45:27 -0700 Subject: [PATCH 03/13] Add changelog seed --- CHANGELOG.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..140eb61 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,22 @@ +# Changelog + +All notable OpenBeat changes should be summarized here for users. GitHub Releases can still use generated notes, but this file should keep the plain-language history easy to scan. + +## 0.0.2 - 2026-04-19 + +- Bundled the OpenBeat runtime into macOS and Windows installer packages. +- Added release workflow support for attaching installer assets to GitHub Releases. +- Improved cross-platform Resolve script handling for bundled CLI execution. +- Kept OpenBeat as no-UI Resolve menu scripts for compatibility with the non-Studio Resolve workflow. + +Known limits: + +- Timeline markers and clip markers are the most reliable actions today. +- Click-track WAV files and subtitle SRT files are reliable generated outputs. +- Automatic click-track and subtitle placement on the timeline remains best-effort because of Resolve scripting limitations. + +## 0.0.1 - 2026-04-19 + +- Initial pre-alpha release. +- Added beat analysis, timeline marker, clip marker, click-track, and subtitle export workflows. +- Added Quantized and Raw Beats modes. From 4e94afc06d1a05360ea5073dceb381f512570e05 Mon Sep 17 00:00:00 2001 From: eimexdev <130890337+eimexdev@users.noreply.github.com> Date: Thu, 21 May 2026 18:45:39 -0700 Subject: [PATCH 04/13] Clarify release install docs --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3589cea..84f478d 100644 --- a/README.md +++ b/README.md @@ -14,14 +14,14 @@ OpenBeat is an independent community project. It is not an official Resolve comp ## Install -Recommended installer packages: +Download the latest installer from [GitHub Releases](https://github.com/eimexdev/OpenBeat/releases/latest): - macOS: `OpenBeat-macos-.pkg` - Windows: `OpenBeat-windows--installer.exe` -These installers bundle the OpenBeat runtime, so no separate Python setup is required. +Close DaVinci Resolve before installing, then restart Resolve after the installer finishes. The installers bundle the OpenBeat runtime, so no separate Python setup is required. -If you want to run from source or build installers locally, use [docs/development.md](docs/development.md). +For step-by-step install, update, and uninstall instructions, use [docs/install.md](docs/install.md). If you want to run from source or build installers locally, use [docs/development.md](docs/development.md). ## Use It @@ -47,6 +47,8 @@ Each action is available in both `Quantized` and `Raw Beats` variants. ## Docs +- [Install guide](docs/install.md) - [User guide](docs/guide.md) - [Development notes](docs/development.md) +- [Release checklist](docs/release-checklist.md) - [Docs index](docs/README.md) From 63609939b3f86da757722642d490da757d678d28 Mon Sep 17 00:00:00 2001 From: eimexdev <130890337+eimexdev@users.noreply.github.com> Date: Thu, 21 May 2026 18:45:44 -0700 Subject: [PATCH 05/13] Expand docs index for release docs --- docs/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index b1818d3..a254035 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,7 +2,9 @@ The docs are intentionally small: +- [Install guide](install.md): installer download, platform setup, update, uninstall, and compatibility notes - [User guide](guide.md): usage, modes, actions, outputs, troubleshooting, and technical details - [Development notes](development.md): source setup, installer builds, and engineering context +- [Release checklist](release-checklist.md): versioning, verification, installer smoke tests, release publishing, and site updates -For the shortest overview, start with the repo [README](../README.md). +For the shortest overview, start with the repo [README](../README.md). For user-visible release history, see the [changelog](../CHANGELOG.md). From 2f561ce13b47bc6283496e508e1f6557b954abd2 Mon Sep 17 00:00:00 2001 From: eimexdev <130890337+eimexdev@users.noreply.github.com> Date: Thu, 21 May 2026 18:46:00 -0700 Subject: [PATCH 06/13] Add Windows troubleshooting paths --- docs/guide.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/guide.md b/docs/guide.md index aba8520..12b77b9 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -78,9 +78,16 @@ That is also a current Resolve scripting limitation. Use the generated `.srt` fi ### Where to look for logs +macOS: + - Runtime log: `~/Library/Application Support/Blackmagic Design/DaVinci Resolve/logs/OpenBeat.log` - Analysis cache: `~/Library/Caches/OpenBeat` +Windows: + +- Runtime log: `%APPDATA%\Blackmagic Design\DaVinci Resolve\Support\logs\OpenBeat.log` +- Analysis cache: `%USERPROFILE%\.cache\openbeat` + ## Technical Details ### Source Selection From c5d4468280bc7fb69aeb9b06316b3805f0a9d70c Mon Sep 17 00:00:00 2001 From: eimexdev <130890337+eimexdev@users.noreply.github.com> Date: Thu, 21 May 2026 18:55:22 -0700 Subject: [PATCH 07/13] Document Ko-fi build distribution model --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 84f478d..f3cf399 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,9 @@ OpenBeat is an independent community project. It is not an official Resolve comp ## Install -Download the latest installer from [GitHub Releases](https://github.com/eimexdev/OpenBeat/releases/latest): +Installer builds are distributed through Ko-fi as a pay-what-you-want digital download. You can enter `$0` to download for free, or add support if OpenBeat saves you time. + +Download the installer for your operating system: - macOS: `OpenBeat-macos-.pkg` - Windows: `OpenBeat-windows--installer.exe` From c21b790b9ad5e8c084af171ff25d1786430da54f Mon Sep 17 00:00:00 2001 From: eimexdev <130890337+eimexdev@users.noreply.github.com> Date: Thu, 21 May 2026 18:55:34 -0700 Subject: [PATCH 08/13] Point install guide to Ko-fi builds --- docs/install.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/install.md b/docs/install.md index fbc4d8a..38d7b7c 100644 --- a/docs/install.md +++ b/docs/install.md @@ -4,11 +4,16 @@ Use the installer package for normal editing work. The installers include the Op ## Download -1. Open the latest GitHub release: https://github.com/eimexdev/OpenBeat/releases/latest -2. Download the installer for your operating system: +Installer builds are distributed through Ko-fi as a pay-what-you-want digital download. You can enter `$0` to download for free, or add support if OpenBeat saves you time. + +1. Open the OpenBeat Ko-fi shop listing. +2. Choose the amount you want to pay. `$0` is fine. +3. Download the installer for your operating system: - macOS: `OpenBeat-macos-.pkg` - Windows: `OpenBeat-windows--installer.exe` -3. Close DaVinci Resolve before running the installer. +4. Close DaVinci Resolve before running the installer. + +If you prefer source builds, the public repository includes development setup and local installer build notes in [development.md](development.md). ## macOS From 83bfc06d186a4e8ea23582c6611279b72b9d87b9 Mon Sep 17 00:00:00 2001 From: eimexdev <130890337+eimexdev@users.noreply.github.com> Date: Thu, 21 May 2026 18:55:49 -0700 Subject: [PATCH 09/13] Add Ko-fi publishing steps to release checklist --- docs/release-checklist.md | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/docs/release-checklist.md b/docs/release-checklist.md index 11ebf71..fb965a2 100644 --- a/docs/release-checklist.md +++ b/docs/release-checklist.md @@ -55,19 +55,26 @@ For both platforms: - Verify subtitle SRT generation. - Treat automatic click-track and subtitle timeline placement as best-effort only. -## Publish +## Publish Source -- Trigger the `Release` workflow with tag `v`. -- Keep `draft` enabled for the first run. -- Check the generated release notes. -- Check both installer assets are attached to the draft release. -- Replace or supplement generated notes with concise install and known-limit notes. -- Publish the release. +- Confirm the chosen license is present before using open-source wording publicly. +- Publish a GitHub source release or tag for the version. +- Do not attach installer builds to public GitHub releases if builds are meant to be distributed through Ko-fi. +- Confirm the repository is public before launch. + +## Publish Ko-fi Build + +- Create or update the Ko-fi Shop digital product for OpenBeat. +- Upload the macOS and Windows installer assets. +- Set the minimum price to `$0` if Ko-fi allows it for the account/currency. +- Enable Pay What You Want so supporters can pay more than the minimum. +- Add preview images, summary, install notes, and known limitations. +- Add a post-purchase message that thanks supporters and tells them to restart Resolve after installing. +- Test the listing in an incognito browser and confirm `$0` checkout/download works. ## Site And Announcement -- Update the landing page download link to the published GitHub release or exact release assets. -- Confirm the GitHub repository is public before launch. -- Confirm the chosen license is present before using open-source wording publicly. +- Update the landing page download link to the Ko-fi product listing. +- Confirm the GitHub source link points to the public repository. - Publish the landing page. -- Post the launch announcement after the download link and release assets are live. +- Post the launch announcement after the Ko-fi download link and source repository are live. From b30eb509549f9f8e1fe571cbfc47395b812375b3 Mon Sep 17 00:00:00 2001 From: eimexdev <130890337+eimexdev@users.noreply.github.com> Date: Thu, 21 May 2026 19:05:24 -0700 Subject: [PATCH 10/13] Simplify Ko-fi install copy --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f3cf399..397f13e 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ OpenBeat is an independent community project. It is not an official Resolve comp ## Install -Installer builds are distributed through Ko-fi as a pay-what-you-want digital download. You can enter `$0` to download for free, or add support if OpenBeat saves you time. +Installer builds are free downloads through Ko-fi. Ko-fi also gives people a way to support the project if OpenBeat saves them time. Download the installer for your operating system: From c00ea8fe48f9e59ce22c174864cfb3919268f658 Mon Sep 17 00:00:00 2001 From: eimexdev <130890337+eimexdev@users.noreply.github.com> Date: Thu, 21 May 2026 19:05:50 -0700 Subject: [PATCH 11/13] Simplify Ko-fi install guide copy --- docs/install.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/install.md b/docs/install.md index 38d7b7c..bd0e090 100644 --- a/docs/install.md +++ b/docs/install.md @@ -4,14 +4,13 @@ Use the installer package for normal editing work. The installers include the Op ## Download -Installer builds are distributed through Ko-fi as a pay-what-you-want digital download. You can enter `$0` to download for free, or add support if OpenBeat saves you time. +Installer builds are free downloads through Ko-fi. Ko-fi also gives people a way to support the project if OpenBeat saves them time. 1. Open the OpenBeat Ko-fi shop listing. -2. Choose the amount you want to pay. `$0` is fine. -3. Download the installer for your operating system: +2. Download the installer for your operating system: - macOS: `OpenBeat-macos-.pkg` - Windows: `OpenBeat-windows--installer.exe` -4. Close DaVinci Resolve before running the installer. +3. Close DaVinci Resolve before running the installer. If you prefer source builds, the public repository includes development setup and local installer build notes in [development.md](development.md). From 8e3acadab142e59bd87506aada4d80696eb25321 Mon Sep 17 00:00:00 2001 From: eimexdev <130890337+eimexdev@users.noreply.github.com> Date: Thu, 21 May 2026 19:06:10 -0700 Subject: [PATCH 12/13] Simplify Ko-fi release checklist wording --- docs/release-checklist.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/release-checklist.md b/docs/release-checklist.md index fb965a2..ab7cbf9 100644 --- a/docs/release-checklist.md +++ b/docs/release-checklist.md @@ -66,11 +66,11 @@ For both platforms: - Create or update the Ko-fi Shop digital product for OpenBeat. - Upload the macOS and Windows installer assets. -- Set the minimum price to `$0` if Ko-fi allows it for the account/currency. -- Enable Pay What You Want so supporters can pay more than the minimum. +- Set the product price to free. +- Keep support optional in the listing copy. - Add preview images, summary, install notes, and known limitations. - Add a post-purchase message that thanks supporters and tells them to restart Resolve after installing. -- Test the listing in an incognito browser and confirm `$0` checkout/download works. +- Test the listing in an incognito browser and confirm the free checkout/download path works. ## Site And Announcement From 8574d325678966181b62f24eb9d8fa7e0f9ad482 Mon Sep 17 00:00:00 2001 From: eimexdev Date: Thu, 21 May 2026 19:39:25 -0700 Subject: [PATCH 13/13] Simplify README launch positioning --- README.md | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 397f13e..cacbc94 100644 --- a/README.md +++ b/README.md @@ -12,18 +12,11 @@ OpenBeat is an independent community project. It is not an official Resolve comp - Exports beat-based subtitle files - Supports both `Quantized` and `Raw Beats` analysis modes -## Install +## Get OpenBeat -Installer builds are free downloads through Ko-fi. Ko-fi also gives people a way to support the project if OpenBeat saves them time. +Free Beat for DaVinci Resolve. Open source for DaVinci Resolve. -Download the installer for your operating system: - -- macOS: `OpenBeat-macos-.pkg` -- Windows: `OpenBeat-windows--installer.exe` - -Close DaVinci Resolve before installing, then restart Resolve after the installer finishes. The installers bundle the OpenBeat runtime, so no separate Python setup is required. - -For step-by-step install, update, and uninstall instructions, use [docs/install.md](docs/install.md). If you want to run from source or build installers locally, use [docs/development.md](docs/development.md). +Download OpenBeat from Ko-fi, or run it from source. For step-by-step setup, update, and uninstall instructions, use [docs/install.md](docs/install.md). If you want source setup notes, use [docs/development.md](docs/development.md). ## Use It