Skip to content

Commit bdd76a4

Browse files
committed
docs: add clean AI narration throughout the demo video
1 parent ecef87b commit bdd76a4

5 files changed

Lines changed: 122 additions & 51 deletions

File tree

‎docs/demo/README.md‎

Lines changed: 23 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,29 @@
11
# Short Poltergit demo
22

3-
**poltergit-demo.mp4** — 46 seconds, 1920×1080, 30 fps, H.264 video + AAC audio.
3+
**poltergit-demo-narrated.mp4** — the revised narrated walkthrough, 1920×1080, 30 fps,
4+
H.264 video + AAC audio. Exact timings are recorded in `timeline.json`.
5+
Use this version for submission. `poltergit-demo.mp4` preserves the original
6+
46-second version with the voice sample and atmosphere, for comparison.
47

58
This is an edited walkthrough made from authentic saved UI screenshots and a
6-
recorded local Kokoro voice sample. It is not a continuous screen recording.
9+
clean local Kokoro AI voiceover throughout. It is not a continuous screen recording.
710
The video explicitly labels the omitted CPU inference wait and the fictional
811
demo repository. UI text, model responses, and commit evidence were not altered.
9-
The voice sample comes from another successful séance of the same line; it is
10-
not presented as a verbatim reading of the screenshot's answer.
12+
The voice chapter reads the actual answer shown in the screenshot. Narration is
13+
generated directly through Kokoro without the application's echo effect.
1114

12-
## Timeline
15+
## Chapters
1316

14-
- 00:00–00:05: Poltergit introduction.
15-
- 00:05–00:13: Actual Gemma answer for `src/client.py:13`.
16-
- 00:13–00:20: Supporting Git commit message.
17-
- 00:20–00:35: Recorded local Kokoro voice, with a quiet echo.
18-
- 00:35–00:42: Ofrenda for the deleted file and function.
19-
- 00:42–00:46: Closing card and honest-silence principle.
17+
- Poltergit introduction.
18+
- Actual Gemma answer for `src/client.py:13`.
19+
- Supporting Git commit message.
20+
- A clean Kokoro reading of the displayed answer.
21+
- Ofrenda for the deleted file and function.
22+
- Closing card and honest-silence principle.
2023

21-
The soundtrack is a quiet synthesized tone; no third-party music was used.
24+
There is no background hum, music, echo, or reverb in the revised video.
25+
The full AI narration script is saved in `narration.txt`. Scene lengths adjust
26+
to fit the speech naturally without cutting words or speeding up the audio.
2227
No Tiger Data connection, Sentry dashboard, Entire integration, or hosted live
2328
séance is claimed in the video.
2429

@@ -31,11 +36,12 @@ image. The video has not been uploaded or published by the build process.
3136
## Rebuild locally
3237

3338
```powershell
34-
uv run python scripts/make_demo_video.py
39+
uv run --extra voice python scripts/make_demo_video.py
3540
```
3641

3742
Requires the existing FFmpeg/ffprobe installation, Windows fonts, the screenshots
38-
in `docs/screenshots/`, and the original ignored recording at
39-
`.poltergit/audio/c122b36d95a447fbaf23bc1b925e05e0.wav`.
40-
No additional Python dependencies are installed. Intermediate render files and
41-
copied fonts are kept in the ignored `.poltergit/video-build/` directory.
43+
in `docs/screenshots/`, voice extras, and the local Kokoro model/voices configured
44+
in `.env`. No additional Python dependencies were installed for this revision.
45+
Narration is cached by text and voice settings. Intermediate render files,
46+
voice WAVs, and copied fonts are kept in the ignored `.poltergit/video-build/`
47+
directory. The app's own ghost-voice effect remains unchanged.

‎docs/demo/narration.txt‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Some code never rests. Poltergit asks a line why it exists.
2+
3+
This three-second delay answers through Gemma, running locally. It speaks as the code, with a citation.
4+
5+
The original commit explains it: the gateway reserves closed sessions for two seconds. Every ghost brings receipts.
6+
7+
Kokoro gives the code a voice. My existence is tied to preventing a reconnect storm, as a three-second delay gives that reservation time to expire.
8+
9+
The ofrenda remembers deleted code: how long it served, and the commit that retired it.
10+
11+
And when history has no answer, the record is silent.
1.64 MB
Binary file not shown.

‎docs/demo/timeline.json‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,41 +4,53 @@
44
"end_seconds": 5,
55
"chapter": "POLTERGIT",
66
"caption": "Ask a line why it exists. Let the history speak.",
7+
"narration": "Some code never rests. Poltergit asks a line why it exists.",
8+
"speech_seconds": 3.833,
79
"source": "01-seance-home.png"
810
},
911
{
1012
"start_seconds": 5,
1113
"end_seconds": 13,
1214
"chapter": "01 / ASK THE CODE",
1315
"caption": "Gemma 4 answers in the line’s own voice, with a citation.",
16+
"narration": "This three-second delay answers through Gemma, running locally. It speaks as the code, with a citation.",
17+
"speech_seconds": 5.988,
1418
"source": "08-seance-gemma.png"
1519
},
1620
{
1721
"start_seconds": 13,
18-
"end_seconds": 20,
22+
"end_seconds": 20.566666666666666,
1923
"chapter": "02 / FOLLOW THE EVIDENCE",
2024
"caption": "The commit explains the gateway’s two-second reservation.",
25+
"narration": "The original commit explains it: the gateway reserves closed sessions for two seconds. Every ghost brings receipts.",
26+
"speech_seconds": 6.943,
2127
"source": "03-evidence-cards.png"
2228
},
2329
{
24-
"start_seconds": 20,
25-
"end_seconds": 35,
30+
"start_seconds": 20.566666666666666,
31+
"end_seconds": 32.56666666666666,
2632
"chapter": "03 / HEAR THE SPIRIT",
27-
"caption": "Kokoro speaks locally, with a quiet echo.",
33+
"caption": "Kokoro gives the code a voice, entirely locally.",
34+
"narration": "Kokoro gives the code a voice. My existence is tied to preventing a reconnect storm, as a three-second delay gives that reservation time to expire.",
35+
"speech_seconds": 9.427,
2836
"source": "08-seance-gemma.png"
2937
},
3038
{
31-
"start_seconds": 35,
32-
"end_seconds": 42,
39+
"start_seconds": 32.56666666666666,
40+
"end_seconds": 39.56666666666666,
3341
"chapter": "04 / HONOR THE PAST",
3442
"caption": "Deleted code gets an ofrenda: its lifetime and removal record.",
43+
"narration": "The ofrenda remembers deleted code: how long it served, and the commit that retired it.",
44+
"speech_seconds": 5.066,
3545
"source": "05-ofrenda.png"
3646
},
3747
{
38-
"start_seconds": 42,
39-
"end_seconds": 46,
48+
"start_seconds": 39.56666666666666,
49+
"end_seconds": 43.56666666666666,
4050
"chapter": "POLTERGIT",
4151
"caption": "Local Gemma. Real Git history. Sources you can inspect.",
52+
"narration": "And when history has no answer, the record is silent.",
53+
"speech_seconds": 2.966,
4254
"source": "Original title card"
4355
}
4456
]

‎scripts/make_demo_video.py‎

Lines changed: 68 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
1-
"""Render the short demo from authentic UI captures and the recorded Kokoro WAV.
1+
"""Render the short demo from authentic UI captures and clean Kokoro narration.
22
3-
No model calls, paid services, or extra Python packages. Requires ffmpeg/ffprobe.
4-
Run from the project root: uv run python scripts/make_demo_video.py
3+
Uses the already-installed local voice model. Requires ffmpeg/ffprobe and voice extras.
4+
Run from the project root: uv run --extra voice python scripts/make_demo_video.py
55
"""
66

7+
import hashlib
78
import json
9+
import math
810
import shutil
911
import subprocess
1012
from pathlib import Path
@@ -23,22 +25,28 @@
2325
SCENES = [
2426
dict(duration=5, image="01-seance-home.png", crop=(62, 116, 1140, 405),
2527
box=(100, 215, 1720, 612), chapter="POLTERGIT", title="A séance for your Git history.",
26-
caption="Ask a line why it exists. Let the history speak.", note="Recorded local demo · fictional repository with real Git history"),
28+
caption="Ask a line why it exists. Let the history speak.", note="Recorded local demo · fictional repository with real Git history",
29+
narration="Some code never rests. Poltergit asks a line why it exists."),
2730
dict(duration=8, image="08-seance-gemma.png", crop=(69, 38, 1128, 610),
2831
box=(300, 210, 1320, 714), chapter="01 / ASK THE CODE", title="Why am I waiting three seconds?",
29-
caption="Gemma 4 answers in the line’s own voice, with a citation.", note="Actual recorded model result · CPU inference wait omitted"),
32+
caption="Gemma 4 answers in the line’s own voice, with a citation.", note="Actual recorded model result · CPU inference wait omitted",
33+
narration="This three-second delay answers through Gemma, running locally. It speaks as the code, with a citation."),
3034
dict(duration=7, image="03-evidence-cards.png", crop=(70, 285, 563, 240),
3135
box=(260, 235, 1400, 597), chapter="02 / FOLLOW THE EVIDENCE", title="Every ghost brings receipts.",
32-
caption="The commit explains the gateway’s two-second reservation.", note="Original commit message · supporting quotations are checked against the source"),
33-
dict(duration=15, image="08-seance-gemma.png", crop=(665, 183, 530, 465),
36+
caption="The commit explains the gateway’s two-second reservation.", note="Original commit message · supporting quotations are checked against the source",
37+
narration="The original commit explains it: the gateway reserves closed sessions for two seconds. Every ghost brings receipts."),
38+
dict(duration=12, image="08-seance-gemma.png", crop=(665, 183, 530, 465),
3439
box=(790, 190, 815, 715), chapter="03 / HEAR THE SPIRIT", title="The code has a voice.",
35-
caption="Kokoro speaks locally, with a quiet echo.", note="Recorded Kokoro output from a successful séance of the same line", voice=True),
40+
caption="Kokoro gives the code a voice, entirely locally.", note="Clean AI narration · reading the actual answer shown here", voice=True,
41+
narration="Kokoro gives the code a voice. My existence is tied to preventing a reconnect storm, as a three-second delay gives that reservation time to expire."),
3642
dict(duration=7, image="05-ofrenda.png", crop=(69, 403, 767, 380),
3743
box=(280, 220, 1360, 674), chapter="04 / HONOR THE PAST", title="Gone from the tree. Still part of the story.",
38-
caption="Deleted code gets an ofrenda: its lifetime and removal record.", note="A standalone memorial site, ready to publish on GitHub Pages"),
44+
caption="Deleted code gets an ofrenda: its lifetime and removal record.", note="A standalone memorial site, ready to publish on GitHub Pages",
45+
narration="The ofrenda remembers deleted code: how long it served, and the commit that retired it."),
3946
dict(duration=4, chapter="POLTERGIT", title="Some code never rests.",
4047
caption="Local Gemma. Real Git history. Sources you can inspect.",
41-
note="When evidence is missing: “The record is silent.”", end=True),
48+
note="When evidence is missing: “The record is silent.”", end=True,
49+
narration="And when history has no answer, the record is silent."),
4250
]
4351

4452

@@ -58,11 +66,55 @@ def text_filter(index, key, value, size, y, *, color=PAPER, font="sans", x=None)
5866
f"x={x if x is not None else '(w-text_w)/2'}:y={y}")
5967

6068

69+
def make_narration():
70+
"""Generate dry speech directly; never apply the app's ghost echo or a hum."""
71+
import numpy as np
72+
import soundfile as sf
73+
from poltergit.config import Settings
74+
from poltergit.voice import engine
75+
76+
settings = Settings()
77+
synthesizer = None
78+
combined = []
79+
rate = 24000
80+
for index, scene in enumerate(SCENES):
81+
signature = hashlib.sha256(("af_heart:1.06:" + scene["narration"]).encode()).hexdigest()[:12]
82+
cache = BUILD / f"narration-{index}-{signature}.wav"
83+
if cache.exists():
84+
samples, rate = sf.read(str(cache), dtype="float32")
85+
else:
86+
if synthesizer is None:
87+
synthesizer = engine(str(settings.kokoro_model), str(settings.kokoro_voices))
88+
print(f"Synthesizing clean narration {index + 1}/{len(SCENES)}", flush=True)
89+
samples, rate = synthesizer.create(scene["narration"], voice="af_heart", speed=1.06, lang="en-us")
90+
samples = np.asarray(samples, dtype=np.float32)
91+
# Trim long synthesis padding, keeping 50 ms around speech.
92+
active = np.flatnonzero(np.abs(samples) > 0.003)
93+
if not len(active):
94+
raise ValueError("The local voice model returned silent audio.")
95+
margin = int(0.05 * rate)
96+
samples = samples[max(0, active[0] - margin):min(len(samples), active[-1] + margin)]
97+
sf.write(str(cache), samples, rate)
98+
lead = 0.25
99+
duration = max(scene["duration"], math.ceil((len(samples) / rate + lead + 0.35) * FPS) / FPS)
100+
scene["duration"] = duration
101+
scene["speech_seconds"] = round(len(samples) / rate, 3)
102+
padded = np.zeros(round(duration * rate), dtype=np.float32)
103+
offset = int(lead * rate)
104+
padded[offset:offset + len(samples)] = samples
105+
combined.append(padded)
106+
print(f"Narration {index + 1}: {len(samples) / rate:.1f}s speech, {duration:.1f}s scene", flush=True)
107+
destination = BUILD / "clean-narration.wav"
108+
sf.write(str(destination), np.concatenate(combined), rate)
109+
return destination
110+
111+
61112
def main():
62113
if not shutil.which("ffmpeg") or not shutil.which("ffprobe"):
63114
raise SystemExit("Install FFmpeg before rendering the demo.")
64115
BUILD.mkdir(parents=True, exist_ok=True)
65116
OUTPUT.mkdir(parents=True, exist_ok=True)
117+
narration = make_narration()
66118
font_sources = {"sans": "segoeui.ttf", "serif": "georgia.ttf", "italic": "georgiai.ttf", "mono": "consola.ttf"}
67119
for name, source in font_sources.items():
68120
path = Path("C:/Windows/Fonts") / source
@@ -118,35 +170,25 @@ def main():
118170
run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-y", "-f", "concat", "-safe", "0",
119171
"-i", str(concat), "-c", "copy", str(picture)])
120172

121-
voice = ROOT / ".poltergit/audio/c122b36d95a447fbaf23bc1b925e05e0.wav"
122-
if not voice.is_file():
123-
raise SystemExit("Recorded demo voice is missing. Generate and select a verified local voice sample.")
124-
# The original voice sample begins 0.55 seconds into its fifteen-second scene.
125173
total = sum(s["duration"] for s in SCENES)
126-
voice_start = sum(s["duration"] for s in SCENES[:3]) + 0.55
127-
target = OUTPUT / "poltergit-demo.mp4"
128-
audio_filter = (
129-
f"[1:a]highpass=f=65,lowpass=f=8500,loudnorm=I=-17:TP=-2:LRA=8,"
130-
f"afade=t=in:d=0.08,afade=t=out:st=13.55:d=0.3,"
131-
f"adelay={int(voice_start * 1000)}:all=1,apad=whole_dur={total}[voice];"
132-
f"[2:a]volume=0.055,afade=t=in:d=2,afade=t=out:st={total-2}:d=2[atmosphere];"
133-
"[voice][atmosphere]amix=inputs=2:duration=longest:normalize=0[audio]"
134-
)
174+
target = OUTPUT / "poltergit-demo-narrated.mp4"
135175
run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-y", "-i", str(picture),
136-
"-i", str(voice), "-f", "lavfi", "-i", f"sine=frequency=65:sample_rate=48000:duration={total}",
137-
"-filter_complex", audio_filter, "-map", "0:v:0", "-map", "[audio]", "-t", str(total),
176+
"-i", str(narration), "-map", "0:v:0", "-map", "1:a:0", "-t", str(total),
177+
"-af", "highpass=f=65,loudnorm=I=-16:TP=-1.5:LRA=7",
138178
"-c:v", "copy", "-c:a", "aac", "-b:a", "192k", "-ar", "48000", "-ac", "2",
139179
"-movflags", "+faststart", "-metadata", "title=Poltergit — a séance for your Git history",
140-
"-metadata", "comment=Edited demonstration using authentic local screenshots and recorded Kokoro audio. Inference wait omitted.", str(target)])
180+
"-metadata", "comment=Authentic local screenshots with clean local Kokoro AI narration throughout. No echo or background music. Inference wait omitted.", str(target)])
141181

142182
timeline = []
143183
start = 0
144184
for scene in SCENES:
145185
timeline.append({"start_seconds": start, "end_seconds": start + scene["duration"],
146186
"chapter": scene["chapter"], "caption": scene["caption"],
187+
"narration": scene["narration"], "speech_seconds": scene["speech_seconds"],
147188
"source": scene.get("image", "Original title card")})
148189
start += scene["duration"]
149190
(OUTPUT / "timeline.json").write_text(json.dumps(timeline, indent=2, ensure_ascii=False), encoding="utf-8")
191+
(OUTPUT / "narration.txt").write_text("\n\n".join(s["narration"] for s in SCENES) + "\n", encoding="utf-8")
150192
run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-y", "-ss", "2", "-i", str(target),
151193
"-frames:v", "1", str(OUTPUT / "poster.jpg")])
152194
print(f"Saved {target} ({total}s, {target.stat().st_size / 1_000_000:.1f} MB)", flush=True)

0 commit comments

Comments
 (0)