| Name | PySimaiParser JSON |
| Version |
0.2.3
JSON |
| download |
| home_page | None |
| Summary | A Python library and command-line tool to parse Simai chart files into JSON. |
| upload_time | 2025-07-30 21:57:36 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | None |
| keywords |
simai
parser
rhythm game
maidata
chart
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[Read this document in English (阅读英文版)](README_en.md)
# PySimaiParser：Python Simai 谱面解析器
PySimaiParser 是一个 Python 库和命令行工具，用于解析某些音乐游戏中使用的 Simai 谱面文件（通常是 `maidata.txt` 或类似格式）。它将谱面数据，包括元数据和详细的音符信息，转换为结构化的 JSON 格式。这使得谱面数据更易于分析、处理或集成到其他应用程序和工具中。
## 特性
- **全面的元数据解析**: 提取谱面的关键信息，如标题 (`&title`)、艺术家 (`&artist`)、谱师 (`&des`)、初始偏移时间 (`&first`) 和难度等级 (`&lv_x`)。
- **详细的谱面数据解析**:
- 处理 BPM 变化 `(value)`。
- 处理节拍记号变化 `{value}`。
- 解析变速调整 `<Hvalue>` 或 `<HS*value>`。
- 基于以上参数精确计算音符时间。
- **精细的音符解释**:
- 支持所有标准 Simai 音符类型：TAP、HOLD、SLIDE (支持 `-`, `^`, `v`, `<`, `>`, `V`, `p`, `q`, `s`, `z`, `w` 等多种路径记号)、TOUCH (A-E, C) 和 TOUCH_HOLD。
- 解析复杂的音符修饰符和标志：BREAK 音符 (`b`)、EX 音符 (`x`)、烟花效果 (`f`)、无头滑条 (`!`, `?`)、强制星星显示 (`$`) 和伪旋转效果 (`$$`)。
- 解释复杂的 HOLD/SLIDE 时值和 SLIDE 星星等待时间语法 (例如 `[拍号分母:拍数]`、`[BPM#拍号分母:拍数]`、`[#绝对秒数]` 以及 `[等待BPM#...]`、`[绝对等待秒数##持续秒数]`)。
- 正确处理通过 `/` 分隔的同时音符、使用 `*` 的同头滑条以及使用 ``` 的伪同时音符（装饰音）。
- **结构化 JSON 输出**: 生成组织良好且易读的 JSON 对象，代表整个解析后的谱面，适合直接使用或进一步处理。
- **命令行接口 (CLI)**: 提供简单易用的命令行工具 (`cli.py`)，用于快速将 Simai 谱面文件转换为 JSON，并可指定输出文件和缩进。
- **Python 包**: 设计为 Python 包 (`SimaiParser`)，方便集成到其他 Python 项目中。
## 项目结构
```
PySimaiParser/
├── SimaiParser/
│ ├── __init__.py
│ ├── core.py # 包含 SimaiChart 和解析器核心逻辑
│ ├── note.py # 包含 SimaiNote 音符数据类
│ └── timing.py # 包含 SimaiTimingPoint 时间点类
├── tests/ # 单元测试
│ ├── __init__.py
│ └── test_core.py # core.py 的测试文件
├── cli.py # 命令行接口脚本
├── LICENSE.txt # LICENSE 文件
├── README_en.md # 英文版 README
└── README.md # 中文版 README (本文档)
```
## 安装
1. **使用 pip 安装** (推荐):
```bash
# 从 GitHub 直接安装
pip install git+https://github.com/Choimoe/PySimaiParser.git
# 或者 clone 后本地安装
git clone https://github.com/Choimoe/PySimaiParser.git
cd PySimaiParser
pip install .
```
2. **验证安装**:
```bash
pysimaiparser-cli --version
# 应该输出 0.1.0
```
建议在虚拟环境中安装：
```bash
python -m venv venv
source venv/bin/activate # Windows 系统: venv\Scripts\activate
pip install .
```
## 使用方法
### 作为 Python 库
```
from SimaiParser import SimaiChart
simai_file_content = """
&title=示例歌曲
&artist=某艺术家
&first=1.0
&lv_4=12
&inote_4=
(120)
1,2,
E1h[4:1],
"""
chart = SimaiChart()
chart.load_from_text(simai_file_content)
json_data = chart.to_json(indent=2)
print(json_data)
# 访问解析后的数据
# print(chart.metadata["title"])
# if chart.processed_fumens_data and chart.processed_fumens_data[3]["note_events"]:
# first_note_time = chart.processed_fumens_data[3]["note_events"][0]["time"]
# print(f"Expert 难度谱面的第一个音符时间: {first_note_time}")
```
### 作为命令行工具
`cli.py` 脚本允许您直接从终端解析 Simai 文件。
1. **导航到 `cli.py` 所在的目录。**
2. **运行脚本:**
- 解析文件并将 JSON 打印到控制台：
```
python cli.py path/to/your/chart.txt
```
- 解析文件并将 JSON 保存到输出文件：
```
python cli.py path/to/your/chart.txt -o path/to/output.json
```
- 指定 JSON 缩进 (例如, 4个空格)：
```
python cli.py path/to/your/chart.txt -i 4
```
- 获取紧凑的 JSON 输出 (无额外空格的单行)：
```
python cli.py path/to/your/chart.txt -i -1
```
- 查看帮助信息：
```
python cli.py -h
```
- 查看版本号：
```
python cli.py --version
```
## 运行测试
单元测试位于 `tests/` 目录中，并使用 Python 内置的 `unittest` 模块。
1. **导航到项目根目录 (`PySimaiParser/`)。**
2. **运行测试:**
```
python -m unittest discover tests
```
或者，运行特定的测试文件：
```
python -m unittest tests.test_core
```
## 贡献
欢迎参与贡献！如果您想为项目做出贡献，请考虑以下几点：
- Fork 本仓库。
- 为您的新功能或错误修复创建一个新的分支。
- 为您的更改编写测试。
- 确保所有测试都通过。
- 提交一个 Pull Request，并清晰描述您的更改。
## 许可证
本项目采用 MIT 许可证。详情请参阅 `LICENSE` 文件。
Raw data
{
"_id": null,
"home_page": null,
"name": "PySimaiParser",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "simai, parser, rhythm game, maidata, chart",
"author": null,
"author_email": "Choimoe <qwqshq@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/6d/25/bf0fa6142d7a619248295afbe03ee2d6441479d3a0fa850da629ed2d29a7/pysimaiparser-0.2.3.tar.gz",
"platform": null,
"description": "[Read this document in English (\u9605\u8bfb\u82f1\u6587\u7248)](README_en.md)\r\n\r\n# PySimaiParser\uff1aPython Simai \u8c31\u9762\u89e3\u6790\u5668\r\n\r\nPySimaiParser \u662f\u4e00\u4e2a Python \u5e93\u548c\u547d\u4ee4\u884c\u5de5\u5177\uff0c\u7528\u4e8e\u89e3\u6790\u67d0\u4e9b\u97f3\u4e50\u6e38\u620f\u4e2d\u4f7f\u7528\u7684 Simai \u8c31\u9762\u6587\u4ef6\uff08\u901a\u5e38\u662f `maidata.txt` \u6216\u7c7b\u4f3c\u683c\u5f0f\uff09\u3002\u5b83\u5c06\u8c31\u9762\u6570\u636e\uff0c\u5305\u62ec\u5143\u6570\u636e\u548c\u8be6\u7ec6\u7684\u97f3\u7b26\u4fe1\u606f\uff0c\u8f6c\u6362\u4e3a\u7ed3\u6784\u5316\u7684 JSON \u683c\u5f0f\u3002\u8fd9\u4f7f\u5f97\u8c31\u9762\u6570\u636e\u66f4\u6613\u4e8e\u5206\u6790\u3001\u5904\u7406\u6216\u96c6\u6210\u5230\u5176\u4ed6\u5e94\u7528\u7a0b\u5e8f\u548c\u5de5\u5177\u4e2d\u3002\r\n\r\n## \u7279\u6027\r\n\r\n- **\u5168\u9762\u7684\u5143\u6570\u636e\u89e3\u6790**: \u63d0\u53d6\u8c31\u9762\u7684\u5173\u952e\u4fe1\u606f\uff0c\u5982\u6807\u9898 (`&title`)\u3001\u827a\u672f\u5bb6 (`&artist`)\u3001\u8c31\u5e08 (`&des`)\u3001\u521d\u59cb\u504f\u79fb\u65f6\u95f4 (`&first`) \u548c\u96be\u5ea6\u7b49\u7ea7 (`&lv_x`)\u3002\r\n- **\u8be6\u7ec6\u7684\u8c31\u9762\u6570\u636e\u89e3\u6790**:\r\n - \u5904\u7406 BPM \u53d8\u5316 `(value)`\u3002\r\n - \u5904\u7406\u8282\u62cd\u8bb0\u53f7\u53d8\u5316 `{value}`\u3002\r\n - \u89e3\u6790\u53d8\u901f\u8c03\u6574 `<Hvalue>` \u6216 `<HS*value>`\u3002\r\n - \u57fa\u4e8e\u4ee5\u4e0a\u53c2\u6570\u7cbe\u786e\u8ba1\u7b97\u97f3\u7b26\u65f6\u95f4\u3002\r\n- **\u7cbe\u7ec6\u7684\u97f3\u7b26\u89e3\u91ca**:\r\n - \u652f\u6301\u6240\u6709\u6807\u51c6 Simai \u97f3\u7b26\u7c7b\u578b\uff1aTAP\u3001HOLD\u3001SLIDE (\u652f\u6301 `-`, `^`, `v`, `<`, `>`, `V`, `p`, `q`, `s`, `z`, `w` \u7b49\u591a\u79cd\u8def\u5f84\u8bb0\u53f7)\u3001TOUCH (A-E, C) \u548c TOUCH_HOLD\u3002\r\n - \u89e3\u6790\u590d\u6742\u7684\u97f3\u7b26\u4fee\u9970\u7b26\u548c\u6807\u5fd7\uff1aBREAK \u97f3\u7b26 (`b`)\u3001EX \u97f3\u7b26 (`x`)\u3001\u70df\u82b1\u6548\u679c (`f`)\u3001\u65e0\u5934\u6ed1\u6761 (`!`, `?`)\u3001\u5f3a\u5236\u661f\u661f\u663e\u793a (`$`) \u548c\u4f2a\u65cb\u8f6c\u6548\u679c (`$$`)\u3002\r\n - \u89e3\u91ca\u590d\u6742\u7684 HOLD/SLIDE \u65f6\u503c\u548c SLIDE \u661f\u661f\u7b49\u5f85\u65f6\u95f4\u8bed\u6cd5 (\u4f8b\u5982 `[\u62cd\u53f7\u5206\u6bcd:\u62cd\u6570]`\u3001`[BPM#\u62cd\u53f7\u5206\u6bcd:\u62cd\u6570]`\u3001`[#\u7edd\u5bf9\u79d2\u6570]` \u4ee5\u53ca `[\u7b49\u5f85BPM#...]`\u3001`[\u7edd\u5bf9\u7b49\u5f85\u79d2\u6570##\u6301\u7eed\u79d2\u6570]`)\u3002\r\n - \u6b63\u786e\u5904\u7406\u901a\u8fc7 `/` \u5206\u9694\u7684\u540c\u65f6\u97f3\u7b26\u3001\u4f7f\u7528 `*` \u7684\u540c\u5934\u6ed1\u6761\u4ee5\u53ca\u4f7f\u7528 ``` \u7684\u4f2a\u540c\u65f6\u97f3\u7b26\uff08\u88c5\u9970\u97f3\uff09\u3002\r\n- **\u7ed3\u6784\u5316 JSON \u8f93\u51fa**: \u751f\u6210\u7ec4\u7ec7\u826f\u597d\u4e14\u6613\u8bfb\u7684 JSON \u5bf9\u8c61\uff0c\u4ee3\u8868\u6574\u4e2a\u89e3\u6790\u540e\u7684\u8c31\u9762\uff0c\u9002\u5408\u76f4\u63a5\u4f7f\u7528\u6216\u8fdb\u4e00\u6b65\u5904\u7406\u3002\r\n- **\u547d\u4ee4\u884c\u63a5\u53e3 (CLI)**: \u63d0\u4f9b\u7b80\u5355\u6613\u7528\u7684\u547d\u4ee4\u884c\u5de5\u5177 (`cli.py`)\uff0c\u7528\u4e8e\u5feb\u901f\u5c06 Simai \u8c31\u9762\u6587\u4ef6\u8f6c\u6362\u4e3a JSON\uff0c\u5e76\u53ef\u6307\u5b9a\u8f93\u51fa\u6587\u4ef6\u548c\u7f29\u8fdb\u3002\r\n- **Python \u5305**: \u8bbe\u8ba1\u4e3a Python \u5305 (`SimaiParser`)\uff0c\u65b9\u4fbf\u96c6\u6210\u5230\u5176\u4ed6 Python \u9879\u76ee\u4e2d\u3002\r\n\r\n## \u9879\u76ee\u7ed3\u6784\r\n\r\n```\r\nPySimaiParser/\r\n\u251c\u2500\u2500 SimaiParser/\r\n\u2502 \u251c\u2500\u2500 __init__.py\r\n\u2502 \u251c\u2500\u2500 core.py # \u5305\u542b SimaiChart \u548c\u89e3\u6790\u5668\u6838\u5fc3\u903b\u8f91\r\n\u2502 \u251c\u2500\u2500 note.py # \u5305\u542b SimaiNote \u97f3\u7b26\u6570\u636e\u7c7b\r\n\u2502 \u2514\u2500\u2500 timing.py # \u5305\u542b SimaiTimingPoint \u65f6\u95f4\u70b9\u7c7b\r\n\u251c\u2500\u2500 tests/ # \u5355\u5143\u6d4b\u8bd5\r\n\u2502 \u251c\u2500\u2500 __init__.py\r\n\u2502 \u2514\u2500\u2500 test_core.py # core.py \u7684\u6d4b\u8bd5\u6587\u4ef6\r\n\u251c\u2500\u2500 cli.py # \u547d\u4ee4\u884c\u63a5\u53e3\u811a\u672c\r\n\u251c\u2500\u2500 LICENSE.txt # LICENSE \u6587\u4ef6\r\n\u251c\u2500\u2500 README_en.md # \u82f1\u6587\u7248 README\r\n\u2514\u2500\u2500 README.md # \u4e2d\u6587\u7248 README (\u672c\u6587\u6863)\r\n```\r\n\r\n## \u5b89\u88c5\r\n\r\n1. **\u4f7f\u7528 pip \u5b89\u88c5** (\u63a8\u8350):\r\n\r\n ```bash\r\n # \u4ece GitHub \u76f4\u63a5\u5b89\u88c5\r\n pip install git+https://github.com/Choimoe/PySimaiParser.git\r\n\r\n # \u6216\u8005 clone \u540e\u672c\u5730\u5b89\u88c5\r\n git clone https://github.com/Choimoe/PySimaiParser.git\r\n cd PySimaiParser\r\n pip install .\r\n ```\r\n\r\n2. **\u9a8c\u8bc1\u5b89\u88c5**:\r\n\r\n ```bash\r\n pysimaiparser-cli --version\r\n # \u5e94\u8be5\u8f93\u51fa 0.1.0\r\n ```\r\n\r\n\u5efa\u8bae\u5728\u865a\u62df\u73af\u5883\u4e2d\u5b89\u88c5\uff1a\r\n\r\n```bash\r\npython -m venv venv\r\nsource venv/bin/activate # Windows \u7cfb\u7edf: venv\\Scripts\\activate\r\npip install .\r\n```\r\n\r\n## \u4f7f\u7528\u65b9\u6cd5\r\n\r\n### \u4f5c\u4e3a Python \u5e93\r\n\r\n```\r\nfrom SimaiParser import SimaiChart\r\n\r\nsimai_file_content = \"\"\"\r\n&title=\u793a\u4f8b\u6b4c\u66f2\r\n&artist=\u67d0\u827a\u672f\u5bb6\r\n&first=1.0\r\n&lv_4=12\r\n&inote_4=\r\n(120)\r\n1,2,\r\nE1h[4:1],\r\n\"\"\"\r\n\r\nchart = SimaiChart()\r\nchart.load_from_text(simai_file_content)\r\njson_data = chart.to_json(indent=2)\r\n\r\nprint(json_data)\r\n\r\n# \u8bbf\u95ee\u89e3\u6790\u540e\u7684\u6570\u636e\r\n# print(chart.metadata[\"title\"])\r\n# if chart.processed_fumens_data and chart.processed_fumens_data[3][\"note_events\"]:\r\n# first_note_time = chart.processed_fumens_data[3][\"note_events\"][0][\"time\"]\r\n# print(f\"Expert \u96be\u5ea6\u8c31\u9762\u7684\u7b2c\u4e00\u4e2a\u97f3\u7b26\u65f6\u95f4: {first_note_time}\")\r\n```\r\n\r\n### \u4f5c\u4e3a\u547d\u4ee4\u884c\u5de5\u5177\r\n\r\n`cli.py` \u811a\u672c\u5141\u8bb8\u60a8\u76f4\u63a5\u4ece\u7ec8\u7aef\u89e3\u6790 Simai \u6587\u4ef6\u3002\r\n\r\n1. **\u5bfc\u822a\u5230 `cli.py` \u6240\u5728\u7684\u76ee\u5f55\u3002**\r\n\r\n2. **\u8fd0\u884c\u811a\u672c:**\r\n\r\n - \u89e3\u6790\u6587\u4ef6\u5e76\u5c06 JSON \u6253\u5370\u5230\u63a7\u5236\u53f0\uff1a\r\n\r\n ```\r\n python cli.py path/to/your/chart.txt\r\n ```\r\n\r\n - \u89e3\u6790\u6587\u4ef6\u5e76\u5c06 JSON \u4fdd\u5b58\u5230\u8f93\u51fa\u6587\u4ef6\uff1a\r\n\r\n ```\r\n python cli.py path/to/your/chart.txt -o path/to/output.json\r\n ```\r\n\r\n - \u6307\u5b9a JSON \u7f29\u8fdb (\u4f8b\u5982, 4\u4e2a\u7a7a\u683c)\uff1a\r\n\r\n ```\r\n python cli.py path/to/your/chart.txt -i 4\r\n ```\r\n\r\n - \u83b7\u53d6\u7d27\u51d1\u7684 JSON \u8f93\u51fa (\u65e0\u989d\u5916\u7a7a\u683c\u7684\u5355\u884c)\uff1a\r\n\r\n ```\r\n python cli.py path/to/your/chart.txt -i -1\r\n ```\r\n\r\n - \u67e5\u770b\u5e2e\u52a9\u4fe1\u606f\uff1a\r\n\r\n ```\r\n python cli.py -h\r\n ```\r\n\r\n - \u67e5\u770b\u7248\u672c\u53f7\uff1a\r\n\r\n ```\r\n python cli.py --version\r\n ```\r\n\r\n## \u8fd0\u884c\u6d4b\u8bd5\r\n\r\n\u5355\u5143\u6d4b\u8bd5\u4f4d\u4e8e `tests/` \u76ee\u5f55\u4e2d\uff0c\u5e76\u4f7f\u7528 Python \u5185\u7f6e\u7684 `unittest` \u6a21\u5757\u3002\r\n\r\n1. **\u5bfc\u822a\u5230\u9879\u76ee\u6839\u76ee\u5f55 (`PySimaiParser/`)\u3002**\r\n\r\n2. **\u8fd0\u884c\u6d4b\u8bd5:**\r\n\r\n ```\r\n python -m unittest discover tests\r\n ```\r\n\r\n \u6216\u8005\uff0c\u8fd0\u884c\u7279\u5b9a\u7684\u6d4b\u8bd5\u6587\u4ef6\uff1a\r\n\r\n ```\r\n python -m unittest tests.test_core\r\n ```\r\n\r\n## \u8d21\u732e\r\n\r\n\u6b22\u8fce\u53c2\u4e0e\u8d21\u732e\uff01\u5982\u679c\u60a8\u60f3\u4e3a\u9879\u76ee\u505a\u51fa\u8d21\u732e\uff0c\u8bf7\u8003\u8651\u4ee5\u4e0b\u51e0\u70b9\uff1a\r\n\r\n- Fork \u672c\u4ed3\u5e93\u3002\r\n- \u4e3a\u60a8\u7684\u65b0\u529f\u80fd\u6216\u9519\u8bef\u4fee\u590d\u521b\u5efa\u4e00\u4e2a\u65b0\u7684\u5206\u652f\u3002\r\n- \u4e3a\u60a8\u7684\u66f4\u6539\u7f16\u5199\u6d4b\u8bd5\u3002\r\n- \u786e\u4fdd\u6240\u6709\u6d4b\u8bd5\u90fd\u901a\u8fc7\u3002\r\n- \u63d0\u4ea4\u4e00\u4e2a Pull Request\uff0c\u5e76\u6e05\u6670\u63cf\u8ff0\u60a8\u7684\u66f4\u6539\u3002\r\n\r\n## \u8bb8\u53ef\u8bc1\r\n\r\n\u672c\u9879\u76ee\u91c7\u7528 MIT \u8bb8\u53ef\u8bc1\u3002\u8be6\u60c5\u8bf7\u53c2\u9605 `LICENSE` \u6587\u4ef6\u3002\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python library and command-line tool to parse Simai chart files into JSON.",
"version": "0.2.3",
"project_urls": {
"Bug Tracker": "https://github.com/Choimoe/PySimaiParser/issues",
"Homepage": "https://github.com/Choimoe/PySimaiParser"
},
"split_keywords": [
"simai",
" parser",
" rhythm game",
" maidata",
" chart"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d5c01a83af849a71218cbc2e6429d0cdeb21c5539a9c1a885410fff75223efde",
"md5": "97a6bd73c67e0267729f973e3025d8fc",
"sha256": "9dcfb76182b269f76290de46c8b6bba08a21b99680bf5f44ea4bf8f46267f638"
},
"downloads": -1,
"filename": "pysimaiparser-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "97a6bd73c67e0267729f973e3025d8fc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 31615,
"upload_time": "2025-07-30T21:57:34",
"upload_time_iso_8601": "2025-07-30T21:57:34.104636Z",
"url": "https://files.pythonhosted.org/packages/d5/c0/1a83af849a71218cbc2e6429d0cdeb21c5539a9c1a885410fff75223efde/pysimaiparser-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6d25bf0fa6142d7a619248295afbe03ee2d6441479d3a0fa850da629ed2d29a7",
"md5": "33cd62c6db6949638c70c4ed24699899",
"sha256": "fefe403956a44a12a21528e59ffe87414f20e636fa09cd3e276d69d5e6856070"
},
"downloads": -1,
"filename": "pysimaiparser-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "33cd62c6db6949638c70c4ed24699899",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 31680,
"upload_time": "2025-07-30T21:57:36",
"upload_time_iso_8601": "2025-07-30T21:57:36.812672Z",
"url": "https://files.pythonhosted.org/packages/6d/25/bf0fa6142d7a619248295afbe03ee2d6441479d3a0fa850da629ed2d29a7/pysimaiparser-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 21:57:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Choimoe",
"github_project": "PySimaiParser",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pysimaiparser"
}
