Spaces:
Sleeping
Sleeping
Claude commited on
Commit Β·
2403a32
1
Parent(s): d06062f
Add USER_GUIDE.md: end-user walkthrough of upload, AI options, editor, downloads
Browse files- 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.
|