xnano.music

def note(
    pitch: Pitch | Sequence[Pitch],
    *,
    beats: float = 1.0,
    instrument: InstrumentName = 'piano',
    velocity: float = 0.8,
    effects: Sequence[PlayableEffectSpecification] = (),
    symbol: str | None = None,
) -> Note:
    """
    Make a [`Note`][xnano.Note]: a pitch, or several for a chord, with its length and sound.

    Nothing is played and no sound device is needed. Play it with [`play`][xnano.play] or
    [`Canvas.play`][xnano.canvas.Canvas.play]. ``symbol='kick'`` registers the note, and then
    ``play('kick')`` plays it.

    Args:
        pitch: A note name such as ``'C#4'``, a MIDI number from 0 to 127, or a sequence of
            them for a chord.
        beats: How long the note is held, in beats.
        instrument: A built-in instrument, from
            [`instrument_names`][xnano_audio.instrument_names].
        velocity: How hard the note is played, from 0.0 to 1.0.
        effects: Sound effects as dictionaries with a ``kind`` key, such as
            ``{'kind': 'audio.reverb'}``.
        symbol: A name to register the note under in [`symbols`][xnano.symbols]. A ``str``
            given to [`play`][xnano.play] is looked up as a symbol name before it is read as a
            note name, so the name must not look like a note.

    Raises:
        TypeError: The pitch is not a note name or a number.
        ValueError: A value is out of range or the instrument is unknown.

    Examples:
        ```python
        import xnano

        kick = xnano.note('C2', instrument='kick', symbol='kick_drum')
        with xnano.new(width=8, height=1) as canvas:
            canvas.play('kick_drum')
            canvas.step(delta_seconds=0.5)
            assert canvas.audio.render_sound().peak > 0.0
        ```
    """
    chord = (
        tuple(pitch)
        if isinstance(pitch, Sequence) and not isinstance(pitch, str)
        else pitch
    )
    return Note(
        chord,  # type: ignore[arg-type]
        beats=beats,
        instrument=instrument,
        velocity=velocity,
        effects=effect_sequence(effects, 'playable'),  # type: ignore[arg-type]
        symbol=symbol,
    )

def play(playable: PlaySource, /, **options: Unpack[PlayOptions]) -> PlayHandle:
    """
    Play a note, a sound, a symbol name, a melody or a sequence of those.

    The sound goes to the running canvas (see [`active`][xnano.active]); with no canvas
    running it goes to this computer's sound output. On a canvas from [`new`][xnano.new],
    which has a clock you move, the sound is recorded and makes no noise: read it with
    ``canvas.audio.render_sound()``.

    A ``str`` is a symbol name first, so ``play('kick')`` plays the note or sound registered
    with ``symbol='kick'``. Any other ``str`` is a note name such as ``'C#4'``, a frequency such
    as ``'440hz'`` or melody text: notes separated by spaces, ``:2`` holds a note for two
    beats, ``rest`` is a silence, ``+`` joins a chord and ``|`` marks a bar, as in
    ``'C4 E4 G4:2 rest C5+E5+G5'``. A sequence plays one after another. An option replaces
    the same value on a [`Note`][xnano.Note], so ``play(note('C4'), instrument='violin')``
    plays the violin.

    Args:
        playable: What to play.
        **options: See [`PlayOptions`][xnano.types.PlayOptions]: ``instrument``, ``velocity``,
            ``effects``, ``volume``, ``pan``, ``at_beat`` and ``beats``, the length in beats
            of a note name, a number or a ``Note``.

    Returns:
        A [`PlayHandle`][xnano.music.PlayHandle].

    Raises:
        ImportError: ``xnano-audio`` is not installed. Install it with
            ``pip install "xnano[audio]"``.
        TerminalAudioUnavailableError: No canvas is running and this computer has no sound
            output device.
        ValueError: An option is out of range, or a ``str`` is neither a symbol, a note name
            nor melody text. The message lists the known sound symbols.

    Examples:
        ```python
        import xnano

        with xnano.new(width=8, height=1) as canvas:
            xnano.play([xnano.note('C4'), xnano.note('E4'), xnano.note('G4')])
            canvas.step(delta_seconds=1.5)
            assert canvas.audio.render_sound().peak > 0.0
        ```
    """
    from xnano.canvas import active

    canvas = active(is_required=False)
    if canvas is not None:
        return canvas.play(playable, **options)
    return _default_player().play(playable, **options)