xnano.audio

A sound you can play with Canvas.play or AudioDevice.play.

Make one from the path of a WAV file, the bytes of one, or a TerminalSound.

Attributes:

• sound (TerminalSound) –

  The rendered sound.

• symbol (str | None) –

  The name the sound is registered under in symbols, or None. play('kick') plays the sound registered as 'kick'.

Examples:

import xnano
from xnano_audio import TerminalSound

audio = xnano.Audio(TerminalSound.from_samples([0.0, 0.5, -0.5, 0.0]))
assert audio.sound.sample_rate == 44100

Load a sound.

Parameters:

• source (TerminalSound | PathLike[str] | str | bytes) –

  The path of a WAV file, the bytes of one, or a sound.

• symbol (str | None, default: None ) –

  A name to register the sound under in symbols, so play(name) plays it.

Raises:

• ImportError –

  xnano-audio is not installed. Install it with pip install "xnano[audio]".

• TypeError –

  source is not a path, bytes or a sound.

• FileNotFoundError –

  source is a path to a file that does not exist.

• ValueError –

  The file is not a PCM WAV file that xnano can read, or symbol cannot be a symbol name, or another kind of value already has it.

574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617

def __init__(
    self,
    source: TerminalSound | os.PathLike[str] | str | bytes,
    *,
    symbol: str | None = None,
) -> None:
    """
    Load a sound.

    Args:
        source: The path of a WAV file, the bytes of one, or a sound.
        symbol: A name to register the sound under in [`symbols`][xnano.symbols], so
            ``play(name)`` plays it.

    Raises:
        ImportError: ``xnano-audio`` is not installed. Install it with
            ``pip install "xnano[audio]"``.
        TypeError: ``source`` is not a path, bytes or a sound.
        FileNotFoundError: ``source`` is a path to a file that does not exist.
        ValueError: The file is not a PCM WAV file that xnano can read, or ``symbol`` cannot
            be a symbol name, or another kind of value already has it.
    """
    module = require('audio', needed_for='xnano.Audio')
    if isinstance(source, module.TerminalSound):
        sound = source
    elif isinstance(source, bytes):
        sound = _decode_wave(module, source)
    elif isinstance(source, (str, os.PathLike)):
        path = pathlib.Path(source)
        if not path.is_file():
            raise FileNotFoundError(
                f'Audio could not load {str(path)!r}, because no WAV file exists '
                f'there. Check the path, or pass the bytes of the sound.'
            )
        sound = _decode_wave(module, path.read_bytes())
    else:
        raise TypeError(
            f'Audio needs the path of a WAV file, the bytes of one or a sound, but got '
            f'{type(source).__name__}. Pass Audio("sound.wav").'
        )
    object.__setattr__(self, 'sound', sound)
    object.__setattr__(self, 'symbol', symbol)
    if symbol is not None:
        symbols.register(symbol, self)

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.

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

1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095

def render(
    self,
    instrument: InstrumentName = 'piano',
    *,
    sample_rate: int = 44100,
    effects: list[TerminalAudioEffect] | None = None,
    from_seconds: float = 0.0,
    to_seconds: float | None = None,
) -> TerminalSound:
    """
    Render the melody, or the notes starting inside a window, to a sound.

    Notes are placed sample-accurately from the tempo map and mixed; the result is
    limited to stay below clipping. The first sample is the instant ``from_seconds``.
    Notes ring past the window with their natural tail.

    Args:
        instrument: One of [`instrument_names`][xnano_audio.instrument_names].
        sample_rate: Output rate in hertz, 8000 to 192000.
        effects: Effects applied in order to the mixed result (at most 32).
        from_seconds: Melody time of the first sample.
        to_seconds: Melody time at which the window ends; defaults to the melody's end.

    Raises:
        ValueError: If the instrument is unknown, an argument is out of range or the
            window is longer than 600 seconds.
    """

One note on a beat timeline.

Immutable. Pitches are MIDI numbers (60 is middle C); a name such as "C#4" is accepted wherever a pitch is. Times are measured in quarter-note beats from the start of the melody. Every with_* method returns a new note.

Attributes:

• pitch (int) –

  The MIDI pitch, 0 to 127.

• name (NoteName) –

  The sharp-spelled note name, such as "C#4".

• frequency_hertz (float) –

  The pitch in hertz.

• velocity (float) –

  The strength, 0.0 to 1.0.

• start_beats (float) –

  Where the note starts, in beats.

• duration_beats (float) –

  How long the key is held, in beats.

• end_beats (float) –

  Where the note ends, in beats.

Examples:

note = TerminalNote("C4", start_beats=1.0, duration_beats=0.5)
assert note.pitch == 60 and note.end_beats == 1.5

Create a note.

Parameters:

• pitch (Pitch) –

  A NoteName such as "C4" or "Db5", or a MIDI number from 0 to 127. Lower case and a missing octave ("c#" is "C#4") are accepted too.

• start_beats (float, default: 0.0 ) –

  Where the note starts, zero or more.

• duration_beats (float, default: 1.0 ) –

  How long the key is held, greater than zero.

• velocity (float, default: 0.8 ) –

  Strength from 0.0 to 1.0.

Raises:

• ValueError –

  If an argument is out of range or the pitch name is not recognized.

• TypeError –

  If pitch is not an int or str.

Methods:

• with_pitch –

  Return the note with another pitch.

• with_start_beats –

  Return the note starting at another beat.

• with_duration_beats –

  Return the note held for another number of beats.

• with_velocity –

  Return the note with another strength.

• transposed –

  Return the note moved by semitones.

• __add__ –

  Move the note up by semitones, or play something after it.

• __sub__ –

  Move the note down by semitones, or measure the distance to another note.

• __or__ –

  Play notes together, as a chord.

• __int__ –

  The MIDI pitch, so int(TerminalNote("C4")) is 60.

• __lt__ –

  Notes are ordered by pitch, then by where they start.

509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531

def __init__(
    self,
    pitch: Pitch,
    *,
    start_beats: float = 0.0,
    duration_beats: float = 1.0,
    velocity: float = 0.8,
) -> None:
    """
    Create a note.

    Args:
        pitch: A [`NoteName`][xnano_audio.NoteName] such as ``"C4"`` or ``"Db5"``, or a
            MIDI number from 0 to 127. Lower case and a missing octave (``"c#"`` is
            ``"C#4"``) are accepted too.
        start_beats: Where the note starts, zero or more.
        duration_beats: How long the key is held, greater than zero.
        velocity: Strength from 0.0 to 1.0.

    Raises:
        ValueError: If an argument is out of range or the pitch name is not recognized.
        TypeError: If ``pitch`` is not an ``int`` or ``str``.
    """

pitch: int

name: NoteName

frequency_hertz: float

velocity: float

start_beats: float

duration_beats: float

end_beats: float

with_pitch(pitch: Pitch) -> TerminalNote

561
562

def with_pitch(self, pitch: Pitch) -> TerminalNote:
    """Return the note with another pitch."""

with_start_beats(start_beats: float) -> TerminalNote

564
565

def with_start_beats(self, start_beats: float) -> TerminalNote:
    """Return the note starting at another beat."""

with_duration_beats(duration_beats: float) -> TerminalNote

567
568

def with_duration_beats(self, duration_beats: float) -> TerminalNote:
    """Return the note held for another number of beats."""

with_velocity(velocity: float) -> TerminalNote

570
571

def with_velocity(self, velocity: float) -> TerminalNote:
    """Return the note with another strength."""

transposed(semitones: int) -> TerminalNote

573
574
575
576
577
578
579

def transposed(self, semitones: int) -> TerminalNote:
    """
    Return the note moved by ``semitones``.

    Raises:
        ValueError: If the result leaves the MIDI range 0 to 127.
    """

__add__(other: int) -> TerminalNote

__add__(other: TerminalNote | TerminalMelody) -> TerminalMelody

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