BPM Finder Agent Skill

https://github.com/wsgtcyx/bpm-finder-agent-skill
Admin
BPM Finder Agent Skill is a lightweight agent skill for analyzing and estimating BPM (beats per...
Tokens:4,067
Snippets:45
Trust Score:5.8
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Codex Skill Integration (Bash)

Source: https://context7.com/wsgtcyx/bpm-finder-agent-skill/llms.txt

Instructions for installing the BPM Finder Agent Skill into a Codex environment. The skill automatically handles BPM-related queries via the SKILL.md entry point after being copied to the skills directory.

```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?"
```

--------------------------------

### Install BPM Finder Agent Skill into Codex

Source: https://github.com/wsgtcyx/bpm-finder-agent-skill/blob/master/README.md

This command copies the bpm-finder-agent-skill directory into the specified Codex skills directory, making it available for use within the Codex environment.

```bash
cp -R bpm-finder-agent-skill "$CODEX_HOME/skills/bpm-finder-agent-skill"
```

--------------------------------

### Example JSON Output for Tap Tempo Analysis

Source: https://github.com/wsgtcyx/bpm-finder-agent-skill/blob/master/README.md

This JSON object represents the output from analyzing tap tempo data. It includes the source of the data, calculated BPM, average and median interval in milliseconds, and the tap count.

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

--------------------------------

### Audio File BPM Analysis (Bash)

Source: https://context7.com/wsgtcyx/bpm-finder-agent-skill/llms.txt

Detects BPM directly from an audio file using onset envelope analysis. Requires `ffmpeg` to be installed and accessible. Supports common audio formats and outputs detailed analysis results including BPM, confidence, and duration.

```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
}
```

--------------------------------

### NPM Scripts for Testing (Bash)

Source: https://context7.com/wsgtcyx/bpm-finder-agent-skill/llms.txt

Provides predefined npm scripts for quickly testing core functionalities of the BPM Finder Agent Skill. These scripts simplify the execution of tests for interval analysis, timestamp analysis, and JSON file loading without requiring users to type 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
```

--------------------------------

### Read Tap Tempo Sample Data using CLI

Source: https://github.com/wsgtcyx/bpm-finder-agent-skill/blob/master/README.md

This Node.js script reads tap tempo data from a JSON file. It requires the tap-tempo.js script and the path to a JSON file containing sample tap data.

```bash
node scripts/tap-tempo.js --file examples/sample-taps.json
```

--------------------------------

### Set FFMPEG Path for Audio Analysis CLI

Source: https://github.com/wsgtcyx/bpm-finder-agent-skill/blob/master/README.md

This command demonstrates how to explicitly set the path to the ffmpeg binary if it's not found in the system's PATH. This is necessary for the Node.js script to decode audio files.

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

--------------------------------

### Analyze Tap Tempo Intervals using CLI

Source: https://github.com/wsgtcyx/bpm-finder-agent-skill/blob/master/README.md

This Node.js script analyzes tap tempo based on provided intervals in milliseconds. It requires the tap-tempo.js script and accepts a comma-separated list of intervals as input.

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

--------------------------------

### Environment Configuration for FFmpeg (Bash)

Source: https://context7.com/wsgtcyx/bpm-finder-agent-skill/llms.txt

Details how to configure the FFmpeg binary path when the default system FFmpeg is not suitable or available. The `FFMPEG_PATH` environment variable can be set to an absolute path for custom FFmpeg binaries, with a specified binary search order if the variable is not set.

```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
```

--------------------------------

### Tap Tempo from Intervals (Bash)

Source: https://context7.com/wsgtcyx/bpm-finder-agent-skill/llms.txt

Analyzes BPM from an array of millisecond intervals between taps. Requires at least one interval (two taps). Outputs BPM, interval statistics, and tap count.

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

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

--------------------------------

### Analyze Local Audio File using CLI

Source: https://github.com/wsgtcyx/bpm-finder-agent-skill/blob/master/README.md

This Node.js script analyzes the BPM of a local audio file using ffmpeg for decoding. It requires the tap-tempo.js script and an absolute or relative path to the audio file.

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

--------------------------------

### Load Tap Data from JSON File (Bash)

Source: https://context7.com/wsgtcyx/bpm-finder-agent-skill/llms.txt

Analyzes BPM by loading tap intervals or timestamps from a JSON file. The JSON file must contain either an `intervals` or `timestamps` array. Useful for batch processing or stored tap sessions.

```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
}
```

--------------------------------

### Analyze Tap Tempo Timestamps using CLI

Source: https://github.com/wsgtcyx/bpm-finder-agent-skill/blob/master/README.md

This Node.js script analyzes tap tempo based on provided timestamps in milliseconds. It requires the tap-tempo.js script and accepts a comma-separated list of timestamps as input.

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

--------------------------------

### Tap Tempo from Timestamps (Bash)

Source: https://context7.com/wsgtcyx/bpm-finder-agent-skill/llms.txt

Analyzes BPM from an array of absolute timestamps in milliseconds. Internally converts timestamps to intervals. Requires at least two timestamps in strictly increasing order. Outputs BPM, interval statistics, and tap count.

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

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

--------------------------------

### Tune BPM Search Range for Audio Analysis CLI

Source: https://github.com/wsgtcyx/bpm-finder-agent-skill/blob/master/README.md

This Node.js script analyzes a local audio file while allowing customization of the BPM search range. It's useful for genre-specific BPM guessing and requires the tap-tempo.js script.

```bash
node scripts/tap-tempo.js --audio-file ./song.wav --min-tempo 120 --max-tempo 150
```

--------------------------------

### Audio Analysis with Custom Tempo Range (Bash)

Source: https://context7.com/wsgtcyx/bpm-finder-agent-skill/llms.txt

Performs audio file BPM analysis while constraining the search to a specific tempo range using `--min-tempo` and `--max-tempo` flags. This improves accuracy for genre-specific analysis. Outputs BPM within the specified range.

```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
}
```

--------------------------------

### BPM Conversion Formulas (JavaScript)

Source: https://context7.com/wsgtcyx/bpm-finder-agent-skill/llms.txt

Provides essential JavaScript formulas for direct tempo calculations without requiring audio analysis. Includes conversions between BPM, milliseconds per beat, milliseconds per bar, and delay times for musical notes.

```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 Logic (JavaScript)

Source: https://context7.com/wsgtcyx/bpm-finder-agent-skill/llms.txt

Normalizes detected tempos to a practical range (default 70-180 BPM) by doubling values below the minimum and halving values above the maximum. This function is useful for ensuring tempo readings are within a usable range for applications like DJ software.

```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)
```
Tokens:
Raw