high-taiko

REDAME for other languages:

🇺🇸 English

🇪🇸 Spain

Собственный рендерер реплеев osu!taiko в видео MP4 (форк osu-taiko-renderer). Разбирает файлы реплеев .osr, симулирует и оценивает прохождение карт, отрисовывает игровое поле с движущимися справа налево нотами покадрово и кодирует итоговый результат в видео через ffmpeg.

Особенность форка: если путь к папке карты (BEATMAP_DIR) не указан, high-taiko автоматически скачивает нужную карту через API osu.direct, используя MD5-хэш из файла реплея.

Часть R3D Renderer

Это движок taiko для R3D Renderer — сервиса конвертации реплеев osu! в MP4 (Discord-бот и веб-сайт, пакет mania_ordr), который отправляет каждый рендер отдельному движку для соответствующего режима игры. Ядро запускает данный движок как отдельный процесс под каждую задачу, поэтому изменения в коде подтягиваются сразу на следующий рендер без перезапуска сервиса. В продакшене этот движок работает в виртуальном окружении Python от движка catch (общее окружение, но код находится в собственном репозитории).

Примечание: часть кода репозитория изначально была взята из catch-рендерера — в докстрингах некоторых модулей (например, osu_taiko_renderer/__init__.py, render/gl.py) всё ещё может упоминаться «catch». Сам исполняемый код предназначен именно для режима taiko.

Четкость и физика рендеринга

• Объекты Taiko: доны (красный центр), каты (синий край), большие ноты (финишеры для обоих типов), барабанные дроби (с тиками) и гейши/сквоши (Swell/Denden, требующие чередования нажатий). Моделируются четыре клавиши: центр-лево/право и край-лево/право.
• Точная симуляция и судейство (render/scene.py): каждое нажатие обрабатывает ближайшую ещё не нажатую ноту соответствующего цвета в пределах временного окна OD (без перехвата нажатий и с поддержкой notelock); если нота выходит за пределы окна, засчитывается MISS. Это позволяет точно определить ноты, на которых игрок реально потерял комбо.
• Согласование с заголовком (beatmap/score_fidelity.py): заголовок .osr остается главным источником статистики — отдельный этап сверки приводит итоговые GREAT/OK/MISS и максимальное комбо к значениям из заголовка. Таким образом, точность, счёт и количество 300/100/miss всегда точно совпадают с оригиналом, а симуляция определяет, какие именно ноты сбили комбо.
• Интерфейс Argon (lazer) по умолчанию (argon/ — композитинг, HUD, счётчики, процедурные глифы). Ресурсы из osu! не вшиты; вариант без скинов использует процедурную графику Argon и встроенный шрифт Nunito. Пользовательский скин можно подключить через параметр --skin.
• pp / SR: подсчёт pp и звёздной сложности на лету через rosu_pp_py; параметры --pp / --sr фиксируют эти показатели на итоговом экране (и для счетчика pp) в официальные значения osu!, сохраняя динамику графика от rosu.
• Сториборды: встроенный движок сторибордов (--storyboard, по умолчанию отключён; работает аналогично движку std). Если отключён, вывод побайтово совпадает с оригиналом.
• Дополнительно: финальный экран результатов с локальным топом рендеров (локальная база данных или глобальные топы osu! через --leaderboard-source osu), затемнение/размытие фона, плашки во время перерывов, хитсаунды карты/промахов/Nightcore, водяные знаки и покадровый JSON-файл со счётом (--score-json) для оверлей-композитора.

Использование

Запуск в качестве модуля:

python -m osu_taiko_renderer REPLAY.osr [BEATMAP_DIR] -o out.mp4 \
    [--resolution 1920x1080] [--fps 60] [--encoder auto] [--skin DIR]

• REPLAY.osr — файл реплея (позиционный аргумент).
• BEATMAP_DIR — папка с файлом .osu, аудио и фоном (необязательный позиционный аргумент; если не указан, карта автоматически скачивается через osu.direct по MD5-хэшу из реплея).
• -o, --output — путь для сохранения видео (обязательный).

Основные флаги (проверено по osu_taiko_renderer/cli.py):

Флаг	По умолчанию	Назначение
--resolution WxH	1920x1080	Разрешение видео
--fps N	60	Частота кадров
--encoder	auto	Кодировщик: `auto
--encoder-device	нет	Устройство (например, /dev/dri/renderD128)
--skin DIR / --default-skin DIR	нет	Папка со скином / резервный скин
--scroll-time MS	1600	Время видимости ноты при скорости 1.0× (меньше = быстрее)
--pp FLOAT / --sr FLOAT	нет	Фиксация официальных значений pp / звёздности на экране результатов
--storyboard	off	Включить рендеринг сториборда
--[no-]results, --[no-]pp-counter, --[no-]hit-counter, --[no-]leaderboard	on	Переключатели HUD и экрана результатов
--leaderboard-source {r3d,osu}	r3d	Источник таблицы лидеров (osu читает --leaderboard-json)
--watermark, --music-volume, --general-volume, --audio-offset, --bg-dim-*, --bg-blur	—	Настройки звука и фонового изображения

Логические флаги используют argparse BooleanOptionalAction (--flag / --no-flag). Неизвестные флаги принимаются и игнорируются, что позволяет единому пайплайну передавать общие для всех движков параметры.

Переменные окружения: R3D_EGL_DEVICE_INDEX (выбор GPU/EGL-устройства), R3D_FRAME_MD5 (хэширование сырых кадров для проверки точности).

Требования

• Python 3.10+ (используются объединения типов X | Y и BooleanOptionalAction).

• Сторонние библиотеки (импортируются напрямую; requirements.txt/pyproject.toml отсутствуют, так как зависимости берется из общего venv):

• numpy

• Pillow (PIL — сборка HUD на CPU)

• moderngl (контекст EGL / буфер кадра RGBA — headless GPU)

• osrparse (парсер файлов реплеев)

• rosu_pp_py (расчёт pp / сложности; опционально)

• osu_renderer — общий пакет R3D Core для кодирования через ffmpeg и работу со скинами (wiki_renderer.SkinPair)

• ffmpeg в системном PATH (рендерер запускает собственный подпроцесс ffmpeg, передавая raw rgb24 на stdin).

Структура проекта

osu_taiko_renderer/
  __main__.py, cli.py       Точка входа CLI (argparse) → render_taiko()
  beatmap/                  Модели парсинга и симуляции
    beatmap.py, models.py, replay.py, sliderpath.py,
    storyboard.py, score_fidelity.py, legacy_random.py
  render/                   Оркестрация + GL + кодирование
    render.py               Парсинг → симуляция → покадровый GL-рендер + HUD → ffmpeg
    scene.py                Симуляция taiko + пошаговый билдер сцены
    gl.py                   Пакетная отрисовка спрайтов moderngl/EGL
    effects.py, flashlight.py, dim.py, hitsounds.py,
    storyboard_engine.py, storyboard_render.py
  argon/                    Процедурный HUD Argon (lazer) — композитинг, HUD,
                            счётчики, геометрия, текстуры, шрифты, глифы
  hud/                      HUD и финальный экран: hud.py, lazer_results.py,
                            leaderboard.py, lb_cards.py, break_overlay.py, …
  skin/                     Загрузка скинов: taiko_skin.py, lazer_skin.py,
                            assets.py, fonts.py
  assets/                   Логотип, шрифт Nunito (OFL), хитсаунды Nightcore
  fonts_data/               Атласы шрифта Torus
tests/                      Тесты сторибордов и интро

Лицензия

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later) — см. LICENSE. Copyright (C) 2026 Cool Adults (см. COPYRIGHT).

Атрибуция (согласно COPYRIGHT): логика геймплея, таймингов, судейства и HUD перенесена из osu! / osu-framework от peppy / ppy (MIT); проект danser-go от Wieku (GPL-3.0) использовался в качестве эталона поведения. Игровые ресурсы osu! не входят в комплект — скины, карты, аудио и арт из osu! распространяются под лицензией CC BY-NC; в этом репозитории используется только оригинальная или процедурно сгенерированная графика. Встроенный шрифт Nunito распространяется по лицензии SIL Open Font License 1.1 (assets/fonts/OFL.txt).