Beat times and downbeats from a song in Node, with life2film-engine

A short Node script that decodes a song with ffmpeg and prints BPM, beat times and downbeats on your machine, ready to place cuts on. No upload, no API key.

Set up beat detection in this folder.
1. Run npm i life2film-engine, then read node_modules/life2film-engine/SKILL.md.
2. Write beats.mjs. It takes one audio or video file, decodes it with ffmpeg to mono 22050 Hz float32 on stdout, loads the WASM module the way SKILL.md shows for Node, calls detect_beats, and prints one JSON line with bpm, confidence, pulse_strength, the first 8 beats and the first 4 downbeats, in seconds.
3. Run it on {song.mp3}.
4. If pulse_strength is under 0.2, tell me the BPM is a guess. If the tempo could be double or half of the real one, print both readings.
5. Then write cuts.json: a list of cut times for a {30}-second video, one cut every {2} bars, each cut on a downbeat.

In Claude Code, paste the prompt as a message.

Install

npm i life2film-engine

Steps

  1. You need Node.js 20 or newer and ffmpeg on the PATH.
  2. Paste the prompt into Claude Code in an empty folder, or write beats.mjs yourself from the example.
  3. Check the numbers against the song: tap along for ten seconds and compare with the first beat times.
  4. Hand the beat list to the beat-sync cutting prompt, or to /solo-video-edit, to turn it into a cut list.

Example

// beats.mjs  ·  node beats.mjs song.mp3
import init, { detect_beats } from 'life2film-engine';
import { readFileSync } from 'node:fs';
import { createRequire } from 'node:module';
import { execFileSync } from 'node:child_process';

const require = createRequire(import.meta.url);
await init({ module_or_path: readFileSync(require.resolve('life2film-engine/va_wasm_bg.wasm')) });

// ffmpeg decodes: mono, 22050 Hz, 32-bit float on stdout
const raw = execFileSync('ffmpeg', ['-v', 'error', '-i', process.argv[2], '-ac', '1', '-ar', '22050', '-f', 'f32le', '-'], { maxBuffer: 1 << 30 });
const mono = new Float32Array(raw.buffer, raw.byteOffset, raw.byteLength / 4);

const { bpm, beats, confidence, pulse_strength, downbeats } = JSON.parse(detect_beats(mono, 22050, null));
console.log(JSON.stringify({ bpm, confidence, pulse_strength, beats: beats.slice(0, 8), downbeats: downbeats?.slice(0, 4) }));

Run on a synthetic 120 BPM click track, it printed bpm 119.92, confidence 1, pulse_strength 0.85, beats at 0, 0.51, 1.0, 1.51 seconds and downbeats at 0, 2.0, 4.0 seconds. On real music pulse_strength is lower: the package notes say music is over 0.4 and a pure tone or noise under 0.15.

Tips

  • Licence: the package is free for noncommercial use (hobby, study, research, charities). Commercial use needs a separate licence from its authors; read LICENSE.md in the package before shipping it in a product.
  • Tempo is ambiguous by an octave: 140 BPM is also 70 in half time. A result that is exactly double or half of what you expect is the other valid reading, not an error.
  • The engine only analyses. Decoding and encoding stay with ffmpeg, which is why the script pipes raw samples in.
  • No code needed for a quick look: the BPM detector on life2film.com/tools runs the same engine in a browser tab.

Read more

works withClaude Code: Runs as a skill or a prompt in the terminal; can read your files and write the result. · ffmpeg: A terminal command you run yourself. · Life2Film: The montage app: analysis, segment scoring and cuts on your device.
costFree. No API, no key.
statusUnverified: written from the technique, not yet run end to end by us.
sourcelife2film-engine on npm (README and SKILL.md)
licenseCC BY 4.0 for the text here; skills are MIT.
updated2026-11-10
for agentsbeat-times-and-downbeats-from-a-song-with-node.md
#beats#bpm#downbeats#node#ffmpeg#wasm#beat-sync

Related

Music & sound intermediate

Beat-sync cutting: cut on the beat, not on every beat

A rule and an agent prompt for cutting to music from a list of beat timestamps: cuts land on beats, phrases get room to breathe, and the best shot is held through the hook.

Claude CodeClaudeChatGPT
Skills & tools advanced

Edit real footage into a film with the agent as the editor (/solo-video-edit)

Edit real footage into a film with the agent as the editor: read the day's speech as text, write the cut as a script, lay cutaways that match the words, score it, strip other people's music, and…

Claude Code
Music & sound intermediate

Score with a hole, not ducking, where something plays live

Cut the score to silence under live music, a laugh or a knock instead of ducking it; ducking is audible, a hole is not. The rule, the measured levels and the ffmpeg line.

ffmpegCapCut / any editorClaude Code
Skills & tools intermediate

Cut a vertical reel to a song with real beats (/solo-music-reels-cut)

Footage plus a music track becomes a 1080x1920 reel: beats and phrases detected for real, cut density that follows verse and chorus, 14 ffmpeg effects, a flash on every downbeat.

Claude Codeffmpeg
Editing & montage beginner

Find the cuts in a video with ffmpeg's scene filter

One ffmpeg command that lists the timestamps where the picture changes, how to set the threshold, and why phone footage often has no cuts to find.

ffmpegClaude CodeBy hand
Skills & tools intermediate

Scan a screen recording for leaked secrets before you post it (screenshield)

Before a demo, lecture or stream goes public, scan the video for API keys, personal data and QR phishing, and blur what it finds. On-device OCR, no LLM needed for the scan.

Claude Codeffmpeg