💜 简介 / About

StrangeUtaGame（简称 SUG）是一款受 RhythmicaLyrics 启发的卡拉 OK 歌词打轴软件。它在保留 RhythmicaLyrics工作流的同时，重写了音频引擎与渲染管线，专注于低延迟、高精度的时间标签制作，并把对中文创作者友好的体验放在首位 —— 无需日语转区、全格式音视频导入、高质量变速、演唱者管理。

> StrangeUtaGame (SUG) is a karaoke timing tool inspired by RhythmicaLyrics. It rebuilds the audio engine and rendering pipeline around ultra-low latency and frame-accurate timestamping, with a focus on a smoother experience for Chinese-speaking creators — no Japanese locale switch required, import any audio/video format, and studio-grade time-stretching, Singer Management.

🎬 截图 / Screenshots

打轴主界面 · Main timing view 音频拖入即用，全局偏移、变速、音量随手可调	运行时 · Live timing with waveform & furigana 波形 + 节奏点 + 注音 + 多演唱者上色
导出 · 13 种歌词格式 LRC×3 / KRA / TXT / SRT / txt2ass / ASS / Nicokara×2 / RL / 春日向注音 / Kirakara	设置 · 10 个分类页 演奏控制 / 打轴 / 自动保存 / AutoCheck / 词典 / 界面 / 导出 / 快捷键 / 网络 / 关于/语言
演唱者管理 · Singer manager 颜色、顺序、启用/禁用、软件预设	全文本编辑 · Inline format editor {原文||读音} + [mm:ss.cc] 时间戳一行式编辑

✨ 功能特性 / Features

🧭 常用功能入口 / Where to find settings

| 功能 / Feature | 入口或设置位置 / Location | 说明 / Notes | |---|---|---| | AI 打轴（Beta） / AI-assisted timing | 打轴界面 → AI 打轴 | 模型、设备、下载镜像、模型目录、AI 缓存和运行环境均在弹窗内设置；执行结果可撤销一次。 | | 播放区间锁定 / Playback range locks | 设置 → 快捷键 → 锁定播放起点 / 锁定播放终点 | 默认按键为 [ / ]；再次触发可取消锁定。 | | 播放头居中模式 / Centered playhead | 设置 → 打轴 → 波形时间标签 → 播放头居中模式 | 默认关闭；开启后播放头固定在时间轴中央。 | | Karaoke 实时预览 / Live preview | 设置 → 界面 | 进入该页面后自动显示；拖动标题可移动，拖动边缘可缩放。 | | 软件界面字体 / Interface font | 设置 → 界面 → 界面设定 → 界面字体 | 留空时按界面语言自动选择，修改后立即应用。 | | Karaoke 预览横向滚动 / Horizontal preview scrolling | Karaoke 预览区域 | 内容超宽时自动显示横向滚动条；也可按住 Alt 滚动鼠标滚轮。 | | 最近打开的项目 / Recent projects | 打轴界面 → 文件管理 → 最近打开的文件 | 最多显示 10 条记录，可在同一菜单中清空。 | | F2 注音快捷编辑 / Quick ruby editor | 设置 → 快捷键 → 字符与行编辑 → 注音编辑窗口 | 默认 F2；可选择迷你浮窗或经典大窗口。 | | Kirakara 导入与导出 / Kirakara import & export | 导入：首页 → 导入歌词文件或打轴界面 → 文件管理 → 加载歌词；导出：导出 → 导出格式 → Kirakara | 支持带 config 配置块的 KRL；默认导出格式可在 设置 → 导出 → 默认导出格式 中修改。 |

📦 安装与运行 / Installation

🪟 支持系统 / Supported OS： Windows 10 / 11 · 🍎 macOS（实验性 / experimental）

🚀 方式一 · 直接运行（推荐） / Pre-built release (recommended)

从 Releases 页面下载最新版本，解压后双击 StrangeUtaGame.exe 即可。 Download the latest archive from the Releases page, unzip, then run StrangeUtaGame.exe.

_{📦 体积参考 / Approx. size: ~250 MB}

🍎 macOS 注意事项 / macOS notes

macOS 版为实验性构建，使用前请留意：

• 按芯片选择安装包 / Pick the build for your chip. Apple Silicon（M1/M2/M3…）下载 StrangeUtaGame-mac-arm64-vX.Y.Z.dmg；Intel 芯片下载 StrangeUtaGame-mac-intel-vX.Y.Z.dmg。不确定芯片类型可在「终端」执行 uname -m（arm64 = Apple Silicon，x86_64 = Intel）。装错架构会在启动时报 Bad CPU type in executable。（另有一个名为 StrangeUtaGame-mac-vX.Y.Z.zip 的旧命名包仅为老版本的更新检测保留，请勿下载。）
• 首次打开被拦截（未签名）/ Unsigned app blocked on first launch. 应用未做 Apple 签名与公证，双击会提示「无法打开，因为无法验证开发者」。绕过方式：在 StrangeUtaGame.app 上右键 → 打开，在弹窗里再次点「打开」；或在终端执行 xattr -dr com.apple.quarantine /path/to/StrangeUtaGame.app 后再启动。
• 无自动更新 / No auto-update. macOS 不支持应用内自动更新；检测到新版本时只会在浏览器打开 Releases 页面，需手动下载并替换旧的 .app。

macOS builds are experimental. Pick by chip: Apple Silicon → …-mac-arm64-.dmg, Intel → …-mac-intel-.dmg (run uname -m if unsure — arm64 = Apple Silicon, x86_64 = Intel; the wrong arch fails with Bad CPU type in executable). The app is not signed/notarized — on first launch use right-click → Open (or xattr -dr com.apple.quarantine ) to bypass Gatekeeper. No in-app auto-update; new versions open the Releases page in your browser for a manual download.

🛠️ 方式二 · 从源码运行 / Run from source

# 克隆仓库 / Clone
git clone https://github.com/karaoke-studio/StrangeUtaGame.git
cd StrangeUtaGame
创建虚拟环境（推荐） / Create a virtualenv (recommended)
python -m venv venv
venv\Scripts\activate
安装依赖 / Install dependencies
pip install -r requirements.txt
启动 / Launch
python main.py

或使用 uv（更快） / Or with uv (faster):

uv venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install -r requirements.txt -r requirements-dev.txt
python main.py

依赖文件说明 / Dependency files. 依赖真源是锁定版本的 requirements*.txt（被发布流程做内容哈希用于增量更新，改动需谨慎）；pyproject.toml 仅承载工具配置（ruff/black/mypy/pytest）。安装时按平台/变体追加其一：

- main 变体（Windows，WinRT 注音）：额外 pip install -r requirements-winrt.txt

- noWinIME / mac 变体（sudachi 注音）：额外 pip install -r requirements-variants.txt

> Source of truth for deps is the pinned requirements*.txt (content-hashed by the release pipeline for incremental updates — change with care); pyproject.toml only holds tool config. Add one extra file per platform/variant as above.

📦 方式三 · 自行打包 / Build it yourself

# 安装 PyInstaller / Install PyInstaller
pip install pyinstaller
使用打包脚本（推荐） / Run the build script
python build.py

打包完成后可在 dist/StrangeUtaGame/ 目录找到可执行文件。 The packaged executable will appear in dist/StrangeUtaGame/.

⌨️ 键位说明 / Hotkeys

✅ 以下为打轴模式的默认键位，可在 设置 → 快捷键 中重新映射。

These are the default Timing Mode bindings. Remap them under Settings → Hotkeys.

🧰 技术栈 / Tech Stack

_{以上仅为代表性依赖；完整清单以仓库 requirements.txt / requirements-dev.txt 为准。
Representative deps only — see requirements.txt & requirements-dev.txt for the full list.}

🗂️ 项目结构 / Project Structure

StrangeUtaGame/
├── main.py                       # 入口 / Entry point
├── build.py · build_all.py       # PyInstaller 打包脚本（单变体 / 全变体）
├── pyproject.toml                # 工具配置（ruff/black/mypy/pytest）/ Tool config
├── requirements.txt              # 运行依赖（锁定版本）/ Runtime deps (pinned)
├── requirements-winrt.txt        # main 变体：WinRT 注音 / WinRT furigana (main)
├── requirements-variants.txt     # noWinIME / mac 变体：sudachi 注音
├── requirements-dev.txt          # 开发依赖 / Dev deps
├── setup_env.bat                 # Windows 一键环境 / Win one-click setup
│
├── config.json                   # 全局配置（含快捷键 / AutoCheck / 网络源）
├── dictionary.json               # 读音词典 / Reading dictionary
├── network_dictionary.json       # 联网词典缓存 / Online dict cache
├── singers.json                  # 演唱者预设 / Singer presets
│
├── docs/                         # 设计文档 / Design docs
│   ├── application.md            #   应用层 / App layer
│   ├── architecture.md           #   总体架构 / Architecture
│   ├── auto_update.md            #   自动更新 / Auto-update
│   ├── domain.md                 #   领域模型 / Domain model
│   ├── infrastructure.md         #   基础设施 / Infrastructure
│   ├── timetag-spec-mapping.md   #   时间标签规范 / Timetag spec
│   ├── ui.md                     #   UI 设计 / UI design
│   └── 更新日志-0.2.0.md
│
├── src/strange_uta_game/         # 主包 / Main package
│   ├── __version__.py            # 版本号 + 变体标识 / Version & build variant
│   │
│   ├── backend/                  # 后端（无 Qt 依赖）/ Backend (Qt-free)
│   │   ├── domain/               #   领域层 / Domain (纯数据模型)
│   │   │   └── entities.py · models.py · project.py
│   │   ├── application/          #   应用服务 / Application services
│   │   │   ├── timing_service.py · export_service.py
│   │   │   ├── auto_check_service.py · calibration_service.py
│   │   │   ├── command_manager.py · singer_service.py
│   │   │   └── project_service.py · project_import_service.py
│   │   └── infrastructure/       #   基础设施 / Infrastructure
│   │       ├── audio/            #     音频引擎 / Audio engine
│   │       │   ├── bass_engine.py · bass_tsm_engine.py
│   │       │   ├── sounddevice_engine.py · ring_buffer.py
│   │       │   └── tsm_cache.py · keysound_player.py · video_converter.py
│   │       ├── parsers/          #     解析与注音 / Parsers & furigana
│   │       │   ├── lyric_parser.py · ass_parser.py · srt_parser.py
│   │       │   ├── ruby_analyzer.py · english_ruby.py · e2k_engine.py
│   │       │   ├── inline_format.py · annotated_text.py · romaji.py
│   │       │   └── kanji_reading_split.py · rl_dictionary.py · text_splitter.py · llm_ruby.py
│   │       ├── exporters/        #     导出器 / Exporters
│   │       │   ├── lrc_exporter.py · nicokara_exporter.py · srt_exporter.py
│   │       │   └── txt_exporter.py · txt2ass_exporter.py · inline_exporter.py
│   │       ├── data/default_dictionary.py   #   内置词典 / Built-in dict
│   │       ├── persistence/sug_io.py        #   .sug 工程读写 / Project IO
│   │       └── network_dictionary.py        #   联网词典 / Online dict
│   │
│   ├── frontend/                 # 界面层 / UI layer (PyQt6 + Fluent)
│   │   ├── main_window.py · theme.py · workers.py
│   │   ├── window_sizing.py · splash_screen.py · winrt_japanese_guide.py
│   │   ├── editor/               #   编辑器 / Editors
│   │   │   ├── timing_interface.py + timing/   #     打轴主界面 + 子组件
│   │   │   ├── fulltext_interface.py           #     全文本编辑（已废弃）
│   │   │   └── line_interface.py               #     行编辑
│   │   ├── home/ · export/ · singer/ · online/ #   起始 / 导出 / 演唱者 / 联网词典
│   │   ├── settings/             #   设置页 + cards + dialogs
│   │   ├── localization/         #   多语言 i18n (zh / en / ja)
│   │   └── startup/ · log/
│   │
│   ├── updater/                  # 自动更新器 / Auto-updater
│   │   ├── http_client.py · installer.py · manifest.py · worker.py
│   │   ├── proxy.py · settings.py · sources.py · version.py
│   │   └── ui/                   #   更新弹窗 / Update dialogs
│   │
│   ├── bass/                     # BASS DLLs（x86 + x64）/ BASS DLLs
│   ├── config/                   # 默认配置与词典 / Default config & dicts
│   │   ├── config.json · dictionary.json · singers.json
│   │   └── cmudict-0.7b · e2k.txt · kanji_readings.json
│   └── resource/                 # 图标与音效 / Icons & key sounds
│       └── icon.ico · icon.icns · mascot.png · sounds/
│
├── tests/                        # 测试 / Tests (pytest + pytest-qt)
│   ├── app/services/    · app/domain/
│   ├── infrastructure/  · ui/
│   └── updater/
│
└── scripts/                      # 杂项脚本 / Misc scripts
    ├── release.py
    ├── import_rl_builtin_dict.py
    └── migrate_dictionary*.py

_{📌 节略自仓库实际目录；命名 / 层级以 src/strange_uta_game/ 真实内容为准。
Compressed from the real repo layout — see src/strange_uta_game/ for the authoritative tree.}

🤝 贡献指南 / Contributing

我们欢迎任何形式的贡献！ We welcome contributions of all kinds.

git checkout -b feat/your-idea
……写代码 / make changes
git commit -m "feat: your idea"
git push origin feat/your-idea

_{提交前请运行 ruff check . 与 pytest。
Please run ruff check . and pytest before opening a PR.}

💐 致谢 / Credits

• RhythmicaLyrics — 灵感来源与工作流原型 / Original inspiration & workflow
• FA-Kara (moriwx) — AI 打轴对齐与注音转写思路参考（MIT）/ Forced-alignment & transcription reference for AI timing
• yohane (Japan7) — AI 打轴 Wav2Vec2 CTC 对齐思路参考 / Wav2Vec2 CTC alignment reference for AI timing
• BASS Audio Library (un4seen) — 低延迟音频引擎与解码 / Low-latency audio engine & decoding
• BASS-FX — 实时音频变速 / Real-time pitch-preserving stretch
• pedalboard (Spotify) — 音频效果与高质量变速 / Audio effects & HQ stretch
• sounddevice · soundfile — 音频 I/O
• PyQt6 + PyQt6-Fluent-Widgets — UI 框架 / UI framework
• WinRT JapanesePhoneticAnalyzer — 系统 IME 注音 / System IME furigana
• pykakasi · jaconv · pyphen — 日语 / 英文音节处理
• CMUdict · e2k — 英文注音词典 / English pronunciation dicts
• 所有提 issue / PR 的伙伴们 · Everyone who filed an issue or PR 💜

❓ FAQ

📜 License

本项目采用 GNU General Public License v3.0 开源。 Released under the GNU General Public License v3.0.

Copyright (C) 2026 karaoke-studio and contributors
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

_{Made with 💜 by karaoke-studio  ·  Powered by Python + PyQt6 + BASS}

「打出你听见的每一个字。」
_{"Tag every syllable you can hear."}