Converts a podcast episode JSON file into a themed chat-UI video (MP4). Audio clips are sequenced by their measured durations and the final video is frame-perfectly synced with the audio track.
npm install -g playchat
Or run directly with npx:
npx playchat episode.json --record
# HTML preview (default theme: kakaotalk, files go to <input-json-dir>/output/<timestamp>-<name>/)
npx playchat episode.json
# HTML preview to an explicit output folder
npx playchat episode.json --output ./my-output --theme imessage
# Record to MP4 (output goes to <input-json-dir>/output/<timestamp>-<name>/)
npx playchat episode.json --record
# Record with explicit output folder, custom theme and pause
npx playchat episode.json --output ./my-output --record --theme kakaotalk --pause 4000
# Record a horizontal (16:9) video at 4K with a media pane on the right
npx playchat episode.json --record --orientation horizontal --resolution 4k
npx playchat <input.json> [--output <dir>] [--record] [--record-full] [--segments] [--theme <id>] [--pause <ms>] [--orientation <o>] [--resolution <r>] [--no-avatar] [--no-bottom]
| Flag | Default | Description |
|---|---|---|
--output <dir> | auto-generated | Output folder path |
--record | (off) | Produce an MP4 using static images (fast; one screenshot per dialogue) |
--record-full | (off) | Produce an MP4 using full frame-by-frame recording (slow; more CPU) |
--segments | (off) | Also produce individual MP4 videos per section (requires --record or --record-full) |
--theme <id> | kakaotalk | Chat theme to render |
--pause <ms> | 3000 | Silence between messages that have no audio file |
--orientation <o> | vertical | Frame orientation: vertical (9:16) or horizontal (16:9) |
--resolution <r> | 1k | Output resolution: 1k, 2k, or 4k |
--no-avatar | (off) | Hide avatar circles and sender names |
--no-bottom | (off) | Hide the show-name band/label (shown by default) |
When --output is omitted, files are written next to the input JSON, under its output/ folder:
<input-json-dir>/output/<YYYYMMDD-HHmmss>-<json-name>/
output.html ← rendered chat page (always)
output.mp4 ← final video (with --record or --record-full)
first_bubble.png ← first message bubble frame (with --record or --record-full)
last_bubble.png ← last message bubble frame (with --record or --record-full)
highlights/ ← highlight clip MP4s (when input JSON has highlights)
manifest.json ← run metadata and file list
Example: for path/to/episode.json → path/to/output/20260414-143025-name/
A full example render from fixtures/example1/episode.json is committed under fixtures/example1/output/:
| File | Description |
|---|---|
fixtures/example1/output/output.html | Chat UI (open in a browser) |
fixtures/example1/output/output.mp4 | Sample recording from --record (same episode) |
fixtures/example1/output/first_bubble.png | First message bubble frame from that recording |
fixtures/example1/output/last_bubble.png | Last message bubble frame from that recording |
fixtures/example1/output/manifest.json | Run metadata for that sample |
Bubble still frames (from the same sample --record run):
Video output (recorded with --record, KakaoTalk theme):
Hosted HTML preview (layout and remote assets; no clone required):
Local preview (best match to how the CLI writes files): clone the repo and open fixtures/example1/output/output.html, play fixtures/example1/output/output.mp4, or inspect fixtures/example1/output/first_bubble.png and fixtures/example1/output/last_bubble.png; or regenerate into that folder:
npx playchat fixtures/example1/episode.json --record --segments
npx playchat fixtures/example2/episode.json --record --segments
npx playchat fixtures/example1/episode.json --record --segments --theme kakaotalk --output fixtures/example1/kakaotalk
npx playchat fixtures/example1/episode.json --record --segments --theme imessage --output fixtures/example1/imeesage
npx playchat fixtures/example1/episode.json --record --segments --theme wechat --output fixtures/example1/wechat
Every run writes a manifest.json to the output folder:
{
"input": "/absolute/path/to/episode.json",
"theme": "kakaotalk",
"pauseMs": 3000,
"showAvatar": true,
"showBottomBand": true,
"createdAt": "2026-04-14T20:57:14.123Z",
"files": {
"html": "output.html",
"mp4": "output.mp4",
"firstBubblePng": "first_bubble.png",
"lastBubblePng": "last_bubble.png",
"highlights": [
{
"title": "Highlight title",
"description": "Highlight description",
"tags": ["tag1", "tag2"],
"mp4": "highlights/highlight_1_title.mp4"
}
]
},
"dialogueCount": 5
}
files.mp4, files.firstBubblePng, and files.lastBubblePng are only present when --record or --record-full was used. files.highlights is only present when the input JSON contains a highlights array. All file paths are relative to the output folder.
By default all themes render at a 9:16 aspect ratio (--orientation vertical),
exporting to 1080×1920 (Full HD) at 1k resolution (540×960 logical viewport
captured at 2× scale).
| Theme | ID | Default output |
|---|---|---|
| KakaoTalk | kakaotalk | 1080×1920 (9:16) |
| iMessage | imessage | 1080×1920 (9:16) |
wechat | 1080×1920 (9:16) |
The first host in episode.hosts is treated as "me" and renders on the right
side; all other hosts render on the left. By default every message shows an
avatar circle and sender name. Pass --no-avatar to hide them.
Use --orientation to choose the frame shape:
vertical (default) — a portrait 9:16 frame for Shorts/Reels/TikTok.horizontal — a landscape 16:9 frame. The chat stays in a portrait
strip on the left (about 45% of the width, the same narrow ratio as
vertical), and the right pane displays a large image/video.In horizontal mode the right pane shows media that follows the currently active scope, falling back down the hierarchy:
dialogue image → section image → episode image
Each media item's lifecycle follows its parent: a dialogue image is shown only
while that dialogue is active and reverts to the section image when the dialogue
ends; the section image reverts to the episode image when the section changes.
A .mp4/.webm/.mov source is played as a looping muted video instead of an
image. In horizontal mode the inline chat-bubble thumbnail is suppressed since
the image is shown large on the right.
Set the images with episode.image, sections[].image, and dialogues[].image
(see Episode JSON Format).
--resolution scales the exported video while keeping the aspect ratio:
| Value | Long side | Vertical (9:16) | Horizontal (16:9) |
|---|---|---|---|
1k (default) | 1920 | 1080×1920 | 1920×1080 |
2k | 2560 | 1440×2560 | 2560×1440 |
4k | 3840 | 2160×3840 | 3840×2160 |
The episode's name field is displayed as branding, positioned to stay clear of
platform overlay UI:
name, centered. This pushes the chat
content up out of the zone where YouTube Shorts / TikTok overlay their caption,
username, and action buttons.name moves to a pill label in the top-right corner
overlaid on the right media pane, keeping the left chat strip clean.It is shown by default, omitted automatically when the episode JSON has no
name, and can be disabled explicitly with --no-bottom.
{
"name": "...",
"episode_title": "...",
"episode_number": 1,
"topic": "...",
"subtitle": "...",
"summary": "...",
"image": "https://cdn.example.com/episode.jpg",
"hosts": [
{
"id": "host_1",
"name": "Minsu",
"image": "https://cdn.example.com/avatar_minsu.png",
"gender": "male",
"role": "main_host",
"lang": "ko",
"voice_config": { "voice_index": 0, "pitch": 0, "speed": 1.0 }
}
],
"sections": [
{
"section_id": 1,
"section_title": "Opening",
"section_type": "opening",
"corner_name": "Opening 🎙️",
"image": "https://cdn.example.com/section1.jpg",
"dialogues": [
{
"id": 1,
"speaker": "host_1",
"name": "Minsu",
"text": "Hello!",
"audio": "path/to/segment_0000.mp3",
"image": "https://cdn.example.com/dialogue1.jpg"
}
]
}
],
"highlights": [
{
"ids": [1, 2, 3],
"title": "Highlight title",
"description": "What makes this moment interesting",
"tags": ["tag1", "tag2"]
}
]
}
hosts[i].image is optional. When present, the value is used as the avatar
image in chat themes; when omitted or if loading fails, the theme falls back to
the host's initial letter.
The top-level image, sections[].image, and dialogues[].image fields are
optional and only used in --orientation horizontal mode, where they populate
the right media pane (dialogue image \u2192 section image \u2192 episode image). Each
accepts a local path or a remote URL, and may point at an image or a video
(.mp4/.webm/.mov).
The top-level highlights array is optional. Each entry references dialogue IDs
(ids) that form a highlight clip. When recording (--record or --record-full),
the CLI automatically cuts an MP4 clip for each highlight and writes them to a
highlights/ subdirectory. No extra flag is needed.
The audio field on each dialogue accepts:
| Value | Behaviour |
|---|---|
"" (empty) | Message shown for --pause ms, then next message |
path/to/file.mp3 | Relative or absolute local path |
C:\absolute\path.mp3 | Windows absolute path |
https://cdn.example.com/a.mp3 | Remote URL (HTML preview only; not muxed into MP4) |
Local paths are resolved relative to the working directory and automatically
converted to file:/// URIs in the rendered HTML.
episode.json
│
├─ flattenDialogues() normalise audio paths
│
├─ buildTimeline() ffprobe each audio file for exact duration
│ showAtMs[0] = 0
│ showAtMs[1] = dur[0] + 400ms gap
│ showAtMs[N] = sum of previous (duration + gap), or pauseMs for no-audio
│
├─ Puppeteer (scrubber mode)
│ window.__TIMELINE__ injected before page load
│ for each frame:
│ page.evaluate("__SCRUB__(frameTimeMs)") ← recorder is the clock
│ page.screenshot() ← zero timing drift
│
├─ ffmpeg: frames → silent MP4
│
├─ buildAudioTrack()
│ ffmpeg concat: [silence][clip0][silence][clip1]...
│ gaps match the timeline exactly
│
└─ ffmpeg: mux silent MP4 + audio track → output.mp4
The browser never uses its own clock during recording. The recorder calls
window.__SCRUB__(ms) before every frame, passing the exact video timestamp
that frame represents. The browser renders whatever messages are due by that
time and no more — guaranteeing frame-perfect chat/audio sync regardless of
screenshot overhead.
The HTML file uses the normal live-audio mode for browser preview: audio
plays via new Audio() and the next message appears when onended fires.
Production (installs from npm):
docker build -t playchat .
docker run --rm -v $(pwd)/input:/work/input -v $(pwd)/output:/work/output playchat \
playchat input/episode.json
docker run --rm -v $(pwd)/input:/work/input -v $(pwd)/output:/work/output playchat \
playchat input/episode.json --record --theme kakaotalk
├── cli.ts # CLI entry point (HTML preview + optional MP4 recording)
├── core/
│ ├── types.ts # Interfaces, flattenDialogues(), normalizeAudioPath()
│ └── output.ts # resolveOutputDir() — structured output folders
├── themes/
│ ├── base.ts # Abstract BaseTheme (engine script, scrubber mode)
│ ├── kakaotalk.ts # KakaoTalk theme
│ ├── imessage.ts # iMessage theme
│ └── index.ts # Theme registry + getTheme()
├── tests/
│ ├── flatten.test.ts # Data layer + audio normalisation tests
│ ├── output.test.ts # Output directory tests
│ └── themes.test.ts # Theme contract + pauseMs tests
└── fixtures/example1/
├── episode.json # Full sample episode with real audio paths
├── episode_short.json # Shorter fixture for quick testing
└── preview/ # Sample CLI output for README preview
├── output.html
├── output.mp4 # sample --record output (tracked despite root *.mp4)
├── first_bubble.png
├── last_bubble.png
└── manifest.json
git clone https://github.com/doum1004/playchat.git
cd chat-in-video
npm install
npx ts-node cli.ts episode.json --record
npm test
themes/yourtheme.ts:import { BaseTheme, ThemeConfig } from "./base";
export class YourTheme extends BaseTheme {
get id() { return "yourtheme"; }
get label() { return "Your Theme"; }
get viewport(): ThemeConfig { return { width: 440, height: 600 }; }
render() { return this.wrapHTML(this.css, this.html, this.js); }
private get css(): string { return `/* styles */`; }
private get html(): string {
return `
<div class="device">
<div id="chat-body"></div>
</div>`;
}
private get js(): string {
return `
const body = document.getElementById('chat-body');
function appendMsg(d) {
// create and append one chat bubble for dialogue d
}
${this.engineScript}`;
}
}
themes/index.ts:import { YourTheme } from "./yourtheme";
const registry = {
kakaotalk: KakaoTalkTheme,
imessage: IMessageTheme,
yourtheme: YourTheme, // ← add here
};
npx playchat episode.json --theme yourtheme
npx playchat episode.json --theme yourtheme --record
Every theme must satisfy three requirements in its JS block:
| Requirement | Why |
|---|---|
Element id="chat-body" in HTML | Engine appends bubbles here |
Function appendMsg(d) | Called once per dialogue — render one bubble |
${this.engineScript} at the end of JS | Injects playback engine + scrubber mode |
appendMsg(d) receives a FlatDialogue object:
{
speaker: string; // "host_1", "host_2", ...
name: string; // display name
text: string; // message content
audio: string; // file:/// URI or https:// URL (empty if none)
audioRaw: string; // original value from JSON
section: string; // corner_name of the containing section
}
MIT
FAQs
Multi-theme podcast chat renderer with video recording
The npm package playchat receives a total of 9 weekly downloads. As such, playchat popularity was classified as not popular.
We found that playchat demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
GPT-6 Astra hits 100% on ExploitBench and finds zero-days autonomously, while independent tests reveal scope violations and monitoring gaps.
Product
Socket can now send alerts and supply chain attack notifications to Microsoft Teams, with filters that route the right updates to each channel.
Security News
pnpm 12 rewrites the package manager in Rust, cutting install times by up to 90% while preserving pnpm 11 workflows and lockfiles.