BeatMarker

UXP Plugin for Adobe Premiere Pro that automatically detects beats in an audio track and creates colored markers on the source clip — giving editors a precise visual rhythm reference for music-synced cuts.

---

✨ Features

• 🎵 Detects BPM and beats in WAV and MP3 files with one click
• 🎨 Creates colored markers on the source clip, visually distinguishing each beat position:
  • 🔴 Beat 1 → Red — Downbeat (strongest beat of the bar)
  • 🔵 Beats 2 & 4 → Blue — Backbeats (where the snare typically hits)
  • 🟡 Beat 3 → Yellow — Secondary downbeat (mid-bar emphasis)

  Marker colors are fixed and cannot be changed — they map directly to beat position.

• 🎯 BPM Confidence Indicator — after analysis, shows how reliable the beat detection was:
  • 🟢 High (>85%) — rock solid grid, markers ready
  • 🟡 Medium (60–85%) — some tempo variation, worth a check
  • 🔴 Low (<60%) — tempo is unpredictable, markers may drift
• 🎛️ Beat selection — tap the 1 2 3 4 buttons to choose which beats to mark (all on by default)
• ◀ ▶ Phase adjustment — shifts which beat is the "1" without re-analyzing
• 🗑️ Remove markers with one click (any clip selected in the Project panel)
• 🌐 Bilingual (ENG / PT-BR) — UI language automatically detected from system locale

---

🎬 Who it's for

Video editors who cut to the beat — music videos, trailers, reels, sync edits. No music theory required. Works on Windows and macOS from the same installer.

---

🚀 How to use

Step	Action
1	Open the BeatMarker panel (Window → Extensions → BeatMarker) and select a .WAV clip in the Project panel
2	Click ANALYZE SELECTED CLIP and wait for the BPM to be detected
3	Check the confidence indicator — if it's red or yellow, markers may need manual review
4	(Optional) Tap the 1 2 3 4 beat buttons to choose which positions to mark
5	Click CREATE MARKERS ON CLIP — colored markers appear on the clip
6	If beat "1" is in the wrong place, use ◀ ▶ to shift the phase
7	To start over, click REMOVE MARKERS

⌨️ Navigating markers in Premiere Pro

Once markers are placed, use these standard Premiere shortcuts to jump between them:

Action	Windows	macOS
Next marker	Shift + M	Shift + M
Previous marker	Ctrl + Shift + M	Cmd + Shift + M

These shortcuts work both in the Timeline and inside a clip in the Source Monitor.

📸 View individual steps

Step 1 — Select clip & open panel

Step 2 — Analyze

Step 3 — Create markers

Step 4 — Adjust phase if needed

Step 5 — Remove markers

---

🛠️ Dev install

Prerequisites

• Adobe Premiere Pro 25.0+
• UXP Developer Tool

Steps

git clone https://github.com/samaBR85/BeatMarker-PremierePlugin.git

1. Open the UXP Developer Tool
2. Click Add Plugin
3. Navigate to the plugin/ folder and select manifest.json
4. Click Load in Premiere Pro

The analysis-bundle.js is pre-compiled inside plugin/ — no build step needed to run the plugin.

---

🔨 Rebuild the bundle

Only needed if you modify the audio analysis code in experiments/exp-b-uxp-viability/src/.

cd experiments/exp-b-uxp-viability
npm install
npm run build

# Copy to plugin:
# Windows:
copy analysis-bundle.js ..\..\plugin\analysis-bundle.js
# macOS/Linux:
cp analysis-bundle.js ../../plugin/analysis-bundle.js

---

📁 Project structure

BeatMarker-PremierePlugin/
│
├── plugin/                        ← Ready-to-install plugin
│   ├── manifest.json              ← UXP manifest v5
│   ├── index.html                 ← Panel UI
│   ├── main.js                    ← UXP logic + Premiere API + i18n
│   └── analysis-bundle.js        ← Pre-compiled bundle (WAV decoder + music-tempo)
│
├── experiments/
│   ├── exp-a-beat-detection/      ← Node.js proof of concept (mpg123 + music-tempo)
│   ├── exp-b-uxp-viability/       ← Bundle source (active)
│   │   ├── src/
│   │   │   ├── analysis.js        ← Pipeline: WAV + MP3 decoder + resample + beat detection
│   │   │   └── stubs/             ← Polyfills for modules missing in UXP
│   │   ├── build.js               ← esbuild config
│   │   └── package.json
│   └── exp-c-uxp-mp3viability/    ← mpg123-decoder (WASM) — crashes Premiere; abandoned
│
├── screenshots/                   ← Usage screenshots
├── assets/                        ← Icon source files
├── SPEC.md                        ← Full technical spec
├── INSTALL.md                     ← End-user installation guide
└── README.md

---

⚙️ Tech stack

Component	Technology
Runtime	UXP (Unified Extensibility Platform) — manifest v5
UI	HTML + CSS + vanilla JavaScript
WAV decoding	Pure JS via DataView — PCM 8/16/24-bit + float32, any sample rate
Beat detection	music-tempo
Bundler	esbuild
i18n	Auto-detected via navigator.language

Why no WASM

Technology	Problem
WASM with pthreads	Crashes Premiere Pro immediately
Web Workers	typeof Worker === 'undefined' in UXP
AudioContext	Does not exist in UXP
fs.readFileSync	"Route not found" in UXP

---

🌐 Languages

The UI language is detected automatically from the system locale — no configuration needed.

Language	Locale
🇧🇷 Portuguese (PT-BR)	pt, pt-BR
🇺🇸 English	all other locales

---

⚠️ Known limitations

• Only 4/4 time signature is supported
• No support for variable tempo (rubato, accelerando, ritardando)
• Marker colors are fixed — 🔴 downbeat, 🔵 backbeats, 🟡 secondary downbeat. Premiere Pro does not expose a color picker API for markers created by plugins.

---

📄 License

This project is licensed under the GNU GPL v3 — any derivative work must also be open source.

Third-party licenses

• music-tempo — MIT

---

👤 Credits

Created by samaBR buy me a coffe on