Beat Detector — BPM, Drops & Video Edit Markers

Give the Actor a song or a video soundtrack and it returns an exact beat map you can cut video to: BPM, every beat and bar timestamp, the energy curve over time, drop (climax) and breakdown moments, section labels with a mood, plus marker files ready to import into Adobe Premiere, DaVinci Resolve, Audacity and CapCut.

The Actor only measures. It never re-encodes or cuts your file.

Input

Field	Type	Notes
audioUrls	array of URLs	MP3, WAV, M4A, OGG, FLAC, MP4, MOV — audio is extracted from video automatically
keyValueStoreRecords	array of {key, storeId?}	analyze files you already uploaded to an Apify key-value store
beatsPerBar	2–12, default 4	time signature numerator
fixedBpm	number	lock the tempo, only the phase is fitted
bpmRangeMin / bpmRangeMax	number	fold half/double tempo into your range (default 60–190)
peakSensitivity	1–10, default 5	how many drops / breakdowns are reported
maxSections	2–24, default 8	structural segmentation resolution
analyzeMood	boolean, default true	mood label per section
includeBeatList	boolean, default true	full beat/downbeat arrays in the dataset
exportMarkerFiles	boolean, default true	write the four marker files to the key-value store
maxDurationSecs	number	analyze only the first N seconds
depth	fast / standard / deep	fast = beats + energy, standard (default) adds lead/vocal, drops, key and mood, deep adds chords and drum/bass/harmony/voice levels
tempoMode	auto / constant / variable	auto keeps a constant grid unless the track really drifts
detectMeter	boolean, default true	detect 3/4 vs 4/4 instead of trusting beatsPerBar
precisionMode	high / standard, default high	high snaps every beat to the real onset at 2.9 ms resolution with sub-frame interpolation, then re-fits tempo and phase. Grid drift typically drops from ~20 ms to 1–8 ms on produced music

Output

One dataset row per file: bpm, bpmRaw, bpmConfidence, beatGridDriftMs, beatGridDriftP90Ms, driftFloorMs, gridAdherence, beatRefined, precisionMode, beatsPerBar, firstBeatSecs, firstDownbeatSecs, beatCount, barCount, beats[], downbeats[], tempoCurve, energyCurve, climaxPoints, breakdownPoints, transitionPoints, sections[] {startSecs, endSecs, role, mood, energy}, mood, energyMean, brightness, keyMode, markerFiles, analysisMs.

Marker files written to the run key-value store:

• *-premiere-markers.csv — Premiere Pro / DaVinci Resolve marker import (bar, beat, CLIMAX, BREAKDOWN, section)
• *-audacity-labels.txt — Audacity label track
• *-cuts.json — CapCut / script-friendly JSON with beats, downbeats, cuts, drops
• *-strong-beats.txt — downbeat timestamps only, one per line

Measured accuracy

Real Apify run, 6 files in one run, 4 GB container, 74 s total, 0.0823 compute units:

Track	Duration	BPM	Grid confidence	Grid drift	Analysis time
SoundHelix Song 1 (electronic)	6:13	134.98	0.94	16.5 ms	11.8 s
SoundHelix Song 2 (rock)	7:06	146.00	0.94	11.9 ms	9.1 s
SoundHelix Song 5 (downtempo)	5:54	95.33	0.93	8.9 ms	7.0 s
SoundHelix Song 8 (ballad)	5:25	96.00	0.95	8.5 ms	7.2 s
SoundHelix Song 11 (cinematic)	9:11	140.02	0.90	15.7 ms	10.8 s
MP4 video soundtrack	0:10	129.26	0.64	22.0 ms	0.8 s
Synthetic 128 BPM click grid (local)	1:00	127.98	1.00	17.2 ms	7.6 s

On the synthetic reference the tempo error is 0.02 BPM. Grid drift stays under 20 ms even on a nine-minute track, because the Actor optimises both the beat interval and its phase against the onset envelope instead of trusting a single tempo estimate. bpmConfidence is the share of grid beats that land on a real transient — use it to spot rubato or beat-free material.

In precisionMode: high (default) every beat is re-measured on a 2.9 ms onset grid with parabolic sub-frame interpolation, then tempo and phase are re-fitted through the snapped beats with outlier rejection. driftFloorMs reports the timing resolution of the run (2.9 ms high / 23.2 ms standard), beatGridDriftP90Ms the 90th-percentile drift (worst-case alignment), gridAdherence the share of grid beats that hit a real onset, and beatRefined whether the refinement pass ran. On quantized, produced music the median drift lands at 1–8 ms; on live rubato playing the residual is the performer's real timing, not measurement error.

Cost

CPU-only and far faster than real time: 34 minutes of audio were analyzed in 74 seconds for 0.0823 compute units (about $0.02), roughly $0.003 per song. There is no rental fee — you pay Apify compute only.

Limits

• Files up to 512 MB per URL.
• Tempo is reported as one stable grid; heavily rubato or live-drummer material will show a lower bpmConfidence and a higher beatGridDriftMs.
• Mood labels are derived from tempo, energy, brightness and major/minor colouring — they are a useful editing hint, not a musicological verdict.
• vocalSegments / vocalRatio mark where the lead line dominates the 300–3500 Hz band. This is a presence heuristic, not source separation: a lead synth or a solo instrument scores the same as a singer.

Measured accuracy (real POC runs)

Test	Result
Click track, exactly 128 BPM (ground truth)	128.00 BPM measured, confidence 0.99, grid drift 28.6 ms over 1 minute
SoundHelix Song 1 (EDM, 6:13)	134.98 BPM, confidence 0.94, drift 16.5 ms, key E minor, 5 drops, 200 ranked cut points
SoundHelix Song 8 (ballad, 5:25)	96.00 BPM, confidence 0.95, drift 8.2 ms, key F# minor
"Votre Toast" from Carmen (live band + voices, 2:35)	112.35 BPM, confidence 0.90, drift 23.2 ms, variable grid, key C major
Kevin MacLeod "Monkeys Spinning Monkeys"	144.00 BPM (true 144), confidence 0.98
Kevin MacLeod "Heartbreaking" (rubato piano)	lowConfidence: true — correctly flagged as uncertain instead of guessing

Speed on Apify (version 0.3, real run, 4 GB container)

Two full songs (11:38 of audio) analysed at standard depth in 68 s wall clock including container start and download, 0.0755 compute units (about $0.019 for both).

Speed on a full CPU core (version 0.3, per track)

Depth	6:13 EDM track	5:25 ballad	2:35 live recording
fast	1.8 s (180x realtime)	1.8 s	1.0 s
standard	7.6 s (49x realtime)	4.5 s (72x)	2.4 s (66x)
deep	4.6 s (80x)	4.3 s	2.2 s

Version 0.3 runs the harmonic/percussive split on a 128-band reduction of the spectrogram instead of the full STFT, which is why standard depth is roughly 4x faster than 0.2 at identical BPM, drift and section output. Runs also process several files concurrently and cache identical files, so re-analysing the same track costs nothing.

Typical cost per song: ~$0.002 at fast, well under $0.01 at standard.

For AI agents (MCP-ready)

This actor is built to be called by AI agents. It works out of the box with the Apify MCP Server — add it to Claude Desktop, Cursor or any MCP client: the agent can analyse music tempo and structure on its own.

{
  "mcpServers": {
    "audio-beat-analyzer": {
      "url": "https://mcp.apify.com/?actors=andrew_babo/audio-beat-analyzer",
      "headers": { "Authorization": "Bearer <YOUR_APIFY_TOKEN>" }
    }
  }
}

Agent skill (paste into your agent's instructions)

Use the "audio-beat-analyzer" tool when you need the tempo, beat grid,
downbeats, drops, sections or mood of an audio file — for video editing
markers, auto-cut timing, DJ/playlist work or music QA. Do NOT use it for
transcription or speech.

HOW TO CALL
- { "audioUrls": ["https://.../song.mp3"], "maxDurationSecs": 90 }
- Long files: always set "maxDurationSecs" (60-120) unless the user needs
  the whole track — it is the main cost driver.
- "depth": "quick" for BPM only, "standard" (default) for sections + mood,
  "deep" only when the user asks for maximum precision.
- Known tempo? Pass "fixedBpm" to skip detection. Non-4/4 music: set
  "beatsPerBar".
- Marker files for Premiere/Resolve/Audition come from
  "exportMarkerFiles": true (default).

OUTPUT CONTRACT
- bpm, bpmConfidence, beatGrid, downbeats, sections[], drops[], mood.
- Trust bpmConfidence: below ~0.5, say the tempo is uncertain instead of
  presenting it as fact.
- noResults: true with errorCode NO_INPUT means no audio was supplied;
  errorCode on a row means that file failed (bad URL, unsupported codec) —
  report it, never invent a BPM.