diff --git a/README.md b/README.md index 9168f07..0e21792 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,56 @@ -# AE Anons - Automated After Effects Announcement Generator +# AE Anons - Автоматизированный генератор спортивных анонсов After Effects -Automated pipeline for generating sports announcements using After Effects templates via Nexrender, with data sourced from Synology Office spreadsheets. +Автоматизированная система для создания спортивных анонсов с использованием шаблонов After Effects через Nexrender, с данными из электронных таблиц Synology Office. -## Overview +## Обзор -AE Anons automates the creation of broadcast announcement videos by: +AE Anons автоматизирует создание видеороликов спортивных анонсов путем: -1. Connecting to Synology NAS to retrieve schedule data from Office spreadsheets (.osheet) -2. Parsing Excel data containing sports events, teams, channels and timing information -3. Generating Nexrender jobs with appropriate templates and assets -4. Monitoring render completion and managing output files +1. Подключения к NAS Synology для получения данных расписания из файлов офисных таблиц (.osheet) +2. Парсинга Excel данных, содержащих информацию о спортивных событиях, командах, каналах и временных интервалах +3. Генерации заданий Nexrender с соответствующими шаблонами и ресурсами +4. Мониторинга завершения рендеринга и управления выходными файлами -## Features +## Особенности -- **Synology Integration**: Seamless authentication and file retrieval from Synology NAS -- **Office Spreadsheet Export**: Automatic conversion of .osheet files to Excel format -- **Flexible Data Parsing**: Dynamic sheet parsing with header detection -- **Multi-variant Generation**: Creates "Today", "Tomorrow" and dated variants for each announcement -- **Smart Logo Management**: Automatic logo resolution and scaling based on team/sport associations -- **Nexrender Job Orchestration**: Automated job submission, monitoring and cleanup -- **Professional Logging**: Structured logging with configurable verbosity levels -- **Environment-based Configuration**: All settings managed via `.env` file +- **Интеграция с Synology**: Плавная аутентификация и загрузка файлов с NAS Synology +- **Экспорт офисных таблиц**: Автоматическое преобразование файлов .osheet в формат Excel +- **Гибкий парсинг данных**: Динамический парсинг листов с обнаружением заголовков +- **Множественная генерация вариантов**: Создание "Сегодня", "Завтра" и датированных версий для каждого анонса +- **Умное управление логотипами**: Автоматическое разрешение и масштабирование логотипов на основе связей команд/спорта +- **Оркестрация заданий Nexrender**: Автоматическая отправка, мониторинг и очистка заданий +- **Профессиональное логирование**: Структурированный журнал с возможностью настройки уровня детализации +- **Конфигурация через переменные окружения**: Все параметры управляются через файл `.env` -## Prerequisites +## Предварительные требования -- Rust 1.70 or higher -- Access to Synology NAS with File Station and Office enabled -- Nexrender server instance -- After Effects templates configured on render nodes +- Rust 1.70 или выше +- Доступ к NAS Synology с включенными File Station и Office +- Экземпляр сервера Nexrender +- Шаблоны After Effects, настроенные на узлах рендеринга (формат Adobe After Effects 2024 .aepx) -## Installation +## Установка -### 1. Clone the Repository +### 1. Клонирование репозитория ```bash git clone https://github.com/your-org/ae_anons.git cd ae_anons +``` -2. Build the Project -bash +### 2. Сборка проекта +```bash cargo build --release +``` -The binary will be available at target/release/ae_anons -3. Configure Environment +Бинарный файл будет доступен по пути `target/release/ae_anons` -Create a .env file in the project root: -env +### 3. Настройка окружения +Создайте файл `.env` в корне проекта: + +```env NAS_FQDN=https://your-synology-nas.example.com:5001 NAS_USER=service_account NAS_PASS=secure_password @@ -55,292 +58,291 @@ NAS_FILE=/Team Folder/Broadcast/Auto_Anons/schedule.osheet NEXRENDER_API_URL=http://nexrender-server:3000/api/v1/jobs OUTPUT_FOLDER=//file-server/edit/Auto_Anons RUST_LOG=info +``` -See Configuration section for detailed options. -Usage -Basic Execution -bash +См. раздел Конфигурация для подробной информации. -# Run with default configuration +## Использование + +### Базовое выполнение + +```bash +# Запуск с настройками по умолчанию ./target/release/ae_anons -# Run with custom log level +# Запуск с пользовательским уровнем логирования RUST_LOG=debug ./target/release/ae_anons +``` -# Run with specific .env file -dotenv -f /path/to/.env.production run ./target/release/ae_anons +## Уровни логирования -Development Mode -bash +Управляйте детализацией вывода через переменную окружения `RUST_LOG`: -cargo run - -Logging Levels - -Control output verbosity via RUST_LOG environment variable: - - error - Only critical errors - - warn - Warnings and errors - - info - General operational messages (default) - - debug - Detailed processing information - - trace - Full debugging with API call details - -bash +- **error** - Только критические ошибки +- **warn** - Предупреждения и ошибки +- **info** - Общие операционные сообщения (по умолчанию) +- **debug** - Детальная информация о процессе обработки +- **trace** - Полное отладочное логирование с деталями API вызовов +```bash RUST_LOG=debug cargo run +``` -Configuration -Environment Variables -Variable Required Default Description -NAS_FQDN Yes - Synology NAS URL with protocol and port -NAS_USER Yes - Synology account username -NAS_PASS Yes - Synology account password -NAS_FILE Yes - Full path to .osheet file on NAS -NEXRENDER_API_URL -OUTPUT_FOLDER Network path for rendered videos -RUST_LOG No info Logging verbosity level -Spreadsheet Structure +## Конфигурация -The input Excel file (converted from .osheet) must contain the following sheets: -Start Sheet +### Переменные окружения -Main data source for announcements generation. -Column Description Example -STATE Processing flag FALSE (active), TRUE (skip) -SPORT Sport category Футбол, Хоккей -LEAGUE League name Премьер-лига -TEAM A Home team Спартак#FC Spartak#150 -TEAM B Away team Зенит#FC Zenit#150 -CHANEL Broadcast channel Матч ТВ -TIME Event time 19:30 -DATA Event date 15.04.2026 -SPORT Sheet +| Переменная | Обязательна | Описание | +|------------|-------------|----------| +| `NAS_FQDN` | Да | URL NAS Synology с протоколом и портом | +| `NAS_USER` | Да | Имя пользователя учетной записи Synology | +| `NAS_PASS` | Да | Пароль учетной записи Synology | +| `NAS_FILE` | Да | Полный путь к файлу .osheet на NAS | +| `NEXRENDER_API_URL` | Да | Конечная точка API сервера Nexrender | +| `OUTPUT_FOLDER` | Да | Сетевой путь для рендеренных видео | +| `RUST_LOG` | Нет | Уровень детализации логирования (по умолчанию: info) | -Mapping between sports and their video pack templates. -Column Description -SPORT Sport identifier -LINK Path to video pack file -TEAMS Sheet +## Структура электронной таблицы -Team logo registry with sport associations. -Column Description -TEAM Team identifier -SPORT Associated sport -LINK Path to team logo file -CHANELL Sheet +Файл Excel должен содержать следующие листы со специфичными структурами: -Channel logo mappings. -Column Description -CHANELL Channel name -LINK Path to channel logo file -Team Name Format +### Лист "SPORT" -Team names can include resolution hints using hash separators: -text +Связывает названия видов спорта с соответствующими видео пакетами. -Display Name#Search Key#Target Size +| SPORT | LINK | +|-------|------| +| Без оформления | \\server\share\path\to\null.mov | +| Футбол | \\server\share\path\to\football_pack.mov | +| Волейбол | \\server\share\path\to\volleyball_pack.mov | -Example: Спартак#FC Spartak#150 +### Лист "TEAMS" - Спартак - Display name in graphics +Сопоставляет имена команд с их видами спорта и логотипами. Колонка SPORT заполняется из выпадающего списка (заполнена из листа SPORT). - FC Spartak - Key for logo lookup +Если несколько команд в одном виде спорта имеют одинаковые названия, но разные логотипы, используется разделитель хеш # для уникальной идентификации. - 150 - Target size in pixels for logo scaling +| TEAM | SPORT | LINK | +|------|-------|------| +| Галатасарай#Turki | Футбол | \\server\share\path\to\galatasaray_football.png | +| Галатасарай | Волейбол | \\server\share\path\to\galatasaray_volleyball.png | +| Галатасарай#UCL | Волейбол | \\server\share\path\to\galatasaray_ucl.png | +| Сомбатей##400 | Футбол | \\server\share\path\to\szombathely.png | -Output Files -JSON Exports +### Лист "CHANELL" -During processing, JSON representations of the workbook are saved: +Сопоставляет названия каналов с их логотипами. Поля заполняются вручную без выпадающих списков. - {filename}_workbook.json - Complete workbook structure +| CHANEL | LINK | +|--------|------| +| КАНАЛ | \\server\share\path\to\channel_logo.png | +| TRIUMPH | \\server\share\path\to\triumph_logo.png | - {filename}_{SheetName}.json - Individual sheet data +### Лист "Start" -Rendered Videos +Основной источник данных для генерации анонсов. Большинство полей заполняются из выпадающих списков, основанных на других листах. -Output videos are saved to OUTPUT_FOLDER with naming pattern: -text +Обязательные колонки: DATA, TIME, CHANEL, SPORT, LEAGUE, TEAM A, TEAM B +**Примечание**: Колонка LEAGUE обязательна для заполнения, но не имеет выпадающего списка. Проверка орфографии и опечаток отсутствует! + +| STATE | TRIPPLE | DATA | TIME | SPORT | LEAGUE | CHANEL | TEAM A | TEAM B | +|-------|---------|------|------|-------|--------|--------|--------|--------| +| TRUE | TRUE | 27.2.2026 | 23:40 | Футбол | Чемпионат Португалии | START | Спортинг#ll#550 | Эшторил#ll#550 | +| FALSE | TRUE | 28.2.2026 | 12:55 | Волейбол | Чемпионат Турции. Женщины | TRIUMPH | Бешикташ | Галатасарай#Turki | + +### Формат имен команд + +Имена команд поддерживают два типа разделителей хэш #: + +1. **Первый хеш**: Уникальный идентификатор для команд с одинаковыми названиями в одном виде спорта, или одинаковым названием в разных видах спорта. +Примеры: + +- `Динамо#Футбол`, `Динамо#Волейбол` - Одно название разный вид спорта +- `Спартак#ЖенскийФ`, `Спартак#МужскойФ` Одно название _разный_ вид спорта + +1. **Второй хеш**: Целевой размер в пикселях для масштабирования логотипа + +Формат: `DisplayName#UniqueID#TargetSize` + +Примеры: + +- `Галатасарай#Turki` - только уникальный идентификатор +- `Сомбатей##400` - только целевой размер (обратите внимание на двойной хеш) +- `Спортинг#ll#550` - оба идентификатор и целевой размер + +**Важно**: Обрабатывается **только второй хеш** для масштабирования логотипа. Если уникальный идентификатор не требуется, используйте двойной хеш ## перед целевым размером. + +## Выходные файлы + +### Экспорт JSON + +Во время обработки сохраняются представления таблицы в формате JSON: + +- `{filename}_workbook.json` - Полная структура книги +- `{filename}_{SheetName}.json` - Данные отдельного листа + +### Рендеренные видео + +Рендерные видео сохраняются в `OUTPUT_FOLDER` по следующему шаблону именования: + +``` YYYYMMDD_Sport_League_TeamA_TeamB_Channel[_Variant].mp4 +``` -Examples: +Имена файлов транслитерируются в латиницу. Примеры: - 20260415_Футбол_Премьер-лига_Спартак_Зенит_Матч-ТВ.mp4 (Base version) +- `20260228_Volleyball_Championship-Turkey-Women_Beşiktaş_Galatasaray_TRIUMPH.mp4` +- `20260228_Volleyball_Championship-Turkey-Women_Beşiktaş_Galatasaray_TRIUMPH_Today.mp4` +- `20260228_Volleyball_Championship-Turkey-Women_Beşiktaş_Galatasaray_TRIUMPH_Tomorrow.mp4` - 20260415_Футбол_Премьер-лига_Спартак_Зенит_Матч-ТВ_Today.mp4 +## Рабочий процесс - 20260415_Футбол_Премьер-лига_Спартак_Зенит_Матч-ТВ_Tomorrow.mp4 +1. **Аутентификация**: Подключение к NAS Synology с использованием предоставленных учетных данных +2. **Получение файла**: Поиск и экспорт указанного файла .osheet в Excel +3. **Парсинг данных**: Чтение всех листов и структурирование данных +4. **Разрешение ресурсов**: Сопоставление видов спорта, команд и каналов с визуальными элементами +5. **Генерация заданий**: Создание заданий Nexrender для каждой активной строки с вариантами +6. **Очистка**: Удаление завершенных/неудачных заданий из предыдущих запусков +7. **Отправка**: Отправка заданий на API Nexrender +8. **Мониторинг**: Слежение за прогрессом выполнения до завершения +9. **Завершение сеанса**: Закрытие сессии Synology -Workflow +## Требования к шаблонам After Effects - Authentication: Connects to Synology NAS using provided credentials +Шаблоны должны быть предварительно настроены на узлах рендеринга со следующими именами слоев: - File Retrieval: Locates and exports the specified .osheet file as Excel +### Типы шаблонов - Data Parsing: Reads all sheets and structures the data +| Файл шаблона | Назначение | +|--------------|------------| +| `PackShot_DOUBLE.aepx` | Сопоставление с двумя командами | +| `PackShot_SINGLE.aepx` | Анонсы для одной команды | - Asset Resolution: Matches sports, teams and channels with their visual assets +### Обязательные слои - Job Generation: Creates Nexrender jobs for each active row with variants +| Имя слоя | Тип | Описание | +|----------|-----|----------| +| DATA | Text | Отображение даты (автоматически подстраивается) | +| TIME / TIME_H / TIME_M | Text | Отображение времени | +| LEAGUE | Text | Название лиги | +| SPORT | Text | Категория спорта | +| TEAMS | Text | Скомбинированные имена команд | +| TEAM_A_LOGO | Image | Логотип домашней команды | +| TEAM_B_LOGO | Image | Логотип гостевой команды | +| CHANEL | Image | Логотип канала | +| TOP | Video | Наложение видео оформления | - Cleanup: Removes completed/failed jobs from previous runs +### Настройки композиции - Submission: Sends jobs to Nexrender API +- Имя композиции: `pack` +- Выходной модуль: `Start_h264` +- Формат вывода: `mp4` +- Формат проекта: Adobe After Effects 2024 .aepx - Monitoring: Tracks job progress until completion +## Устранение неисправностей - Logout: Terminates Synology session +### Частые проблемы -After Effects Template Requirements +**Ошибка подключения к NAS** -Templates must be pre-configured on render nodes with specific layer names: -Template Types -Template File Use Case -Double Team PackShot_DOUBLE.aepx Matches with two teams -Single Team PackShot_SINGLE.aepx Single team announcements -Required Layers -Layer Name Type Description -DATA Text Date display (auto-adjusted) -TIME / TIME_H / TIME_M Text Time display -LEAGUE Text League name -SPORT Text Sport category -TEAMS Text Combined team names -TEAM_A_LOGO Image Home team logo -TEAM_B_LOGO Image Away team logo -CHANELL Image Channel logo -TOP Video Sport pack overlay -Composition Settings +- Проверьте, что `NAS_FQDN` включает протокол и порт (например, `https://nas.example.com:5001`) +- Проверьте сетевую связность с NAS +- Убедитесь, что сервисы File Station и Office включены - Composition name: pack +**Файл не найден** - Output module: Start_h264 +- Убедитесь, что путь в `NAS_FILE` точно соответствует пути в Synology Drive +- Путь должен начинаться с `/Team Folder/` для рабочих папок +- Проверьте права доступа к файлу для учетной записи сервиса - Output format: mp4 +**Ошибка отправки задания Nexrender** -Troubleshooting -Common Issues -Connection to NAS failed +- Подтвердите доступность сервера Nexrender +- Убедитесь, что `NEXRENDER_API_URL` правильный +- Проверьте существование файлов шаблонов на узлах рендеринга - Verify NAS_FQDN includes protocol and port (e.g., https://nas.example.com:5001) +### Режим отладки - Check network connectivity to NAS - - Ensure File Station and Office services are enabled - -File not found - - Verify the path in NAS_FILE exactly matches the Synology Drive path - - Path should start with /Team Folder/ for team folders - - Check file permissions for the service account - -Nexrender job submission fails - - Confirm Nexrender server is accessible - - Verify NEXRENDER_API_URL is correct - - Check that template files exist on render nodes - -Debug Mode - -Enable debug logging for detailed troubleshooting: -bash +Включите подробное логирование для детального анализа: +```bash RUST_LOG=debug ./target/release/ae_anons +``` -This will output: +Это выведет: - API request/response details +- Детали API запросов/ответов +- Информацию о парсинге листов +- Детали создания заданий +- Процесс разрешения ресурсов - Sheet parsing information +## Возможные ограничения по производительности - Job creation details +- **Большие таблицы**: Ограничение обработки до 10,000 строк на лист +- **Задержка сети**: Загрузка файлов с NAS может занимать время для больших файлов +- **Параллельные задания**: Nexrender управляет очередью заданий внутренне +- **Использование памяти**: Парсинг Excel сохраняет всю книгу в памяти - Asset resolution process +## Примечания по безопасности -Performance Considerations +- Храните учетные данные только в файле `.env` (исключен из git) +- Используйте специальные аккаунты с минимально необходимыми правами +- Сессии Synology завершаются после выполнения +- HTTPS рекомендуется для подключений NAS в продакшене - Large Spreadsheets: Processing limited to 10,000 rows per sheet +## Разработка - Network Latency: File downloads from NAS may take time for large files - - Concurrent Jobs: Nexrender handles job queuing internally - - Memory Usage: Excel parsing keeps entire workbook in memory - -Security Notes - - Store credentials only in .env file (excluded from git) - - Use dedicated service accounts with minimal required permissions - - Synology sessions are properly terminated after execution - - HTTPS recommended for NAS connections in production - -Development -Running Tests -bash - -cargo test - -Code Structure -text +### Структура кода +``` src/ -├── main.rs # Application entry point and orchestration -├── config.rs # Configuration management -├── nexrender.rs # Nexrender job generation and structures -└── synology.rs # Synology API client +├── main.rs # Точка входа и оркестрация приложения +├── config.rs # Управление конфигурацией +├── nexrender.rs # Генерация заданий Nexrender и структура данных +└── synology.rs # Клиент API Synology +``` -Adding New Features +### Планируемые новые возможностеи - Extend JobData in nexrender.rs for new data fields +1. Расширь `JobData` в `nexrender.rs` для новых полей данных +2. Обновить логику парсинга листов при необходимости добавления новых колонок +3. Добавьть соответствующие слои After Effects в шаблоны +4. Обновите метод `to_nexrender_job()` с новыми сопоставлениями ресурсов - Update sheet parsing logic if new columns are required +## Зависимости - Add corresponding After Effects layers to templates +| Crate | Версия | Назначение | +|-------|--------|------------| +| reqwest | 0.12 | HTTP клиент для коммуникации API | +| serde / serde_json | 1.0 | Сериализация JSON | +| calamine | 0.26 | Парсинг файлов Excel | +| chrono | 0.4 | Обработка дат и времени | +| tokio | 1.0 | Асинхронная среда выполнения | +| dotenv | 0.15 | Конфигурация через переменные окружения | +| log / env_logger | 0.11 | Инфраструктура логирования | +| thiserror | 2.0 | Определение типов ошибок | +| anyhow | 1.0 | Обработка ошибок | - Update to_nexrender_job() method with new asset mappings +## Лицензия -Dependencies -Crate Version Purpose -reqwest 0.12 HTTP client for API communication -serde / serde_json 1.0 JSON serialization -calamine 0.26 Excel file parsing -chrono 0.4 Date/time handling -tokio 1.0 Async runtime -dotenv 0.15 Environment configuration -log / env_logger 0.4 Logging infrastructure -thiserror 2.0 Error type definitions -anyhow 1.0 Error handling -License +Ещё не выбранна -[Specify your license here] -Support +## Поддержка -For issues and feature requests, please contact: +Для вопросов и запросов функций обращайтесь: - [Your Team Email] +- +- [README.md](https://git.tvstart.ru/lexx/AE_Anons) - [Internal Documentation Link] +## История изменений -Changelog -v0.1.0 +### v0.1.0 - Initial release - - Synology Office integration - - Basic Nexrender job generation - - Excel parsing with dynamic sheet detection - - Multi-variant job creation +- Первый выпуск +- Интеграция с Synology Office +- Базовая генерация заданий Nexrender +- Парсинг Excel с динамическим обнаружением листов +- Создание множественных вариантов +- Автоматические настройки размера шрифта и позиции +- Умное масштабирование логотипов по целевому размеру