hyperscore 0.1.0__tar.gz

hyperscore-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.3
+Name: hyperscore
+Version: 0.1.0
+Summary: Structural music composition framework
+Author: inaba1115
+Author-email: inaba1115 <inaba1115@gmail.com>
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: lark>=1.3.1
+Requires-Dist: mido>=1.3.3
+Requires-Dist: python-rtmidi>=1.5.8
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# hyperscore
+
+**hyperscore** is a structural music composition framework that models music as explicit, composable structure rather than notation or performance.
+
+Time is represented uniformly using immutable time spans, pitch is handled as pitch-class structure independent of register, and rhythm is expressed as relative proportions that are resolved into concrete time only when needed. External formats such as MIDI are treated as lossy boundaries rather than as the source of truth.
+
+hyperscore is designed for experimentation, analysis, and integration with algorithmic systems, rather than for score engraving or DAW-style workflows.
+
+---
+
+## Minimal example
+
+This minimal example demonstrates the core hyperscore workflow: selecting pitch material using theory objects, describing rhythm structurally, generating time-based events, and exporting the result to MIDI.
+
+```python
+from hyperscore import CHORDS, Score, parse_rhythm
+from hyperscore.core import NoteEvent, bpm_to_ms
+from hyperscore.io import MidiExporter
+from hyperscore.rhythm import rhythm_ast_to_timespans
+
+# ----------------
+# theory
+# ----------------
+chord = CHORDS["major7"]
+
+pitches = [n for n in range(60, 72) if n % 12 in chord.intervals]
+pitch_iter = iter(pitches)
+
+# ----------------
+# rhythm
+# ----------------
+ast = parse_rhythm("1*4")
+total = int(bpm_to_ms(120, 1))
+spans = rhythm_ast_to_timespans(ast, total=total)
+
+# ----------------
+# score
+# ----------------
+score = Score()
+
+score.add_timespans(
+    spans,
+    factory=lambda span: NoteEvent(
+        pitch=next(pitch_iter),
+        velocity=100,
+        span=span,
+        channel=0,
+    ),
+)
+
+# ----------------
+# output
+# ----------------
+MidiExporter().export(score, "example.mid")
+```
+
+This example intentionally avoids musical interpretation and focuses on structural composition. Pitch, rhythm, and time are treated as independent layers that are combined explicitly.
+
+---
+
+## What this example demonstrates
+
+- Rhythm is expressed as **structure**, not notation
+- Time is handled explicitly via immutable `TimeSpan` objects
+- Pitch and rhythm are **independent layers**
+- MIDI is treated as a **lossy output format**
+
+For more advanced usage, see:
+
+- `examples/`
+- `tests/test_smoke.py`
+
+---
+
+## Optional: ZippedNotes shortcut
+
+For simple sequential note generation without explicit TimeSpan construction, hyperscore provides the `ZippedNotes` convenience API.
+
+This approach is suitable for basic sketches or quick tests, but offers less control than TimeSpan-based workflows.
+
+```python
+from hyperscore import Score
+from hyperscore.core import NoteEvent
+
+score = Score()
+
+score.add(
+    pitch=[60, 64, 67, 71],  # C major 7 chord tones
+    velocity=[100],
+    duration=[125],
+    channel=[0],
+    event_factory=lambda **kw: NoteEvent(
+        pitch=kw["pitch"],
+        velocity=kw["velocity"],
+        span=kw["span"],
+        channel=kw["channel"],
+    ),
+)
+```
+
+For complex timing, transformations, or algorithmic rhythm generation, prefer TimeSpan-based workflows using `parse_rhythm`, `rhythm_ast_to_timespans`, and `TimeSpanPipeline`.
+
+---
+
+## Project status
+
+- Python >= 3.10
+- Typed (`py.typed`)
+- Experimental / research-oriented
+- API may evolve between minor versions
+
+hyperscore favors clarity of structure and explicitness of time over completeness or stylistic prescription.

hyperscore-0.1.0/README.md

@@ -0,0 +1,112 @@
+# hyperscore
+
+**hyperscore** is a structural music composition framework that models music as explicit, composable structure rather than notation or performance.
+
+Time is represented uniformly using immutable time spans, pitch is handled as pitch-class structure independent of register, and rhythm is expressed as relative proportions that are resolved into concrete time only when needed. External formats such as MIDI are treated as lossy boundaries rather than as the source of truth.
+
+hyperscore is designed for experimentation, analysis, and integration with algorithmic systems, rather than for score engraving or DAW-style workflows.
+
+---
+
+## Minimal example
+
+This minimal example demonstrates the core hyperscore workflow: selecting pitch material using theory objects, describing rhythm structurally, generating time-based events, and exporting the result to MIDI.
+
+```python
+from hyperscore import CHORDS, Score, parse_rhythm
+from hyperscore.core import NoteEvent, bpm_to_ms
+from hyperscore.io import MidiExporter
+from hyperscore.rhythm import rhythm_ast_to_timespans
+
+# ----------------
+# theory
+# ----------------
+chord = CHORDS["major7"]
+
+pitches = [n for n in range(60, 72) if n % 12 in chord.intervals]
+pitch_iter = iter(pitches)
+
+# ----------------
+# rhythm
+# ----------------
+ast = parse_rhythm("1*4")
+total = int(bpm_to_ms(120, 1))
+spans = rhythm_ast_to_timespans(ast, total=total)
+
+# ----------------
+# score
+# ----------------
+score = Score()
+
+score.add_timespans(
+    spans,
+    factory=lambda span: NoteEvent(
+        pitch=next(pitch_iter),
+        velocity=100,
+        span=span,
+        channel=0,
+    ),
+)
+
+# ----------------
+# output
+# ----------------
+MidiExporter().export(score, "example.mid")
+```
+
+This example intentionally avoids musical interpretation and focuses on structural composition. Pitch, rhythm, and time are treated as independent layers that are combined explicitly.
+
+---
+
+## What this example demonstrates
+
+- Rhythm is expressed as **structure**, not notation
+- Time is handled explicitly via immutable `TimeSpan` objects
+- Pitch and rhythm are **independent layers**
+- MIDI is treated as a **lossy output format**
+
+For more advanced usage, see:
+
+- `examples/`
+- `tests/test_smoke.py`
+
+---
+
+## Optional: ZippedNotes shortcut
+
+For simple sequential note generation without explicit TimeSpan construction, hyperscore provides the `ZippedNotes` convenience API.
+
+This approach is suitable for basic sketches or quick tests, but offers less control than TimeSpan-based workflows.
+
+```python
+from hyperscore import Score
+from hyperscore.core import NoteEvent
+
+score = Score()
+
+score.add(
+    pitch=[60, 64, 67, 71],  # C major 7 chord tones
+    velocity=[100],
+    duration=[125],
+    channel=[0],
+    event_factory=lambda **kw: NoteEvent(
+        pitch=kw["pitch"],
+        velocity=kw["velocity"],
+        span=kw["span"],
+        channel=kw["channel"],
+    ),
+)
+```
+
+For complex timing, transformations, or algorithmic rhythm generation, prefer TimeSpan-based workflows using `parse_rhythm`, `rhythm_ast_to_timespans`, and `TimeSpanPipeline`.
+
+---
+
+## Project status
+
+- Python >= 3.10
+- Typed (`py.typed`)
+- Experimental / research-oriented
+- API may evolve between minor versions
+
+hyperscore favors clarity of structure and explicitness of time over completeness or stylistic prescription.

hyperscore-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "hyperscore"
+version = "0.1.0"
+description = "Structural music composition framework"
+readme = "README.md"
+authors = [
+    { name = "inaba1115", email = "inaba1115@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "lark>=1.3.1",
+    "mido>=1.3.3",
+    "python-rtmidi>=1.5.8",
+]
+classifiers = [
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Scientific/Engineering",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.21,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.14.10",
+    "ty>=0.0.8",
+]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+extend-select = ["I", "RUF", "UP", "TID", "C", "SIM", "PTH"]
+extend-ignore = ["C901", "F401", "F403", "E722", "RUF007"]
+
+[tool.pytest.ini_options]
+minversion = "9.0"
+testpaths = ["tests"]
+addopts = [
+    "-ra",
+    "--strict-markers",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["hyperscore"]
+omit = [
+    "*/__init__.py",
+]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+precision = 2

hyperscore-0.1.0/src/hyperscore/__init__.py

@@ -0,0 +1,35 @@
+"""
+hyperscore: a structural music composition framework.
+
+hyperscore provides a minimal, composable foundation for
+algorithmic and structural music composition.
+
+Key ideas
+---------
+- Music is modeled as explicit structure, not notation.
+- Time is represented uniformly using immutable TimeSpan objects.
+- Pitch is handled as pitch-class structure, independent of register.
+- External formats (e.g. MIDI) are treated as lossy boundaries.
+
+The library is organized into clear layers:
+- core: time and event primitives
+- rhythm: structural rhythm descriptions
+- theory: pitch-class and scale structures
+- io: adapters to external systems
+
+hyperscore is designed for experimentation, analysis,
+and integration with other algorithmic systems,
+rather than for direct score engraving or DAW replacement.
+"""
+
+from hyperscore.core import Score, ZippedNotes
+from hyperscore.rhythm import parse_rhythm
+from hyperscore.theory import CHORDS, SCALES
+
+__all__ = [
+    "CHORDS",
+    "SCALES",
+    "Score",
+    "ZippedNotes",
+    "parse_rhythm",
+]

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

@@ -0,0 +1,42 @@
+"""
+Core time and event primitives for hyperscore.
+
+This module defines the foundational abstractions used throughout
+hyperscore:
+
+- TimeSpan: immutable representation of linear time intervals
+- NoteEvent: minimal time-bounded musical event
+- Score: container and coordinator for events on a time axis
+- TimeSpanPipeline: composable transformations over TimeSpans
+- ZippedNotes: convenience API for simple sequential note generation
+
+Design principles
+-----------------
+- Time is represented explicitly and uniformly via TimeSpan.
+- Core abstractions are unit-agnostic (milliseconds, ticks, etc.).
+- Musical interpretation (harmony, rhythm, MIDI) is handled in
+  higher-level modules.
+- All core objects favor immutability and composability.
+
+This module is intentionally minimal and free of musical semantics.
+It serves as the stable foundation upon which rhythm, theory,
+and I/O layers are built.
+"""
+
+from .score import NoteEvent, Score, ZippedNotes
+from .time import TimeSpan, bpm_to_ms
+from .time_pipeline import TimeSpanPipeline
+from .time_transforms import gate, probability, shift, stretch
+
+__all__ = [
+    "NoteEvent",
+    "Score",
+    "TimeSpan",
+    "TimeSpanPipeline",
+    "ZippedNotes",
+    "bpm_to_ms",
+    "gate",
+    "probability",
+    "shift",
+    "stretch",
+]