xnano_audio

What audio support this build and machine offer.

Returned by detect_audio_capabilities.

Attributes:

• has_device_support (bool) –

  Whether this build was compiled with audio device support.

• is_output_available (bool) –

  Whether a default output device exists.

• is_input_available (bool) –

  Whether a default input device (microphone) exists.

• output_unavailable_reason (str | None) –

  Why output is unavailable, or None when it is available.

• input_unavailable_reason (str | None) –

  Why input is unavailable, or None when it is available.

has_device_support: bool

is_output_available: bool

is_input_available: bool

output_unavailable_reason: str | None

input_unavailable_reason: str | None

An immutable audio effect description.

Build one with a static constructor and pass it, in order, to render_note, TerminalSound.with_effects or TerminalAudioPlayer.play_note. Effects hold no state, so one instance can be reused for any number of sounds.

Every constructor raises ValueError when an argument is out of range.

Attributes:

• name (str) –

  The effect's kind, such as "reverb".

Methods:

• bit_crush –

  Lo-fi: quantize to bits and hold every downsample-th sample.

• distortion –

  Soft-clip (tanh) distortion.

• low_pass –

  Remove frequencies above cutoff.

• high_pass –

  Remove frequencies below cutoff.

• delay –

  Echoes.

• reverb –

  Room reverb (Freeverb-style).

• tremolo –

  Amplitude wobble.

• __or__ –

  Chain this effect with another effect or sequence of effects.

name: str

bit_crush(*, bits: int = 8, downsample: int = 4) -> TerminalAudioEffect

173
174
175
176
177
178
179
180
181

@staticmethod
def bit_crush(*, bits: int = 8, downsample: int = 4) -> TerminalAudioEffect:
    """
    Lo-fi: quantize to ``bits`` and hold every ``downsample``-th sample.

    Args:
        bits: Resolution, 1 to 16. Lower is crunchier.
        downsample: Hold each value for this many samples, 1 to 256.
    """

distortion(*, drive: float = 4.0) -> TerminalAudioEffect

183
184
185
186
187
188
189
190
191

@staticmethod
def distortion(*, drive: float = 4.0) -> TerminalAudioEffect:
    """
    Soft-clip (tanh) distortion.

    Args:
        drive: Input gain before clipping, 0.1 to 100. Around 1 is nearly
            clean; higher is harsher. The output is normalized.
    """

low_pass(*, cutoff: float = 1200.0, resonance: float = 0.707) -> TerminalAudioEffect

193
194
195
196
197
198
199
200
201
202
203

@staticmethod
def low_pass(
    *, cutoff: float = 1200.0, resonance: float = 0.707
) -> TerminalAudioEffect:
    """
    Remove frequencies above ``cutoff``.

    Args:
        cutoff: Corner frequency in hertz, 20 to 20000.
        resonance: Filter Q, 0.1 to 20. The default is flat.
    """

high_pass(*, cutoff: float = 400.0, resonance: float = 0.707) -> TerminalAudioEffect

205
206
207
208
209
210
211
212
213
214
215

@staticmethod
def high_pass(
    *, cutoff: float = 400.0, resonance: float = 0.707
) -> TerminalAudioEffect:
    """
    Remove frequencies below ``cutoff``.

    Args:
        cutoff: Corner frequency in hertz, 20 to 20000.
        resonance: Filter Q, 0.1 to 20. The default is flat.
    """

delay(*, time_milliseconds: float = 250.0, feedback: float = 0.4, mix: float = 0.35) -> TerminalAudioEffect

217
218
219
220
221
222
223
224
225
226
227
228
229
230

@staticmethod
def delay(
    *, time_milliseconds: float = 250.0, feedback: float = 0.4, mix: float = 0.35
) -> TerminalAudioEffect:
    """
    Echoes.

    The result is longer than the input so the echoes ring out.

    Args:
        time_milliseconds: Time between echoes, 1 to 2000.
        feedback: How much of each echo is fed back, 0.0 to 0.95.
        mix: Level of the echoes against the dry sound, 0.0 to 1.0.
    """

reverb(*, room: float = 0.5, damping: float = 0.5, mix: float = 0.25) -> TerminalAudioEffect

232
233
234
235
236
237
238
239
240
241
242
243
244
245

@staticmethod
def reverb(
    *, room: float = 0.5, damping: float = 0.5, mix: float = 0.25
) -> TerminalAudioEffect:
    """
    Room reverb (Freeverb-style).

    The result is longer than the input so the tail rings out.

    Args:
        room: Room size, 0.0 to 1.0. Larger rooms ring longer.
        damping: How quickly high frequencies fade, 0.0 to 1.0.
        mix: Wet level against the dry sound, 0.0 to 1.0.
    """

tremolo(*, rate_hertz: float = 5.0, depth: float = 0.5) -> TerminalAudioEffect

247
248
249
250
251
252
253
254
255

@staticmethod
def tremolo(*, rate_hertz: float = 5.0, depth: float = 0.5) -> TerminalAudioEffect:
    """
    Amplitude wobble.

    Args:
        rate_hertz: Wobbles per second, 0.1 to 40.
        depth: 0.0 (none) to 1.0 (silent at each trough).
    """

__or__(other: AudioEffectSource) -> list[TerminalAudioEffect]

chain = TerminalAudioEffect.low_pass(cutoff=800.0) | TerminalAudioEffect.reverb(room=0.5)
assert [effect.name for effect in chain] == ["low_pass", "reverb"]

269
270
271
272
273
274
275
276
277
278

def __or__(self, other: AudioEffectSource) -> list[TerminalAudioEffect]:
    """
    Chain this effect with another effect or sequence of effects.

    Examples:
        ```python
        chain = TerminalAudioEffect.low_pass(cutoff=800.0) | TerminalAudioEffect.reverb(room=0.5)
        assert [effect.name for effect in chain] == ["low_pass", "reverb"]
        ```
    """

Bases: RuntimeError

Raised when an audio device or stream fails.

Treat this (and a failed import of the package) as "audio is not available": SSH sessions, containers and CI usually have no audio device.

Plays sounds on the default output device, with one musical clock.

Not thread-safe (unsendable): use it from the thread that created it.

Sounds can start immediately or on a clock beat. The clock runs at a tempo in beats per minute (120 by default), and a sound scheduled with at_beat starts sample-accurately when the clock reaches that beat, so sequences do not drift with Python's timing.

Attributes:

• is_clock_running (bool) –

  Whether the clock is currently running.

• tempo (float) –

  The clock tempo in beats per minute.

• beat (float) –

  The clock position in beats, including the fraction of the current beat.

• clock_position_milliseconds (float) –

  The clock position in milliseconds at the current tempo.

Examples:

player = TerminalAudioPlayer()
player.play_note("bell", "C6")  # a "ding", right now
player.start_clock()
for index, note in enumerate(["C4", "E4", "G4"]):
    player.play_note("piano", note, at_beat=int(player.beat) + 1 + index)

Open the default output device.

Parameters:

• beats_per_minute (float, default: 120.0 ) –

  Initial clock tempo, greater than 0 and at most 600000.

Raises:

• TerminalAudioUnavailableError –

  If no output device is available, or this build has no device support.

• ValueError –

  If beats_per_minute is out of range.

Methods:

• is_available –

  Whether an output device exists, without opening it.

• play_note –

  Render a built-in instrument note and play it.

• play_sound –

  Play an already rendered sound, optionally on a clock beat.

• start_clock –

  Start the clock.

• pause_clock –

  Pause the clock, keeping its position.

• stop_clock –

  Stop the clock and reset it to beat zero.

• set_tempo –

  Change the clock tempo.

• close –

  Close owned audio output; repeated calls are safe.

1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226

def __init__(self, *, beats_per_minute: float = 120.0) -> None:
    """
    Open the default output device.

    Args:
        beats_per_minute: Initial clock tempo, greater than 0 and at most
            600000.

    Raises:
        TerminalAudioUnavailableError: If no output device is available, or
            this build has no device support.
        ValueError: If ``beats_per_minute`` is out of range.
    """

is_clock_running: bool

tempo: float

beat: float

clock_position_milliseconds: float

is_available() -> bool

1228
1229
1230

@staticmethod
def is_available() -> bool:
    """Whether an output device exists, without opening it."""

play_note(instrument: InstrumentName, note: NoteName | float | str | None = None, *, duration_milliseconds: int = 500, velocity: float = 0.8, effects: list[TerminalAudioEffect] | None = None, volume: float = 1.0, pan: float = 0.0, at_beat: int | None = None) -> None

1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262

def play_note(
    self,
    instrument: InstrumentName,
    note: NoteName | float | str | None = None,
    *,
    duration_milliseconds: int = 500,
    velocity: float = 0.8,
    effects: list[TerminalAudioEffect] | None = None,
    volume: float = 1.0,
    pan: float = 0.0,
    at_beat: int | None = None,
) -> None:
    """
    Render a built-in instrument note and play it.

    See [`render_note`][xnano_audio.render_note] for ``instrument``,
    ``note``, ``duration_milliseconds``, ``velocity`` and ``effects``.
    Rendering takes a few milliseconds and releases the GIL.

    Args:
        volume: Playback gain, 0.0 to 1.0 (values outside are clamped;
            NaN and infinity raise ``ValueError``).
        pan: Stereo position from -1.0 (left) to 1.0 (right). The centre
            keeps full level; panning only quiets the far side.
        at_beat: If set, start sample-accurately when the clock reaches
            this beat; otherwise start immediately.

    Raises:
        TerminalAudioError: If the mixer cannot accept the sound.
        ValueError: If an argument is out of range (including ``pan``).
    """

play_sound(sound: TerminalSound, *, volume: float = 1.0, pan: float = 0.0, at_beat: int | None = None) -> None

1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289

def play_sound(
    self,
    sound: TerminalSound,
    *,
    volume: float = 1.0,
    pan: float = 0.0,
    at_beat: int | None = None,
) -> None:
    """
    Play an already rendered sound, optionally on a clock beat.

    Render once and play many times to avoid re-rendering.

    Args:
        sound: From [`render_note`][xnano_audio.render_note] or
            [`TerminalSound.with_effects`][xnano_audio.TerminalSound.with_effects].
        volume: Playback gain, as in
            [`play_note`][xnano_audio.TerminalAudioPlayer.play_note].
        pan: Stereo position from -1.0 to 1.0.
        at_beat: As in
            [`play_note`][xnano_audio.TerminalAudioPlayer.play_note].

    Raises:
        TerminalAudioError: If the mixer cannot accept the sound.
        ValueError: If ``pan`` is outside -1.0 to 1.0.
    """

start_clock() -> None

1291
1292
1293
1294
1295
1296
1297
1298

def start_clock(self) -> None:
    """
    Start the clock.

    Clock commands (start, pause, stop, tempo) are applied by the audio
    thread on its next buffer, so [`beat`][xnano_audio.TerminalAudioPlayer.beat]
    can lag a call by a few milliseconds.
    """

pause_clock() -> None

1300
1301

def pause_clock(self) -> None:
    """Pause the clock, keeping its position."""

stop_clock() -> None

1303
1304

def stop_clock(self) -> None:
    """Stop the clock and reset it to beat zero."""

set_tempo(beats_per_minute: float) -> None

1314
1315
1316
1317
1318
1319
1320
1321

def set_tempo(self, beats_per_minute: float) -> None:
    """
    Change the clock tempo.

    Raises:
        ValueError: If ``beats_per_minute`` is not greater than 0 and at
            most 600000.
    """

close() -> None

1336
1337

def close(self) -> None:
    """Close owned audio output; repeated calls are safe."""

Lazy decoded file source; no whole-file TerminalSound allocation is required.

Attributes:

• format (TerminalPCMFormat) –

  The layout of the bytes read returns.

• is_closed (bool) –

  Whether the stream has been closed.

Methods:

• open –

  Open an audio file (WAV, FLAC, Ogg Vorbis, MP3 or MP4/AAC); decoding starts on the first read.

• read –

  Decode up to frames frames; empty bytes mean the end of the file.

• seek –

  Move to frame, counted in frames of this stream's format.

• close –

  Release the file; repeated calls are safe.

format: TerminalPCMFormat

is_closed: bool

open(path: str | PathLike[str], *, format: TerminalPCMFormat | None = None) -> TerminalAudioStream

1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551

@classmethod
def open(
    cls, path: str | PathLike[str], *, format: TerminalPCMFormat | None = None
) -> TerminalAudioStream:
    """
    Open an audio file (WAV, FLAC, Ogg Vorbis, MP3 or MP4/AAC); decoding starts on the first read.

    Args:
        path: The audio file.
        format: The layout to decode into. Defaults to the file's own rate and channels as ``f32le``.

    Raises:
        TerminalAudioError: The file cannot be opened or decoded.
    """

read(frames: int) -> bytes

1561
1562

def read(self, frames: int) -> bytes:
    """Decode up to ``frames`` frames; empty bytes mean the end of the file."""

seek(frame: int) -> None

1564
1565

def seek(self, frame: int) -> None:
    """Move to ``frame``, counted in frames of this stream's ``format``."""

close() -> None

1567
1568

def close(self) -> None:
    """Release the file; repeated calls are safe."""

Bases: TerminalAudioError

Raised when an audio device is missing, or this build has no device support.

The message says which of the two it is and how to fix it.

Notes on a beat timeline with a tempo map and a time signature.

Immutable: every method that changes the melody returns a new one. Notes can start together to form chords. Ask which notes are due between two readings of any clock with scheduled_between, or render the melody to a TerminalSound with render. len(melody) is the number of notes and iterating yields the notes in start order.

Attributes:

• notes (list[TerminalNote]) –

  The notes in start order.

• tempo_map (TerminalTempoMap) –

  The tempo map.

• time_signature (TerminalTimeSignature) –

  The time signature.

• length_beats (float) –

  The end of the last note, or the explicit length when that is longer, in beats.

• duration_seconds (float) –

  The melody's length in seconds.

Examples:

melody = (
    TerminalMelody(tempo_map=TerminalTempoMap(100))
    .appended_note("C4")
    .appended_chord(["E4", "G4"], duration_beats=2)
    .appended_rest(1)
)
sound = melody.render("piano")
due = melody.scheduled_between(0.0, 1.0)

Create a melody.

Parameters:

• notes (list[TerminalNote] | None, default: None ) –

  The notes, in any order.

• tempo_map (TerminalTempoMap | None, default: None ) –

  Defaults to a constant 120 beats per minute.

• time_signature (TerminalTimeSignature | None, default: None ) –

  Defaults to 4/4.

• length_beats (float, default: 0.0 ) –

  A minimum length that adds trailing silence after the last note.

Raises:

• ValueError –

  If there are more than 100000 notes or length_beats is negative.

Methods:

• with_notes –

  Return the melody with notes added.

• with_tempo_map –

  Return the melody with another tempo map.

• with_time_signature –

  Return the melody with another time signature.

• with_length_beats –

  Return the melody lasting at least length_beats, which adds trailing silence.

• appended_note –

  Return the melody with one note appended at its end.

• appended_chord –

  Return the melody with notes that sound together appended at its end.

• appended_rest –

  Return the melody with silence appended at its end.

• transposed –

  Return the melody with every pitch moved by semitones.

• shifted –

  Return the melody moved later by beats, or earlier when negative.

• stretched –

  Return the melody with every start, duration and tempo change multiplied by factor.

• repeated –

  Return the melody played count times in a row.

• followed_by –

  Return the melody followed by other, keeping this melody's tempo map.

• layered_with –

  Return the notes of both melodies played together, keeping this tempo map.

• __add__ –

  Play something after the melody, or raise it by semitones.

• __sub__ –

  Lower every note by semitones.

• __mul__ –

  Play the melody several times in a row.

• __or__ –

  Play two melodies together.

• __rshift__ –

  Start the melody later by beats.

• __lshift__ –

  Start the melody earlier by beats.

• notes_between_beats –

  Return the notes that start in [from_beats, to_beats).

• notes_between_seconds –

  Return the notes that start in [from_seconds, to_seconds) of melody time.

• scheduled_between –

  Return the notes due on an external clock between two readings.

• render –

  Render the melody, or the notes starting inside a window, to a sound.

872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891

def __init__(
    self,
    notes: list[TerminalNote] | None = None,
    *,
    tempo_map: TerminalTempoMap | None = None,
    time_signature: TerminalTimeSignature | None = None,
    length_beats: float = 0.0,
) -> None:
    """
    Create a melody.

    Args:
        notes: The notes, in any order.
        tempo_map: Defaults to a constant 120 beats per minute.
        time_signature: Defaults to 4/4.
        length_beats: A minimum length that adds trailing silence after the last note.

    Raises:
        ValueError: If there are more than 100000 notes or ``length_beats`` is negative.
    """

notes: list[TerminalNote]

tempo_map: TerminalTempoMap

time_signature: TerminalTimeSignature

length_beats: float

duration_seconds: float

with_notes(notes: list[TerminalNote]) -> TerminalMelody

913
914

def with_notes(self, notes: list[TerminalNote]) -> TerminalMelody:
    """Return the melody with ``notes`` added."""

with_tempo_map(tempo_map: TerminalTempoMap) -> TerminalMelody

916
917

def with_tempo_map(self, tempo_map: TerminalTempoMap) -> TerminalMelody:
    """Return the melody with another tempo map."""

with_time_signature(time_signature: TerminalTimeSignature) -> TerminalMelody

919
920
921
922

def with_time_signature(
    self, time_signature: TerminalTimeSignature
) -> TerminalMelody:
    """Return the melody with another time signature."""

with_length_beats(length_beats: float) -> TerminalMelody

924
925

def with_length_beats(self, length_beats: float) -> TerminalMelody:
    """Return the melody lasting at least ``length_beats``, which adds trailing silence."""

appended_note(pitch: Pitch, *, duration_beats: float = 1.0, velocity: float = 0.8) -> TerminalMelody

927
928
929
930

def appended_note(
    self, pitch: Pitch, *, duration_beats: float = 1.0, velocity: float = 0.8
) -> TerminalMelody:
    """Return the melody with one note appended at its end."""

appended_chord(pitches: Sequence[Pitch], *, duration_beats: float = 1.0, velocity: float = 0.8) -> TerminalMelody

932
933
934
935
936
937
938
939

def appended_chord(
    self,
    pitches: Sequence[Pitch],
    *,
    duration_beats: float = 1.0,
    velocity: float = 0.8,
) -> TerminalMelody:
    """Return the melody with notes that sound together appended at its end."""

appended_rest(duration_beats: float = 1.0) -> TerminalMelody

941
942

def appended_rest(self, duration_beats: float = 1.0) -> TerminalMelody:
    """Return the melody with silence appended at its end."""

transposed(semitones: int) -> TerminalMelody

944
945
946
947
948
949
950

def transposed(self, semitones: int) -> TerminalMelody:
    """
    Return the melody with every pitch moved by ``semitones``.

    Raises:
        ValueError: If a pitch would leave the MIDI range 0 to 127.
    """

shifted(beats: float) -> TerminalMelody

952
953
954
955
956
957
958

def shifted(self, beats: float) -> TerminalMelody:
    """
    Return the melody moved later by ``beats``, or earlier when negative.

    Raises:
        ValueError: If a note would start before beat zero.
    """

stretched(factor: float) -> TerminalMelody

960
961
962
963
964
965

def stretched(self, factor: float) -> TerminalMelody:
    """
    Return the melody with every start, duration and tempo change multiplied by ``factor``.

    The tempo values are unchanged, so 2.0 makes the melody twice as long in time.
    """

repeated(count: int) -> TerminalMelody

967
968
969
970
971
972
973

def repeated(self, count: int) -> TerminalMelody:
    """
    Return the melody played ``count`` times in a row.

    Raises:
        ValueError: If ``count`` is zero or the result would hold too many notes.
    """

followed_by(other: TerminalMelody) -> TerminalMelody

975
976

def followed_by(self, other: TerminalMelody) -> TerminalMelody:
    """Return the melody followed by ``other``, keeping this melody's tempo map."""

layered_with(other: TerminalMelody) -> TerminalMelody

978
979

def layered_with(self, other: TerminalMelody) -> TerminalMelody:
    """Return the notes of both melodies played together, keeping this tempo map."""

__add__(other: int) -> TerminalMelody

__add__(other: TerminalMelody | TerminalNote) -> TerminalMelody

__add__(other: int | TerminalMelody | TerminalNote) -> TerminalMelody

phrase = TerminalNote("C4") + TerminalNote("E4")
assert len((phrase + TerminalNote("G4")).notes) == 3
assert [note.name for note in phrase + 2] == ["D4", "F#4"]

985
986
987
988
989
990
991
992
993
994
995

def __add__(self, other: int | TerminalMelody | TerminalNote) -> TerminalMelody:
    """
    Play something after the melody, or raise it by semitones.

    Examples:
        ```python
        phrase = TerminalNote("C4") + TerminalNote("E4")
        assert len((phrase + TerminalNote("G4")).notes) == 3
        assert [note.name for note in phrase + 2] == ["D4", "F#4"]
        ```
    """

__sub__(other: int) -> TerminalMelody

 999
1000

def __sub__(self, other: int) -> TerminalMelody:
    """Lower every note by semitones."""

__mul__(other: int) -> TerminalMelody

phrase = TerminalNote("C4") + TerminalNote("E4")
assert len((phrase * 3).notes) == 6

1002
1003
1004
1005
1006
1007
1008
1009
1010
1011

def __mul__(self, other: int) -> TerminalMelody:
    """
    Play the melody several times in a row.

    Examples:
        ```python
        phrase = TerminalNote("C4") + TerminalNote("E4")
        assert len((phrase * 3).notes) == 6
        ```
    """

__or__(other: TerminalMelody | TerminalNote) -> TerminalMelody

1015
1016

def __or__(self, other: TerminalMelody | TerminalNote) -> TerminalMelody:
    """Play two melodies together."""

__rshift__(other: float) -> TerminalMelody

phrase = TerminalNote("C4") + TerminalNote("E4")
assert [note.start_beats for note in phrase >> 2] == [2.0, 3.0]

1018
1019
1020
1021
1022
1023
1024
1025
1026
1027

def __rshift__(self, other: float) -> TerminalMelody:
    """
    Start the melody later by beats.

    Examples:
        ```python
        phrase = TerminalNote("C4") + TerminalNote("E4")
        assert [note.start_beats for note in phrase >> 2] == [2.0, 3.0]
        ```
    """

__lshift__(other: float) -> TerminalMelody

1029
1030

def __lshift__(self, other: float) -> TerminalMelody:
    """Start the melody earlier by beats."""

notes_between_beats(from_beats: float, to_beats: float) -> list[TerminalNote]

1032
1033
1034
1035

def notes_between_beats(
    self, from_beats: float, to_beats: float
) -> list[TerminalNote]:
    """Return the notes that start in ``[from_beats, to_beats)``."""

notes_between_seconds(from_seconds: float, to_seconds: float) -> list[TerminalNote]

1037
1038
1039
1040

def notes_between_seconds(
    self, from_seconds: float, to_seconds: float
) -> list[TerminalNote]:
    """Return the notes that start in ``[from_seconds, to_seconds)`` of melody time."""

scheduled_between(from_elapsed_seconds: float, to_elapsed_seconds: float, *, start_seconds: float = 0.0, should_loop: bool = False) -> list[TerminalScheduledNote]

1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067

def scheduled_between(
    self,
    from_elapsed_seconds: float,
    to_elapsed_seconds: float,
    *,
    start_seconds: float = 0.0,
    should_loop: bool = False,
) -> list[TerminalScheduledNote]:
    """
    Return the notes due on an external clock between two readings.

    The melody begins when the clock reads ``start_seconds``. Notes that start in
    ``[from_elapsed_seconds, to_elapsed_seconds)`` are returned with their times on
    that same clock, so consecutive windows never repeat or skip a note. Call it every
    frame with the previous and current reading of a manual or monotonic clock.

    Args:
        from_elapsed_seconds: The previous clock reading (inclusive).
        to_elapsed_seconds: The current clock reading (exclusive).
        start_seconds: The clock reading at which the melody begins.
        should_loop: Restart the melody every time it reaches its length.

    Raises:
        ValueError: If a reading is not finite or ``to_elapsed_seconds`` is earlier than
            ``from_elapsed_seconds``.
    """

render(instrument: InstrumentName = 'piano', *, sample_rate: int = 44100, effects: list[TerminalAudioEffect] | None = None, from_seconds: float = 0.0, to_seconds: float | None = None) -> TerminalSound