Fix beat timing and Resolve action reliability

.github/workflows/build-installers.yml

@@ -55,6 +55,9 @@ jobs:
       - name: Compile Python sources
         run: python -m compileall openbeat scripts tests
 
+      - name: Install Lua for Resolve behavior tests
+        run: sudo apt-get update && sudo apt-get install -y lua5.1
+
       - name: Run tests
         run: python -m unittest discover -s tests -v
 
@@ -68,10 +71,12 @@ jobs:
         include:
           - platform: macos
             runner: macos-latest
+            runtime_path: dist/openbeat
             artifact_path: dist/installers/*.pkg
             artifact_name: OpenBeat-macos-installer
           - platform: windows
             runner: windows-latest
+            runtime_path: dist/openbeat/openbeat.exe
             artifact_path: dist/installers/*installer.exe
             artifact_name: OpenBeat-windows-installer
 
@@ -94,6 +99,9 @@ jobs:
       - name: Build installer bundle
         run: python scripts/build_installers.py --platform ${{ matrix.platform }}
 
+      - name: Verify bundled runtime with real audio
+        run: python scripts/smoke_test_runtime.py ${{ matrix.runtime_path }}
+
       - name: Upload installer artifact
         if: github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call'
         uses: actions/upload-artifact@v6

.gitignore

@@ -19,6 +19,7 @@ __pycache__/
 *.egg-info/
 build/
 dist/
+*.spec
 
 # Generated OpenBeat outputs
 *.openbeat-clicks.wav

README.md

@@ -20,9 +20,9 @@ Download the macOS or Windows installer from the [latest GitHub Release](https:/
 
 ## Use It
 
-1. Select the target timeline audio clip.
+1. Place the playhead over the target timeline audio clip.
 2. Run an OpenBeat action from `Workspace > Scripts > OpenBeat`.
-3. If Resolve does not expose the selection cleanly, place the playhead over the clip and run the action again.
+3. If audio clips overlap, OpenBeat uses the usable source on the lowest-numbered audio track.
 
 Available actions:
 

docs/development.md

@@ -36,6 +36,12 @@ python scripts/build_installers.py --platform windows
 
 Generated installer archives are written to `dist/installers/`.
 
+## Run Tests
+
+Install Lua 5.1 or a later Lua release, then run `python -m unittest discover -s tests -v`. The suite tests timecode conversion, source selection, marker replacement and rollback, and subtitle timing without an open Resolve project. It also sends generated audio through the real CLI and checks both click-track modes.
+
+After building an installer, test the bundled runtime with `python scripts/smoke_test_runtime.py dist/openbeat` on macOS or `python scripts/smoke_test_runtime.py dist/openbeat/openbeat.exe` on Windows. CI runs these checks on both platform builds. They verify analysis and output generation; placement inside Resolve still needs a manual check.
+
 Installer builds are platform-specific. Build the macOS `.pkg` on macOS and the Windows `.exe` on Windows; PyInstaller does not cross-compile the bundled runtime.
 
 ## Release Workflow
@@ -59,7 +65,7 @@ The release workflow expects the repository version to already be updated in bot
 - The non-Studio version of DaVinci Resolve does not reliably allow the kind of `UIManager` popup workflow used by older tools, so OpenBeat ships as no-UI menu scripts
 - Audio click-track placement onto the timeline is not reliable enough to claim as automatic
 - Subtitle-track population is still not reliable enough to claim as automatic
-- Source resolution still depends on what Resolve exposes for the selected timeline item or the playhead clip
+- Source resolution uses the audio clip under the playhead, choosing the lowest-numbered usable audio track when clips overlap
 
 ## Verified Behavior
 

docs/guide.md

@@ -4,9 +4,9 @@
 
 OpenBeat works from the active timeline.
 
-1. Select the target timeline audio clip
+1. Place the playhead over the target timeline audio clip
 2. Run the action from `Workspace > Scripts > OpenBeat`
-3. If that does not work, place the playhead over the target clip and run it again
+3. If audio clips overlap, OpenBeat uses the usable source on the lowest-numbered audio track
 
 ## Choose A Mode
 
@@ -21,9 +21,11 @@ OpenBeat works from the active timeline.
 
 Adds markers to the timeline ruler for beats that land inside matching source segments in the active timeline.
 
-- Re-running replaces only the previous OpenBeat timeline markers
+- Re-running replaces only the previous OpenBeat timeline markers for that source
 - User-created timeline markers are left alone
 - If the same source file appears multiple times, markers can appear across every matching use
+- Occupied frames belonging to other sources or user markers are skipped and reported
+- Older OpenBeat timeline markers without source information are preserved; remove them manually if you want to replace them
 
 ### `Create Clip Markers`
 
@@ -32,6 +34,7 @@ Adds markers to both the Media Pool source clip and matching timeline clip insta
 - Matching instances are updated from source timing, not only from visible clip position
 - If the same source appears multiple times, multiple instances can be updated
 - User-created clip markers are left alone
+- A failed marker update attempts to restore the previous markers and reports any restoration failure
 
 ### `Create Beat Click Audio`
 
@@ -46,6 +49,8 @@ Renders a click-track WAV next to the source file and imports it into the Media
 Writes an `.srt` file based on beat-to-beat ranges.
 
 - Subtitle files are written relative to the active timeline start
+- Cues stay within each matching clip, including trimmed beat ranges, and do not span gaps between clips
+- Beat numbers refer to the analyzed source and restart when that source is repeated
 - OpenBeat can try to import the file and create a subtitle track
 - Treat the generated `.srt` as the reliable result
 
@@ -64,8 +69,8 @@ If a file already exists, OpenBeat currently overwrites it.
 
 ### OpenBeat picked the wrong clip
 
-1. Select the target timeline item
-2. If that does not work, place the playhead over the target audio clip
+1. Place the playhead inside the target audio clip
+2. Check whether a source on a lower-numbered audio track also overlaps the playhead
 3. Run the action again
 
 ### The click track did not appear on the timeline
@@ -93,12 +98,9 @@ Windows:
 
 ### Source Selection
 
-OpenBeat checks the timeline in this order:
+OpenBeat uses the audio clip under the playhead. If multiple audio tracks overlap, it uses the usable source on the lowest-numbered audio track. Empty tracks and clips without source file paths are skipped. A clip's end belongs to the next clip at a cut.
 
-1. The selected timeline item, if Resolve exposes it and it maps back to a usable audio source
-2. The audio clip under the playhead
-
-It does not use the selected Media Pool item as a fallback.
+Resolve's API does not expose selected timeline audio clips. Video and Media Pool selection do not choose OpenBeat's source.
 
 ### Shared Behavior
 

docs/install.md

@@ -51,10 +51,10 @@ 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.
+2. Place the playhead over a timeline 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.
+If multiple audio clips overlap the playhead, OpenBeat uses the usable source on the lowest-numbered audio track.
 
 ## Current Compatibility