🧠 Course Tutor

Turn your professor's lectures into an AI tutor that talks like them — locally, with 70% fewer tokens.

把你老师的课件和录音，蒸馏成一个模仿老师讲课风格的 AI 助教。本地预处理，不烧 API token。

---

Why Course Tutor?

The problem with dumping files into ChatGPT

❌ Before — You have 500 MB of lecture slides and 10 hours of class recordings. You try to ask ChatGPT for help:

• The PPT is 30 K tokens of layout metadata, embedded fonts, and chart XML
• The AI answers in its own generic voice — nothing like your professor
• Audio? Can't upload it. You'd re-listen to three hours for one definition
• Quota burned before you even asked the real question

✅ After — Course Tutor processes everything on your machine first:

• PPT/PDF → clean Markdown (text + speaker notes, ~70% smaller)
• Audio/Video → timestamped transcript (Whisper, local, no API key)
• Recording analysis → your teacher's 口头禅 · 举例偏好 · 解释策略 · 语气 distilled into a style profile
• One structured knowledge_base.md → copy-paste into any LLM

Now when you ask "can you explain this the way my professor does?" the AI actually can.

---

Features

📦 Smart File Processing

Drag any mix of files or folders (any nesting depth), or drop a .zip archive. Course Tutor sorts, extracts, and silently discards garbage (.DS_Store, ~$lock.docx, __MACOSX, Thumbs.db) automatically. Unsupported formats don't crash the pipeline — they're skipped with a visible note in the UI.

Category	Formats
📊 Slides	.pptx, .ppt — extracts text, tables, and speaker notes per slide
📄 PDFs	.pdf — layout-aware text extraction (PyMuPDF)
📝 Word	.docx — paragraphs + tables
📈 Spreadsheets	.xlsx, .xls, .csv, .tsv — one Markdown table per sheet
🌐 Web	.html, .htm — text-only, strips scripts/styles
📓 Notebooks	.ipynb — code + markdown cells preserved
📃 Text	.txt, .md
🎙️ Audio	.mp3, .m4a, .wav, .flac, .ogg, .aac
🎬 Video	.mp4, .mov, .avi, .mkv, .webm (audio track transcribed)
🖼️ Images	.jpg, .png, .bmp — OCR via Tesseract (optional)
🗜️ Archives	.zip — auto-expands with structure preserved

🎙️ Audio Transcription

Powered by OpenAI Whisper, running locally. No API key, no cloud, no per-minute billing. Each audio or video file produces four outputs:

• name.md — 5-minute chapter-like chunks (reading-friendly)
• name_plain.txt — clean text for embedding or search
• name_timestamped.txt — [00:05:23 → 00:05:41]-tagged lines for jumping back to specific moments
• name_segments.json — structured segments for programmatic use

Model size is configurable (tiny · base · small · medium · large) so you can trade speed for accuracy. Chinese and English both work out of the box; other Whisper-supported languages via --language.

🎭 Teacher Style Extraction

The feature that makes this more than a file converter. Course Tutor analyzes transcripts to build a style profile:

{
  "口头禅": ["比如说", "你们想一想", "关键在于"],
  "解释策略": "先给直觉再给公式，经常用生活类比",
  "举例偏好": "偏好用学生日常生活场景（点外卖、考试分数）",
  "纠错方式": "先肯定学生的思路，再指出哪里偏了",
  "语气特征": "亲切、鼓励性强、偶尔幽默"
}

This profile travels with the knowledge base, so the downstream LLM can speak in your teacher's voice — not its own default.

📚 Structured Knowledge Base

One click merges every processed material + transcript + style profile into a single knowledge_base.md, organized by folder (which usually matches your course's chapter structure). From the Dashboard:

• 📋 Copy the entire KB to clipboard — paste into Claude / ChatGPT
• 💾 Download the .md — upload to Claude Projects or ChatGPT Knowledge
• 👁️ Preview inline with syntax-highlighted headers before exporting

⚡ Token Efficiency

Approach	Input tokens	Signal-to-noise
Drop raw .pptx into ChatGPT	~30,000	XML/layout junk, no audio
Course Tutor → Markdown	~8,000	Structured, audio included, style-aware

Roughly a 70% reduction, often the difference between fitting and not fitting in a single context window. Batch it across 10 lectures and you save a real amount of quota.

🖥️ Dashboard (pure Python, no Node.js)

A single-file Flask server plus a vanilla-JS index.html. Start it, open http://localhost:5000, drag in a folder:

• Per-file processing status (pending / processed / transcribed / oversized / unsupported)
• Folder-grouped file tree that matches your upload structure
• Live progress bar for batch operations (/process-all)
• Inline KB preview with one-click copy / download

[screenshot]

---

Quick Start

Python 3.9+ and conda recommended. Total setup: ~5 minutes (plus Whisper model download on first audio run).

# 1. Clone
git clone https://github.com/uczltw6/course-tutor.git
cd course-tutor

# 2. Create a clean env with ffmpeg baked in
conda create -n tutor python=3.11 ffmpeg -c conda-forge -y
conda activate tutor

# 3. Install Python deps (whisper pulls in a CPU torch wheel automatically)
pip install -r requirements.txt

# 4. Launch
python server.py
# Windows shortcut: just double-click run.bat

Open http://localhost:5000 → click ＋ 添加课程 → drag your lecture folder in → hit 🚀 一键处理全部.

Troubleshooting

Whisper fails with OSError: [WinError 1114] on Windows

This is PyTorch's c10.dll failing to load — almost always a missing Visual C++ Redistributable or a mixed conda/pip torch install. Easiest fix: use a fresh conda env as shown above. Don't pip install torch into your base env.

ffmpeg not found during transcription

Whisper shells out to ffmpeg as a separate process. Make sure it's on your PATH:

ffmpeg -version  # should print "ffmpeg version 4.x"

If you used the conda command above, ffmpeg lives in <env>/Library/bin and is activated automatically.

GPU acceleration

For 10× faster transcription on NVIDIA GPUs, install CUDA-enabled torch before pip install -r requirements.txt:

pip install torch --index-url https://download.pytorch.org/whl/cu121

See pytorch.org for the right index for your CUDA version.

---

How It Works

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌──────────────┐
│   Upload    │ ──▶ │  Classify   │ ──▶ │  Extract /  │ ──▶ │   Style     │ ──▶ │     KB       │
│             │     │  per file   │     │ Transcribe  │     │  Analysis   │     │  build .md   │
│ drag folder │     │    type     │     │   (local)   │     │  (keywords) │     │              │
│   or .zip   │     │             │     │             │     │             │     │              │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘     └──────┬───────┘
                                                                                       │
                                 ┌─────────────────────────────────────────────────────┘
                                 ▼
                        📋 Copy → paste into Claude / ChatGPT
                        💾 Download → Claude Projects knowledge
                        🧠 Install SKILL.md → native tutor mode

Everything runs on your machine. Whisper runs locally. No cloud uploads, no API keys, no per-request billing.

---

Project Structure

course-tutor/
├── server.py                    # Flask server — backend + routing + static serving
├── requirements.txt             # Python deps
├── run.bat / run.ps1            # Windows launchers (activate env + PATH → start server)
├── templates/
│   └── index.html               # Dashboard — CSS + HTML + JS, self-contained
├── scripts/
│   ├── process_materials.py     # PPT/PDF/Word/Excel/CSV/HTML/ipynb/OCR → Markdown
│   ├── transcribe_audio.py      # Whisper audio/video → timestamped Markdown + JSON
│   └── build_knowledge_base.py  # Merge materials + transcripts + style → knowledge_base.md
├── skill/
│   └── SKILL.md                 # Drop-in Claude Skill — native tutor mode
└── data/                        # Runtime, gitignored
    └── courses/
        └── <course-name>/
            ├── config.json          # Course metadata + teacher style profile
            ├── raw/                 # Originals (preserves your folder hierarchy)
            ├── materials/           # Extracted Markdown, mirrors raw/ structure
            ├── transcripts/         # Audio transcripts, mirrors raw/ structure
            └── knowledge_base.md    # Final KB (what you copy / download)

---

API Reference

All endpoints under /api. JSON bodies unless noted.

Method	Path	Purpose
GET	/courses	List all courses with file status
POST	/courses	Create a course — {name, teacher}
PUT	/courses/:id	Rename / reassign teacher
DELETE	/courses/:id	Delete course (all files + KB)
POST	/courses/:id/upload	Upload files/folders (multipart: files[] + paths[])
POST	/courses/:id/process	Process one file — {path}
POST	/courses/:id/process-all	Kick off background batch
GET	/courses/:id/process-all/progress	Poll batch progress {running, total, done, current, results}
POST	/courses/:id/extract-style	Compute teacher style profile from transcripts
POST	/courses/:id/build-kb	Build / rebuild knowledge_base.md
GET	/courses/:id/kb-content	Get KB as JSON — {content}
GET	/courses/:id/kb-download	Download KB as attachment

---

Use with Claude / ChatGPT / Any LLM

Three ways to feed the knowledge base to an LLM, from quickest to most seamless:

1. One-shot conversation

Click 📋 一键复制全部内容 on the KB tab → paste into any chat. Good for a single study session.

2. Persistent knowledge (recommended)

Click 💾 下载 .md → upload to Claude Projects knowledge or ChatGPT's custom GPT "Knowledge". Every conversation in that project automatically sees your teacher.

3. Native Skill integration

Drop skill/SKILL.md into your Claude Skills folder. Claude auto-detects context (user asks "这个老师怎么讲的？" → skill activates) and switches into tutor mode. See skill/SKILL.md for the full spec including setup mode + answering mode + style adherence rules.

---

Roadmap

• Deeper style analysis — optional opt-in to Claude/OpenAI API for richer style profiles beyond keyword frequency
• Review & quiz generation — auto-build flashcards and practice problems from the KB
• Multi-course knowledge merge — cross-reference concepts across courses
• Per-file error surfacing — show the actual stderr on failed cards, not just "❌ 失败"
• Electron desktop build — one binary, no conda setup
• Streaming transcription progress — word-by-word updates instead of file-by-file
• More formats — .epub, .mobi, LaTeX sources, Anki deck import
• Mobile dashboard — responsive layout for phones/tablets

---

Inspired By

This project is directly inspired by alchaincyf/zhangxuefeng-skill (6k+ ⭐), which distills a specific celebrity educator's reasoning framework into a Claude Skill. It also draws on the broader Skill framework (女娲.skill) for structuring LLM-side roleplay.

Course Tutor generalizes that idea:

Instead of distilling a famous person, distill your own professor.

Everyone has a teacher who changed how they think. This tool lets you clone that voice into a study companion — not as a replacement for the teacher, but as the "can you say it one more time?" you wish you could ask at 3 AM before an exam.

---

Contributing

Contributions welcome, especially:

• Testing on macOS and Linux (currently best-tested on Windows 11)
• More OCR language packs
• Dashboard accessibility improvements
• New extractors for .epub, LaTeX, Anki, etc.

1. Fork the repo
2. Create a feature branch — git checkout -b feat/your-thing
3. Commit with a clear message ("why" over "what")
4. Open a PR

For bug reports, please include OS, Python version, and the server terminal output.

---

License

MIT — do whatever you want, just keep the notice. See LICENSE.

---

_{If this tool helped you study, consider giving it a ⭐. If it saved you a month of API tokens, send its creator a 🧋.}