Claude commited on
Commit
2403a32
Β·
1 Parent(s): d06062f

Add USER_GUIDE.md: end-user walkthrough of upload, AI options, editor, downloads

Browse files
Files changed (1) hide show
  1. USER_GUIDE.md +283 -0
USER_GUIDE.md ADDED
@@ -0,0 +1,283 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # VideoGuideMaker β€” User Guide
2
+
3
+ Turn a recorded lecture into an accessible, navigable study guide in a few minutes.
4
+
5
+ You hand it a video and a transcript. It picks the visually distinct moments (slide changes, demos, board work), pulls the on-screen text, and produces a polished HTML document β€” one section per slide β€” with timestamps, narration, key terms, and equations. You can review and edit before publishing.
6
+
7
+ ---
8
+
9
+ ## Table of contents
10
+
11
+ 1. [Quick start](#quick-start)
12
+ 2. [What you'll need before you upload](#what-youll-need-before-you-upload)
13
+ 3. [The upload page, field by field](#the-upload-page-field-by-field)
14
+ 4. [What happens after you click Generate](#what-happens-after-you-click-generate)
15
+ 5. [The review & edit screen](#the-review--edit-screen)
16
+ 6. [Output formats](#output-formats)
17
+ 7. [Tips for the best results](#tips-for-the-best-results)
18
+ 8. [Troubleshooting](#troubleshooting)
19
+
20
+ ---
21
+
22
+ ## Quick start
23
+
24
+ 1. Open the site.
25
+ 2. Drop in your video and your transcript.
26
+ 3. (Optional) paste an Anthropic API key and tick the AI features you want.
27
+ 4. Click **Generate study guide β†’**.
28
+ 5. Wait for the progress bar.
29
+ 6. On the editor screen, fix any rough spots, then click **Download final HTML** or **Download ZIP**.
30
+
31
+ That's it. The rest of this guide is detail.
32
+
33
+ ---
34
+
35
+ ## What you'll need before you upload
36
+
37
+ | You need | What it looks like | Notes |
38
+ |---|---|---|
39
+ | **A lecture video** | `.mp4`, `.mov`, `.mkv`, `.webm`, `.m4v`, `.avi` | Up to 500 MB. A 30-minute lecture is typical. |
40
+ | **A transcript** | `.srt` or `.vtt` (subtitle file) | Up to 5 MB. Required β€” the app aligns narration to slides using your transcript's timestamps. |
41
+ | **(Optional) an Anthropic API key** | Starts with `sk-ant-…` | Only needed if you want the AI features. The key is used per-job and is **never stored**. |
42
+
43
+ > **Don't have a transcript yet?** YouTube auto-captions, Descript, Otter, and Zoom all export `.srt` or `.vtt`. Quality matters β€” bad captions = bad section alignment.
44
+
45
+ ---
46
+
47
+ ## The upload page, field by field
48
+
49
+ The page is divided into numbered sections.
50
+
51
+ ### 1. Upload
52
+
53
+ **Study guide title** β€” the heading of the finished document. Defaults to *"Lecture Study Guide"*. Change it.
54
+
55
+ **Video file** β€” drag and drop, or click to browse.
56
+
57
+ **Transcript** β€” same.
58
+
59
+ ### 2. AI assist (optional)
60
+
61
+ Everything in this section requires an Anthropic API key. **Skip this section entirely if you don't have one** β€” the rest of the app still works.
62
+
63
+ **Anthropic API key** β€” paste your key here. Stored only for this job, never logged or saved on the server.
64
+
65
+ The five toggles below decide what Claude does for each frame. Each adds a small per-frame cost (a few cents for a typical lecture).
66
+
67
+ | Toggle | What Claude produces | Recommendation |
68
+ |---|---|---|
69
+ | **Section titles** | A short, descriptive title for each segment ("Combining AI models") instead of the default "Segment 3 β€” 4:25". | Tick this β€” it makes the table of contents readable. |
70
+ | **Alt-text drafts** | Accessible alt text describing the *purpose* of each visual, not just a transcription. | Tick if you'll publish the guide where accessibility matters. |
71
+ | **Key terms** | A list of named concepts the lecturer is teaching, with short definitions. | Tick for content-rich lectures. |
72
+ | **Math equations** | LaTeX for equations on the slide, plus a screen-reader description. | Tick if your slides contain math. |
73
+ | **On-screen text (Claude)** | Replaces the local OCR engine with Claude's reading. Much better on coloured callouts, decorative fonts, and rendered math. | Tick if your slides have any visual flair beyond plain black-on-white text. |
74
+
75
+ You can pick any combination. Toggles are independent.
76
+
77
+ ### 3. Media extras
78
+
79
+ **Per-segment audio** β€” slices the lecture's narration into one MP3 clip per segment so learners can re-listen. Adds processing time and ~500 KB per clip. No API key needed. Off by default.
80
+
81
+ ### 4. Output
82
+
83
+ Pick exactly one format:
84
+
85
+ | Format | Best for | Notes |
86
+ |---|---|---|
87
+ | **Review & edit** | Most cases. | Opens an in-browser editor; download from there once you're happy. |
88
+ | **Single HTML** | Quick share, no review. | One self-contained `.html` file with images and audio embedded. Just emails. |
89
+ | **Zip bundle** | Hosting on a website. | HTML plus a `static/` folder of images and audio. |
90
+
91
+ > πŸ’‘ **You can pick "Review & edit" and still get any of the other formats from the editor's toolbar β€” no need to re-run the pipeline.**
92
+
93
+ ### Advanced settings (collapsed by default)
94
+
95
+ Only open this if the defaults don't work for your video. All of these have sane defaults.
96
+
97
+ **Scene-change sensitivity** (default 27)
98
+ How visually different two frames must be before the app counts a new slide. **Lower** (5–15) catches every animation step β€” good if your lecturer uses progressive reveals. **Higher** (35+) only major slide changes β€” good if you want one frame per slide.
99
+
100
+ **Minimum gap between scenes** (default off)
101
+ Drops new scenes that arrive less than X seconds after the previous one. Useful when a slide builds up over several seconds β€” set to ~5 s to keep just the final state.
102
+
103
+ **Max frames** (default unlimited)
104
+ Hard cap on how many frames the guide will contain. Useful for very long lectures or to bound API cost.
105
+
106
+ **Instructor-frame face threshold** (default 0.12)
107
+ The app automatically drops frames that look like a talking-head shot of the instructor (no slide content). This slider controls how aggressive that filter is. Lower = drops more. Raise it if your slides have an inset webcam you want to keep.
108
+
109
+ **Skip OCR** (off)
110
+ Faster, but on-screen text won't appear in the guide. Doesn't affect the AI on-screen-text toggle (Claude reads the image directly).
111
+
112
+ **Document language** (default `en`)
113
+ A BCP-47 code like `en`, `en-US`, `fr`, `de`. Sets the document language and selects local OCR language packs.
114
+
115
+ ---
116
+
117
+ ## What happens after you click Generate
118
+
119
+ You'll see a progress bar with stages:
120
+
121
+ 1. **Detecting scenes** β€” finds visually distinct moments in the video.
122
+ 2. **Filtering instructor frames** β€” drops talking-head shots.
123
+ 3. **Loading transcript** β€” reads your captions.
124
+ 4. **Running OCR** β€” extracts on-screen text from each kept frame.
125
+ 5. **LLM extraction** *(only if you ticked any AI toggle)* β€” sends each frame to Claude.
126
+ 6. **Slicing audio** *(only if you ticked Per-segment audio)* β€” extracts MP3 clips.
127
+ 7. **Building segments** / **Rendering** β€” produces the final HTML.
128
+
129
+ Typical wall time: **about 30 s per minute of video** without AI; **about 60 s per minute** with AI features on.
130
+
131
+ If anything goes wrong, you'll see a red error banner with a message. Click **Try again** to retry without re-uploading (your form values are preserved).
132
+
133
+ ---
134
+
135
+ ## The review & edit screen
136
+
137
+ If you picked the **Review & edit** output, this is where you'll spend most of your time.
138
+
139
+ The screen has three areas:
140
+
141
+ ### The toolbar (top, sticky)
142
+
143
+ | Button | What it does |
144
+ |---|---|
145
+ | **Save edits (JSON)** | Downloads a small `.edits.json` file with everything you've changed. Useful as a checkpoint or for handing the edits to someone else to re-render with the CLI. |
146
+ | **Load edits (JSON)** | Re-applies a previously-saved `.edits.json` to the current page. |
147
+ | **Preview** | Opens a clean copy of the guide (no editor chrome) in a new tab so you can see the final look. |
148
+ | **Download final HTML** | Saves the finished guide as a single self-contained `.html` file. Images and audio inlined. |
149
+ | **Download ZIP** | Saves the finished guide as a zip with separate asset files. Better for hosting on a website. |
150
+
151
+ Status messages appear next to the buttons.
152
+
153
+ ### The document body
154
+
155
+ Edit anything that's underlined or has a placeholder. Specifically, per segment you can:
156
+
157
+ #### **Section title**
158
+ The heading. Editable text field. If you ticked **Section titles** AI, it'll have Claude's draft; otherwise it's a default like "Segment 3 β€” 4:25".
159
+
160
+ #### **Alt-text**
161
+ The accessible description of the slide image. Editable text field. Drafts marked as "needs review" produce an explicit author-warning banner at the top of the page until you confirm them.
162
+
163
+ #### **Choose frame** *(when alternates exist)*
164
+ A row of thumbnails under the slide. The app captures up to three candidate frames per scene; click any thumbnail to swap which one is the canonical image. The on-screen text panel updates automatically to match the picked frame.
165
+
166
+ #### **On-screen text from video**
167
+ A collapsible panel under the slide. The OCR'd (or Claude-read, if you enabled it) text from the slide. Editable β€” fix mis-reads here.
168
+
169
+ #### **(Audio clip)**
170
+ An audio player, only present if you ticked **Per-segment audio**. Plays the lecturer's narration for just this segment.
171
+
172
+ #### **Narration**
173
+ The transcript text aligned to this segment. Editable β€” clean up speech disfluencies, fix homophone errors, or rewrite into prose.
174
+
175
+ #### **Key terms** *(when AI key terms is on)*
176
+ A list of term + definition rows. Add, edit, or remove. Empty rows are dropped on download.
177
+
178
+ #### **Math equations** *(when AI math is on)*
179
+ A list of LaTeX expressions with optional labels and captions. Live-preview MathJax rendering on the right.
180
+
181
+ #### **Include in final guide** (checkbox per section)
182
+ Untick to drop a segment from the final document entirely. Useful for transitions, intro slides, or instructor-only frames the filter let through.
183
+
184
+ ### Per-section status
185
+
186
+ The order on every segment is:
187
+
188
+ ```
189
+ [Slide image]
190
+ ↓
191
+ [Choose frame thumbnails] (if alternates)
192
+ ↓
193
+ [On-screen text from video]
194
+ ↓
195
+ [πŸ”Š Audio clip] (if Per-segment audio is on)
196
+ ↓
197
+ [Narration]
198
+ ↓
199
+ [Key terms] (if AI key terms is on)
200
+ ↓
201
+ [Math equations] (if AI math equations is on)
202
+ ```
203
+
204
+ ---
205
+
206
+ ## Output formats
207
+
208
+ Whatever output format you pick (or whatever you click in the editor's toolbar), the result is **valid HTML you can email, host, or print**. Specifics:
209
+
210
+ ### Single HTML
211
+ - One `.html` file. Open in any browser.
212
+ - Images and audio are encoded as base64 data URIs.
213
+ - File can be 10–50 MB depending on slide count and audio.
214
+ - Best for: emailing, archiving.
215
+
216
+ ### Zip bundle
217
+ - A `.zip` containing `study-guide.html` and a `static/` folder.
218
+ - Images stay as `.jpg` files; audio as `.mp3`.
219
+ - Best for: hosting on a static site, GitHub Pages, an LMS.
220
+
221
+ ### Review & edit (in the editor)
222
+ - The editor page itself. Won't be downloaded as-is.
223
+ - From here, click any of the toolbar's download buttons.
224
+
225
+ ---
226
+
227
+ ## Tips for the best results
228
+
229
+ **Use a clean transcript.**
230
+ Auto-generated captions are usually fine, but they tend to misspell technical terms. A 5-minute pass over the `.srt` before uploading saves a lot of editing later.
231
+
232
+ **Set scene-change sensitivity to your lecture style.**
233
+ Hand-drawn whiteboard work needs lower (10–15). Slide-only decks work fine at 27. Talking-head with a single shared screen needs 35+.
234
+
235
+ **Tick AI on-screen text for slides with colour callouts.**
236
+ The local OCR engine struggles with white-text-on-coloured-background. Claude reads them perfectly.
237
+
238
+ **Don't tick every AI feature on the first run.**
239
+ Each costs API tokens. Section titles and alt text are the highest-leverage two β€” start with those. Add key terms / equations / OCR if specific gaps appear.
240
+
241
+ **The "Include" checkbox is your friend.**
242
+ It's faster to drop bad segments than to re-run the pipeline with stricter settings.
243
+
244
+ **Save the JSON before downloading.**
245
+ If you spend 20 minutes editing and then your browser tab closes, the JSON checkpoint is the only way to recover.
246
+
247
+ ---
248
+
249
+ ## Troubleshooting
250
+
251
+ **"No usable visual segments found"**
252
+ The scene detector found nothing or every frame was filtered as instructor-only. Try (a) lowering the scene-change sensitivity, or (b) raising the instructor-frame face threshold.
253
+
254
+ **"Server is at the 8-job concurrency cap"**
255
+ Someone else's job is currently running on the same server. Wait a minute and click **Generate** again.
256
+
257
+ **"Video exceeds the 500 MB upload limit" / "Transcript exceeds the 5 MB upload limit"**
258
+ Compress the video before uploading (HandBrake, ffmpeg) or split it. The transcript limit is huge β€” if you're hitting it, your captions file is likely a binary blob, not a real `.srt`.
259
+
260
+ **Progress stalls on OCR for a long time**
261
+ Tesseract is slow on the free CPU tier. A 30-min lecture takes 1–2 minutes for OCR. If it's been 5+ minutes, tick **Skip OCR** in advanced settings and re-run, then optionally turn on the AI **On-screen text** toggle instead β€” Claude is much faster.
262
+
263
+ **The OCR text reads like garbage**
264
+ Coloured callouts and decorative fonts confuse Tesseract. Tick **On-screen text (Claude)** under AI assist.
265
+
266
+ **Equations render as raw LaTeX**
267
+ Make sure MathJax loaded β€” check the browser console. If you're behind a corporate firewall that blocks `cdn.jsdelivr.net`, MathJax won't load.
268
+
269
+ **The instructor's face is showing as the slide image**
270
+ Click an alternate thumbnail under that slide. The app keeps up to two alternates per scene precisely for this case.
271
+
272
+ **Edits got lost when I refreshed**
273
+ Always **Save edits (JSON)** before refreshing, closing the tab, or stepping away. The editor doesn't persist to localStorage.
274
+
275
+ **Downloaded HTML won't open**
276
+ Some email clients block `.html` attachments. Zip the file or use the Zip bundle output.
277
+
278
+ **Audio plays in the editor but not in the downloaded file**
279
+ The download path inlines audio as data URIs. If you downloaded the zip bundle, the audio is in `static/segment_*.mp3` β€” check your browser console for missing-file errors.
280
+
281
+ ---
282
+
283
+ If you hit something this guide doesn't cover, hand the error message to whoever set up the app for you. Most issues are resolved by lowering the scene-change sensitivity or ticking the **On-screen text (Claude)** toggle.