UI Reference & Control Documentation

Complete guide to every button, checkbox, dropdown, and setting in BeatMarker Pro

📂 SOURCE TAB

Load audio files, select analysis tier, and configure preferences.

Tab: Source

📁 Choose audio file...

Button
Primary Action
Opens a file browser dialog to select an audio file from your computer. Supports MP3, WAV, AAC, AIFF, FLAC.
When to use: Click this to load a song you want to analyze. You can also drag-drop audio files directly onto the waveform panel without using this button.
Tip: Drag-drop is faster - just drag your audio file from Finder/Explorer onto the waveform area.

⚙️ Analysis Tier Dropdown

Dropdown Menu
Configuration

A note on naming. Your licence (Free / Pro / Studio) is what you've paid for. Inside the panel, you pick an analysis mode per track from this dropdown: Local, Server (EM-Beat Engine), Premium, or Super Premium. Pro and Studio licences unlock all four modes within their monthly caps; the Free licence only unlocks Local and a capped Server allowance. The "Premium / Super Premium" names here describe the analysis engine, not a separate subscription.

Select the analysis algorithm to use: Local, Server, Premium, or Super Premium. Each tier offers different accuracy, speed, and cost.

When to use:
  • Local: Quick previews, no internet, free. ~85% accurate.
  • Server: Production-quality beats, free, ~95% accurate. Recommended default.
  • Premium: Server features + Gemini Flash-Lite enrichment. ~$0.004/track. Adds musical key, genre, mood, tempo feel, vocals language/gender, production notes.
  • Super Premium: Premium + deeper Gemini Flash analysis. ~$0.014/track. Adds chord progression, per-section descriptions, editorial cutting notes.

⚡ Preferences Button

Button
Secondary Action
Opens a preferences modal with advanced settings for stems, metronome, and analysis behavior.
When to use: Configure optional features like stem format (AAC/Opus/WAV), metronome style, Tempo Lock, and whether to auto-save sidecars.

📊 BPM Readout (Toolbar)

Display
Information
Shows the detected tempo (beats per minute) and musical feel (e.g., "half-time", "straight") from the analysis. Only appears after analysis completes.
When to use: Verify the detected BPM matches the song. If it's half the expected value, enable Tempo Lock in preferences. Use the BPM to guide your editing rhythm.

🔍 ANALYZE TAB

Run analysis, monitor progress, and review detected beats and sections.

Tab: Analyze

💡 Cache Hint (above Analyze)

Status Indicator
Information
A coloured status line that tells you what to expect before you click Analyze:
  • ✓ Cached locally - Analyze loads instantly (green) - IndexedDB has a previous analysis at this file path + tier.
  • ✓ Server has this cached - Analyze is instant (no upload, no re-run) (green) - the server's hash-deduped cache hit; click skips the upload entirely.
  • ⏳ Job in progress (N min ago) - Analyze resumes it (amber) - a previous Server-tier run was interrupted; the server keeps it on a 24-hour TTL.
  • ✗ Not cached anywhere - Analyze will upload + run (~3-7 min cold) (dashed) - fresh run.
BMP hashes the audio bytes locally with SHA-256 (the algorithm the server uses too) and asks HEAD /cache/{hash}. The result is memoised for 30 s so flipping tiers doesn't re-hammer the server.
When to use: Read it before clicking Analyze - saves the surprise of "I thought this was cached" or "I thought it'd be fresh". Big-file editors save the upload time on a server cache hit.

🚀 Analyze Button

Button
Primary Action
Starts the analysis process. Disabled until audio is loaded. Button label adapts to the cache state - shows "Load from cache (or re-analyze)" on a local hit, "Resume previous run (N min ago)" on a pending Server job, or plain "Analyze" on a fresh run.

During the run, the progress bar advances through real server phases (upload → queue → transcode → Demucs → harmonix → onset → lyrics → encode → save) - not just a wall-clock guess. Status text prepends the live percentage for at-a-glance progress: "47% · Separating stems with Demucs…". A pulsing dot before the message confirms the run is still in flight.
When to use: After loading audio, click to detect beats, sections, and key moments. Takes 5 sec (Local) to 3 min (Premium with Gemini).
Keyboard shortcut: Press A to analyze.

⏸ Cancel Button

Button
Secondary Action
Appears during analysis. Label reads "Cancel <track> analysis" so it's clear which run gets cancelled when you've switched tracks. Long names truncate; hover for full name.
When to use: Stop the current run. Cooperative server cancel takes 5-30 s (next phase boundary). Re-analyze later returns instantly via hash-dedup.

📈 Waveform Display

Interactive Visualization
Core UI
Shows the audio waveform with beat markers (dots) and section blocks overlaid. Click any section to jump to it. Scroll to zoom, hover for timeline tooltip.
When to use: Always visible. Use to visualize song structure, preview sections before editing, and navigate the timeline. Space to play/pause.

🎨 Minimap (Below Waveform)

Navigation Tool
Secondary UI
Zoomed-out view of the entire song. Click or drag to pan the main waveform. Shows your current viewport as a highlight.
When to use: Quickly navigate long songs without zooming in and out. Drag the viewport to jump sections.

📊 Results Summary

Information Display
Information
Shows analysis results: BPM, key, sections detected, key moments (drops, buildups), confidence levels. Only appears after analysis completes.
When to use: Review to understand the song structure before creating markers or editing.

✂️ SELECT TAB

Subdivide beats, select patterns, and define custom regions on the waveform.

Tab: Select

➗ Subdivide Beats

Button Group
Filter Options
Buttons: Halve, Keep (1x), Double, Triple. Multiplies the beat grid by the selected factor. Affects marker count and metronome.
When to use:
  • Halve: For slower songs or when you want markers every other beat.
  • Keep (1x): Use the detected beats as-is (default).
  • Double: Twice as many markers - use for fast songs or fine-grained editing.
  • Triple: Three times as many markers - for ultra-detailed sync work.

🔢 Select Every Nth Beat

Dropdown + Input
Filter Options
Choose a number N (1, 2, 4, 8, 16) to select only every Nth beat. Useful for sparse marker grids or emphasis on downbeats.
When to use:
  • Every 1: Use all beats (default).
  • Every 2: Half-note grid (every 2nd beat).
  • Every 4: Bar grid (every 4th beat, one marker per bar).
  • Every 8/16: Very sparse - only major structural points.

🎯 Waveform Region Selection

Interactive Tool
Core UI
Shift+drag on the waveform to draw a custom selection region. Drag edges to resize, drag inside to move. Cursor shows affordance (ew-resize / move). A Clear region link appears next to the time range - click it to remove the region (scope falls back to Entire song, all dropdowns re-sync).
When to use: Isolate a specific section (e.g., just the chorus) for focused editing or looping. Markers created after will only include beats within this region - all 9 marker kinds (beat, section, drop, buildup, breakdown, pre-chorus, vocal-in/out, peak, lyric) are region-filtered. The status appends · (region-scoped) after Create so you can confirm.
Tip: No Shift required for edge/move - hover and drag directly. Drawing a new region replaces any existing one automatically; the Clear-region link is for fully removing it.

🎚️ Scope Dropdown

Dropdown
Filter Options
Choose Entire song or Selected region. Controls what beats the selection rules + Create Markers apply to. Mirrored on the Markers tab - both dropdowns share the same backing state, so changing one updates the other live.
When to use: Switch to Selected region after drawing a region on the waveform to limit marker output to that range. When a region exists and you've set scope=region, the region time range + Clear-region link appear inline.
Auto-flip: when you Clear a region while scope is set to Selected region, scope automatically flips back to Entire song so the dropdown label never lies about what's actually scoped.

🏗️ SECTIONS TAB

Review detected sections, navigate to them, and understand section structure.

Tab: Sections

📝 Section List

Interactive List
Information
Shows all detected sections (Verse, Chorus, Bridge, Drop, Buildup, Intro, Outro) with start time, duration, and confidence level. Sorted chronologically.
When to use: Understand the song's structure at a glance. Click any section to jump to it in the waveform. Use section names to guide editing decisions.

❓ Why am I seeing several CHORUS / VERSE rows in a row?

Phrase-level segmentation
Behavior
You'll often see something like four CHORUS rows back to back, each one ~15 seconds (~32 beats / 8 bars). They aren't four different choruses - they're the same chorus section sliced into four 8-bar phrases.

BeatMarker's detection model (HARMONIX) segments at musical-phrase boundaries (typically 8 bars), not at song-structure boundaries (the full chorus block). When several adjacent 8-bar phrases sound similar, they all get the same type label.
How to read it:
  • As 8-bar phrases - useful when cutting on bar lines. Use the per-phrase rows as cut points within a long chorus.
  • As one logical chorus - sum the durations: 15 + 15 + 15 + 23 = 68 s of chorus.
Quick rule of thumb: if two adjacent rows have the same type label and adjacent times, treat them as one section. Section markers placed in Premiere look identical either way - the count just goes up.

🔗 Click Section to Jump

Interactive Action
Navigation
Click any section row to seek the waveform to that section's start time. Waveform scrolls to center the section.
When to use: Quickly navigate to sections you want to edit without scrolling the waveform manually.

📊 Confidence Indicator

Visual Indicator
Information
Shows the AI's confidence in each section boundary (0-100%). Higher = more certain the section is correctly identified.
When to use: Use as a guide when deciding whether to trust a section boundary. Ambiguous transitions (e.g., subtle verse→chorus) show lower confidence.

🎯 MARKERS TAB

Create markers on your sequence, customize colors, and export/import analysis.

Tab: Markers

ℹ️ Disabled-state before Analyze

Visual State
UI Behavior
The Create Markers controls stay visible but greyed out until an analysis has loaded. A small banner reads "Click Analyze in the Analyze tab first to populate beat / section markers. The Manage row below still works without an analysis."
What it tells you: the marker creation controls exist but aren't actionable yet - without lying about what they'd do. The Manage row below (Wipe Server Cache, Export Bundle, Import Bundle) stays clickable for pre-Analyze actions like server-cache wipe.

🎚️ Scope Dropdown (mirror)

Dropdown
Filter Options
Sits at the top of the Markers tab and mirrors the Select-tab Scope dropdown. Set scope here when you've drawn a region on the waveform and want to limit Create Markers output without trip-back to Select.
When to use: any time you're on Markers tab and want to switch between whole-track and region scope. Both dropdowns share state - changing one updates the other live.

📌 Marker Preset Dropdown

Dropdown Menu
Configuration
Choose a predefined marker set to create. Options: Beats, Section-Aware, Peak Confidence, Custom.
When to use:
  • Beats: Just the beat grid, one marker per beat. No color coding.
  • Section-Aware: Beats colored by section (verse=green, chorus=orange, drop=red, etc.).
  • Peak Confidence: One marker at the peak of each chorus / drop / buildup section. Requires Server tier or above (uses per-frame activations). Best for the big climax moments.
  • Custom: Build your own selection from the Select tab.

🎨 Color Palette

Color Selector
Configuration
8-color palette for section markers: Green (verse), Red (drop), Purple (buildup), Orange (chorus), Yellow (bridge), White (beat), Blue (intro), Cyan (outro). Customize per section.
When to use: Adjust colors to match your editing preferences or to distinguish sections visually on the timeline. Changes apply to newly created markers.

📊 Marker Count Preview

Information Display
Information
Shows how many markers will be created based on your current preset, subdivision, and selection. Updates live as you change settings.
When to use: Check this before creating markers to ensure you're not creating too many (>200 is often excessive) or too few.

📍 Sequence Markers Checkbox

Checkbox
Configuration
When checked, markers are placed on the timeline sequence. When unchecked (and "Clip markers" is checked), markers are placed on the selected clip instead.
When to use:
  • Checked (default): Creates markers on the sequence timeline. Most common for overview and editing.
  • Unchecked: Creates markers on individual clips. Use when working with pre-cut segments or clip-level editing.

📍 Clip Markers Checkbox

Checkbox
Configuration
Inverse of "Sequence markers". When checked, markers go on the clip. Usually one or the other is enabled, not both.
When to use: Enable this when you want markers to follow a specific audio clip, not the timeline. Useful for portable marker sets.

⏐⏐ Offset Input

Number Input
Configuration
Time offset (in seconds) to add to all marker times. Needed when the audio in Premiere is at a different timeline position than where analysis expects it.
When to use: If you load audio from the file picker (not "Use sequence audio"), you may need to adjust this. The formula is: offset = clipStartTime - clipInPoint. If markers appear at wrong positions, adjust this value.
Example: If audio clip starts at 00:00:05 and the in-point is 00:00:00, set offset to +5. If the in-point is 00:00:02 and clip starts at 00:00:05, offset is +3.

🎲 Humanize Slider

Slider 0-100% + 🎲 Shuffle + ⟲ Reset
Configuration
Drops a percentage of selected beats so calmer parts of the track breathe and drops / choruses stay tight. Does not shift beat timing - BMP's beats already follow real onsets, so the human feel comes from cutting fewer beats where the music is quieter, not from displacing them. At slider=100, calm sections (verse / intro / breakdown) drop up to 15% of selected beats; energetic sections (chorus / drop / buildup) drop up to 3%.
When to use: Photo slideshows, b-roll montages, lyric edits - anywhere a strict beat-by-beat cut feels too mechanical. Start at ~30%, audition with the metronome on, push higher if verses still feel too dense. The waveform overlay shows dropped beats in a dimmer amber so you can see what's about to be cut before clicking Create Markers.
Example: On a 4-minute pop track at slider=50%, ~7-8% of verse beats drop out and choruses stay almost untouched. With the metronome playing you'll hear the click pattern thin out in real time as you drag.
Determinism: The same slider value always produces the same drop pattern on the same track. To try a different pattern at the same intensity, click 🎲 Shuffle. To clear all drops, click ⟲ Reset or double-click the slider thumb. Requires Server-tier analysis or above for the section-aware split - on Local-tier (no sections), Humanize applies a uniform low drop rate.

✨ Create Markers Button

Button
Primary Action
Creates markers on the Premiere sequence (or clip) based on your preset and settings. Disabled until analysis completes.
When to use: After analysis, review your preset and offset, then click to place markers on the timeline. Markers are standard Premiere markers - you can edit them afterward.
Keyboard shortcut: Press Shift+C to create markers.

🎬 Auto-distribute…

Button
Primary Action
Opens a modal that filters sequence markers by colour (= BMP semantic kind: chorus / drop / buildup / verse / etc.), reads your Premiere Project-panel selection, and places one bin clip per matching marker on the chosen video track. Selection order = placement order. Preview shows the count before any timeline mutation; Apply does the placement (Ctrl+Z undoes).
When to use: Music-video / trailer cuts where you want b-roll on specific marker types only - only the choruses, only the drops, only intro + outro. Bypasses Premiere's native Automate to Sequence (which can only use every marker uniformly), so you keep all markers on the timeline and choose which to use.
Tip: Cmd/Ctrl-click clips in the Project panel for multi-select. The "Use native flow" button next to it opens the help modal for Premiere's stock Automate to Sequence if you prefer that.

💾 Export as JSON

Button
Secondary Action
Exports the analysis result as a .beatmarker.json file. Contains all beats, sections, confidence levels, semantic data, and metadata. Useful for backup or sharing. Auto-fetches the analysis from the server if it's not yet in memory but is server-cached - hash-dedup means this is typically ~1 second, no full re-analysis needed.
When to use: Save analysis for later (portable across machines if you clear the cache). Share with collaborators so they don't need to re-analyze.

📂 Import JSON

Button
Secondary Action
Opens a file browser to load a previously exported .beatmarker.json file. Restores all analysis data as if you had just re-analyzed.
When to use: Load analysis from a backup or from a collaborator. Skips re-analysis and saves cost/time.

📦 Export Bundle…

Button → Modal
Secondary Action
Opens a tier-picker modal that shows live, per-track contents and sizes for each tier - pulled from the analysis result, the cached stems in IndexedDB, and the source audio file on disk. So instead of guessing "~80-200 MB", the modal might read e.g.:
  • Full - track.mp3 (5.2 MB) · 4 stems (vocals/drums/bass/other, AAC, 8.1 MB) · analysis (incl. lyrics, semantics, activations) · ≈ 14.9 MB total
  • Lite - 4 stems (...) · analysis (...) · ≈ 9.7 MB total
  • Minimal - analysis (...) · ≈ 1.6 MB
Picking Full or Lite when stems exist server-side but haven't been downloaded yet auto-fetches the missing stems before packing - no separate trip to the Stems tab. The modal status updates per-stem ("Downloading stem 2/4 (drums)…"). Same auto-fetch applies to the analysis itself: if you click Export Bundle before running Analyze on a server-cached track, the panel pulls the cached analysis in ~1 second (hash-dedup) before opening the tier picker. Clicking Export opens a native Save dialog defaulting to the source-audio folder; the saved path is reported in the status line afterward.
When to use: Move a paid analysis (Premium, Super Premium, or any Server-tier run with stems) between machines without re-paying for the run. Hand off to a collaborator in one drag-droppable file. Archive everything for a finished project.

📥 Import Bundle

Button
Secondary Action
Restores an analysis from a .beatmarker.zip. Hydrates beats, sections, lyrics, semantics, and IDB stems. Full bundles also extract the source audio to a temp folder and auto-load it so the waveform renders instantly. Equivalent to drag-dropping the .beatmarker.zip onto the panel.
When to use: Pick up a teammate's analysis on your machine, or restore a Premium / Super Premium run from your own backup without paying for it again.
Tip: You can also drag-drop a .beatmarker.zip directly onto the panel's drop zone - same code path as this button.

🎵 STEMS TAB

Separate audio into stems (vocals, drums, bass, etc.) and build custom mixes.

Tab: Stems

🎯 Stems Model Dropdown (Preferences)

Dropdown Menu
Configuration
Choose 4-stem (htdemucs: vocals, drums, bass, other) or 6-stem (htdemucs_6s: + guitar, piano) separation model. Set in Source → Preferences.
When to use:
  • 4-stem: Faster (~2-3 min), good for most music. Default.
  • 6-stem: Slower (~5-7 min), separates guitar and piano individually. Use for complex arrangements or when you need those stems.

🚀 Separate Stems Button

Button
Primary Action
Runs the Demucs neural network to separate the loaded audio into individual stems. Takes 2-5 minutes depending on song length and model. Disabled until audio is loaded.
When to use: Click to extract stems. Results are cached, so re-separating the same song is instant. Use stems for backing tracks, creating loops, or detailed mix control.

🎚️ Stem Mix Checkboxes

Checkbox Group
Configuration
Individual toggles for each stem: Vocals, Drums, Bass, Other (and Guitar/Piano for 6-stem). Check/uncheck to build custom mixes. "Mix & Import" button uses selected stems.
When to use:
  • Drums + Bass: Rhythmic foundation, good for intro/outro builds.
  • Vocals only: Isolated vocals for podcasts or voice-overs.
  • Everything except Vocals (Instrumental): For karaoke or instrumental versions.
  • Drums only: Metronome backing or rhythm reference.

📥 Download Stems

Button
Secondary Action
Downloads all stems (or checked stems) as individual audio files in your chosen format (AAC/Opus/WAV). Useful for importing into other apps or archiving.
When to use: Get raw stem files for use outside Premiere, or backup stems for future projects.

📥 Mix & Import to Premiere

Button
Primary Action
Imports checked stems directly into Premiere as separate audio tracks on the active sequence. Each stem gets its own track, aligned to the audio.
When to use: Build a multi-stem Premiere sequence for mixing, layering, or sound design. Each stem is independently controllable (volume, effects, etc.).
Note: Requires available audio tracks in the sequence. If not enough tracks exist, BMP will prompt you to add them.

⚙️ Stem Format Preference

Dropdown
Configuration
Set in Source → Preferences. Choose AAC (default, Premiere-friendly), Opus (compact), or WAV (uncompressed, large files).
When to use:
  • AAC: Balanced quality/size. Works natively in Premiere. Recommended.
  • Opus: Smallest files, good compression. May need conversion in Premiere.
  • WAV: Best quality, largest files (~500 MB per stem per 3-min track).

🔄 LOOPS TAB

Generate loopable sections and preview before importing.

Tab: Loops

🎵 Auto-Detect Loop

Button
Secondary Action
Automatically detects the longest chorus and extracts it as a loopable segment. Finds a clean section boundary for seamless looping.
When to use: Quick loop generation. No manual editing needed. Great for intro/outro building or theme song extraction.

🖌️ Manual Loop from Region

Button
Secondary Action
Uses the waveform region you drew (in Select tab) as the loop bounds. If no region is drawn, prompts you to draw one.
When to use: Full control over loop boundaries. Draw a region on the waveform (Shift+drag), then click this button.

🎚️ Stem Mix Selector

Dropdown
Configuration
Choose which stems to include in the loop: Full Mix, Drums Only, Bass Only, Vocals Only, Instrumental (no vocals), Karaoke (vocals only), or Custom Stems.
When to use:
  • Full Mix: Complete song loop.
  • Drums + Bass: Rhythm foundation for builds.
  • Instrumental: No vocals - good for backing tracks.
  • Vocal Solo: Just the vocal melody.

🔊 Loop Preview

Audio Player
Information
Built-in player to listen to the generated loop before importing. Play, pause, and repeat to verify the loop sounds natural.
When to use: Always preview before importing. Listen for seamless fade, crossfade, or abrupt edges. Adjust loop bounds if needed.

📥 Import Loop to Bin

Button
Primary Action
Imports the generated loop as a media item into the Premiere bin. You can then drag it to the sequence as needed.
When to use: After previewing and confirming the loop sounds good, click to import. It appears in the bin for easy access.

🎚️ CLICK TRACK TAB

Generate metronome/click tracks for the timeline.

Tab: Click Track

🔘 Click Track Mode Dropdown

Dropdown Menu
Configuration
Choose how the click track is generated: Downbeat-accented, Every-beat, Match-markers, or Steady-grid.
When to use:
  • Downbeat-accented: Accent on bar 1 (4/4 time). Standard metronome feel.
  • Every-beat: Equal volume on all beats. Minimalist.
  • Match-markers: Mirrors your marker preset - only clicks where markers exist.
  • Steady-grid: Uniform BPM grid, ignores detected beat variations. For strict sync.

🎵 Generate Click Track Button

Button
Primary Action
Renders the click track as a WAV file and imports it to the Premiere bin. Takes a few seconds. You can then drop it on an audio track.
When to use: After selecting a mode, click to generate. Import to an audio track, mute before exporting final video.

🎛️ GLOBAL CONTROLS & SHORTCUTS

Always Available

⏯ Metronome Toggle

Button (Toolbar)
Global Control
Toggles the metronome click on/off. Syncs to waveform playback. Responds to the detected BPM and configured style (in Preferences).
When to use: Press M to toggle on/off. Use while editing to verify rhythm, or as a backing track reference.

🥁 Offbeat Click ("And")

Button (Toolbar)
Global Control
Toggles a subtle offbeat click between the main beats. Adds groove. Can be driven by detected onsets for authentic rhythm feel.
When to use: Press Shift+M. Useful for adding pocket/swing to the click without overwhelming it.

🥁 Drum-Stem Backing

Button (Toolbar)
Global Control
If stems are available, plays just the drums stem as backing to the metronome. Adds realism to click-track rhythm.
When to use: Press D to toggle. Available only after stems are extracted. Great for editing to the actual drum sound.

ℹ️ About (Beta Badge)

Button (Header)
Information
Clicking the Beta badge in the top-left opens the About modal with keyboard shortcuts, links, and analysis metadata.
When to use: Check keyboard shortcuts, access Help & FAQ link, or see which analysis model was last used.

📊 Status Bar (Bottom)

Information Display
Information
Shows live status: file loading, analysis progress, error messages, and operation outcomes (e.g., "✓ Imported 4 stems onto sequence").
When to use: Always visible. Watch for status messages to understand what's happening, especially during long operations.

📌 Tab Counter Badges

Information Display
Information
Small badges on Sections and Markers tabs show the count (e.g., "Markers ×8" when subdivided). Updated live as analysis/selection changes.
When to use: Quick reference to see how many markers/sections exist without opening the tab.

⌨️ Keyboard Shortcuts Reference

Key Action
Space Play / Pause waveform
A Start / Cancel analysis
M Toggle metronome
Shift+M Toggle offbeat click
D Toggle drum-stem backing
Shift+C Create markers on sequence
Shift+Drag Draw region selection on waveform
Ctrl/Cmd+Scroll Zoom waveform in/out