Skip to content
Back to search

beatdeck

MarketplaceWorks with Claude CodeGitHub

beatdeck: talks as beats, not slides.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/borjaperfra--beatdeck/badge.svg)](/listings/borjaperfra--beatdeck)

HTML

<a href="/listings/borjaperfra--beatdeck"><img src="/api/listings/borjaperfra--beatdeck/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "beatdeck",
  3. "owner": {
  4. "name": "Borja Pérez Francés",
  5. "url": "https://github.com/borjaperfra"
  6. },
  7. "description": "beatdeck: talks as beats, not slides.",
  8. "plugins": [
  9. {
  10. "name": "beatdeck",
  11. "source": "./",
  12. "description": "Skill for building talks with beatdeck: source material → content audit → beat map → scenes → verified offline build.",
  13. "version": "0.5.1"
  14. }
  15. ]
  16. }
README.md · README · 164 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # beatdeck
  2. [![ci](https://github.com/borjaperfra/beatdeck/actions/workflows/ci.yml/badge.svg)](https://github.com/borjaperfra/beatdeck/actions/workflows/ci.yml)
  3. **Try it:** [the demo deck](https://borjaperfra.github.io/beatdeck/) · [the Kernel Panic showcase](https://borjaperfra.github.io/beatdeck/kernel-panic/)
  4. — click or → to advance, O for the overview, P for the presenter window.
  5. **Talks as beats, not slides.** A fixed 1920×1080 React stage where one click is one beat. Motion is
  6. authored, the state is `{ scene, beat }`, every beat rebuilds from the URL, and the build runs with Wi-Fi off.
  7. It comes with a presenter window, an overview and a debug panel, plus a Claude Code skill that writes the talk
  8. with you.
  9. ![The demo deck: title](docs/media/demo-title.jpg)
  10. ```bash
  11. npx degit borjaperfra/beatdeck my-talk && cd my-talk
  12. npm run init -- --title "My talk" --author "Your Name" --lang en # --theme light for bright rooms, --demo to keep the demo
  13. npm install
  14. npm run dev # http://127.0.0.1:5173
  15. ```
  16. `init` turns the copy into a clean talk project: it removes the showcase, the plugin files, this README and
  17. beatdeck's CI, renames the package, writes title, author, language and theme into the deck, and leaves a blank
  18. two-scene starter (title, questions) plus `reference/`, a content audit, a runbook and a CI workflow for the
  19. talk. `--demo` keeps the demo deck instead.
  20. ## Why
  21. Slides are pages: you flip them. A talk that feels like a live system, with a diagram that grows, a counter
  22. that runs or a crash that cuts to black, is a sequence of **beats** inside a few **scenes**. beatdeck makes
  23. that the model:
  24. - **One click = one beat.** Clickers (PageDown/PageUp), arrows, space, number keys and mouse all work.
  25. - **Deterministic.** The whole state is `{ scene, beat }` plus the beat's automatic sub-state. `#3.4` in the
  26. URL always renders the same frame, whether you got there going forwards, going back, jumping or refreshing.
  27. - **Automatic motion only where you want it.** A beat can run a GSAP timeline (a boot log, a counter, a
  28. cascade). Everything else waits for the speaker.
  29. - **One stage.** Fixed 1920×1080, scaled with black letterbox. Nothing reflows on the projector.
  30. - **Offline.** Fonts, images and QR codes are all bundled or computed locally. `npm run build` fails if anything
  31. references the network.
  32. - **Operator tools.** A presenter window (P) with current/next beat, notes and a timer, synced over
  33. BroadcastChannel. An overview (O) to jump anywhere. Blackout (B). A debug panel with `?debug=1`.
  34. ![The demo deck: the state diagram, built one node per click](docs/media/demo-state.jpg)
  35. ## How a deck looks
  36. ```
  37. deck/
  38. deck.config.ts title, speaker, QR target, timings
  39. scenes.ts the beat map: scenes → beats (+ source refs and speaker notes)
  40. timeline.ts automatic beats: initialLive(pos) + timeline(pos, host)
  41. index.tsx defineDeck({...}) + the Stage (layer order) + theme
  42. scenes/*.tsx one layer per scene
  43. ```
  44. ```tsx
  45. import { Reveal, Scene, useScene } from 'beatdeck';
  46. function Idea_() {
  47. const { here, b } = useScene();
  48. return (
  49. <>
  50. <Reveal on={here} x={150} y={150}><h1 className="t-statement">Slides are pages.</h1></Reveal>
  51. <Reveal on={here && b >= 1} x={150} y={360}><h1 className="t-statement">Talks are beats.</h1></Reveal>
  52. </>
  53. );
  54. }
  55. export const Idea = () => <Scene index={1}><Idea_ /></Scene>;
  56. ```
  57. Built in: `Reveal`, `Scene`, `CountUp`, `Typewriter`, `Terminal` (real commands and output, character-exact,
  58. with highlights and labels), `NodeBox` + `Arrow` (diagrams that draw themselves), `Plot` + `Zone` / `Series` /
  59. `Marker` / `PlotLabel` (charts), `QR` (computed locally).
  60. The demo in `deck/` (7 scenes, 24 beats) uses every pattern: an automatic boot, a strike-through, a diagram
  61. built node by node, terminal output with highlights, a chart, a self-counting number, and a locally generated
  62. QR code. A new talk starts from a blank two-scene deck instead (`init --demo` keeps this one).
  63. ## Commands
  64. | | |
  65. | --- | --- |
  66. | `npm run dev` | dev server at `http://127.0.0.1:5173/#1.1` |
  67. | `npm run build` | typecheck + bundle + offline check → `dist/` (self-contained, any static server) |
  68. | `npm run present` | build and open the production build locally |
  69. | `npm run shot -- 3 4.2` | quick frames of a few beats (a scene, a beat, a range) from the dev server → `artifacts/shot/`, with the same text/layout audit. |
  70. | `npm run verify` | every beat walked forwards, walked back and reloaded from its URL, frames pixel-compared, reduced motion, QR decoded, presenter + overview, contact sheet → `artifacts/verify/`. Fails on any mismatch, console error or remote request. Uses Chrome or Edge if installed, else Playwright's Chromium (`npx playwright-core install chromium`). |
  71. ## Updating a talk
  72. The engine is copied into each talk, so a talk keeps working even if beatdeck changes. To take a newer version:
  73. ```bash
  74. npm run upgrade # latest; or: npm run upgrade -- --ref v0.4.0 (--dry-run to preview)
  75. npm install && npm run verify
  76. ```
  77. `upgrade` replaces the engine (`src/beatdeck/`, the skill, the scripts, the base themes), updates engine
  78. dependencies and adds new scripts. It never touches `deck/`, `index.html` or `docs/`. Engine files you edited
  79. are backed up to `.beatdeck-backup/`; shared config you edited (`vite.config.ts`, `tsconfig.json`, …) is left as
  80. is, with the new version beside it as `*.beatdeck-new`. `.beatdeck.json` records the version.
  81. Talks created before `upgrade` existed (≤ 0.3.0) bootstrap it once (`--clean` also removes what early copies
  82. carried over from this repo: the showcase and its non-MIT assets, the plugin files, beatdeck's CI):
  83. ```bash
  84. npx degit borjaperfra/beatdeck/scripts .beatdeck-tmp && node .beatdeck-tmp/upgrade.mjs --clean && rm -rf .beatdeck-tmp
  85. ```
  86. ## Keys
  87. → ↓ PageDown, click, Space (fullscreen) next · ← ↑ PageUp previous · 1–9 scene · Home / End ·
  88. F fullscreen · O overview · P presenter window · B blackout. URL flags: `?view=presenter`, `?debug=1`,
  89. `?capture=1` (verification), `?reduced=1` (reduced motion).
  90. ## The skill
  91. `skills/building-a-beatdeck/` teaches an agent the whole workflow: collect the source (it ships a PPTX
  92. extractor), write a content audit so nothing is lost or invented, design the beat map, apply a theme, build
  93. the scenes, then run `npm run verify` and look at every frame before calling it done.
  94. **Claude Code** (plugin):
  95. ```
  96. /plugin marketplace add borjaperfra/beatdeck
  97. /plugin install beatdeck@beatdeck
  98. ```
  99. **Any agent that reads `SKILL.md`**: copy `skills/building-a-beatdeck/` to `~/.claude/skills/` (or your
  100. agent's skills folder). Inside a scaffolded deck it is already there, and `AGENTS.md` points to it.
  101. Then ask for something like *"Turn talk.pptx into a beatdeck"* or *"Add a scene where the architecture grows
  102. to three servers"*.
  103. ## Themes
  104. `themes/neutral.css` is the default: near-black stage, off-white Inter + JetBrains Mono, one accent (`--accent`),
  105. hairlines. `themes/light.css` is for bright rooms. To brand a deck, copy the theme and change the tokens. Fonts
  106. must be local (`@fontsource*` packages or `.woff2` files).
  107. ## Showcase: Kernel Panic
  108. ![Kernel Panic: the current architecture scene](docs/media/kernel-panic-architecture.jpg)
  109. `examples/kernel-panic/` is the production talk beatdeck was extracted from. *Escalando inferencia* by Cristian
  110. Córdova, KERNEL PANIC #01, Madrid. It has 47 beats, a particle field that survives scene changes, an SVG
  111. architecture that grows from one GPU to Cloudflare + Kubernetes, and a 520 ms kernel panic that cuts to
  112. absolute black.
  113. ```bash
  114. npm run example:kernel-panic
  115. ```
  116. Its assets are not MIT; see [examples/kernel-panic/ASSETS-CREDITS.md](examples/kernel-panic/ASSETS-CREDITS.md).
  117. ## Stack
  118. React 18, TypeScript, Vite, GSAP for timelines, SVG for diagrams, Canvas 2D for particles, CSS for type. No
  119. backend, no CDN, no remote fonts. The engine is in `src/beatdeck/` and never imports from the deck.
  120. ## License
  121. MIT for the code and docs. Third-party assets in the showcase keep their own terms.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.