Smart Chapters

Smart Chapters (Lua Script)

Smart Chapters is a lightweight Lua script for OBS Studio that lets you create timestamped chapter markers while streaming or recording. Chapters are written directly to a plain text file, making it easy to reuse them later for YouTube chapters, editing timelines, or VOD descriptions.

You can add chapters manually with a hotkey or let OBS generate them automatically whenever you change scenes perfect for structured content and clean post-production workflows.

How It Works

The script tracks the elapsed stream or recording time and writes a new line to a chapter file whenever a chapter is triggered. Each entry includes the timestamp and a descriptive label, keeping everything simple, readable, and portable.

At the start of every new session, the script inserts a header line so multiple sessions can safely share the same file without confusion.

Features

• Manual chapter markers: drop a chapter at any moment using a hotkey
• Automatic scene chapters: optionally add a chapter every time the scene changes
• Scene label overrides: map OBS scene names to custom chapter labels
• Plain text output: human-readable, editor-friendly chapter file
• Session separators: clearly mark the start of each stream or recording
• No plugins required: runs as a simple OBS Lua script

Installation

1. Open OBS Studio.
2. Go to Tools → Scripts.
3. Click the + button and load smart_chapters.lua.

Configuration

1. Set the chapters file
   In the script settings, choose a file path such as: D:\OBS\chapters.txt
2. Optional: enable auto scene chapters
   Enable “Auto add chapter on scene change” to write a new chapter line automatically every time you switch scenes.
3. Scene-specific labels (optional)
   Use one mapping per line in Scene label overrides:

   Intro = Intro
   Gameplay = Gameplay Start
   Boss = Boss Fight
   BRB Screen = Break

   The left side must match the OBS scene name exactly. The right side is the text that will appear in the chapters file.

Hotkey Setup

To add chapters on demand, bind a hotkey:

1. Open Settings → Hotkeys.
2. Find Smart Chapters: Add chapter (current scene).
3. Assign a key combination.
4. Press the hotkey during a stream or recording to drop a chapter instantly.

Resulting File

The chapters file will look like this:

# --- New session: 2025-12-01 20:00:15 ---
00:00 – Intro
03:25 – Gameplay Start
14:10 – Boss Fight
23:42 – Break

Ideal Use Cases

• YouTube uploads: copy timestamps directly into video descriptions
• Long streams: mark segments, topics, or highlights in real time
• Editing workflows: use chapter markers as a reference timeline
• Structured shows: podcasts, tutorials, and event-style streams