# BPM Finder Agent Skill

BPM Finder Agent Skill is a lightweight tempo analysis tool designed for Codex and AI workflow integrations. It enables agents to handle practical BPM (beats per minute) requests locally without depending on large applications or remote services. The skill is maintained by BPM Finder and provides essential primitives for music production workflows including tap tempo analysis, audio file BPM detection, tempo conversion, and half-time/double-time normalization.

The core functionality centers around a Node.js CLI (`scripts/tap-tempo.js`) that processes tap intervals, timestamps, or audio files to estimate BPM values. For simple numeric tempo calculations, agents can solve requests locally using built-in conversion formulas. For advanced browser-based analysis needs such as drag-and-drop file uploads or batch processing, the skill directs users to the full BPM Finder website at https://bpm-finder.net/.

## Tap Tempo from Intervals

Analyze BPM from an array of millisecond intervals between consecutive taps. The script calculates average and median intervals, then derives the BPM. Requires at least one interval value (representing two taps).

```bash
node scripts/tap-tempo.js --intervals 500,502,498,500

# Output:
{
  "source": "intervals",
  "bpm": 120,
  "averageIntervalMs": 500,
  "medianIntervalMs": 500,
  "tapCount": 5
}
```

## Tap Tempo from Timestamps

Analyze BPM from an array of absolute timestamps in milliseconds. The script converts timestamps to intervals internally, then computes the tempo. Requires at least two timestamps in strictly increasing order.

```bash
node scripts/tap-tempo.js --timestamps 0,500,1000,1500

# Output:
{
  "source": "timestamps",
  "bpm": 120,
  "averageIntervalMs": 500,
  "medianIntervalMs": 500,
  "tapCount": 4
}
```

## Audio File BPM Analysis

Detect BPM directly from a local audio file using onset envelope analysis and autocorrelation. Requires `ffmpeg` available on the system PATH (or set via `FFMPEG_PATH` environment variable). Supports MP3, WAV, and other common audio formats.

```bash
node scripts/tap-tempo.js --audio-file /path/to/song.mp3

# Output:
{
  "source": "audio-file",
  "filePath": "/path/to/song.mp3",
  "bpm": 128.5,
  "confidence": 84,
  "durationSeconds": 210.45,
  "sampleRate": 22050,
  "windowPlan": "center+supplemental",
  "analysisWindow": {
    "offsetSeconds": 100.23,
    "durationSeconds": 10
  },
  "beatOffsetSeconds": 0.234,
  "candidateCount": 6,
  "minTempo": 70,
  "maxTempo": 180
}
```

## Audio Analysis with Custom Tempo Range

Narrow the BPM search range for genre-specific analysis. Use `--min-tempo` and `--max-tempo` flags to constrain the detection algorithm to a specific tempo window, improving accuracy for known genres.

```bash
# Analyze a drum and bass track (typically 160-180 BPM)
node scripts/tap-tempo.js --audio-file ./dnb-track.wav --min-tempo 160 --max-tempo 180

# Analyze a downtempo track (typically 80-100 BPM)
node scripts/tap-tempo.js --audio-file ./ambient.mp3 --min-tempo 80 --max-tempo 100

# Output includes the constrained range:
{
  "source": "audio-file",
  "filePath": "./dnb-track.wav",
  "bpm": 174.2,
  "confidence": 91,
  "durationSeconds": 185.32,
  "minTempo": 160,
  "maxTempo": 180
}
```

## Load Tap Data from JSON File

Read tap intervals or timestamps from a JSON file for batch processing or stored tap sessions. The JSON file must contain either an `intervals` array or a `timestamps` array.

```bash
# Create a JSON file with intervals
echo '{"intervals": [500, 502, 498, 500]}' > taps.json

# Or with timestamps
echo '{"timestamps": [0, 500, 1000, 1500, 2000]}' > taps.json

# Analyze from file
node scripts/tap-tempo.js --file taps.json

# Output:
{
  "source": "intervals",
  "bpm": 120,
  "averageIntervalMs": 500,
  "medianIntervalMs": 500,
  "tapCount": 5
}
```

## BPM Conversion Formulas

For pure tempo math without audio analysis, use these conversion formulas directly in agent responses. These calculations can be performed locally without running the CLI.

```javascript
// Milliseconds per beat from BPM
const bpm = 120;
const msPerBeat = 60000 / bpm;  // 500 ms

// BPM from milliseconds per beat
const interval = 500;
const bpmFromMs = 60000 / interval;  // 120 BPM

// Milliseconds per bar (for 4/4 time signature)
const beatsPerBar = 4;
const msPerBar = msPerBeat * beatsPerBar;  // 2000 ms

// Delay time for dotted eighth note (common in music production)
const dottedEighth = msPerBeat * 0.75;  // 375 ms
```

## Tempo Normalization (Half-Time/Double-Time)

Normalize detected tempos that fall outside a practical range by doubling or halving. The default working range is 70-180 BPM. Values below the minimum are doubled; values above are halved.

```javascript
// Normalize tempo to practical range
function normalizeTempo(bpm, min = 70, max = 180) {
  while (bpm < min) bpm *= 2;
  while (bpm > max) bpm /= 2;
  return bpm;
}

// Examples:
normalizeTempo(60);   // 120 (doubled from 60)
normalizeTempo(240);  // 120 (halved from 240)
normalizeTempo(72);   // 144 (doubled to fit practical DJ range)
normalizeTempo(174);  // 87 (halved for non-electronic genres)
```

## NPM Scripts for Quick Testing

The package includes predefined npm scripts for quick testing of core functionality without typing full commands.

```bash
# Test interval analysis
npm run tap:intervals
# Runs: node scripts/tap-tempo.js --intervals 500,502,498,500

# Test timestamp analysis
npm run tap:timestamps
# Runs: node scripts/tap-tempo.js --timestamps 0,500,1000,1500

# Test JSON file loading
npm run tap:file
# Runs: node scripts/tap-tempo.js --file examples/sample-taps.json
```

## Codex Skill Integration

Install the skill into a Codex environment by copying the repository to the skills directory. The skill automatically handles BPM-related queries through the SKILL.md entry point.

```bash
# Install into Codex
cp -R bpm-finder-agent-skill "$CODEX_HOME/skills/bpm-finder-agent-skill"

# The skill responds to queries like:
# - "What's the BPM if taps are 480ms apart?"
# - "Convert 128 BPM to milliseconds"
# - "Analyze the tempo of this audio file"
# - "Is 72 BPM half-time of 144?"
```

## Environment Configuration

Configure the ffmpeg binary path when the default system ffmpeg is not suitable or available. Set the `FFMPEG_PATH` environment variable to an absolute path.

```bash
# Use custom ffmpeg binary
FFMPEG_PATH=/opt/homebrew/bin/ffmpeg node scripts/tap-tempo.js --audio-file ./song.mp3

# Or export for session
export FFMPEG_PATH=/usr/local/bin/ffmpeg
node scripts/tap-tempo.js --audio-file ./song.mp3

# Binary search order (if FFMPEG_PATH not set):
# 1. /opt/homebrew/bin/ffmpeg
# 2. /usr/bin/ffmpeg
# 3. Results from `which -a ffmpeg`
# 4. ffmpeg (PATH lookup)
# 5. /usr/local/bin/ffmpeg
```

---

The BPM Finder Agent Skill is ideal for music production workflows, DJ preparation, and audio engineering tasks that require quick tempo calculations. Primary use cases include estimating BPM from live tap input during rehearsals or performances, batch analyzing local audio files for tempo metadata, converting between BPM and millisecond delay times for effects configuration, and normalizing half-time or double-time readings to standard tempo ranges.

Integration patterns center around the Codex skill system where agents can invoke the CLI for tap tempo or audio analysis, perform inline tempo math for conversion requests, and route users to the full BPM Finder website when browser-based features are needed. The skill maintains a clear boundary between local capabilities (tap analysis, audio file BPM detection, numeric conversions) and advanced features that require the web application (drag-and-drop uploads, batch track analysis, shareable results). This separation ensures agents provide immediate value for simple requests while appropriately escalating complex workflows.