{"id":51518017,"url":"https://github.com/ark2016/lecture-scribe","last_synced_at":"2026-07-08T13:01:27.542Z","repository":{"id":339352640,"uuid":"1153524173","full_name":"ark2016/lecture-scribe","owner":"ark2016","description":"A Python CLI tool that converts lecture video recordings into structured notes (Markdown + HTML) with LaTeX formulas and timestamps.  Developed for processing screen recordings from Telegram calls where the lecturer writes by hand in Paint.","archived":false,"fork":false,"pushed_at":"2026-02-19T09:00:34.000Z","size":53,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-19T14:06:58.985Z","etag":null,"topics":["asr","handwriting-recognition","llm","mistral","ocr","video-processing","video-to-text-converter"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ark2016.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-09T11:57:02.000Z","updated_at":"2026-02-15T17:02:45.000Z","dependencies_parsed_at":"2026-02-19T14:07:05.022Z","dependency_job_id":null,"html_url":"https://github.com/ark2016/lecture-scribe","commit_stats":null,"previous_names":["ark2016/lecture-scribe"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ark2016/lecture-scribe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ark2016%2Flecture-scribe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ark2016%2Flecture-scribe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ark2016%2Flecture-scribe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ark2016%2Flecture-scribe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ark2016","download_url":"https://codeload.github.com/ark2016/lecture-scribe/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ark2016%2Flecture-scribe/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35265380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asr","handwriting-recognition","llm","mistral","ocr","video-processing","video-to-text-converter"],"created_at":"2026-07-08T13:01:26.752Z","updated_at":"2026-07-08T13:01:27.431Z","avatar_url":"https://github.com/ark2016.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lecture Scribe\n\nCLI-инструмент на Python, который превращает видеозаписи лекций в структурированные конспекты (Markdown + HTML) с LaTeX-формулами и таймстемпами.\n\nРазработан для обработки записей экрана из Telegram-звонков, где лектор пишет от руки в Paint.\n\n\u003e Проект использует **бесплатную исследовательскую лицензию Mistral API** (free research tier). Все API-вызовы — бесплатны в рамках этого тарифа.\n\n## Как это работает\n\n```\nvideo.mp4\n│\n├── [Audio Pipeline]\n│   ffmpeg → WAV → Voxtral Transcribe → transcript.json\n│\n├── [Visual Pipeline]\n│   OpenCV (2 fps) → SSIM keyframe detection → Mistral OCR → LLM structuring → visual.json\n│\n└── [Merge]\n    transcript + visual → synchronized blocks → output.md + output.html\n```\n\n**Три этапа:**\n\n1. **Аудио** — ffmpeg извлекает звук, Voxtral Mini транскрибирует с таймстемпами\n2. **Визуал** — OpenCV семплирует кадры, SSIM детектирует ключевые кадры, Mistral OCR читает текст, LLM структурирует в JSON с LaTeX\n3. **Объединение** — синхронизация по таймстемпам, вывод в Markdown + HTML (с MathJax)\n\n## Используемые модели Mistral\n\n| Задача | Модель | Тип |\n|--------|--------|-----|\n| Транскрипция аудио | `voxtral-mini-latest` | Audio |\n| OCR кадров | `mistral-ocr-latest` | OCR |\n| Структурирование текста | `mistral-large-latest` | Chat |\n\nВсе модели доступны на бесплатном исследовательском тарифе Mistral с ограничением по rate limit (~1 RPS).\n\n## Установка\n\n**Требования:**\n- Python 3.11+\n- ffmpeg (установлен в системе и доступен в PATH)\n\n```bash\ngit clone https://github.com/\u003cyour-user\u003e/lecture-scribe.git\ncd lecture-scribe\npython -m venv .venv\n.venv\\Scripts\\activate  # Windows\n# source .venv/bin/activate  # Linux/macOS\n\npip install -e .\n# или с фиксированными версиями:\npip install -r requirements.txt\n```\n\n**Настройка API-ключа:**\n\n```bash\ncp .env.example .env\n# Отредактировать .env, вставить свой ключ:\n# MISTRAL_API_KEY=your_key_here\n```\n\nКлюч можно получить на [console.mistral.ai](https://console.mistral.ai/) — бесплатный research tier.\n\n## Использование\n\n```bash\n# Базовый запуск\nlecture-transcribe video.mp4 -o notes.md\n\n# Только визуал (без аудио), с кэшированием промежуточных файлов\nlecture-transcribe video.mp4 -o notes.md --no-audio \\\n  --save-keyframes ./keyframes \\\n  --save-transcript ./transcript.json \\\n  --save-visual ./visual.json \\\n  --cache\n\n# С терминами предмета (context bias для транскрипции)\nlecture-transcribe video.mp4 -o notes.md \\\n  --terms \"определитель,матрица,собственное значение\"\n\n# Отладка\nlecture-transcribe video.mp4 -o notes.md --debug\n```\n\n### Основные опции\n\n| Опция | Описание |\n|-------|----------|\n| `-o, --output` | Путь к выходному .md файлу (HTML генерируется автоматически) |\n| `--no-audio` | Пропустить аудио-пайплайн (только визуал) |\n| `--cache` | Переиспользовать кэшированные промежуточные файлы |\n| `--save-keyframes DIR` | Сохранить ключевые кадры как PNG |\n| `--save-transcript PATH` | Сохранить транскрипт в JSON |\n| `--save-visual PATH` | Сохранить результаты OCR в JSON (поддерживает resume) |\n| `--terms` | Термины предмета через запятую (context bias) |\n| `--fps` | Частота семплирования кадров (по умолчанию 2.0) |\n| `--vision-model` | Модель для структурирования (по умолчанию `mistral-large-latest`) |\n| `--vision-interval` | Минимальный интервал между API-вызовами в секундах |\n| `--vision-rate-retries` | Количество повторов при 429 ошибке |\n| `--continue-after-rate-limit` | Продолжать обработку после исчерпания rate limit |\n| `--config` | Путь к YAML-файлу конфигурации |\n| `--debug` | Подробное логирование |\n\n## Работа с rate limit (бесплатный тарифф)\n\nНа бесплатном research tier Mistral есть ограничения по количеству запросов. Пайплайн адаптирован для этого:\n\n- **Инкрементальное сохранение** — каждый успешный результат OCR сразу записывается в `visual.json`\n- **Resume** — при повторном запуске с `--cache` уже обработанные кадры пропускаются\n- **Адаптивные интервалы** — при получении 429 интервал между запросами автоматически увеличивается\n- **Graceful abort** — при исчерпании лимита обработка останавливается, сохраняя прогресс\n\nТипичный сценарий для длинной лекции:\n\n```bash\n# Запуск 1 — обработает первые N кадров до rate limit\nlecture-transcribe video.mp4 -o notes.md --no-audio \\\n  --save-keyframes ./keyframes --save-visual ./visual.json --cache\n\n# Подождать ~10-30 минут (восстановление квоты)\n\n# Запуск 2 — продолжит с того места, где остановился\nlecture-transcribe video.mp4 -o notes.md --no-audio \\\n  --save-keyframes ./keyframes --save-visual ./visual.json --cache\n```\n\n## Выходные форматы\n\n### Markdown (`output.md`)\n\n```markdown\n# Конспект лекции\n\n## [00:02:15]\n\n**Лектор:** Рассмотрим функцию f(x) = 1/x на промежутке...\n\n**На доске:**\n\nЗадана функция $f(x) = \\frac{1}{x}$ на множестве $x \\in [1; +\\infty)$.\n\n\u003e **Схема:** График функции f(x) = 1/x, убывающей от 1 до 0.\n```\n\n### HTML (`output.html`)\n\nАвтоматически генерируется вместе с Markdown. Включает:\n- MathJax v3 для рендеринга LaTeX-формул\n- Адаптивный дизайн с dark mode\n- Стилизованные блоки для таймстемпов, речи лектора и содержимого доски\n\n## Структура проекта\n\n```\nlecture_transcriber/\n├── cli.py                    # CLI (Click)\n├── config.py                 # Конфигурация (dataclass + YAML + .env)\n├── pipeline.py               # Оркестратор пайплайна\n├── audio/\n│   ├── extractor.py          # ffmpeg: video → WAV\n│   └── transcriber.py        # Voxtral API: audio → transcript\n├── video/\n│   ├── sampler.py            # OpenCV: video → frames (N fps)\n│   ├── keyframe_detector.py  # SSIM + flicker filter\n│   ├── keyframe_tracker.py   # Buffer matching (Phase 2 stub)\n│   └── visual_recognizer.py  # OCR + LLM structuring → visual segments\n├── merge/\n│   ├── synchronizer.py       # Align audio + visual by timestamps\n│   └── formatter.py          # Markdown + HTML generation\n└── utils/\n    └── api_client.py         # Mistral API wrapper (retry, rate limit, backoff)\n```\n\n## Конфигурация (YAML)\n\n```yaml\n# config.yaml (опционально)\nmistral_api_key: \"...\"  # или через .env / MISTRAL_API_KEY\n\nsample_fps: 2.0\nssim_threshold_significant: 0.85\nssim_threshold_minor: 0.95\n\nvision_model: \"mistral-large-latest\"\nvision_min_interval: 8.0\nvision_max_429_retries: 3\nvision_abort_on_rate_limit: true\n\nmerge_window_seconds: 5.0\ninclude_timestamps: true\ninclude_audio_text: true\n```\n\n## Лицензия\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fark2016%2Flecture-scribe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fark2016%2Flecture-scribe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fark2016%2Flecture-scribe/lists"}