mirror of
https://github.com/EDeev/circlechek.git
synced 2026-10-07 20:49:51 +03:00
README на русском и английском с иллюстрацией фонов
This commit is contained in:
parent
a15bfba330
commit
44010bba0b
3 changed files with 127 additions and 78 deletions
78
README.en.md
Normal file
78
README.en.md
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
# Circlechek
|
||||
|
||||
[Русский](README.md) · **English**
|
||||
|
||||
[](https://github.com/EDeev/circlechek/actions/workflows/ci.yml)
|
||||
[](https://github.com/EDeev/circlechek/actions/workflows/docker.yml)
|
||||
[](LICENSE)
|
||||
|
||||
A Telegram bot for video notes ("circles"): turns a square video into a round video note, and turns a
|
||||
video note back into a regular video with the corners filled by a blurred frame or a gradient matching
|
||||
the picture. The bot speaks Russian.
|
||||
|
||||
**Status:** personal project, completed · bot [@circlechek_bot](https://t.me/circlechek_bot)
|
||||
|
||||
|
||||
|
||||
**Stack:** Python 3.12 · aiogram 3 · MoviePy 2 · Pillow · NumPy · Docker
|
||||
|
||||
## Features
|
||||
|
||||
- **Video → video note.** A square video up to one minute comes back as a circle.
|
||||
- **Video note → video.** The bot splits the circle into frames, fills the corners and reassembles the
|
||||
video with sound. Background options:
|
||||
- **blur** — a blurred center of the frame;
|
||||
- **gradient** — based on the frame's average color.
|
||||
- Heavy processing runs in a separate thread, so the bot keeps answering others while one circle is
|
||||
processed. Each job gets its own temporary folder, cleaned up even on errors.
|
||||
|
||||
> [!NOTE]
|
||||
> Some Telegram video notes have broken metadata; processing then fails or the video has artifacts. The
|
||||
> bot warns about this, so check the result.
|
||||
|
||||
## Running
|
||||
|
||||
```bash
|
||||
git clone https://github.com/EDeev/circlechek.git && cd circlechek
|
||||
cp .env.example .env # BOT_TOKEN from @BotFather
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Prebuilt image: `docker pull ghcr.io/edeev/circlechek` or `docker pull dcr.deev.su/edeev/circlechek`.
|
||||
|
||||
Without Docker: Python 3.12, `pip install -r requirements.txt`, then `cd code && BOT_TOKEN=… python bot.py`
|
||||
(FFmpeg comes with MoviePy).
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
code/bot.py entry point
|
||||
code/handlers.py commands, receiving videos and video notes, background buttons
|
||||
code/scripts.py Movie — frames and audio via MoviePy; Frame — background and circle mask via Pillow and NumPy
|
||||
data/ temporary processing files
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
pip install ruff -r requirements.txt
|
||||
ruff check --select E9,F code
|
||||
```
|
||||
|
||||
CI checks the code on every push and processes test video notes (with and without sound, both
|
||||
backgrounds). The Docker image is built on `v*` tags and published to GitHub Packages and `dcr.deev.su`.
|
||||
|
||||
## License
|
||||
|
||||
MIT — see [LICENSE](LICENSE).
|
||||
|
||||
## Author
|
||||
|
||||
**Egor Deev** — [GitHub](https://github.com/EDeev) · [Telegram](https://t.me/DeevEgor) · [egor@deev.space](mailto:egor@deev.space)
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<sub>⭐ If you find this project useful, give it a star on GitHub!</sub>
|
||||
<p><sub>Made with ❤️ — <a href="https://deev.space">deev.space</a></sub></p>
|
||||
</div>
|
||||
127
README.md
127
README.md
|
|
@ -1,106 +1,77 @@
|
|||
# 🎥 Circlechek
|
||||
# Circlechek
|
||||
|
||||
**Telegram-бот для преобразования квадратных видео в кружочки и обработки видеосообщений с настраиваемыми фонами.**
|
||||
**Русский** · [English](README.en.md)
|
||||
|
||||
## 📋 Описание
|
||||
[](https://github.com/EDeev/circlechek/actions/workflows/ci.yml)
|
||||
[](https://github.com/EDeev/circlechek/actions/workflows/docker.yml)
|
||||
[](LICENSE)
|
||||
|
||||
Circlechek — это простой и функциональный Telegram-бот, предназначенный для работы с видеоконтентом. Бот предоставляет две основные возможности:
|
||||
Telegram-бот для кружочков: делает из квадратного видео видеосообщение-кружок, а из присланного
|
||||
кружочка — обычное видео, где углы заполнены размытым кадром или градиентом под цвет картинки.
|
||||
|
||||
1. **Преобразование видео в кружочки** — превращает квадратные видео (до 1 минуты) в формат видеосообщений Telegram
|
||||
2. **Обработка кружочков** — конвертирует видеосообщения в обычные видео с настраиваемым фоном по краям
|
||||
**Статус:** личный проект, завершён · бот [@circlechek_bot](https://t.me/circlechek_bot)
|
||||
|
||||
## ✨ Функциональность
|
||||
|
||||
|
||||
### 🔄 Видео → Кружочек
|
||||
- Принимает квадратные видеофайлы длительностью до 60 секунд
|
||||
- Автоматически преобразует их в формат кружочков Telegram
|
||||
- Сохраняет качество и плавность воспроизведения
|
||||
**Стек:** Python 3.12 · aiogram 3 · MoviePy 2 · Pillow · NumPy · Docker
|
||||
|
||||
### 🎨 Кружочек → Видео
|
||||
- Обрабатывает видеосообщения с добавлением фона по краям
|
||||
- **Градиентный фон** — создает плавный цветовой переход на основе доминирующих цветов кадра
|
||||
- **Размытый фон** — использует размытую версию центральной части видео
|
||||
- Сохраняет исходное аудио и синхронизацию
|
||||
## Возможности
|
||||
|
||||
## 🛠 Технологический стек
|
||||
- **Видео → кружочек.** Квадратное видео до минуты возвращается кружком.
|
||||
- **Кружочек → видео.** Бот разбирает кружок на кадры, заполняет углы и собирает видео обратно со звуком.
|
||||
Фон на выбор:
|
||||
- **блюр** — размытая центральная часть кадра;
|
||||
- **градиент** — по среднему цвету кадра.
|
||||
- Тяжёлая обработка идёт в отдельном потоке, поэтому пока один кружочек обрабатывается, бот отвечает
|
||||
остальным. Каждая обработка — в своей временной папке, которая убирается и при ошибке.
|
||||
|
||||
- **Python 3.x** — основной язык разработки
|
||||
- **aiogram** — асинхронная библиотека для работы с Telegram Bot API
|
||||
- **PIL (Pillow)** — обработка изображений и создание эффектов
|
||||
- **MoviePy** — работа с видеофайлами, извлечение кадров и аудио
|
||||
- **NumPy** — математические операции с массивами для обработки изображений
|
||||
> [!NOTE]
|
||||
> У части кружочков Telegram бывают некорректные метаданные — тогда обработка не удастся или в видео
|
||||
> будет брак. Бот предупреждает об этом, результат стоит проверять.
|
||||
|
||||
## 🚀 Установка и запуск
|
||||
## Запуск
|
||||
|
||||
### Требования
|
||||
- Python 3.8+
|
||||
- Токен Telegram-бота от [@BotFather](https://t.me/BotFather)
|
||||
|
||||
### Установка зависимостей
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
git clone https://github.com/EDeev/circlechek.git && cd circlechek
|
||||
cp .env.example .env # BOT_TOKEN от @BotFather
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Настройка
|
||||
1. Получите токен бота в [@BotFather](https://t.me/BotFather)
|
||||
2. Отредактируйте файл `code/config.py`:
|
||||
```python
|
||||
botToken = "ВАШ_ТОКЕН_БОТА"
|
||||
Готовый образ: `docker pull ghcr.io/edeev/circlechek` или `docker pull dcr.deev.su/edeev/circlechek`.
|
||||
|
||||
Без Docker: Python 3.12, `pip install -r requirements.txt`, затем `cd code && BOT_TOKEN=… python bot.py`
|
||||
(FFmpeg ставится вместе с MoviePy).
|
||||
|
||||
## Структура
|
||||
|
||||
```
|
||||
code/bot.py запуск
|
||||
code/handlers.py команды, приём видео и кружочков, кнопки выбора фона
|
||||
code/scripts.py Movie — кадры и звук через MoviePy; Frame — фон и маска-круг через Pillow и NumPy
|
||||
data/ временные файлы обработки
|
||||
```
|
||||
|
||||
### Запуск
|
||||
## Разработка
|
||||
|
||||
```bash
|
||||
cd code
|
||||
python bot.py
|
||||
pip install ruff -r requirements.txt
|
||||
ruff check --select E9,F code
|
||||
```
|
||||
|
||||
## 📁 Структура проекта
|
||||
CI на каждый push проверяет код и прогоняет обработку тестовых кружочков (со звуком и без, оба вида
|
||||
фона). Docker-образ собирается по тегу `v*` и публикуется в GitHub Packages и `dcr.deev.su`.
|
||||
|
||||
```
|
||||
circlechek/
|
||||
├── code/
|
||||
│ ├── bot.py # Основной файл запуска бота
|
||||
│ ├── handlers.py # Обработчики команд и сообщений
|
||||
│ ├── scripts.py # Классы для работы с видео и изображениями
|
||||
│ ├── config.py # Конфигурация бота
|
||||
│ └── init.py # Инициализация бота и утилиты
|
||||
├── data/
|
||||
│ ├── circles/ # Временные файлы кружочков
|
||||
│ ├── video_notes/ # Временные видеосообщения
|
||||
│ └── videos/ # Обработанные видео
|
||||
└── README.md
|
||||
```
|
||||
## Лицензия
|
||||
|
||||
## 🎯 Использование
|
||||
MIT — см. [LICENSE](LICENSE).
|
||||
|
||||
1. **Начало работы**: Отправьте `/start` боту
|
||||
2. **Создание кружочка**: Отправьте квадратное видео (до 1 минуты)
|
||||
3. **Обработка кружочка**:
|
||||
- Отправьте видеосообщение боту
|
||||
- Выберите тип фона: "Градиент" или "Блюр"
|
||||
- Получите обработанное видео
|
||||
## Автор
|
||||
|
||||
## ⚠️ Важные особенности
|
||||
|
||||
- Видео для преобразования в кружочки должны быть **квадратными** и **не длиннее 1 минуты**
|
||||
- Некоторые кружочки могут иметь некорректные метаданные, что может привести к ошибкам обработки
|
||||
- Рекомендуется всегда проверять качество полученного результата
|
||||
- Все временные файлы автоматически удаляются после обработки
|
||||
|
||||
## 📄 Лицензия
|
||||
|
||||
Проект распространяется под лицензией MIT.
|
||||
|
||||
## 👨💻 Автор
|
||||
|
||||
**Деев Егор Викторович** - Backend Developer
|
||||
- GitHub: [@EDeev](https://github.com/EDeev)
|
||||
- Email: egor@deev.space
|
||||
- Telegram: [@Egor_Deev](https://t.me/Egor_Deev)
|
||||
**Деев Егор Викторович** — [GitHub](https://github.com/EDeev) · [Telegram](https://t.me/DeevEgor) · [egor@deev.space](mailto:egor@deev.space)
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<sub>⭐ Если проект оказался полезным, поставьте звездочку на GitHub!</sub>
|
||||
<p><sub>Создано с ❤️ от вашего дорогого - deev.space ©</sub></p>
|
||||
<sub>⭐ Если проект оказался полезным, поставьте звёздочку на GitHub!</sub>
|
||||
<p><sub>Сделано с ❤️ — <a href="https://deev.space">deev.space</a></sub></p>
|
||||
</div>
|
||||
|
|
|
|||
BIN
docs/demo.png
Normal file
BIN
docs/demo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 328 KiB |
Loading…
Add table
Reference in a new issue