README.md

---
title: CapVideo
emoji: "🎓"
colorFrom: indigo
colorTo: green
sdk: docker
pinned: false
fullWidth: true
suggested_hardware: "cpu-upgrade"
tags:
  - education
  - video-learning
  - whisper
  - captions
  - flask
---

# CapVideo

**Turn a lesson video into a learning kit.** CapVideo creates a captioned video, a timestamped transcript, chapter highlights, and source-linked recall cards from an educational video. The aim is to help learners revisit a difficult idea in seconds rather than rewatching an entire lecture.

![CapVideo workflow](https://img.shields.io/badge/workflow-video_%E2%86%92_captions_%E2%86%92_recall_cards-7b61ff)

## Why it matters

Video is a great teaching medium, but it is difficult to search, easy to passively consume, and not equally accessible to every learner. CapVideo turns a single uploaded lecture or explainer into reusable study material:

- **Captioned video** with configurable size, colour, and language detection.
- **Timestamped transcript** for skimming and accessibility.
- **Lecture map** that groups the source into digestible, source-linked chapters.
- **Recall cards** that ask learners to retrieve an idea before showing its evidence-backed answer.

The app uses Whisper locally for speech-to-text and keeps the learning-kit output grounded in the source transcript and timestamps.

## Fast demo

1. Open the running app.
2. Upload a short MP4 of a lecture, tutorial, or explainer you own or are authorized to process.
3. Select a caption style and press **Build my learning kit**.
4. When processing completes, open a chapter, reveal a recall card, and download the captioned video, `.srt`, or transcript.

For a reliable judge demo, use a short uploaded MP4. The optional public-YouTube-link route is a convenience feature; a video host may restrict automated retrieval at any time.

## Run locally

### Docker (recommended)

```bash
docker build -t capvideo .
docker run --rm -p 7860:7860 -e SECRET_KEY="replace-with-a-long-random-value" capvideo
```

Open `http://localhost:7860`.

### Python

Python 3.10+ and FFmpeg are required.

```bash
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
pip install git+https://github.com/openai/whisper.git
python app.py
```

## Deployment notes

- Set `SECRET_KEY` in your deployment secrets. Never commit it.
- CapVideo processes files in ephemeral `uploads/` and `processed/` folders; do not rely on them for long-term storage.
- If you are authorized to use a cookie file for a deployment, set `YTDLP_COOKIEFILE` to its server-side path. Do **not** paste browser cookies into the UI or commit them to a repository.
- A public project link is sufficient for testing. If the code repository is private, share it with `testing@devpost.com` and `build-week-event@openai.com` before submitting.

## Hackathon extension record

CapVideo is a meaningful extension of the pre-existing **Scrideo** transcription prototype. The distinction is intentional and documented in [HACKATHON.md](HACKATHON.md).

During the hackathon submission period, Codex with GPT-5.6 was used to audit the old extraction flow, redesign the product around reliable upload-first learning, implement the source-linked learning kit, and create this testable frontend and documentation. Before submitting, add the `/feedback` session ID for the main build session in `HACKATHON.md` and commit the completed work with its current date.

## Technology

Python · Flask · Whisper · FFmpeg · yt-dlp · Vanilla HTML/CSS/JavaScript · Codex with GPT-5.6

## License

MIT. See [LICENSE](LICENSE).