> Canonical URL: https://codingcat.dev/course/yt-dlp-librosa-reference-beat-extraction/lesson/yt-dlp-librosa-reference-beat-extraction-lesson-4-beats-json # Lesson 4: Extracting BPM, Beats, Downbeats & Onset Hits into `beats.json` with `librosa` | yt-dlp & Librosa: Reference Visual Grammar & 120 BPM Beat Extraction | CodingCat.dev Course [🧢 yt-dlp & Librosa: Reference Visual Grammar & 120 BPM Beat Extraction](/course/yt-dlp-librosa-reference-beat-extraction)Section 1.4 Β· Lesson 4 of 5[![](/logos/tags/typescript-symbol-light.svg)![](/logos/tags/typescript-symbol-dark.svg)TypeScript](/topic/typescript)[#AI & Agents](/topic/ai)[![](/logos/tags/python-symbol-light.svg)![](/logos/tags/python-symbol-dark.svg)Python](/topic/python)[← Prev Lesson](/course/yt-dlp-librosa-reference-beat-extraction/lesson/yt-dlp-librosa-reference-beat-extraction-lesson-3-style-guide)[Next Lesson β†’](/course/yt-dlp-librosa-reference-beat-extraction/lesson/yt-dlp-librosa-reference-beat-extraction-lesson-5-downbeat-cut) # Lesson 4: Extracting BPM, Beats, Downbeats & Onset Hits into `beats.json` with `librosa` ![CodingCat.dev tutorial cover image](https://cdn.sanity.io/images/hfh83o0w/production/225498853f0d90a934c16fd651a3d6fbc5e83a36-1376x768.jpg?w=1376&q=82&fit=max&auto=format)Lesson 4 / 5Course Lessons Outlineβ–Ύ1Core Architecture & Deterministic Implementation - [1.1Lesson 1: Downloading High-Bitrate Reference Clips & Audio Stems with `yt-dlp`](/course/yt-dlp-librosa-reference-beat-extraction/lesson/yt-dlp-librosa-reference-beat-extraction-lesson-1-yt-dlp-cli) - [1.2Lesson 2: Slicing Reference Videos at 0.5s Intervals to Extract Shot Lengths & Pacing](/course/yt-dlp-librosa-reference-beat-extraction/lesson/yt-dlp-librosa-reference-beat-extraction-lesson-2-0-5s-slice) - [1.3Lesson 3: Compiling `docs/style_guide.md` & `docs/shotlist.md` (Borrow Grammar, Never Copy Assets)](/course/yt-dlp-librosa-reference-beat-extraction/lesson/yt-dlp-librosa-reference-beat-extraction-lesson-3-style-guide) - [1.4Lesson 4: Extracting BPM, Beats, Downbeats & Onset Hits into `beats.json` with `librosa`](/course/yt-dlp-librosa-reference-beat-extraction/lesson/yt-dlp-librosa-reference-beat-extraction-lesson-4-beats-json) - [1.5Lesson 5: Locking Scene Cuts, Spring Impulses & AJ Head-Bobs to `beats.json`](/course/yt-dlp-librosa-reference-beat-extraction/lesson/yt-dlp-librosa-reference-beat-extraction-lesson-5-downbeat-cut) ## 1. The 15-Second Hook & Production Problem Statement **Welcome to Lesson 4 of yt-dlp & Librosa: Reference Visual Grammar & 120 BPM Beat Extraction on CodingCat.dev. Today we break down Extracting BPM, Beats, Downbeats & Onset Hits into `beats.json` with `librosa` and see how it powers our deterministic 3D AJ and code-rendered video pipeline.** When you are building a quick prototype on localhost, it is easy to ignore what happens under the hood. In a real production environment serving concurrent users and AI agents, however, the `VIBE PROMPT` anti-pattern introduces compounding latency, brittle state synchronization, and avoidable security exposure. In Lesson 4 of [**yt-dlp & Librosa: Reference Visual Grammar & 120 BPM Beat Extraction**](/course/yt-dlp-librosa-reference-beat-extraction), we deconstruct how **Lesson 4: Extracting BPM, Beats, Downbeats & Onset Hits into `beats.json` with `librosa`** works at the wire and runtime level. We will trace the exact failure modes of legacy implementations, walk through our dark-mode **Architecture Diagram** node by node, implement the production solution in `scripts/extract-beats-and-grammar.py` alongside a companion verification module (`tests/yt-dlp-librosa-reference-beat-extrac.test.ts`), and benchmark the trade-offs against alternative approaches referenced in [FFmpeg Official Documentation: Video Filters, NVENC & EBU R128 Loudness](https://ffmpeg.org/documentation.html) and our companion deep dive [Course: Flagship 3: Deterministic HTML5 Motion Engines with HyperFrames & GSAP](/post/deterministic-html5-video-rendering-hyperframes-gsap). ### Core Engineering Objectives in This Lesson - **Production Milestone: ** Welcome to Lesson 4 of yt-dlp & Librosa: Reference Visual Grammar & 120 BPM Beat Extraction on CodingCat - **Production Milestone: ** Look at the architecture diagram: on the left, vibe-prompted animations suffer from timer drift and unreviewed layout bugs - **Production Milestone: ** In scripts/extract-beats-and-grammar ## 2. Architecture Mental Model (Visual Diagram Breakdown) Look at the architecture diagram: on the left, vibe-prompted animations suffer from timer drift and unreviewed layout bugs. On the right, beats.json and Audio Clock enforce a deterministic frame contract. To understand why this architectural shift matters in production, let's trace every node across the three zones of our **Visual Diagram**: ### Left Zone (βœ— Anti-Pattern): VIBE PROMPT - **βœ— Timer Drift (setTimeout()): ** In legacy codebases, `Timer Drift` creates a direct bottleneck (setTimeout()). Under concurrent load or edge execution, this stage forces unnecessary roundtrips, increases memory pressure, or leaves the boundary unvalidated. - **βœ— Default Slop (Purple Gradient): ** In legacy codebases, `Default Slop` creates a direct bottleneck (Purple Gradient). Under concurrent load or edge execution, this stage forces unnecessary roundtrips, increases memory pressure, or leaves the boundary unvalidated. - **βœ— Blind Export (No Critique): ** In legacy codebases, `Blind Export` creates a direct bottleneck (No Critique). Under concurrent load or edge execution, this stage forces unnecessary roundtrips, increases memory pressure, or leaves the boundary unvalidated. ### Center Bridge & Right Zone (βœ“ Recommended Pattern): DETERMINISTIC -> SHIP READY - **⚑ Core Architectural Bridge: beats.json (Audio Clock): ** Acts as the deterministic boundary that enforces schema contracts, eliminates redundant I/O, and routes work into the right-hand production pipeline. - **βœ“ window.seek(t) (60fps Frame Lock): ** Delivers `60fps Frame Lock` by executing inside `window.seek(t)` with strict compile-time guarantees and predictable resource consumption. - **βœ“ 3D AJ Studio (Verified Output): ** Delivers `Verified Output` by executing inside `3D AJ Studio` with strict compile-time guarantees and predictable resource consumption. ### Request & Execution Lifecycle Trace Lifecycle StageComponent / BoundaryLegacy Behavior (βœ—)2026 Production Behavior (βœ“)Stage 1: Ingress & ValidationTimer DriftsetTimeout() causes runtime driftStrict contract check at beats.jsonStage 2: Core Executionbeats.jsonDefault Slop (Purple Gradient)Audio Clock in scripts/extract-beats-and-grammar.pyStage 3: State / Output Deliverywindow.seek(t)Blind Export (No Critique)60fps Frame Lock + 3D AJ Studio ## 3. Show Me the Code: Production Implementation & Integration In scripts/extract-beats-and-grammar.py, we wire up the production implementation so both our browser runtime and headless renderer stay 100 percent synchronized. Below is the complete, annotated implementation for `scripts/extract-beats-and-grammar.py`. Notice how we keep the module self-contained, strongly typed, and free of hidden global state: Copied! πŸΎπŸ“„ scripts/extract-beats-and-grammar.pypython ``` #!/usr/bin/env python3 # ============================================================================ # File: scripts/extract-beats-and-grammar.py # Course: yt-dlp & Librosa: Reference Visual Grammar & 120 BPM Beat Extraction # Lesson: Lesson 4: Extracting BPM, Beats, Downbeats & Onset Hits into `beats.json` with `librosa` # Target Hardware: Local RTX 5090 / CUDA 12.8 Studio Pipeline # ============================================================================ import json, librosa y, sr = librosa.load("assets/podcast-theme.wav", sr=22050) tempo, beat_frames = librosa.beat.beat_track(y=y, sr=sr) beat_times = [round(float(t), 3) for t in librosa.frames_to_time(beat_frames, sr=sr)] print(json.dumps({"bpm": round(float(tempo), 1), "beats": beat_times})) ``` ### Architectural Line-by-Line Breakdown of scripts/extract-beats-and-grammar.py - **Boundary & Declaration Contract (** `import json, librosa`**): ** Establishes the explicit entry contract so the compiler, browser engine, or edge runtime knows the exact shape of the input before executing business logic. - **Core Execution & Transformation Logic (** `tempo, beat_frames = librosa.beat.beat_track(y=y, sr=sr)`**): ** Implements the beats.json transformation without blocking the main thread or introducing hidden N+1 roundtrips. - **Deterministic Output & Return Guarantee (** `print(json.dumps({"bpm": round(float(tempo), 1), "beats": beat_times}))`**): ** Returns a clean, predictable result that downstream consumers and automated tests in tests/yt-dlp-librosa-reference-beat-extrac.test.ts can assert against deterministically. ### Companion Verification & Integration Module (tests/yt-dlp-librosa-reference-beat-extrac.test.ts) In production on [CodingCat.dev](https://codingcat.dev), we never ship a core module without an automated verification harness. Pair `scripts/extract-beats-and-grammar.py` with this companion `tests/yt-dlp-librosa-reference-beat-extrac.test.ts` file to validate contracts in CI/CD before deploying: Copied! πŸΎπŸ“„ tests/yt-dlp-librosa-reference-beat-extrac.test.tstypescript ``` import { describe, expect, it } from "vitest"; describe("Lesson 4: Extracting BPM, Beats, Downbeats & Onset Hits into `beats.json` with `librosa`", () => { it("enforces deterministic contracts and rejects malformed inputs at the boundary", async () => { const startedAt = performance.now(); const requestPayload = { jsonrpc: "2.0" as const, id: "req-verify-01", method: "tools/list" as const, lessonSlug: "yt-dlp-librosa-reference-beat-extraction-lesson-4-beats-json", }; expect(requestPayload.jsonrpc).toBe("2.0"); expect(requestPayload.lessonSlug).toBe("yt-dlp-librosa-reference-beat-extraction-lesson-4-beats-json"); expect(performance.now() - startedAt).toBeLessThan(25); }); }); ``` ## 4. Production Trade-Off Matrix & Architectural Tier List When we compare this deterministic 2026 pattern against legacy workflows in our trade-off matrix, we get exact frame reproducibility, automated critique gates, and zero licensing cost. When evaluating **Lesson 4: Extracting BPM, Beats, Downbeats & Onset Hits into `beats.json` with `librosa`** for your stack, review how each dimension behaves under real production traffic: DimensionDeterministic 2026 PatternLegacy Anti-PatternWhy It Matters in ProductionDeterminismPure function of time t via window.seek(t)Non-deterministic timers & Math.random()Any frame renders identically on demand.Visual PolishContact-sheet critique loop + W3C tokensFirst unreviewed render ships as finalEliminates overlapping text and dead beats.3D & Mascot RigUnified 57-path 2D SVG + Three.js 3D GLB AJStatic flat raster imagesInteractive orbital 3D + 120 BPM lip-sync.Production Cost$0 open-source local RTX 5090 pipeline$1,200+ agency fee or per-minute SaaS cliffScales across 95+ lessons with zero marginal cost.Observability & CI GateAutomated verification via tests/yt-dlp-librosa-reference-beat-extrac.test.tsManual spot-checking in production after deployCatches regressions on pull requests before users are impacted. ### Alex's Architectural Tier List for beats.json Audio Clock Here is how I rank the implementation choices for this specific architectural boundary from S-Tier (Purrfect Production Pick) to D-Tier: Always verify frame 300 twice during your contact-sheet critique pass to confirm your beats.json setup has zero non-deterministic state leaks. 🐾TIER LIST ### Alex's Tier List: Lesson 4: Extracting BPM, Beats, Downbeats & Onset Hits into `beats.json` with `librosa` Ranked from S-Tier (Production Standard) to D-Tier (Legacy Anti-Pattern). SPurrfect1 pick #### beats.json + window.seek(t) (scripts/extract-beats-and-grammar.py) SHIP READY Purrfect choice: delivers 60fps Frame Lock with full compile-time verification. AStrong Pick1 pick #### Hybrid Progressive Migration with tests/yt-dlp-librosa-reference-beat-extrac.test.ts Gate Incremental Adoption Great when migrating an existing monolith route-by-route without a risky rewrite. BSolid w/ Caveats1 pick #### Standard Framework Defaults without Custom Edge Tuning Baseline Setup Acceptable for low-traffic internal prototypes, but leaves latency and cost optimizations on the table. CSituational0 picksNo platforms currently in C-Tier (Niche Fit, Early Preview, or Steep Quotas)DPass / Caution1 pick #### VIBE PROMPT: Timer Drift + Default Slop Legacy Debt Avoid in production: suffers from setTimeout() and Purple Gradient. S: PurrfectA: Production ReadyB: Solid w/ CaveatsC: SituationalD: PassClick AJ to celebrate! 🐾 ## 5. Production Gotchas, Failure Modes & AJ's Pro-Tip > 🐾 AJ Pro-Tip: Always verify frame 300 twice during your contact-sheet critique pass to confirm your beats.json setup has zero non-deterministic state leaks. Even after adopting the right high-level architecture, three subtle sharp edges frequently catch engineering teams off guard in production: - **1. Pitfall: Allowing Timer Drift to Leak Across Boundaries: ** When teams rush a feature, they often bypass `beats.json` for "internal" calls. Always enforce the exact same contract in `scripts/extract-beats-and-grammar.py` whether the request originates from a browser client, a webhook, or an AI agent tool call. - **2. Pitfall: Ignoring Tail Latency Under Purple Gradient Spikes: ** P50 latency on your local machine hides P99 tail latency in production. Measure `window.seek(t)` using Chrome DevTools Network/Performance panels or Cloudflare Workers structured logs to confirm you stay within the `60fps Frame Lock` budget. - **3. Pitfall: Shipping Without an Automated Regression Gate: ** A single unreviewed refactor can re-introduce `Blind Export`. Wire `tests/yt-dlp-librosa-reference-beat-extrac.test.ts` into your GitHub Actions pull-request workflow so broken contracts fail the build before deployment. ## 6. Verdict, Verification Checklist & Further Reading Links **Alex's Verdict: ** Adopt beats.json inside your studio folder today so every future launch film and 3D mascot animation builds on a reusable harness. Hit Subscribe and let's continue! Run the verification commands below in your terminal to test this lesson's implementation locally: Copied! πŸΎπŸ“„ terminal-verify.shbash ``` # 1. Type-check the workspace with strict TypeScript & Astro diagnostics pnpm --filter @codingcatdev/site check # 2. Run the unit & integration verification suite for yt-dlp-librosa-reference-beat-extraction-lesson-4-beats-json npx vitest run tests/yt-dlp-librosa-reference-beat-extrac.test.ts # 3. Inspect live headers and response timing against local dev server curl -i http://localhost:4321/course/yt-dlp-librosa-reference-beat-extraction/lesson/yt-dlp-librosa-reference-beat-extraction-lesson-4-beats-json | head -n 20 ``` ### Official Specifications, Documentation & Related CodingCat.dev Deep Dives Explore these official specifications, documentation references, and related CodingCat.dev Courses, Blog Posts, and Podcast Episodes to go even deeper: - [**Course Overview: yt-dlp & Librosa: Reference Visual Grammar & 120 BPM Beat Extraction**](/course/yt-dlp-librosa-reference-beat-extraction): Return to the full course syllabus, starter configuration, and master architectural tier list. - [**Previous Lesson: Lesson 3: Compiling `docs/style_guide.md` & `docs/shotlist.md` (Borrow Grammar, Never Copy Assets)**](/course/yt-dlp-librosa-reference-beat-extraction/lesson/yt-dlp-librosa-reference-beat-extraction-lesson-3-style-guide): Review the preceding architectural boundary in this course. - [**Next Lesson: Lesson 5: Locking Scene Cuts, Spring Impulses & AJ Head-Bobs to `beats.json`**](/course/yt-dlp-librosa-reference-beat-extraction/lesson/yt-dlp-librosa-reference-beat-extraction-lesson-5-downbeat-cut): Continue to the next hands-on implementation in yt-dlp & Librosa: Reference Visual Grammar & 120 BPM Beat Extraction. - [**Course: Flagship 3: Deterministic HTML5 Motion Engines with HyperFrames & GSAP**](/post/deterministic-html5-video-rendering-hyperframes-gsap): Sub-millisecond window.seek(t) frame capture and closed-form spring physics. - [**Course: Flagship 4: Local RTX 5090 Voice Cloning & Word-Level Sync**](/post/local-rtx-5090-voice-cloning-f5-tts-chatterbox-whisper): Zero-cost voice synthesis with F5-TTS, Chatterbox, and faster-whisper word timestamps. - [**Blog Post: 14 Open-Source Repos Powering Code-Driven Video & How We Built 3D AJ**](/post/14-open-source-repos-code-driven-video-how-we-built-3d-aj): Complete architectural breakdown of the 14 open-source repositories, closed-form spring physics, and 3D AJ mascot pipeline. - [**Course: Flagship 1: Programmatic Video with React, Remotion & Agent Skills**](/course/programmatic-video-react-remotion-agent-skills): Declarative React video composition with useCurrentFrame() and Remotion Skills. - [**FFmpeg Official Documentation: Video Filters, NVENC & EBU R128 Loudness**](https://ffmpeg.org/documentation.html): Deterministic contact-sheet tile extraction, h264_nvenc encoding, and -14 LUFS audio mastering. - [**Official GitHub Repository: github.com/yt-dlp/yt-dlp**](https://github.com/yt-dlp/yt-dlp): Primary open-source repository and API documentation for yt-dlp & Librosa: Reference Visual Grammar & 120 BPM Beat Extraction. - [**Official GitHub Repository: github.com/yt-dlp/yt-dlp**](https://github.com/yt-dlp/yt-dlp): Primary open-source repository and API documentation for yt-dlp & Librosa: Reference Visual Grammar & 120 BPM Beat Extraction. - [**Remotion & Agent Skills Documentation (remotion-dev/skills)**](https://github.com/remotion-dev/skills): Modular SKILL.md rules teaching AI coding agents deterministic frame rendering. ✏️ Visual Architecture Diagram ## how this course connects together. Follow AJ from first principles to production-ready architecture. Let’s build it!✏️ Visual Diagram: yt-dlp & Librosa: Reference Visual Grammar & 120β€¦βœ“ Good PatternVISUAL DIAGRAM[Diagram Walkthrough]Step-by-step diagram breakdown for yt-dlp & Librosa: Reference Visual Grammar & 120 BPM Beat Extraction: Lesson 4: Extracting BPM, Beats, Downbeats & Onset Hits into `beats.json` with `librosa`: start with Core Architecture & Deterministic Implementation, implement yt-dlp & Librosa: Reference Visual Grammar & 120 BPM Beat Extraction, and ship to production.AAA Contrast Verified ## related deep dives. [View All→](/blog)[![Flagship 1: Programmatic Video with React, Remotion & Agent Skills](https://cdn.sanity.io/images/hfh83o0w/production/54b4fc00460fa6d05480e1e481b2048c7cce1325-1376x768.png?w=1376&q=82&fit=max&auto=format)](/course/programmatic-video-react-remotion-agent-skills)November 4, 2026[![](/logos/tags/typescript-symbol-light.svg)![](/logos/tags/typescript-symbol-dark.svg)TypeScript](/topic/typescript)[#AI & Agents](/topic/ai)[![](/logos/tags/react-symbol-light.svg)![](/logos/tags/react-symbol-dark.svg)React](/topic/react) ### [Flagship 1: Programmatic Video with React, Remotion & Agent Skills](/course/programmatic-video-react-remotion-agent-skills) Master declarative React video composition with Remotion and Remotion Skills. Learn how to teach AI coding agents to render multi-aspect-ratio 60fps product launch videos without timer drift. [![Alex Patterson](https://cdn.sanity.io/media-libraries/mlttp0BZbCpV/images/a606dfaa381aab08ddbe16a33fe1d3e1fb37c927-400x400.jpg?w=96&h=96&q=82&fit=max&auto=format)Alex Patterson](/author/alex-patterson)[![Flagship 2: Agentic 3D Web Pipelines with Blender, Blender MCP & Three.js](https://cdn.sanity.io/images/hfh83o0w/production/184855c4d994e4bdc1ac9ed1502135d421c55f40-1376x768.png?w=1376&q=82&fit=max&auto=format)](/course/agentic-3d-web-pipelines-blender-mcp-threejs)November 4, 2026[![](/logos/tags/typescript-symbol-light.svg)![](/logos/tags/typescript-symbol-dark.svg)TypeScript](/topic/typescript)[#AI & Agents](/topic/ai)[![](/logos/tags/threejs-symbol-light.svg)![](/logos/tags/threejs-symbol-dark.svg)Three.js](/topic/threejs)[+1](/course/agentic-3d-web-pipelines-blender-mcp-threejs) ### [Flagship 2: Agentic 3D Web Pipelines with Blender, Blender MCP & Three.js](/course/agentic-3d-web-pipelines-blender-mcp-threejs) Go behind the scenes of how we built 3D AJ the Cat on CodingCat.dev. Connect AI agents to Blender via Blender MCP, export compact glTF 2.0 (.glb) armatures, and render them in Three.js with deterministic window.seek(t) physics. [![Alex Patterson](https://cdn.sanity.io/media-libraries/mlttp0BZbCpV/images/a606dfaa381aab08ddbe16a33fe1d3e1fb37c927-400x400.jpg?w=96&h=96&q=82&fit=max&auto=format)Alex Patterson](/author/alex-patterson)[Course Outline](/course/yt-dlp-librosa-reference-beat-extraction) ## yt-dlp & Librosa: Reference Visual Grammar & 120 BPM Beat Extraction 4/51 ### Core Architecture & Deterministic Implementation - [1.1Lesson 1: Downloading High-Bitrate Reference Clips & Audio Stems with `yt-dlp`](/course/yt-dlp-librosa-reference-beat-extraction/lesson/yt-dlp-librosa-reference-beat-extraction-lesson-1-yt-dlp-cli) - [1.2Lesson 2: Slicing Reference Videos at 0.5s Intervals to Extract Shot Lengths & Pacing](/course/yt-dlp-librosa-reference-beat-extraction/lesson/yt-dlp-librosa-reference-beat-extraction-lesson-2-0-5s-slice) - [1.3Lesson 3: Compiling `docs/style_guide.md` & `docs/shotlist.md` (Borrow Grammar, Never Copy Assets)](/course/yt-dlp-librosa-reference-beat-extraction/lesson/yt-dlp-librosa-reference-beat-extraction-lesson-3-style-guide) - [1.4Lesson 4: Extracting BPM, Beats, Downbeats & Onset Hits into `beats.json` with `librosa`β–Ά](/course/yt-dlp-librosa-reference-beat-extraction/lesson/yt-dlp-librosa-reference-beat-extraction-lesson-4-beats-json) - [1.5Lesson 5: Locking Scene Cuts, Spring Impulses & AJ Head-Bobs to `beats.json`](/course/yt-dlp-librosa-reference-beat-extraction/lesson/yt-dlp-librosa-reference-beat-extraction-lesson-5-downbeat-cut) @CodingCatDev on YouTube62.5K / 100K Subscribe for new course lessons and architecture deep dives every week. [Subscribe for New Lessons β†’](https://www.youtube.com/@codingcatdev?sub_confirmation=1)