hesym 0.1.0__tar.gz

hesym-0.1.0/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

hesym-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GTLaimi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hesym-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.5
+Name: hesym
+Version: 0.1.0
+Summary: HesychiaMidS CLI tool - MIDI parsing and visualization in your terminal
+Project-URL: Homepage, https://github.com/GTLaimi/hesym
+Project-URL: Repository, https://github.com/GTLaimi/hesym
+Project-URL: Issues, https://github.com/GTLaimi/hesym/issues
+Author-email: GTLaimi <3935984932@qq.com>
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Requires-Dist: mido>=1.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hesym

hesym-0.1.0/README.md

@@ -0,0 +1 @@
+# hesym

hesym-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hesym"
+version = "0.1.0"
+description = "HesychiaMidS CLI tool - MIDI parsing and visualization in your terminal"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "GTLaimi", email = "3935984932@qq.com"}
+]
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "mido>=1.3.0"
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/GTLaimi/hesym"
+Repository = "https://github.com/GTLaimi/hesym"
+Issues = "https://github.com/GTLaimi/hesym/issues"
+
+[project.scripts]
+hesym = "hesym.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hesym"]

hesym-0.1.0/src/hesym/__init__.py

@@ -0,0 +1,16 @@
+"""
+hesym - HesychiaMidS CLI tool
+MIDI parsing and visualization in your terminal
+"""
+
+from .core.midi_parser import parse_midi
+from .models.note import Note
+from .cli import main
+
+__all__ = [
+    "parse_midi",
+    "Note",
+    "main",
+]
+
+__version__ = "0.1.0"

hesym-0.1.0/src/hesym/cli.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""命令行入口 - MIDI 解析与可视化 CLI"""
+
+import argparse
+import json
+import sys
+import os
+
+# 使用相对导入（包内导入）
+from .core.midi_parser import parse_midi
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="hesym: MIDI file parser and visualizer - extract notes, stats, and more"
+    )
+    parser.add_argument("file", help="要解析的 MIDI 文件路径")
+    parser.add_argument("--json", action="store_true", help="以 JSON 格式输出原始数据")
+    parser.add_argument("--stats", action="store_true", help="显示统计信息（总音符数、时长等）")
+    parser.add_argument("--limit", type=int, default=20, help="显示前 N 个音符 (默认 20)")
+    parser.add_argument("--fix-vel", type=int, default=0, help="将力度为0的音符修正为指定值 (例如 100)")
+
+    args = parser.parse_args()
+
+    if not os.path.exists(args.file):
+        print(f"❌ 错误: 文件 '{args.file}' 不存在", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        notes, total_ticks, bpm, ticks_per_beat, time_sig = parse_midi(args.file)
+    except Exception as e:
+        print(f"❌ 解析 MIDI 失败: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # ---- 力度修复 ----
+    if args.fix_vel > 0:
+        for note in notes:
+            if note.velocity == 0:
+                note.velocity = args.fix_vel
+
+    # ---- 输出逻辑 ----
+    if args.json:
+        data = {
+            "format": "hesym_core",
+            "ticks_per_beat": ticks_per_beat,
+            "bpm": bpm,
+            "time_signature": time_sig,
+            "total_ticks": total_ticks,
+            "note_count": len(notes),
+            "notes": [
+                {
+                    "pitch": n.pitch,
+                    "name": n.pitch_name,
+                    "start_tick": n.start_tick,
+                    "duration_ticks": n.duration,
+                    "velocity": n.velocity
+                } for n in notes
+            ]
+        }
+        print(json.dumps(data, indent=2))
+    elif args.stats:
+        total_sec = total_ticks / ((bpm / 60.0) * ticks_per_beat)
+        pitches = [n.pitch for n in notes]
+        print(f"📊 MIDI 统计报告")
+        print(f"   🎵 音符总数: {len(notes)}")
+        print(f"   ⏱️  总时长: {total_ticks} ticks ≈ {total_sec:.2f} 秒")
+        print(f"   🎚️  BPM: {bpm:.1f}")
+        print(f"   📏  PPQ (每拍Tick数): {ticks_per_beat}")
+        print(f"   🎼 拍号: {time_sig}")
+        if pitches:
+            print(f"   🎹 音域: {min(pitches)} -> {max(pitches)}")
+        if args.fix_vel > 0:
+            print(f"   🔧 已将所有力度 0 修正为 {args.fix_vel}")
+    else:
+        # 默认表格显示
+        print(f"\n🎵 解析成功！共读取 {len(notes)} 个音符 (显示前 {min(args.limit, len(notes))} 个):\n")
+        print(f"{'Note':<6} {'Pitch':<5} {'Start':<10} {'Dur':<8} {'Vel'}")
+        print("-" * 40)
+        for n in notes[:args.limit]:
+            print(f"{n.pitch_name:<6} {n.pitch:<5} {n.start_tick:<10} {n.duration:<8} {n.velocity}")
+        if len(notes) > args.limit:
+            print(f"... (以及其余 {len(notes) - args.limit} 个音符)")
+
+if __name__ == "__main__":
+    main()

hesym-0.1.0/src/hesym/core/__init__.py

@@ -0,0 +1,3 @@
+from .midi_parser import parse_midi
+
+__all__ = ["parse_midi"]

hesym-0.1.0/src/hesym/core/midi_parser.py

@@ -0,0 +1,57 @@
+# core/midi_parser.py
+"""MIDI 文件解析核心模块
+
+依赖: mido (pip install mido)
+"""
+
+import mido
+from ..models.note import Note  # 改用相对导入
+
+
+def parse_midi(file_path: str):
+    """
+    解析 MIDI 文件，返回音符列表和元数据
+
+    Args:
+        file_path: MIDI 文件路径
+
+    Returns:
+        tuple: (notes, total_ticks, bpm, ticks_per_beat, time_sig)
+            - notes: Note 对象列表
+            - total_ticks: 总 tick 数
+            - bpm: 速度 (Beats Per Minute)
+            - ticks_per_beat: 每拍 tick 数 (PPQ)
+            - time_sig: 拍号字符串，如 "4/4"
+
+    Raises:
+        FileNotFoundError: 文件不存在时
+        ValueError: 解析失败时
+    """
+    mid = mido.MidiFile(file_path)
+    notes = []
+    active_notes = {}
+    cur_tick = 0
+    bpm = 120.0
+    ticks_per_beat = mid.ticks_per_beat
+    time_sig = "4/4"
+
+    for track in mid.tracks:
+        for msg in track:
+            cur_tick += msg.time
+            if msg.type == 'note_on' and msg.velocity > 0:
+                active_notes[msg.note] = cur_tick
+            elif msg.type == 'note_off' or (msg.type == 'note_on' and msg.velocity == 0):
+                if msg.note in active_notes:
+                    notes.append(Note(
+                        pitch=msg.note,
+                        start_tick=active_notes[msg.note],
+                        duration=cur_tick - active_notes[msg.note],
+                        velocity=msg.velocity
+                    ))
+                    del active_notes[msg.note]
+            elif msg.type == 'set_tempo':
+                bpm = mido.tempo2bpm(msg.tempo)
+            elif msg.type == 'time_signature':
+                time_sig = f"{msg.numerator}/{msg.denominator}"
+
+    return notes, cur_tick, bpm, ticks_per_beat, time_sig

hesym-0.1.0/src/hesym/models/__init__.py

@@ -0,0 +1 @@
+from .note import Note

hesym-0.1.0/src/hesym/models/note.py

@@ -0,0 +1,29 @@
+# models/note.py
+"""MIDI 音符数据模型"""
+
+
+class Note:
+    """MIDI 音符对象
+
+    Attributes:
+        pitch: 音高 (0-127)
+        start_tick: 起始 tick
+        duration: 持续时间 (tick 数)
+        velocity: 力度 (0-127)
+        pitch_name: 音名，如 "C4" (自动计算)
+    """
+
+    def __init__(self, pitch: int, start_tick: int, duration: int, velocity: int):
+        self.pitch = pitch
+        self.start_tick = start_tick
+        self.duration = duration
+        self.velocity = velocity
+        self.pitch_name = self._midi_to_name(pitch)
+
+    def _midi_to_name(self, midi_note: int) -> str:
+        """将 MIDI 音高编号转换为音名，如 60 -> C4"""
+        notes = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
+        return f"{notes[midi_note % 12]}{(midi_note // 12) - 1}"
+
+    def __repr__(self) -> str:
+        return f"Note(pitch={self.pitch}, name={self.pitch_name}, start={self.start_tick}, dur={self.duration}, vel={self.velocity})"