BPM2OSC Manual

Quick Start

1. Download and run the Windows installer from the download page.
2. Launch BPM2OSC.
3. Click ☰ to open Settings.
4. Select your audio input device (or a loopback device to capture system output).
5. Add an OSC target: set the IP and port of your destination software.
6. Click Save.
7. Click ▶ START. The BPM display will update as soon as the engine detects a stable tempo.
8. Select a genre preset from the preset bar if the detected BPM looks wrong.

Installation

Windows installer (recommended)

Download BPM2OSC Setup and run it. The installer includes all required dependencies (sounddevice, NumPy, SciPy, python-osc, soundcard, pystray). No Python installation needed.

User Interface

The main window is divided into these areas from top to bottom:

Every area except the top bar can be hidden independently from Settings → Interface to save space on cramped multi-monitor or show-control setups — see Settings Reference.

System tray

Minimizing the window sends BPM2OSC to the system tray (Windows, requires pystray). Right-click the tray icon for Start/Stop, Resync, and Quit. The tray tooltip shows the current BPM in real time.

Mini window

Click ⛶ in the top bar to switch to a small, freely resizable BPM-only window — useful when the full window doesn't fit alongside other show-control software on the same screen.

• The BPM digits scale dynamically to whatever size you resize the window to.
• Click the BPM digits to TAP tempo directly from the mini window.
• A thin drag strip replaces the OS title bar and doubles as a drag handle; a button on it returns to the main window.
• Enable Tiny window always on top in Settings to keep it pinned above other windows.

Audio Input

Open Settings → Audio Input to select the audio source. BPM2OSC supports two capture modes:

Microphone / audio interface

Any device recognized by PortAudio (via sounddevice) appears in the device list. This includes USB audio interfaces, line-in inputs, built-in microphones, and virtual audio cables. Use a line-in connection from a mixer or DJ controller for the most stable results.

System loopback (Windows only)

Loopback devices appear in the list prefixed with ⟲. Selecting one captures whatever is playing through that output — no cable needed. Internally this uses the SoundCard WASAPI loopback API.

Buffer size and latency

Smoothing

Controls the depth of the BPM median filter (number of frames kept in history). Higher values produce a steadier readout but react more slowly to genuine tempo changes. The default of 5 is a good balance for most live situations.

BPM Controls

Engine Presets

A preset is a named set of five engine parameters: BPM search range (min and max), Gaussian prior centre (prior), and the octave-correction gates (×2 gate and ÷2 gate).

Click any preset button in the preset bar to apply it live — no restart needed. The active preset is highlighted. You can also edit the five numeric values individually in Settings without changing the preset name.

What each parameter does

• min / max BPM — defines the search range for the ACF peak. Values outside this range are ignored even if the ACF scores them highly.
• prior — centre of a gentle Gaussian bias added to ACF scores. Slightly favours the expected tempo without overriding the data. Effect is small (±15% weight).
• ×2 gate — BPM threshold above which the ×2 octave correction is allowed. If the detected BPM exceeds this gate, the engine checks whether the half-tempo lag scores ≥ 75% as high and, if so, halves the result.
• ÷2 gate — BPM threshold below which the ÷2 correction is allowed. If the detected BPM falls below this gate, the engine checks the double-tempo lag similarly.

Creating and editing presets

In Settings → Engine Presets you can add new presets, rename existing ones, edit their five parameters, or delete them. Factory presets (built-in) can be reset to their defaults with the ⟳ button. Custom presets are stored in the config file.

AlgoMonitor

The Engine panel contains four real-time diagnostic widgets that expose the internal state of the detection algorithm. Updated at ~50 fps.

ODF waveform (top row)

Right panel

BPM history graph (middle row)

Green filled chart of BPM estimates over the last ~40 seconds. The Y-axis auto-scales to the observed range ± 2 BPM. A green dot at the right edge marks the current BPM. Use this to spot drifts, jumps, or oscillations between two tempos.

ACF score curve (bottom row)

Purple curve showing the full ACF harmonic-sum scores across the BPM search range. The X-axis spans from min BPM to max BPM; vertical grid lines mark every 20 BPM. A green dashed vertical line marks the detected peak BPM with a numeric label.

A sharp, isolated peak means the engine is confident. A broad or multi-modal curve means the signal is ambiguous — consider enabling auto-lock.

OSC Targets

BPM2OSC can send to any number of OSC destinations simultaneously. Each target is configured independently. Open Settings → OSC Targets and click + Add target to create a new one.

OSC target edit dialog — Resolume example with BPM normalization enabled

Target dot indicators

Each target has a coloured dot in the main window Targets panel:

• ● Dark blue — idle (no recent send)
• ● Yellow flash — UDP send in progress
• ● Green flash — TCP send in progress
• ✕ Grey with red X — TCP connection error (reconnecting automatically every 15 s)

OSC Messages

Normalized BPM

When Normalize BPM is enabled on a target, the BPM float is mapped linearly to the range [0.0, 1.0] using:

value = (bpm - norm_min) / (norm_max - norm_min)
value = clamp(value, 0.0, 1.0)

With defaults (min=20, max=500): 120 BPM → 0.21, 200 BPM → 0.38. Adjust min and max to match your software's expected range.

Web UI

BPM2OSC includes a built-in web server that runs automatically at launch and serves a real-time remote control page at http://<host>:5000. You can open it from any browser on the same local network — PC, tablet, or phone — without installing anything.

What you see

Accessing the page

1. Launch BPM2OSC — the web server starts immediately.
2. Open http://127.0.0.1:5000 on the same machine, or http://<LAN-IP>:5000 from another device.
3. The connection dot in the top-right corner turns green when the live stream is active.

Web Server settings

Open Settings → Web Server to configure:

Changes to Web Server settings take effect on the next launch of BPM2OSC.

REST API

Every control is also available as an HTTP POST endpoint, making the web server suitable for integration with Bitfocus Companion, home-automation systems, or custom scripts:

Example from the command line:

curl -X POST http://127.0.0.1:5000/api/start
curl -X POST http://127.0.0.1:5000/api/preset/Rock%20%2F%20Live

Settings Reference

Audio Input

Click

Configures the audible metronome click triggered by the CLICK button next to RESYNC. It is independent from the Audio Input device — you can monitor via loopback while the click plays out to your speakers or a separate output.

Web Server

BPM Override

Interface

Independently hide parts of the main window to save vertical space on cramped multi-monitor or show-control setups. The window resizes to fit whatever's left visible.

Config File

Settings are saved automatically to:

• %APPDATA%\BPM2OSC\bpm2osc.json

The file is updated every time you click Save in Settings and on every clean shutdown. You can edit it manually with any text editor. Invalid values are silently ignored and replaced with defaults on the next launch.

{
  "audio_device_name": "Focusrite USB Audio",
  "audio_hostapi_name": "Windows WASAPI",
  "audio_loopback": false,
  "click_hostapi_name": "Windows WASAPI",
  "click_device_name": "Speakers",
  "click_volume": 0.5,
  "buffer_size": 512,
  "smoothing": 5,
  "autostart": false,
  "auto_lock_confidence": 0.53,
  "multiplier_override_secs": 0.0,
  "tap_override_secs": 4.0,
  "tap_guide_pct": 10.0,
  "lock_override_secs": 0.0,
  "metro_hold_on_nobeat": false,
  "web_enabled": true,
  "web_port": 5000,
  "preset": "Rock / Live",
  "min_bpm": 65,
  "max_bpm": 155,
  "prior_bpm": 100,
  "mul2_gate": 128,
  "div2_gate": 95,
  "targets": [
    {
      "name": "MagicQ",
      "ip": "192.168.1.100",
      "port": 8000,
      "protocol": "udp",
      "bpm_path": "/bpm",
      "beat_path": "/beat",
      "bar_path": "/beat/bar",
      "conf_path": "/bpm2osc/confidence",
      "resync_path": "/resync",
      "send_bpm": true,
      "send_beat": true,
      "send_bar": true,
      "send_conf": false,
      "send_resync": true,
      "enabled": true,
      "bpm_normalize": false,
      "bpm_norm_min": 20.0,
      "bpm_norm_max": 500.0
    }
  ]
}

Integrations

ChamSys MagicQ

MagicQ does not accept BPM values via OSC. The correct approach is to map the /beat OSC message to a Speed Master Tap function via the Automation window. This makes MagicQ tap-tempo its Speed Master on every beat, keeping chase speeds locked to the music.

OSC target edit dialog — ChamSys MagicQ example: only Beat is sent

On the MagicQ side — one-time setup:

1. Setup → Network → OSC → enable OSC RX, port 8000
2. Open Macro → View Autom
3. Add a new row (press the Insert soft-button or Add)
4. Set Type = OSC
5. Set P1 = /beat (the OSC address BPM2OSC sends)
6. Set Function = Speed Master Tap
7. Set P2 = 1 (Speed Master ID — SP1; change if you use a different Speed Master)
8. In each Cue Stack that should follow the beat, set Speed Master = SP1

From this point on, every /beat message from BPM2OSC will tap the Speed Master, and all cue stacks assigned to SP1 will chase in sync with the music.

In BPM2OSC:

• IP: MagicQ machine's IP address (or 127.0.0.1 if on the same machine)
• Port: 8000
• Protocol: UDP
• Send BPM: off — Send Beat: on
• Beat path: /beat

MagicQ supports up to 100 Speed Masters (SP1–SP100). If you need different cue stacks to run at different speeds, assign them to different Speed Masters and add one Autom row per Speed Master, each listening on a different OSC address.

Resolume Arena / Avenue

In BPM2OSC — OSC target settings:

• IP: Resolume machine's IP address
• Port: 7000 (Resolume default OSC input port)
• Protocol: UDP
• BPM path: /composition/tempocontroller/tempo — Send ✓
• Beat path: /beat — Send off (Resolume handles its own beat grid)
• Resync path: /composition/tempocontroller/resync — Send ✓
• Enable Normalize BPM (0–1), min: 20.0, max: 500.0

On the Resolume side:

1. Preferences → OSC → enable OSC input on port 7000
2. The tempo controller path /composition/tempocontroller/tempo is built-in — no mapping needed
3. Resolume expects a normalized 0–1 value for tempo, hence the BPM normalization above

Resync in Resolume: sending /composition/tempocontroller/resync triggers Resolume's internal beat-grid reset, keeping its visuals phase-locked to the music when the operator presses RESYNC in BPM2OSC.

Troubleshooting

BPM display shows wrong value

• Try a different genre preset. Most detection errors are octave mistakes fixed by the right preset.
• Check the AlgoMonitor ACF curve: if the peak is at a different position than expected, the prior may be pulling it. Adjust the preset's prior BPM.
• Lower the buffer size if the display lags noticeably behind the music.
• Increase the buffer size if the display oscillates between two values.
• Use TAP to override temporarily while adjusting settings.

CONF bar stays low (red / yellow)

• The audio level may be too low. Check the VU meter — the bars should reach the green zone on the beat.
• Sparse percussion (breakbeats, half-time) is harder to detect. Try the Hip-Hop preset and enable auto-lock at ~50%.
• During breakdowns or DJ transitions low confidence is expected — enable auto-lock to prevent the display from drifting.

No audio devices visible

• Make sure your audio interface or microphone is plugged in before starting BPM2OSC.
• On Windows, check that the device is not set to exclusive mode by another application.
• Loopback devices require the output device to be active (playing audio).

OSC not received by the destination

• Check IP address and port. On a single machine use 127.0.0.1; for network targets use the machine's LAN IP.
• Check that no firewall is blocking UDP/TCP on the destination port.
• Use an OSC monitor (e.g. Protokol) on the same machine as the destination to confirm packets arrive.
• TCP targets show a connection error (grey dot with X) if they can't connect — verify the destination is listening before starting BPM2OSC.

Application doesn't start

• Reinstalling BPM2OSC usually fixes startup issues — download the installer again from the website.
• Check that %APPDATA%\BPM2OSC\bpm2osc.json is not corrupted. Delete it to reset to defaults.

What's New

v2.10.1f — 8 July 2026 (feature release)

• Mini window — small, freely resizable BPM-only readout (⛶ button): tap tempo from the BPM digits, draggable borderless mode, optional always-on-top. See Mini window.
• Hover tooltips on top-bar buttons, BPM controls, beat indicator and AlgoMonitor readouts, reviewed for clarity and accuracy.
• Show/hide UI panels — independently hide the VU meter, beat indicator, AlgoMonitor, metronome bar, click icon, presets or Targets panel; the window resizes to fit. See Settings Reference → Interface.
• Click icon redesigned as a compact metronome-style icon; removed the bottom donate line (still in the About dialog).
• Bug fixes — ODF graph no longer leaves a blank gap on wide panels; "hide metronome" toggle no longer affects the click icon (now separate toggles); RESYNC no longer causes the click to double-fire; top-bar icon sizing made consistent.

v2.8.1f — 6 July 2026 (feature release)

• Audio click — new CLICK button plays an audible, phase-locked click on every beat, with downbeat accent, independent output device/API/volume settings, and loopback feedback protection. Latency is self-calibrated per device for accurate sync.
• Settings — API selector to de-duplicate audio devices listed once per host API (MME/DirectSound/WASAPI/WDM-KS); device channel count now shown.
• Bug fixes — sample-clock drift correction for both standard input and Loopback capture (was reading a slightly wrong BPM); fixed WASAPI "Unanticipated host error" via automatic host-API retry; fixed VU meter always showing 1 channel; fixed app freeze and occasional double/triple click firing on click-enable; fixed status text overlapping the CLICK button and the window resizing itself unexpectedly.

v2.7.8 — 30 June 2026 (feature release)

• Tap Tempo prior override — TAP now permanently overrides the ACF prior BPM until the preset changes or it's manually cleared, shown in the Engine monitor as PRIOR BPM (Preset/Adaptive/Override); the guide window around the tapped BPM is now configurable in Settings.
• Bug fixes — ACF lag search no longer truncates the minimum reachable BPM at preset boundaries; reduced DFT refinement overshoot chasing false harmonic peaks; fixed overlapping Settings fields and overdrawn ACF grid labels.

v2.6.5 — 30 June 2026 (bugfix release)

• Bug fixes — metronome no longer chases live phase estimates while the BPM is locked; fixed octave-correction instability that caused the BPM to oscillate between octaves on tracks with a strong eighth-note pulse.

v2.6.3 — 28 June 2026 (feature release)

• Precision engine upgrade — DFT frequency refinement (±0.1 → ±0.002 BPM), beat-grid regression blended with the Kalman estimate, adaptive Kalman precision mode after sustained high confidence, and output resolution raised to 0.01 BPM.
• AlgoMonitor — new PRECISION row (SYNC/NORM/HIGH); STABILITY now shown to 0.01 BPM.

v2.5.0 — 27 June 2026 (feature release)

• Web UI & Bitfocus Companion integration — built-in web server with a browser remote-control page (BPM, beat wheel, VU meter, engine monitor, presets) and a REST API Companion can drive via its Generic HTTP module.
• Higher BPM precision & stability — harmonic sum extended to k=16, confidence via median noise floor, adaptive Kalman noise scaling, and a dead-band filter for a stable displayed BPM.
• No-beat hold option — keep the last BPM instead of stopping when confidence drops.
• Bug fixes — octave correction now actually commits (gate-driven multipath hypothesis); metronome/OSC properly stop and restart on no-beat with auto-lock hysteresis and a large-jump guard; fewer false fast-adapt snaps during track changes; preset changes reset the Kalman filter; fixed beat-wheel glitch and hold-BPM display bug.

v2.0.1a — 25 June 2026 (bugfix release)

• Breakdown hold (Gate 3) — low-confidence frames are discarded once the Kalman filter is initialised, preventing hi-hat/pad periodicities from drifting the BPM during breakdowns or DJ transitions.
• Tempo inertia hardening and auto-preset smart gate narrowing reduce the need for manual preset selection and wrong large BPM jumps.
• Per-target OSC Confidence/Bar-beat paths, each independently configurable and opt-in.

v2.0.0 — 25 June 2026 (major release)

• scipy.fft + high-pass filter for cleaner onset detection; multi-scale ACF (4 s / 12 s windows) with fast-adapt track-change detection.
• Multipath EMA hypothesis system for octave correction (BASE, ÷2, ×2, 4:3), eliminating single-frame octave flips.
• Adaptive prior that self-anchors after sustained high confidence; TAP injects prior for instant convergence.
• New OSC outputs — /bpm2osc/confidence and /beat/bar, fully configurable per target.