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. diff --git a/README.md b/README.md index 3589cea..cacbc94 100644 --- a/README.md +++ b/README.md @@ -12,16 +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 -Recommended installer packages: +Free Beat for DaVinci Resolve. Open source for DaVinci Resolve. -- macOS: `OpenBeat-macos-.pkg` -- Windows: `OpenBeat-windows--installer.exe` - -These 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). +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 @@ -47,6 +42,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) 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). 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 diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..bd0e090 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,61 @@ +# 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 + +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. Download the installer for your operating system: + - macOS: `OpenBeat-macos-.pkg` + - Windows: `OpenBeat-windows--installer.exe` +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). + +## 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. diff --git a/docs/release-checklist.md b/docs/release-checklist.md new file mode 100644 index 0000000..ab7cbf9 --- /dev/null +++ b/docs/release-checklist.md @@ -0,0 +1,80 @@ +# 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 Source + +- 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 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 the free checkout/download path works. + +## Site And Announcement + +- 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 Ko-fi download link and source repository are live.