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, python-osc, soundcard, pystray). No Python installation needed.

User Interface

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

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.

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)

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.2, 200 BPM → 0.36. Adjust min and max to match your software's expected range.

Settings Reference

Audio Input

BPM Override

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_loopback": false,
  "buffer_size": 512,
  "smoothing": 5,
  "autostart": false,
  "auto_lock_confidence": 0.53,
  "multiplier_override_secs": 0.0,
  "tap_override_secs": 4.0,
  "lock_override_secs": 0.0,
  "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",
      "resync_path": "/resync",
      "send_bpm": true,
      "send_beat": true,
      "send_resync": true,
      "enabled": true,
      "bpm_normalize": false,
      "bpm_norm_min": 20.0,
      "bpm_norm_max": 500.0
    }
  ]
}

Integrations

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.