hyperscore 0.1.0__py3-none-any.whl

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/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",
+]

hyperscore/core/score.py

@@ -0,0 +1,369 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Iterator, Sequence
+from dataclasses import dataclass, field, fields
+from typing import Generic, Protocol, TypeVar
+
+from .time import TimeSpan
+
+# ============================================================
+# Event model (default)
+# ============================================================
+
+
+class HasTimeSpan(Protocol):
+    """
+    Protocol for time-aware events.
+
+    Any event type stored in a Score must expose
+    a ``span`` attribute of type TimeSpan.
+    """
+
+    span: TimeSpan
+
+
+@dataclass(frozen=True)
+class NoteEvent:
+    """
+    Default note event implementation.
+
+    This is a minimal, time-bounded musical event.
+    Interpretation (e.g. MIDI, synthesis) is handled
+    by downstream systems.
+    """
+
+    pitch: int
+    velocity: int
+    span: TimeSpan
+    channel: int
+
+
+EventT = TypeVar("EventT", bound=HasTimeSpan)
+
+# ============================================================
+# Score context
+# ============================================================
+
+
+@dataclass(frozen=True)
+class ScoreContext:
+    """
+    Immutable score evaluation context.
+
+    The context tracks the current temporal cursor
+    during event generation.
+    """
+
+    cursor: int
+
+    def advance(self, delta: int) -> ScoreContext:
+        """
+        Return a new context advanced by the given duration.
+
+        Parameters
+        ----------
+        delta : int
+            Time increment in milliseconds.
+        """
+        return ScoreContext(cursor=self.cursor + delta)
+
+
+# ============================================================
+# ScoreInput protocol (event generator)
+# ============================================================
+
+
+class ScoreInput(Protocol[EventT]):
+    """
+    Protocol for event generators consumable by Score.
+
+    Implementations generate events based on the given
+    ScoreContext and return the updated context.
+    """
+
+    def iter_events(
+        self,
+        ctx: ScoreContext,
+    ) -> tuple[list[EventT], ScoreContext]: ...
+
+
+# ============================================================
+# EventFactory protocol
+# ============================================================
+
+
+EventFactory = Callable[..., EventT]
+
+# ============================================================
+# ZippedNotes (generic, factory-based)
+# ============================================================
+
+
+@dataclass(frozen=True)
+class ZippedNotes(Generic[EventT]):
+    """
+    Convenience builder for sequential note generation
+    using zipped parameter lists.
+
+    Parameters are cycled independently and combined
+    position-wise.
+
+    Notes
+    -----
+    This class is intended for simple use cases.
+    For advanced temporal control, prefer:
+
+    - rhythm_tree
+    - TimeSpan pipelines
+    - Score.add_timespans()
+    """
+
+    # ---- core zipped parameters ----
+    pitch: Sequence[int] = field(default_factory=lambda: [60])
+    velocity: Sequence[int] = field(default_factory=lambda: [100])
+    duration: Sequence[int] = field(default_factory=lambda: [1000])
+    channel: Sequence[int] = field(default_factory=lambda: [0])
+
+    # ---- extensibility ----
+    event_factory: EventFactory[EventT] | None = None
+
+    # --------------------------------
+
+    def _max_len(self) -> int:
+        """
+        Return the maximum length among zipped parameters.
+        """
+        return max(len(getattr(self, f.name)) for f in fields(self) if f.name != "event_factory")
+
+    def iter_events(self, ctx: ScoreContext) -> tuple[list[EventT], ScoreContext]:
+        """
+        Generate events sequentially starting from the given context.
+
+        Parameters
+        ----------
+        ctx : ScoreContext
+            Initial evaluation context.
+
+        Returns
+        -------
+        list of EventT
+            Generated events.
+        ScoreContext
+            Updated context after all events.
+        """
+        if self.event_factory is None:
+            raise ValueError("event_factory must be provided")
+
+        events: list[EventT] = []
+        cur = ctx
+
+        for i in range(self._max_len()):
+            d = self.duration[i % len(self.duration)]
+            span = TimeSpan(start=cur.cursor, duration=d)
+
+            kwargs = {
+                "pitch": self.pitch[i % len(self.pitch)],
+                "velocity": self.velocity[i % len(self.velocity)],
+                "span": span,
+                "channel": self.channel[i % len(self.channel)],
+            }
+
+            ev = self.event_factory(**kwargs)
+            events.append(ev)
+
+            cur = cur.advance(d)
+
+        return events, cur
+
+
+# ============================================================
+# Score
+# ============================================================
+
+
+class Score(Generic[EventT], Iterable[EventT]):
+    """
+    Container and coordinator for time-bounded events.
+
+    Score does not enforce musical semantics.
+    It manages event ordering, temporal queries,
+    and integration of event sources.
+    """
+
+    def __init__(self):
+        self._context: ScoreContext = ScoreContext(cursor=0)
+        self._events: list[EventT] = []
+        self._sorted_by_start: list[EventT] = []
+        self._dirty: bool = False
+
+    def __iter__(self) -> Iterator[EventT]:
+        """
+        Iterate over all events in ascending start-time order.
+        """
+        self._ensure_sorted()
+        return iter(self._sorted_by_start)
+
+    # ---------------- cursor ----------------
+
+    def get_cursor(self) -> int:
+        """
+        Return the current score cursor position.
+        """
+        return self._context.cursor
+
+    def set_cursor(self, cursor: int) -> None:
+        """
+        Set the score cursor to an explicit position.
+
+        This affects subsequent event generation.
+        """
+        self._context = ScoreContext(cursor=cursor)
+
+    # ---------------- add ----------------
+
+    def add(
+        self,
+        source: ScoreInput[EventT] | None = None,
+        *,
+        pitch: Sequence[int] | None = None,
+        velocity: Sequence[int] | None = None,
+        duration: Sequence[int] | None = None,
+        channel: Sequence[int] | None = None,
+        start: int | None = None,
+        event_factory: EventFactory[EventT] | None = None,
+    ) -> None:
+        """
+        Add events to the score using a convenience API.
+
+        This method supports either:
+        - a ScoreInput source, or
+        - zipped parameter lists with an event factory.
+
+        Notes
+        -----
+        This API is intentionally simple.
+        For explicit temporal structure, prefer
+        ``add_timespans()``.
+        """
+        ctx = self._context
+
+        if start is not None:
+            ctx = ScoreContext(cursor=start)
+
+        if source is not None:
+            events, ctx = source.iter_events(ctx)
+            self._events.extend(events)
+            self._context = ctx
+            self._dirty = True
+            return
+
+        if event_factory is None:
+            raise ValueError("event_factory must be provided when using zipped parameters")
+
+        kwargs = {
+            "pitch": pitch,
+            "velocity": velocity,
+            "duration": duration,
+            "channel": channel,
+        }
+
+        source_ = ZippedNotes[EventT](
+            **{k: v for k, v in kwargs.items() if v is not None},  # type: ignore[arg-type]
+            event_factory=event_factory,
+        )
+
+        events, ctx = source_.iter_events(ctx)
+        self._events.extend(events)
+        self._context = ctx
+        self._dirty = True
+
+    def add_timespans(
+        self,
+        spans: Iterable[TimeSpan],
+        *,
+        factory: Callable[[TimeSpan], EventT],
+    ) -> None:
+        """
+        Add events generated from explicit TimeSpans.
+
+        Score does not interpret TimeSpan contents.
+        It only stores the resulting events.
+        """
+        for span in spans:
+            ev = factory(span)
+            self._events.append(ev)
+
+        self._dirty = True
+
+    # ---------------- query ----------------
+
+    def _ensure_sorted(self) -> None:
+        """
+        Ensure events are sorted by start time.
+        """
+        if self._dirty:
+            self._sorted_by_start = sorted(
+                self._events,
+                key=lambda e: e.span.start,
+            )
+            self._dirty = False
+
+    def events_between_span(self, span: TimeSpan) -> list[EventT]:
+        """
+        Return events whose TimeSpan overlaps the given span.
+        """
+        self._ensure_sorted()
+
+        if not self._sorted_by_start:
+            return []
+
+        result: list[EventT] = []
+
+        for e in self._sorted_by_start:
+            if e.span.overlaps(span):
+                result.append(e)
+
+            # optimization: early exit due to ordering
+            if e.span.start >= span.end:
+                break
+
+        return result
+
+    def events_between(
+        self,
+        start: int = 0,
+        end: int | None = None,
+    ) -> list[EventT]:
+        """
+        Return events whose start time lies within the given time window.
+
+        Parameters
+        ----------
+        start : int
+            Inclusive start position on the score time axis.
+        end : int or None
+            Exclusive end position.
+            If None, all events starting at or after ``start`` are returned.
+
+        Returns
+        -------
+        list of EventT
+            Events matching the given time range.
+
+        Notes
+        -----
+        - Time values are interpreted in the same unit used by TimeSpan
+          (typically milliseconds or ticks).
+        - This method filters by event start time, not full TimeSpan overlap.
+          For overlap-based queries, use ``events_between_span()``.
+        - The returned list is ordered by start time.
+        """
+        if end is None:
+            self._ensure_sorted()
+            return [e for e in self._sorted_by_start if e.span.start >= start]
+
+        span = TimeSpan(
+            start=start,
+            duration=end - start,
+        )
+        return self.events_between_span(span)

hyperscore/core/time.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TimeSpan:
+    """
+    Immutable representation of a half-open time interval.
+
+    A TimeSpan represents a duration on a linear time axis,
+    measured in milliseconds (or any consistent time unit).
+
+    Attributes
+    ----------
+    start : int
+        Inclusive start position.
+    duration : int
+        Non-negative duration.
+
+    Notes
+    -----
+    - The interval is half-open: [start, end)
+    - No ordering or global timeline is enforced.
+    - Musical interpretation is handled elsewhere.
+    """
+
+    start: int
+    duration: int
+
+    @property
+    def end(self) -> int:
+        """
+        Return the exclusive end position of the span.
+        """
+        return self.start + self.duration
+
+    def shift(self, delta: int) -> TimeSpan:
+        """
+        Return a new TimeSpan shifted along the time axis.
+
+        Parameters
+        ----------
+        delta : int
+            Time shift in milliseconds.
+            Positive values move the span forward,
+            negative values move it backward.
+        """
+        return TimeSpan(self.start + delta, self.duration)
+
+    def stretch(self, factor: float) -> TimeSpan:
+        """
+        Return a new TimeSpan with scaled duration.
+
+        The start position is preserved.
+
+        Parameters
+        ----------
+        factor : float
+            Duration scaling factor.
+        """
+        return TimeSpan(self.start, round(self.duration * factor))
+
+    def overlaps(self, other: TimeSpan) -> bool:
+        """
+        Return True if this span overlaps with another span.
+        """
+        return not (self.end <= other.start or other.end <= self.start)
+
+    def contains(self, t: int) -> bool:
+        """
+        Return True if the given time point lies within this span.
+        """
+        return self.start <= t < self.end
+
+
+def bpm_to_ms(bpm: float, note_division: float = 1.0) -> float:
+    """
+    Convert a musical duration at a given BPM into milliseconds.
+
+    This function performs a purely arithmetic conversion.
+    It does not assume any time signature or rhythmic structure.
+
+    Parameters
+    ----------
+    bpm : float
+        Tempo in beats per minute.
+    note_division : float, optional
+        Beat multiplier or subdivision.
+        For example:
+        - 1.0 = quarter note
+        - 0.5 = eighth note
+        - 2.0 = half note
+
+    Returns
+    -------
+    float
+        Duration in milliseconds.
+    """
+    return 60_000.0 / bpm * note_division

hyperscore/core/time_pipeline.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+
+from hyperscore.core.time import TimeSpan
+
+TimeSpanTransform = Callable[[TimeSpan], TimeSpan | None]
+
+
+@dataclass(frozen=True)
+class TimeSpanPipeline:
+    """
+    Immutable pipeline for transforming TimeSpan objects.
+
+    A pipeline is a pure, composable sequence of TimeSpan
+    transformations. Each transform may either:
+
+    - return a modified TimeSpan
+    - return ``None`` to drop the span
+
+    Notes
+    -----
+    - The pipeline itself holds no state.
+    - No temporal ordering is enforced.
+    - This class does not generate TimeSpans; it only
+      transforms existing ones.
+
+    Typical use cases include:
+    - quantization
+    - clipping
+    - filtering by duration or position
+    - time-warping in the TimeSpan domain
+    """
+
+    transforms: tuple[TimeSpanTransform, ...] = ()
+
+    # ---------------- core ----------------
+
+    def apply(self, span: TimeSpan) -> TimeSpan | None:
+        """
+        Apply the pipeline to a single TimeSpan.
+
+        Parameters
+        ----------
+        span : TimeSpan
+            Input TimeSpan.
+
+        Returns
+        -------
+        TimeSpan or None
+            Transformed TimeSpan, or None if dropped
+            by any transform.
+        """
+        cur: TimeSpan | None = span
+        for t in self.transforms:
+            if cur is None:
+                return None
+            cur = t(cur)
+        return cur
+
+    def apply_all(self, spans: Iterable[TimeSpan]) -> list[TimeSpan]:
+        """
+        Apply the pipeline to an iterable of TimeSpans.
+
+        TimeSpans dropped by the pipeline are excluded
+        from the result.
+
+        Parameters
+        ----------
+        spans : iterable of TimeSpan
+            Input TimeSpans.
+
+        Returns
+        -------
+        list of TimeSpan
+            Transformed TimeSpans.
+        """
+        out: list[TimeSpan] = []
+        for s in spans:
+            s2 = self.apply(s)
+            if s2 is not None:
+                out.append(s2)
+        return out
+
+    # ---------------- composition ----------------
+
+    def then(self, *more: TimeSpanTransform) -> TimeSpanPipeline:
+        """
+        Return a new pipeline with additional transforms appended.
+
+        This method does not modify the original pipeline.
+
+        Parameters
+        ----------
+        *more : callable
+            Additional TimeSpan transforms.
+
+        Returns
+        -------
+        TimeSpanPipeline
+            A new composed pipeline.
+        """
+        return TimeSpanPipeline(self.transforms + more)
+
+    def __or__(self, other: TimeSpanPipeline) -> TimeSpanPipeline:
+        """
+        Compose two pipelines using the ``|`` operator.
+
+        The resulting pipeline applies this pipeline first,
+        then the other pipeline.
+
+        Returns
+        -------
+        TimeSpanPipeline
+            Composed pipeline.
+        """
+        return TimeSpanPipeline(self.transforms + other.transforms)