📼 slides-tape

The terminal-first, Markdown-native presentation engine. Write slides, record terminals, automate browsers — all from one CLI.

✨ What is slides-tape?

slides-tape turns Markdown files into fully-featured technical presentations. It is built specifically for developers who want to showcase code, terminal operations, and web interfaces seamlessly. It combines:

• 🖥️ A live browser viewer — serve your slides as a beautiful interactive presentation with synchronized Presenter and Audience modes.
• 🎙️ Audio Narrative Sync & Ducking — record your voiceover live, mux background music (--bg-music), and let FFmpeg automatically duck the music when you speak.
• 🎬 A terminal video recorder — export any bash/Python/Node script to MP4 using native Rust-speed canvas rendering.
• 🌐 A headless browser automation engine — record real UI flows with Playwright, embedded directly into your slides.
• 📦 A slide deck exporter — export your entire Markdown presentation to a standalone video file with cinematic transitions.

🌐 Official Documentation Site

📦 Installation

# Install globally
npm install -g slides-tape

# Or run without installation
npx slides-tape serve talk.md

Requires Node.js 18+ and ffmpeg (system install or auto-bundled via @ffmpeg-installer/ffmpeg)

🚀 Quick Start

# 1. Serve your slides live in the browser
slides-tape serve my-talk.md

# 2. Record a terminal script to MP4
slides-tape run deploy.sh -o deploy.mp4

# 3. Export entire slide deck to video
slides-tape export my-talk.md -o talk.mp4

# 4. Run a standalone web UI demo
slides-tape web demo.md

# 5. Export a web demo to video
slides-tape web demo.md -o ui-tour.mp4

📝 Markdown Authoring Guide

Author your presentations purely in Markdown. Separate slides using ---.

The Basics

# 🚀 Introduction
Welcome to slides-tape!

> Note: These are speaker notes! They only show up in the presenter dashboard.

---

<!-- duration: 5s -->
<!-- columnCount: 2 -->

# A Two-Column Slide
This slide will auto-play for 5 seconds when exported.

The `columnCount: 2` frontmatter automatically splits this slide's content into two balanced columns!

Staggered Fragments

Use the <!-- fragment --> marker to reveal content step-by-step.

# Why slides-tape?
<!-- fragment -->
1. It's written in Markdown.
<!-- fragment -->
2. It's built for developers.

Advanced Code Highlighting

slides-tape features an intelligent, step-by-step code highlighting engine. When presenting, press the H key to dim unfocused lines and spotlight specific code segments.

There are two ways to define highlights:

1. Internal Markers (Inline)

Append // highlight or // [!code highlight] to the end of a line. The engine will strip the comment visually and register it as a highlight step.

const user = await db.getUser(id);
if (!user) throw new Error("Not found"); // highlight
return res.json(user); // highlight

Pressing H twice will highlight each tagged line sequentially.

2. External Markers (Sequence)

Use the <!-- highlight: ... --> HTML comment to define a sequence of line numbers.

<!-- highlight: 2, 4-5 -->
```javascript
const a = 1;
const b = 2;
const c = 3;
const d = 4;
const e = 5;

Pressing H once highlights line 2. Pressing it again highlights lines 4 and 5 simultaneously.

🎭 The Presentation Engine (UI Modes)

When you run slides-tape serve my-talk.md, the local server spawns a live WebSockets-synchronized presentation environment.

Navigate to different modes using URL parameters:

1. Audience Mode (/?mode=audience)

The default, distraction-free view designed to be dragged onto the projector or shared over Zoom.

• True 1080p Scaling: The canvas strictly enforces a 16:9 1920x1080 grid that automatically scales perfectly to fit any window size without breaking layouts.
• Fluid Typography: Embedded code blocks, Mermaid diagrams, and typography seamlessly adapt.

2. Presenter Mode (/?mode=presenter)

A powerful, dual-pane desktop-style dashboard for the speaker.

• Dual-Pane View: See your "Current Slide" alongside a dimmed preview of your "Next Slide/Fragment".
• Real-time Highlighting: Code block dimming and highlighting renders natively inside your dashboard in real-time as you press H.
• Speaker Notes: Dedicated scrolling panel for your > Note: blocks.
• Thumbnail Strip: A scrollable mini-map of your entire deck for rapid non-linear navigation.
• Synchronization: The Presenter UI acts as the master remote. Every slide transition, fragment reveal, and highlight step is instantly broadcasted to all active Audience viewers.

🌐 Web Automation Directives (web run)

slides-tape embeds a full Playwright headless browser engine. You can write scripts directly inside ```web run blocks to automatically record UI demos.

Highlighting Elements (The Visual Laser Pointer)

The web engine allows you to visually direct the audience's attention using CSS glow boxes and the powerful --dim flag (which dims the rest of the browser screen).

# @highlightText "Login" --dim
# @highlightParent "Submit Button" 2 "#4361ee" --dim

Automation Commands

# @goto <url>                    Navigate to a URL
# @wait <time>                   Wait (e.g. 2s, 500ms)
# @waitUntilIdle                 Wait for network activity to settle
# @clickText "text"              Click element containing specific text
# @clickLabel "label"            Click field by its associated label
# @click <selector>              Click an element by CSS
# @type <selector> "text"        Type text (with human-like jitter)
# @typeText "text" into "selector" Natural language typing
# @clear <selector>              Clear input field or reset <form>
# @scroll <selector>             Manual scroll-to-element
# @scrollToText "text"           Scroll until text is centered
# @focus <selector>              Set browser focus
# @press <key>                   Simulate keyboard key press (e.g. Enter)
# @viewport <w> <h>              Resize browser window

💻 Terminal Automation & .tre Event System

Record highly customized, perfectly paced CLI tutorials using ```bash run or slides-tape run.

Commands

# @type "cmd"                    Simulates human typing
# @wait <time>                   Pause (e.g. 2s, 500ms)
# @await port <n>                Wait for server on port
# @await file <path>             Wait for file to exist
# @hide / @show                  Run commands silently (background tasks)
# @echo off                      Stop echoing typed commands
# @clear                         Clear terminal screen
# @title "text"                  Change terminal title
# @print "text"                  Inject raw text/ANSI into stream
# @ps1 "prompt"                  Change shell prompt on-the-fly

The 2-Phase .tre System

Every execution saves a .tre (Terminal Recording Event) file. This decouples the recording phase from the rendering phase! You can re-render a 10-minute terminal session instantly with new themes or fonts—without actually re-running the network calls or builds.

slides-tape run deploy.sh --load-events deploy.tre --speed 2 --font-size 20

🛠️ CLI Reference

serve <file.md>

Starts the live presentation server. | Option | Description | Default | | ----------------------------------- | ------------------------------ | ------- | | --port <n> | HTTP port | 3000 | | -d, --autoplay-duration <s/ms> | Wait time per slide in seconds | 4 | | --no-open | Don't open browser | — |

export <file.md>

Bakes the entire slide deck to MP4/WebM. | Option | Description | Default | | -------------------------- | ---------------------------- | ----------- | | -o, --output <path> | Output file | <md>.mp4 | | -r, --resolution <WxH> | Video resolution | 1920x1080 | | -t, --transition <ms> | Crossfade duration | 500 | | --transition-type <n> | fade | zoom | wiperight... | fade | | --no-run | Skip all run blocks | — | | --no-narrative | Disable audio mixing | — | | --theme <name> | Export theme (dark/light) | dark | | --bg-music <path> | Path to background music | — | | --bg-volume <vol> | Background music volume | 0.2 | | --screenshot | Save PNG of every slide | — |

run <script.sh>

Renders a terminal script to MP4. | Option | Description | Default | | ------------------------ | --------------------------------- | ------------------ | | --speed <n> | Playback speed multiplier | 1 | | --cols / --rows <n> | Terminal dimensions | 120x30 | | --font-size <px> | Font size (pixels) | 14 | | --font-family <name> | Font family name | "JetBrains Mono" | | --load-events <path> | Re-render from a saved .tre log | — | | --skip-idle <ms> | Cap idle gaps longer than ms | off |

web <demo.md>

Headless browser rendering. | Option | Description | Default | | ------------------------ | ---------------- | ----------- | | -o, --output <path> | Target MP4 path | — |

📚 Further Reading & Roadmap

• Webcam Integration (Upcoming): Declarative PIP avatars and full-screen presenter webcam recording.
• Web Automation Guide
• Terminal Event Log (.tre) Guide
• Examples Showcase

For bugs, feature requests, or discussions:

👉 https://github.com/alex-migwi/slides-tapes-community

📄 License

CC-BY-NC-4.0 © Alex Muturi J.