Score (NRT)¶

Non-real-time rendering. A Score is a timestamped OSC bundle sequence handed to the offline engine, producing an audio file without a live audio device.

nanosynth.score ¶

Non-real-time (NRT) score rendering for offline audio synthesis.

Score ¶

A sequence of timestamped OSC bundles for offline (NRT) rendering.

Build a score by adding OSC messages at specific timestamps, then call render() to produce an audio file without real-time audio hardware.

Example::

from nanosynth import Score, SynthDefBuilder, SinOsc, Out

with SynthDefBuilder(freq=440.0) as b:
    Out.ar(bus=0, source=SinOsc.ar(frequency=b["freq"]) * 0.3)
sd = b.build(name="sine")

score = Score()
score.add_synthdef(0.0, sd)
node = score.add_synth(0.0, "sine", node_id=None, freq=440.0)
score.add(1.0, OscMessage("/n_free", node))
score.render("output.wav", sample_rate=44100)

from_pattern `classmethod` ¶

from_pattern(
    pattern: Iterable[Event],
    duration: float,
    *,
    bpm: float = 120.0,
    synthdefs: Iterable[SynthDef] = (),
) -> Score

Schedule an event pattern into a new score.

Uses the same event-to-command logic as realtime :class:Player playback (chords, gate release after sustain, Pmono). Events starting at or after duration are dropped; held Pmono synths are released at the end of the stream or at duration, whichever is earlier.

Args: pattern: Event pattern, e.g. a Pbind. May be infinite. duration: Cut-off for event onsets, in seconds. bpm: Tempo used to convert beats to seconds. synthdefs: SynthDefs to load at time 0, ahead of every event.

add ¶

add(
    time: float, messages: list[OscMessage] | OscMessage
) -> None

Add OSC message(s) at the given time (seconds).

add_synthdef ¶

add_synthdef(time: float, synthdef: SynthDef) -> None

Add a /d_recv command for a SynthDef at the given time.

next_node_id ¶

next_node_id() -> int

Return a node ID not yet used in this score (counting from 1000).

add_synth ¶

add_synth(
    time: float,
    name: str,
    node_id: int | None = -1,
    add_action: AddAction | int = AddAction.ADD_TO_HEAD,
    target: int = 0,
    *,
    controls: Controls = None,
    **params: float,
) -> int

Add a /s_new command at the given time. Returns the node ID.

Args: time: Onset in seconds. name: SynthDef name. node_id: Explicit node ID; -1 (default) for an engine-assigned one that cannot be addressed later; None to allocate an addressable one from this score. add_action: Add action (AddAction enum or int 0-4). target: Target node for placement (NRT has only root group 0). controls: Values for any control name, including ones that collide with this method's parameters (time, target, ...). **params: Initial synth parameter values.

add_set ¶

add_set(
    time: float,
    node_id: int,
    *,
    controls: Controls = None,
    **params: float,
) -> None

Add a /n_set command at the given time.

controls takes any control name, including time and node_id.

sort ¶

sort() -> None

Sort entries by time (in-place, stable).

duration ¶

duration() -> float

Return the timestamp of the last entry, or 0.0 if empty.

to_binary ¶

to_binary() -> bytes

Serialize to SC's binary command file format.

Format: repeated [int32 packet_size][OSC bundle datagram]. The bundle timestamp is the raw time in seconds (no NTP epoch).

A non-empty score ends with a guard bundle (/g_freeAll 0 then /c_set 0 0) shortly after the last event. Freeing all nodes before engine shutdown prevents crashes from delay UGens whose buffers are released during World cleanup while synths still reference them.

render ¶

render(
    output_path: str | Path,
    *,
    sample_rate: int = 44100,
    header_format: str = "WAV",
    sample_format: str = "int16",
    input_path: str | Path | None = None,
    output_channels: int = 2,
    input_channels: int = 0,
    options: Options | None = None,
) -> None

Render this score to an audio file (non-real-time).

Writes to_binary() to a temp file, then invokes the embedded scsynth NRT renderer.

Args: output_path: Path for the output audio file. sample_rate: Output sample rate in Hz. header_format: Audio file format ("WAV" or "AIFF"). sample_format: Sample encoding ("int16", "int24", "float"). input_path: Optional input audio file for NRT processing. output_channels: Number of output channels. input_channels: Number of input channels. options: Optional Options for engine configuration overrides.