EDeev/mospoly-helper
1
0
Fork 0
mirror of https://github.com/EDeev/mospoly-helper.git synced 2026-10-07 20:49:32 +03:00
Code Releases 1 Activity

README на русском и английском

Browse source 
Авторы — по списку участников практики (practice_README.md); честно указано, для каких
кампусов есть видео; версии и примеры форматов приведены к коду.
This commit is contained in:
Деев Егор Викторович 2026-10-05 18:00:17 +00:00
parent f7b22ed764
commit 401fcfb2a9
2 changed files with 105 additions and 302 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

57
README.en.md Normal file
View file

@ -0,0 +1,57 @@
# MosPolyHelper
[Русский](README.md) · **English**
[![CI](https://github.com/EDeev/mospoly-helper/actions/workflows/ci.yml/badge.svg)](https://github.com/EDeev/mospoly-helper/actions/workflows/ci.yml)
A Telegram bot that sends a video route to a classroom in Moscow Polytechnic University buildings: pick a
campus, type the room number and get a video note with the way from the campus gate or from the building
entrance.
**Status:** team coursework (project practice, Moscow Polytech, group 241-327, 2025), completed · bot
[@MosPoly_Helperbot](https://t.me/MosPoly_Helperbot)
**Stack:** Python 3.10 · aiogram 3 · MoviePy 2 · FFmpeg · Docker
## Features
- Five campuses: Bolshaya Semyonovskaya, Pavla Korchagina, Pryanishnikova, Mikhalkovskaya, Avtozavodskaya
- A route from the campus gate or the building entrance: the clip is assembled from "building → floor →
room" fragments, sped up 2× and encoded for Telegram (H.264, 1500k)
- Finished clips are cached and repeat requests are instant; `combine.py` pre-builds the cache
- Room number validation with hints when the format or campus doesn't match
Videos were filmed for the Pryanishnikova buildings (76 rooms) and partly for Avtozavodskaya; for other
campuses the bot replies that the route isn't available yet and suggests writing by email.
## Running
```bash
git clone https://github.com/EDeev/mospoly-helper.git && cd mospoly-helper
cp .env.example .env # BOT_TOKEN from @BotFather
docker compose up -d
```
Without Docker: Python 3.10+, FFmpeg, `pip install -r requirements.txt`, then
`cd src/code && BOT_TOKEN=… python bot.py`. More in [QUICKSTART.md](QUICKSTART.md) and [DOCKER.md](DOCKER.md) (in Russian).
> [!NOTE]
> The repository holds about 220 video clips (sources and cache), so it is over 500 MB.
## License
Coursework (project practice, Moscow Polytechnic University, 2025). The code is open for study; there is
no separate license.
## Authors
- **Egor Deev** — [GitHub](https://github.com/EDeev)
- **Petr Saprykin** — [GitHub](https://github.com/PetrSaprykin)
- **Ruslan Starkov** — [GitHub](https://github.com/RayStar-k)
---
<div align="center">
<sub>⭐ If you find this project useful, give it a star on GitHub!</sub>
<p><sub>Made with ❤️ by Moscow Polytech students, group 241-327</sub></p>
</div>

350
README.md
View file

@ -1,330 +1,76 @@
# МосПолиХелпер 🎓 # МосПолиХелпер
**Телеграм-бот для навигации по кампусам Московского Политехнического Университета** **Русский** · [English](README.en.md)
[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://python.org) [![CI](https://github.com/EDeev/mospoly-helper/actions/workflows/ci.yml/badge.svg)](https://github.com/EDeev/mospoly-helper/actions/workflows/ci.yml)
[![Aiogram](https://img.shields.io/badge/Aiogram-3.0.0-green.svg)](https://aiogram.dev/)
[![MoviePy](https://img.shields.io/badge/MoviePy-1.0.3-red.svg)](https://moviepy.readthedocs.io/)
[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED.svg?logo=docker&logoColor=white)](https://www.docker.com/)
[![Bot](https://img.shields.io/badge/Telegram-@MosPoly__Helperbot-blue.svg)](https://t.me/MosPoly_Helperbot)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
## 📋 Описание Telegram-бот, который присылает видео-маршрут до нужной аудитории в корпусах Московского Политеха:
выбираешь кампус, пишешь номер кабинета — получаешь кружок с дорогой от входа на территорию или от входа
в корпус.
МосПолиХелпер — это практическое решение реальной проблемы ориентирования в кампусах Московского Политехнического Университета. Бот разработан студентами для студентов и предоставляет интерактивные видео-маршруты до любого кабинета в пяти основных кампусах университета. **Статус:** учебный командный проект (проектная практика, Московский Политех, группа 241-327, 2025),
завершён · бот [@MosPoly_Helperbot](https://t.me/MosPoly_Helperbot)
Проект создан в рамках проектной практики и демонстрирует применение современных технологий для решения повседневных задач студенческой жизни. **Стек:** Python 3.10 · aiogram 3 · MoviePy 2 · FFmpeg · Docker
### ✨ Основные возможности ## Возможности
- 🗺️ **Интерактивная навигация** по 5 кампусам МосПолитеха - Пять кампусов: Большая Семёновская, Павла Корчагина, Прянишникова, Михалковская, Автозаводская
- 🎥 **Динамические видео-маршруты** от входа на территорию или от входа в корпус - Маршрут от входа на территорию или от входа в корпус: ролик собирается из фрагментов «корпус → этаж →
- ⚡ **Мгновенная отдача** готовых маршрутов благодаря интеллектуальному кешированию кабинет», ускоряется вдвое и кодируется под Telegram (H.264, 1500k)
- 📱 **Интуитивный интерфейс** с адаптивными inline-кнопками - Готовые ролики кешируются, повторный запрос отдаётся сразу; `combine.py` собирает кеш заранее
- 🔄 **Автоматическая обработка видео** с оптимизацией для Telegram (H.264, битрейт 1500k) - Проверка номера кабинета и подсказки, если формат не тот или кампус не совпадает
- 🚀 **Высокая производительность** — время отклика менее 5 секунд для кешированных маршрутов
- 📊 **Умная валидация** входных данных с подсказками пользователю
### 🏢 Поддерживаемые кампусы Видео сняты для корпусов на Прянишникова (76 кабинетов) и частично на Автозаводской; для остальных
кампусов бот отвечает, что маршрута пока нет, и предлагает написать на почту.
| Кампус | Код | Формат номера кабинета | Пример | | Кампус | Формат кабинета | Пример |
|--------|-----|------------------------|---------| |---|---|---|
| **Большая Семёновская** | `bs` | [корпус][этаж]-[номер] | `а1-01`, `б2-15` | | Прянишникова | пр[корпус][этаж][номер] | `пр2202а` |
| **Павла Корчагина** | `pk` | пк[корпус][этаж][номер] | `пк1201`, `пк2315` | | Автозаводская | ав[корпус][этаж][номер] | `ав2301` |
| **Прянишникова** | `pr` | пр[корпус][этаж][номер] | `пр1101`, `пр2208` | | Павла Корчагина | пк[корпус][этаж][номер] | `пк1201` |
| **Михалковская** | `mi` | м[корпус][этаж][номер] | `м1205`, `м3110` | | Михалковская | м[корпус][этаж][номер] | `м1205` |
| **Автозаводская** | `av` | ав[корпус][этаж][номер] | `ав2301`, `ав1105` | | Большая Семёновская | [корпус][этаж]-[номер] | `а1-01` |
> 📝 **Важно**: Указывайте номер кабинета точно в том формате, как он указан в личном кабинете или расписании ## Запуск
## 🚀 Быстрый старт
### 🐳 Запуск через Docker (рекомендуется)
```bash ```bash
# 1. Клонирование репозитория git clone https://github.com/EDeev/mospoly-helper.git && cd mospoly-helper
git clone https://github.com/EDeev/mospoly-helper.git cp .env.example .env # BOT_TOKEN от @BotFather
cd mospoly-helper docker compose up -d
# 2. Настройка токена
cp .env.example .env
# Отредактируйте .env и добавьте ваш BOT_TOKEN
# 3. Запуск
docker-compose up -d
``` ```
📖 **Подробнее**: [QUICKSTART.md](QUICKSTART.md) | [DOCKER.md](DOCKER.md) Без Docker: Python 3.10+, FFmpeg, `pip install -r requirements.txt`, затем
`cd src/code && BOT_TOKEN=… python bot.py`. Подробнее — [QUICKSTART.md](QUICKSTART.md) и [DOCKER.md](DOCKER.md).
### Команды бота > [!NOTE]
> В репозитории около 220 роликов (исходники и кеш), поэтому он весит больше 500 МБ.
- `/start` — Приветствие и инструкции ## Структура
- `/help` — Справка по командам
- `/route` — Построить маршрут до кабинета
### Использование
1. Запустите бота командой `/start`
2. Выберите команду `/route`
3. Укажите кампус из предложенного списка
4. Введите номер кабинета в точном формате
5. Выберите тип маршрута (от территории или от входа в корпус)
6. Получите видео с маршрутом
## 🛠️ Архитектура и технический стек
### 🧩 Технологии
| Компонент | Технология | Версия | Назначение |
|-----------|------------|---------|------------|
| **Backend** | Python | 3.10+ | Основной язык разработки |
| **Bot Framework** | Aiogram | 3.0.0 | Асинхронная работа с Telegram Bot API |
| **Video Processing** | MoviePy | 1.0.3 | Обработка и монтаж видеофрагментов |
| **Video Encoding** | FFmpeg | latest | Кодирование и оптимизация видео |
| **Data Storage** | JSON | native | Хранение пользовательских сессий |
| **State Management** | MemoryStorage | aiogram | Управление состояниями пользователей |
### 🏗️ Модульная архитектура
``` ```
src/code/ src/code/ бот: handlers.py (команды и кнопки), scripts.py (маршруты и монтаж), combine.py (кеш)
├── bot.py # 🚀 Точка входа и координация приложения src/videos/ исходные фрагменты: <кампус>/buildings, floors, offices
├── config.py # ⚙️ Конфигурационные параметры src/data/cache собранные маршруты
├── database.py # 💾 Управление пользовательскими данными site/ сайт проекта практики
├── handlers.py # 🎛️ Обработчики команд и callback'ов reports/ отчёты участников и презентация
├── init.py # 🔧 Инициализация компонентов бота task/ задание практики
├── scripts.py # 🎬 Обработка видео и формирование маршрутов
└── combine.py # 🔄 Утилита для предварительной генерации кеша
``` ```
**Принципы проектирования:** ## Лицензия
- **Single Responsibility** — каждый модуль отвечает за конкретную задачу
- **Dependency Injection** — слабая связанность между компонентами
- **Async/Await** — асинхронная обработка для высокой производительности
- **Error Handling** — корректная обработка ошибок на всех уровнях
## 📁 Структура данных и файловая система Учебный проект (проектная практика, Московский Политех, 2025). Код открыт для изучения, отдельной
лицензии нет.
``` ## Авторы
📦 mospoly-helper/
├── 📂 src/code/ # Исходный код
├── 📂 data/ # Рабочие данные
│ ├── 📂 cache/ # Сгенерированные видеомаршруты
│ │ ├── 📄 *-all.mp4 # Полные маршруты (от территории)
│ │ └── 📄 *-small.mp4 # Короткие маршруты (от входа в корпус)
│ ├── 📂 users/ # JSON-файлы сессий пользователей
│ │ └── 📄 {user_id}.json # Данные конкретного пользователя
│ └── 📂 videos/ # Библиотека исходных видеофрагментов
│ ├── 📂 av/ # Автозаводская
│ │ ├── 📂 buildings/ # Видео от входа до корпуса
│ │ ├── 📂 floors/ # Видео по этажам
│ │ └── 📂 offices/ # Видео до конкретных кабинетов
│ ├── 📂 bs/ # Большая Семёновская
│ ├── 📂 mi/ # Михалковская
│ ├── 📂 pk/ # Павла Корчагина
│ └── 📂 pr/ # Прянишникова
└── 📂 logs/ # Журналы работы (рекомендуется)
```
## ⚡ Установка и настройка - **Деев Егор** — [GitHub](https://github.com/EDeev)
- **Сапрыкин Пётр** — [GitHub](https://github.com/PetrSaprykin)
### 📋 Системные требования - **Старков Руслан** — [GitHub](https://github.com/RayStar-k)
- **OS**: Linux (Ubuntu 20.04+), macOS, Windows 10+
- **Python**: 3.10 или выше
- **RAM**: минимум 2 ГБ (рекомендуется 4 ГБ)
- **Storage**: минимум 10 ГБ для видеофрагментов и кеша
- **Network**: стабильное интернет-соединение
### 🔧 Установка зависимостей
1. **Клонирование репозитория**
```bash
git clone https://github.com/EDeev/mospoly-helper.git
cd mospoly-helper
```
2. **Установка Python-зависимостей**
```bash
pip install -r requirements.txt
```
3. **Установка FFmpeg**
**Ubuntu/Debian:**
```bash
sudo apt update && sudo apt install ffmpeg
```
**macOS (с Homebrew):**
```bash
brew install ffmpeg
```
**Windows:**
Скачайте с [официального сайта](https://ffmpeg.org/download.html) и добавьте в PATH
### ⚙️ Конфигурация
1. **Создание Telegram бота**
- Перейдите к [@BotFather](https://t.me/BotFather)
- Создайте нового бота командой `/newbot`
- Сохраните полученный токен
2. **Настройка конфигурации**
```python
# config.py
BOT_TOKEN = "YOUR_BOT_TOKEN_HERE" # Замените на ваш токен
```
3. **Создание структуры каталогов**
```bash
mkdir -p data/{cache,users,videos/{av,bs,mi,pk,pr}/{buildings,floors,offices}}
mkdir -p logs
```
### 🚀 Запуск
**Основной режим:**
```bash
cd src/code
python bot.py
```
**С логированием:**
```bash
python bot.py 2>&1 | tee ../../logs/bot.log
```
**Предварительная генерация кеша (опционально):**
```bash
python combine.py # Генерирует кеш для всех доступных маршрутов
```
## 🎯 Алгоритмы и оптимизации
### 🎬 Обработка видео
Система обработки видео использует продвинутые техники оптимизации:
```python
# Параметры кодирования (scripts.py)
full_clip.write_videofile(
filename,
fps=30, # Оптимальная частота кадров
codec="libx264", # Эффективный кодек H.264
bitrate="1500k", # Баланс качество/размер
preset="fast", # Быстрое кодирование
ffmpeg_params=["-crf", "23"] # Constant Rate Factor для качества
)
```
**Применяемые оптимизации:**
- ✂️ **Удаление аудиодорожки** — экономия 30-40% размера файла
- ⏩ **Ускорение в 2 раза** — сокращение времени просмотра
- 📐 **Изменение разрешения до 400px** — оптимизация для мобильных устройств
- 🗜️ **CRF 23** — оптимальный баланс качества и размера файла
### ⚡ Система кеширования
**Двухуровневое кеширование:**
1. **Полные маршруты** (`*-all.mp4`) — от входа на территорию
2. **Короткие маршруты** (`*-small.mp4`) — от входа в корпус
**Алгоритм проверки кеша:**
```python
# Проверка существования готового файла
cache_path = f"../data/cache/{route_id}-{'all' if full_route else 'small'}.mp4"
if os.path.exists(cache_path):
return cache_path # Мгновенная отдача
else:
return await make_full_clip(video_segments) # Генерация нового
```
### 📊 Производительность
| Метрика | Кешированный маршрут | Новый маршрут |
|---------|---------------------|---------------|
| **Время отклика** | < 3 секунды | 15-30 секунд |
| **Размер файла** | 2-8 МБ | аналогично |
| **Качество видео** | 400p, 30fps | аналогично |
| **Нагрузка на CPU** | минимальная | высокая |
## 🧪 Оптимизации производительности
| Компонент | До оптимизации | После оптимизации | Улучшение |
|-----------|----------------|-------------------|-----------|
| **Размер видео** | 15-25 МБ | 2-8 МБ | 🔻 70% |
| **Время генерации** | 45-60 сек | 15-30 сек | 🔻 50% |
| **Время отдачи (кеш)** | N/A | < 3 сек | ⚡ мгновенно |
| **Использование RAM** | 200-300 МБ | 100-150 МБ | 🔻 40% |
## 📦 combine.py — Пакетная генерация кеша
Утилита для предварительной генерации видеомаршрутов:
```python
async def combine_all_videos():
"""
Массовая генерация кеша для всех доступных маршрутов
Обрабатывает:
- Все корпуса: pr, pk, mi, av, bs
- Полные и короткие маршруты для каждого кабинета
- Пропускает несуществующие видеофрагменты
"""
corpora = ["pr", "pk", "mi", "av", "bs"]
for corpus in corpora:
offices_path = f"../videos/{corpus}/offices"
for video_file in os.listdir(offices_path):
# Генерация полного маршрута
await make_full_clip([building_path, floor_path, office_path])
# Генерация короткого маршрута
await make_full_clip([floor_path, office_path])
```
**Использование:**
```bash
cd src/code
python combine.py # Запуск в фоновом режиме для больших объемов
```
## 👨‍💻 Команда разработки
Проект создан в рамках проектной практики студентами группы **241-327** направления "Системная и программная инженерия":
| Участник | Роль | Вклад | Контакты |
|----------|------|-------|----------|
| **[Деев Егор Викторович](https://github.com/EDeev)** | Tech Lead & Backend Developer | Архитектура системы, обработка видео, оптимизация производительности | [@EDeev](https://t.me/EDeev) |
| **[Сапрыкин Пётр Иванович](https://github.com/PetrSaprykin)** | Frontend & UX Developer | Пользовательский интерфейс, логика взаимодействия, тестирование | [@PetrSaprykin](https://github.com/PetrSaprykin) |
| **[Старков Руслан Владимирович](https://github.com/RayStar-k)** | DevOps & QA Engineer | Развертывание, мониторинг, обеспечение качества | [@RayStar-k](https://github.com/RayStar-k) |
**Научное руководство:**
- **Куратор практики**: Баринова Наталья Владимировна
- **Кураторы проектной деятельности**: Киреева Галина Ивановна, Будылина Евгения Александровна
## 📞 Поддержка и контакты
### 🆘 Получение помощи
**Официальные каналы поддержки:**
1. **📧 Email**: [support@new-devs.ru](mailto:support@new-devs.ru)
- Время ответа: 24-48 часов
- Для технических вопросов и предложений
2. **🐙 GitHub Issues**: [Создать issue](https://github.com/EDeev/mospoly-helper/issues)
- Для сообщений об ошибках и feature requests
- Публичное обсуждение и tracking
## 📄 Лицензия и правовая информация
Этот проект создан в учебных целях как работа по дисциплине "Проектной практики" в Московском Политехническом Университете, 2024-2025 учебный год.
--- ---
<div align="center"> <div align="center">
<sub>МосПолиХелпер — делаем навигацию в университете простой и понятной! 🎓✨</sub> <sub>⭐ Если проект оказался полезным, поставьте звёздочку на GitHub!</sub>
<p><sub>Создано с ❤️ студентами МосПолитеха для студенческого сообщества</sub></p> <p><sub>Сделано с ❤️ студентами Московского Политеха, группа 241-327</sub></p>
</div> </div>