adafruit-circuitpython-ay8912 1.0.0__py3-none-any.whl

adafruit_ay8912/ay8912_emulator.py

@@ -0,0 +1,459 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Liz Clark for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+:py:class:`~adafruit_ay8912.ay8912_emulator.AY8912`
+================================================================================
+
+AY-3-8910 / AY-8912 emulator for CircuitPython with :py:mod:`synthio`.
+
+Translates AY-3-8910 register writes into ``synthio.Note`` property updates. Three
+synthesizers (one per channel) feed an :py:class:`audiomixer.Mixer` for
+per-channel volume and stereo panning.
+
+* Author(s): Liz Clark
+
+Implementation Notes
+--------------------
+
+**Software and Dependencies:**
+
+* Adafruit CircuitPython firmware for the supported boards:
+  https://circuitpython.org/downloads
+"""
+
+import array
+from random import randint
+
+import audiomixer
+import synthio
+import ulab.numpy as np
+
+try:
+    from typing import Tuple
+except ImportError:
+    pass
+
+__version__ = "1.0.0"
+__repo__ = "https://github.com/your-org/Adafruit_CircuitPython_AY8912_Emulator.git"
+
+
+class AY8912:
+    """AY-3-8910 / AY-8912 emulator backed by :py:mod:`synthio`.
+
+    :param int sample_rate: Output sample rate in Hz.
+    :param int clock_rate: AY chip clock frequency in Hz. Defaults to the ZX
+        Spectrum 128K clock (1773400 Hz).
+    :param int waveform_size: Number of samples in the square waveform.
+    :param int noise_size: Number of samples in the noise waveform.
+    :param int volume: Peak sample amplitude used when building the waveforms.
+    """
+
+    # AY DAC volume table -- 16 levels
+    DAC = (
+        0.0,
+        0.00999,
+        0.01445,
+        0.02106,
+        0.03070,
+        0.04555,
+        0.06450,
+        0.10736,
+        0.12659,
+        0.20499,
+        0.29221,
+        0.37284,
+        0.49253,
+        0.63532,
+        0.80558,
+        1.0,
+    )
+
+    # Envelope segment functions per shape: (segment0, segment1)
+    # 0=decay (start high), 1=attack (start low), 2=hold, 3=hold-alt
+    _ENV_SEG = (
+        (0, 2),
+        (0, 2),
+        (0, 2),
+        (0, 2),  # shapes 0-3:   \___
+        (1, 2),
+        (1, 2),
+        (1, 2),
+        (1, 2),  # shapes 4-7:   /|__
+        (0, 0),
+        (0, 2),
+        (0, 1),
+        (0, 3),  # shapes 8-11:  \\\\  \___  \/\/  \^^^
+        (1, 1),
+        (1, 3),
+        (1, 0),
+        (1, 2),  # shapes 12-15: ////  /^^^  /\/\  /|__
+    )
+
+    def __init__(
+        self,
+        sample_rate: int = 22050,
+        clock_rate: int = 1773400,
+        waveform_size: int = 256,
+        noise_size: int = 256,
+        volume: int = 32000,
+    ) -> None:
+        self._clock = clock_rate
+        self._sample_rate = sample_rate
+
+        self._regs = bytearray(16)
+
+        self._square = array.array(
+            "h",
+            [volume] * (waveform_size // 2) + [-volume] * (waveform_size // 2),
+        )
+        self._noise = np.array(
+            [randint(-volume, volume) for _ in range(noise_size)],
+            dtype=np.int16,
+        )
+
+        self._synths = []
+        self._notes = []
+        for _ in range(3):
+            s = synthio.Synthesizer(sample_rate=sample_rate, channel_count=2)
+            n = synthio.Note(
+                frequency=440.0,
+                waveform=self._square,
+                amplitude=1.0,
+            )
+            s.press(n)
+            self._synths.append(s)
+            self._notes.append(n)
+
+        self._mixer = audiomixer.Mixer(
+            voice_count=3,
+            sample_rate=sample_rate,
+            channel_count=2,
+            buffer_size=2048,
+        )
+
+        self._started = False
+
+        self._tone_on = [False, False, False]
+        self._noise_on = [False, False, False]
+        self._env_enabled = [False, False, False]
+
+        self._env_shape = 0
+        self._env_period = 1
+        self._env_level = 0  # 0..31
+        self._env_segment = 0  # 0 or 1
+        self._env_accumulator = 0.0
+        self._env_steps_per_tick = 0.0
+        self._compute_env_rate()
+
+    @property
+    def mixer(self) -> "audiomixer.Mixer":
+        """The :py:class:`audiomixer.Mixer`. Connect to audio output
+        with ``audio.play(ay.mixer)`` (or just call :meth:`begin`)."""
+        return self._mixer
+
+    def begin(self, audio_out) -> None:
+        """Begin audio signal chain.
+
+        Handles ``audio_out.play(mixer)`` first, then connects the synth voices::
+
+            ay = AY8912(sample_rate=22050)
+            ay.begin(audio)
+
+        :param audio_out: The audio output object
+        """
+        audio_out.play(self._mixer)
+
+        for i in range(3):
+            self._mixer.voice[i].play(self._synths[i], loop=True)
+            self._mixer.voice[i].level = 0.0
+
+        # Default ACB stereo panning
+        self._mixer.voice[0].panning = -0.4  # A -> left
+        self._mixer.voice[1].panning = 0.0  # B -> center
+        self._mixer.voice[2].panning = 0.4  # C -> right
+
+        self._started = True
+
+    @property
+    def notes(self) -> "Tuple[synthio.Note, ...]":
+        """Direct access to the three ``synthio.Note`` objects (read-only
+        tuple)."""
+        return tuple(self._notes)
+
+    def read_register(self, reg: int) -> int:
+        """Read an AY register.
+
+        :param int reg: Register index (0-15).
+        :return: The stored register value, or 0 if ``reg`` is out of range.
+        """
+        if reg > 15:
+            return 0
+        return self._regs[reg]
+
+    def write_register(self, reg: int, value: int) -> None:
+        """Write an AY register (0-13). R14/R15 (I/O ports) are stored but
+        otherwise ignored.
+
+        :param int reg: Register index (0-15). Out-of-range writes are ignored.
+        :param int value: Byte value to write (masked to 0-255).
+        """
+        if reg > 15:
+            return
+        value &= 0xFF
+        self._regs[reg] = value
+        self._apply_reg(reg)
+
+    def set_pan(self, channel: int, pan: float) -> None:
+        """Stereo panning for a channel.
+
+        :param int channel: Channel index (0-2).
+        :param float pan: Pan position: ``-1.0`` = hard left, ``0.0`` = center,
+            ``1.0`` = hard right. Values are clamped to that range.
+        """
+        if 0 <= channel <= 2:
+            self._mixer.voice[channel].panning = max(-1.0, min(1.0, pan))
+
+    def set_tone_period(self, channel: int, period: int) -> None:
+        """The 12-bit tone period directly (R0/R1, R2/R3, R4/R5).
+
+        :param int channel: Channel index (0-2).
+        :param int period: Tone period, clamped to 1-4095.
+        """
+        if channel > 2:
+            return
+        period = max(1, min(4095, period))
+        r = channel * 2
+        self.write_register(r, period & 0xFF)
+        self.write_register(r + 1, (period >> 8) & 0x0F)
+
+    def set_noise_period(self, period: int) -> None:
+        """The 5-bit noise period (R6).
+
+        :param int period: Noise period (only the low 5 bits are used).
+        """
+        self.write_register(6, period & 0x1F)
+
+    def set_volume(self, channel: int, volume: int, envelope: bool = False) -> None:
+        """Set a channel's volume (R8/R9/R10).
+
+        :param int channel: Channel index (0-2).
+        :param int volume: Fixed volume level (0-15).
+        :param bool envelope: If ``True``, the hardware envelope controls the
+            channel volume instead of the fixed level.
+        """
+        if channel > 2:
+            return
+        val = min(15, volume) & 0x0F
+        if envelope:
+            val |= 0x10
+        self.write_register(8 + channel, val)
+
+    def enable_tone(self, channel: int, enable: bool = True) -> None:
+        """Enable or disable tone output for a channel via the mixer (R7).
+
+        :param int channel: Channel index (0-2).
+        :param bool enable: ``True`` to enable tone, ``False`` to disable.
+        """
+        if channel > 2:
+            return
+        bit = 1 << channel
+        mixer = self._regs[7]
+        if enable:
+            mixer &= ~bit  # bit=0 means ON in the AY mixer
+        else:
+            mixer |= bit
+        self.write_register(7, mixer)
+
+    def enable_noise(self, channel: int, enable: bool = True) -> None:
+        """Enable or disable noise output for a channel via the mixer (R7).
+
+        :param int channel: Channel index (0-2).
+        :param bool enable: ``True`` to enable noise, ``False`` to disable.
+        """
+        if channel > 2:
+            return
+        bit = 1 << (channel + 3)
+        mixer = self._regs[7]
+        if enable:
+            mixer &= ~bit
+        else:
+            mixer |= bit
+        self.write_register(7, mixer)
+
+    def set_envelope(self, period: int, shape: int) -> None:
+        """Set the envelope period (R11/R12) and shape (R13).
+
+        Writing R13 resets the envelope generator.
+
+        :param int period: 16-bit envelope period.
+        :param int shape: Envelope shape (0-15).
+        """
+        self.write_register(11, period & 0xFF)
+        self.write_register(12, (period >> 8) & 0xFF)
+        self.write_register(13, shape & 0x0F)
+
+    def reset(self) -> None:
+        """Reset all registers and state to power-on defaults."""
+        self._regs = bytearray(16)
+        self._env_level = 0
+        self._env_segment = 0
+        self._env_shape = 0
+        self._env_period = 1
+        self._env_accumulator = 0.0
+        self._compute_env_rate()
+
+        for ch in range(3):
+            self._notes[ch].frequency = 440.0
+            self._notes[ch].amplitude = 1.0
+            self._notes[ch].waveform = self._square
+            self._notes[ch].ring_waveform = None
+            self._mixer.voice[ch].level = 0.0
+            self._tone_on[ch] = False
+            self._noise_on[ch] = False
+            self._env_enabled[ch] = False
+
+    def tick(self) -> None:
+        """Advance the envelope generator.
+
+        Call this at ~50 Hz from your main loop or a timer interrupt.
+        """
+        self._env_accumulator += self._env_steps_per_tick
+        while self._env_accumulator >= 1.0:
+            self._env_accumulator -= 1.0
+            self._step_envelope()
+
+        for ch in range(3):
+            if self._env_enabled[ch]:
+                self._apply_volume(ch)
+
+    def _apply_reg(self, reg: int) -> None:
+        """React to a register write."""
+        if reg <= 5:
+            # Tone period (R0/R1 -> ch0, R2/R3 -> ch1, R4/R5 -> ch2)
+            ch = reg // 2
+            self._update_channel_freq(ch)
+
+        elif reg == 6:
+            # Noise period -- update noise frequency on relevant channels
+            self._update_mixer_state()
+
+        elif reg == 7:
+            # Mixer enable bits
+            self._update_mixer_state()
+
+        elif 8 <= reg <= 10:
+            # Volume / envelope-enable
+            ch = reg - 8
+            vreg = self._regs[reg]
+            self._env_enabled[ch] = bool(vreg & 0x10)
+            self._apply_volume(ch)
+
+        elif reg in {11, 12}:
+            # Envelope period
+            self._env_period = self._regs[11] | (self._regs[12] << 8)
+            self._env_period = max(self._env_period, 1)
+            self._compute_env_rate()
+
+        elif reg == 13:
+            # Envelope shape -- reset envelope generator
+            self._env_shape = self._regs[13] & 0x0F
+            self._env_segment = 0
+            self._env_accumulator = 0.0
+            self._env_reset_segment()
+            self._compute_env_rate()
+
+    def _period_to_hz(self, period: int) -> float:
+        """Convert an AY tone/noise period to Hz, clamped to synthio's valid
+        range of 0-32767 Hz."""
+        period = max(period, 1)
+        freq = self._clock / (16.0 * period)
+        freq = min(freq, 32767.0)
+        freq = max(freq, 1.0)
+        return freq
+
+    def _update_channel_freq(self, ch: int) -> None:
+        """Set a note's frequency from the current tone registers, but only if
+        tone is active on that channel."""
+        if self._tone_on[ch]:
+            lo = self._regs[ch * 2]
+            hi = self._regs[ch * 2 + 1] & 0x0F
+            period = lo | (hi << 8)
+            period = max(period, 1)
+            self._notes[ch].frequency = self._period_to_hz(period)
+
+    def _update_mixer_state(self) -> None:
+        """Read the mixer register (R7) and update waveforms & frequencies."""
+        mixer_reg = self._regs[7]
+        noise_period = self._regs[6] & 0x1F
+        noise_period = max(noise_period, 1)
+        noise_hz = self._period_to_hz(noise_period)
+
+        for ch in range(3):
+            tone_on = not bool(mixer_reg & (1 << ch))
+            noise_on = not bool(mixer_reg & (1 << (ch + 3)))
+
+            self._tone_on[ch] = tone_on
+            self._noise_on[ch] = noise_on
+
+            if tone_on and noise_on:
+                self._notes[ch].waveform = self._square
+                self._notes[ch].ring_waveform = self._noise
+                self._notes[ch].ring_frequency = noise_hz
+                self._update_channel_freq(ch)
+
+            elif tone_on:
+                self._notes[ch].waveform = self._square
+                self._notes[ch].ring_waveform = None
+                self._update_channel_freq(ch)
+
+            elif noise_on:
+                self._notes[ch].waveform = self._noise
+                self._notes[ch].ring_waveform = None
+                self._notes[ch].frequency = noise_hz
+
+            self._apply_volume(ch)
+
+    def _apply_volume(self, ch: int) -> None:
+        """Set the mixer voice level for a channel based on current state."""
+        # If the channel is fully off (no tone, no noise), silence it
+        if not self._tone_on[ch] and not self._noise_on[ch]:
+            self._mixer.voice[ch].level = 0.0
+            return
+
+        if self._env_enabled[ch]:
+            # Envelope: 0-31 mapped to the 16-entry DAC (pairs)
+            self._mixer.voice[ch].level = self.DAC[self._env_level >> 1]
+        else:
+            vol = self._regs[8 + ch] & 0x0F
+            self._mixer.voice[ch].level = self.DAC[vol]
+
+    def _compute_env_rate(self) -> None:
+        """Compute how many envelope steps to advance per 50 Hz tick."""
+        # The AY envelope steps once per (256 * period) clock cycles:
+        #   steps_per_second = clock / (256 * period)
+        #   steps_per_tick   = steps_per_second / 50
+        self._env_steps_per_tick = self._clock / (256.0 * self._env_period * 50.0)
+
+    def _env_reset_segment(self) -> None:
+        """Set the envelope level to the starting value for the current
+        segment."""
+        func = self._ENV_SEG[self._env_shape][self._env_segment & 1]
+        # Decay (0) and hold-alt (3) start at max; attack (1) and hold (2)
+        # start at 0.
+        self._env_level = 31 if func in {0, 3} else 0
+
+    def _step_envelope(self) -> None:
+        """Advance the envelope by one step."""
+        func = self._ENV_SEG[self._env_shape][self._env_segment & 1]
+        if func == 0:  # Decay
+            self._env_level -= 1
+            if self._env_level < 0:
+                self._env_segment ^= 1
+                self._env_reset_segment()
+        elif func == 1:  # Attack
+            self._env_level += 1
+            if self._env_level > 31:
+                self._env_segment ^= 1
+                self._env_reset_segment()
+        # func 2 & 3 = hold -- do nothing

adafruit_ay8912/vgm_player.py

@@ -0,0 +1,416 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Liz Clark for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+:py:class:`~adafruit_ay8912.vgm_player.VGMFile`
+================================================================================
+
+VGM chiptune file parser and player for CircuitPython.
+
+Plays VGM (and gzip-compressed VGZ) files through an
+:py:class:`~adafruit_ay8912.ay8912_emulator.AY8912` instance.
+
+Only files with a non-zero AY-3-8910 clock (header offset ``0x74``) are
+supported. Files targeting other chips (SN76489, YM2612, etc.) are rejected.
+
+* Author(s): Liz Clark
+
+Implementation Notes
+--------------------
+
+**Software and Dependencies:**
+
+* Adafruit CircuitPython firmware for the supported boards:
+  https://circuitpython.org/downloads
+"""
+
+import struct
+import time
+
+try:
+    from typing import TYPE_CHECKING, Optional, Tuple
+
+    if TYPE_CHECKING:
+        from .ay8912_emulator import AY8912
+except ImportError:
+    pass
+
+try:
+    import zlib
+except ImportError:
+    zlib = None
+
+__version__ = "1.0.0"
+__repo__ = "https://github.com/your-org/Adafruit_CircuitPython_AY8912.git"
+
+# VGM runs on a 44100 Hz sample clock for all wait commands
+_VGM_RATE = 44100
+
+
+class VGMFile:
+    """Parse and play an AY8912 VGM/VGZ file.
+
+    :param str filename: Path to a ``.vgm`` or ``.vgz`` file to load
+        immediately. Pass ``None`` to create an empty object and call
+        :meth:`load` later.
+    """
+
+    def __init__(self, filename: Optional[str] = None) -> None:
+        self._data = None
+        self._ay = None
+
+        # Metadata
+        self._title = ""
+        self._author = ""
+        self._game = ""
+
+        # Header info
+        self._clock_hz = 1773400
+        self._total_samples = 0
+        self._loop_offset = 0
+        self._loop_samples = 0
+        self._data_offset = 0
+        self._eof_offset = 0
+        self._version = 0
+
+        # Playback state
+        self._pos = 0  # current byte position in command stream
+        self._playing = False
+        self._sample_clock = 0  # cumulative samples played
+        self._wait_remaining = 0  # samples still to wait
+        self._next_time = 0.0  # monotonic time of next command batch
+        self._loop_count = 0  # how many times we've looped
+
+        if filename:
+            self.load(filename)
+
+    @property
+    def title(self) -> str:
+        """Track title from the GD3 tag, or ``""`` if absent."""
+        return self._title
+
+    @property
+    def author(self) -> str:
+        """Track author from the GD3 tag, or ``""`` if absent."""
+        return self._author
+
+    @property
+    def game(self) -> str:
+        """Game/source name from the GD3 tag, or ``""`` if absent."""
+        return self._game
+
+    @property
+    def clock_hz(self) -> int:
+        """AY chip clock in Hz."""
+        return self._clock_hz
+
+    @property
+    def version(self) -> int:
+        """VGM format version as a packed BCD integer"""
+        return self._version
+
+    @property
+    def total_samples(self) -> int:
+        """Total length of the song in 44100 Hz samples."""
+        return self._total_samples
+
+    @property
+    def duration(self) -> float:
+        """Song duration in seconds."""
+        if self._total_samples:
+            return self._total_samples / _VGM_RATE
+        return 0
+
+    @property
+    def elapsed(self) -> float:
+        """Elapsed playback time in seconds."""
+        return self._sample_clock / _VGM_RATE
+
+    @property
+    def progress(self) -> float:
+        """Playback progress as a fraction from ``0.0`` to ``1.0``."""
+        if self._total_samples:
+            p = self._sample_clock / self._total_samples
+            return p if p < 1.0 else 1.0
+        return 0
+
+    @property
+    def loop_count(self) -> int:
+        """How many times the song has looped back."""
+        return self._loop_count
+
+    @property
+    def loops(self) -> bool:
+        """``True`` if this song defines a loop point."""
+        return bool(self._loop_offset and self._loop_samples)
+
+    @property
+    def playing(self) -> bool:
+        """``True`` while playback is active."""
+        return self._playing
+
+    def load(self, filename: str) -> None:
+        """Load a ``.vgm`` or ``.vgz`` file, decompressing gzip natively.
+
+        :param str filename: Path to the file to load.
+        :raises RuntimeError: If the file is not a VGM, cannot be decompressed,
+            or does not target the AY-3-8910.
+        """
+        with open(filename, "rb") as f:
+            raw = f.read()
+
+        # Detect gzip (VGZ) -- magic bytes 0x1F 0x8B
+        if raw[0] == 0x1F and raw[1] == 0x8B:
+            raw = self._gunzip(raw)
+
+        # Check the VGM magic
+        if bytes(raw[0:4]) != b"Vgm ":
+            raise RuntimeError("Not a VGM file (bad magic)")
+
+        self._data = raw
+        self._parse_header()
+
+    @staticmethod
+    def _gunzip(data: bytes) -> bytes:
+        """Decompress gzip (VGZ) data"""
+        if zlib is None:
+            raise RuntimeError(
+                "Playing compressed .vgz files needs the 'zlib' module, which is "
+                "not present in this build. Use an uncompressed .vgm, or a build "
+                "that includes zlib."
+            )
+        # wbits=31 tells zlib to expect a gzip header/trailer
+        return zlib.decompress(data, 31)
+
+    def _parse_header(self) -> None:
+        """Parse the VGM header and locate the command stream."""
+        data = self._data
+
+        eof_rel = struct.unpack("<I", data[0x04:0x08])[0]
+        self._eof_offset = 0x04 + eof_rel if eof_rel else len(data)
+        self._eof_offset = min(self._eof_offset, len(data))
+
+        self._version = struct.unpack("<I", data[0x08:0x0C])[0]
+        self._total_samples = struct.unpack("<I", data[0x18:0x1C])[0]
+
+        loop_rel = struct.unpack("<I", data[0x1C:0x20])[0]
+        self._loop_offset = (0x1C + loop_rel) if loop_rel else 0
+        self._loop_samples = struct.unpack("<I", data[0x20:0x24])[0]
+
+        # AY-3-8910 clock at offset 0x74 (VGM 1.51+)
+        ay_clock = 0
+        if len(data) >= 0x78:
+            ay_clock = struct.unpack("<I", data[0x74:0x78])[0]
+
+        # Mask off the top bits (flags), keep the clock value
+        ay_clock &= 0x3FFFFFFF
+
+        if ay_clock == 0:
+            raise RuntimeError(
+                "No AY-3-8910 clock in this VGM (offset 0x74 is 0). "
+                "This file targets a different chip."
+            )
+
+        self._clock_hz = ay_clock
+
+        if self._version >= 0x150:
+            data_rel = struct.unpack("<I", data[0x34:0x38])[0]
+            self._data_offset = 0x34 + data_rel if data_rel else 0x40
+        else:
+            self._data_offset = 0x40
+
+        gd3_rel = struct.unpack("<I", data[0x14:0x18])[0]
+        if gd3_rel:
+            self._parse_gd3(0x14 + gd3_rel)
+
+        self._pos = self._data_offset
+
+    def _parse_gd3(self, offset: int) -> None:
+        """Parse the GD3 metadata tag (UTF-16LE null-terminated strings)."""
+        data = self._data
+        if bytes(data[offset : offset + 4]) != b"Gd3 ":
+            return
+
+        ptr = offset + 12
+
+        fields = []
+        for _ in range(11):
+            s, ptr = self._read_utf16(data, ptr)
+            fields.append(s)
+
+        if len(fields) >= 7:
+            self._title = fields[0]
+            self._game = fields[2]
+            self._author = fields[6]
+
+    @staticmethod
+    def _read_utf16(data: bytes, offset: int) -> "Tuple[str, int]":
+        """Read a UTF-16LE null-terminated string.
+
+        :param bytes data: Buffer to read from.
+        :param int offset: Byte offset to start reading at.
+        :return: A ``(string, next_offset)`` tuple.
+        """
+        chars = []
+        ptr = offset
+        while ptr + 1 < len(data):
+            lo = data[ptr]
+            hi = data[ptr + 1]
+            ptr += 2
+            if lo == 0 and hi == 0:
+                break
+            code = lo | (hi << 8)
+            if 32 <= code < 127:
+                chars.append(chr(code))
+            elif code >= 127:
+                chars.append("?")
+        return "".join(chars), ptr
+
+    def play(self, ay: "AY8912") -> None:
+        """Start playback through the AY8912 instance.
+
+        :param ~adafruit_ay8912.ay8912_emulator.AY8912 ay: The emulator that
+            register writes will be sent to. It is reset before playback.
+        """
+        self._ay = ay
+        self._pos = self._data_offset
+        self._sample_clock = 0
+        self._wait_remaining = 0
+        self._loop_count = 0
+        self._playing = True
+        self._next_time = time.monotonic()
+        self._ay.reset()
+
+    def stop(self) -> None:
+        """Stop playback and reset the attached AY8912"""
+        self._playing = False
+        if self._ay:
+            self._ay.reset()
+
+    def update(self) -> None:
+        """Process the command stream with correct timing.
+
+        Call repeatedly in the playback loop. It tracks real time internally
+        and only advances the command stream when the accumulated wait has
+        elapsed.
+        """
+        if not self._playing or self._data is None:
+            return
+
+        now = time.monotonic()
+        if now < self._next_time:
+            return
+
+        wait_samples = self._process_until_wait()
+
+        if wait_samples < 0:
+            if self._loop_offset and self._loop_samples:
+                self._pos = self._loop_offset
+                self._loop_count += 1
+                self._sample_clock = self._total_samples - self._loop_samples
+                wait_samples = 0
+            else:
+                self._playing = False
+                return
+
+        self._sample_clock += wait_samples
+        self._next_time += wait_samples / _VGM_RATE
+
+        self._next_time = max(self._next_time, now)
+
+    def _process_until_wait(self) -> int:  # noqa: PLR0912
+        """Execute commands until a wait.
+
+        :return: The number of samples to wait, or ``-1`` at end of stream.
+        """
+        data = self._data
+        ay = self._ay
+
+        end = self._eof_offset if self._eof_offset else len(data)
+        while self._pos < end:
+            cmd = data[self._pos]
+            self._pos += 1
+
+            # AY-3-8910 register write: 0xA0 aa dd
+            if cmd == 0xA0:
+                reg = data[self._pos]
+                val = data[self._pos + 1]
+                self._pos += 2
+                reg &= 0x0F if reg < 0x10 else 0xFF
+                if reg <= 13:
+                    ay.write_register(reg, val)
+
+            # Wait n samples: 0x61 nn nn
+            elif cmd == 0x61:
+                n = data[self._pos] | (data[self._pos + 1] << 8)
+                self._pos += 2
+                return n
+
+            # Wait 1/60 second (735 samples)
+            elif cmd == 0x62:
+                return 735
+
+            # Wait 1/50 second (882 samples)
+            elif cmd == 0x63:
+                return 882
+
+            # End of sound data
+            elif cmd == 0x66:
+                return -1
+
+            # Wait n+1 samples (0x70-0x7F)
+            elif 0x70 <= cmd <= 0x7F:
+                return (cmd & 0x0F) + 1
+
+            # --- Commands to skip (other chips / unsupported) ---
+
+            # 0x4F dd / 0x50 dd -- SN76489 (Game Gear / SMS): 1 data byte
+            elif cmd in {0x4F, 0x50}:
+                self._pos += 1
+
+            # 0x51-0x5F -- YM chips: 2 data bytes
+            elif 0x51 <= cmd <= 0x5F:
+                self._pos += 2
+
+            # 0xA1-0xBF -- various chip writes: 2 data bytes
+            elif 0xA1 <= cmd <= 0xBF:
+                self._pos += 2
+
+            # 0xC0-0xDF -- various: 3 data bytes
+            elif 0xC0 <= cmd <= 0xDF:
+                self._pos += 3
+
+            # 0xE0-0xFF -- various: 4 data bytes
+            elif 0xE0 <= cmd <= 0xFF:
+                self._pos += 4
+
+            # 0x90-0x95 -- DAC stream control (various lengths)
+            elif cmd == 0x90:
+                self._pos += 4
+            elif cmd == 0x91:
+                self._pos += 4
+            elif cmd == 0x92:
+                self._pos += 5
+            elif cmd == 0x93:
+                self._pos += 10
+            elif cmd == 0x94:
+                self._pos += 1
+            elif cmd == 0x95:
+                self._pos += 4
+
+            # 0x67 -- data block: 0x67 0x66 tt ss ss ss ss [data]
+            elif cmd == 0x67:
+                self._pos += 1  # skip 0x66
+                self._pos += 1  # skip the type byte
+                size = struct.unpack("<I", data[self._pos : self._pos + 4])[0]
+                self._pos += 4 + size
+
+            else:
+                # Unknown command
+                pass
+        return -1
+
+    def __str__(self) -> str:
+        title = self._title or "Untitled"
+        author = self._author or "Unknown"
+        return f"VGM v{self._version:X} | {title} -- {author} ({self.duration:.1f}s)"

adafruit_circuitpython_ay8912-1.0.0.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: adafruit-circuitpython-ay8912
+Version: 1.0.0
+Summary: CircuitPython synthio helper library for AY8912/AY-3-8910 emulation
+Author-email: Adafruit Industries <circuitpython@adafruit.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/adafruit/Adafruit_CircuitPython_AY8912
+Keywords: adafruit,blinka,circuitpython,micropython,ay8912_emulator,ay8912,,ay-3-8910,,synthio,,chiptune
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Classifier: Programming Language :: Python :: 3
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: Adafruit-Blinka
+Provides-Extra: optional
+Dynamic: license-file
+
+Introduction
+============
+
+
+.. image:: https://readthedocs.org/projects/adafruit-circuitpython-ay8912/badge/?version=latest
+    :target: https://docs.circuitpython.org/projects/ay8912/en/latest/
+    :alt: Documentation Status
+
+
+.. image:: https://raw.githubusercontent.com/adafruit/Adafruit_CircuitPython_Bundle/main/badges/adafruit_discord.svg
+    :target: https://adafru.it/discord
+    :alt: Discord
+
+
+.. image:: https://github.com/adafruit/Adafruit_CircuitPython_AY8912/workflows/Build%20CI/badge.svg
+    :target: https://github.com/adafruit/Adafruit_CircuitPython_AY8912/actions
+    :alt: Build Status
+
+
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+    :target: https://github.com/astral-sh/ruff
+    :alt: Code Style: Ruff
+
+CircuitPython synthio helper library for AY8912/AY-3-8910 emulation
+
+
+Dependencies
+=============
+This driver depends on:
+
+* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
+
+Please ensure all dependencies are available on the CircuitPython filesystem.
+This is easily achieved by downloading
+`the Adafruit library and driver bundle <https://circuitpython.org/libraries>`_
+or individual libraries can be installed using
+`circup <https://github.com/adafruit/circup>`_.
+
+Installing from PyPI
+=====================
+
+On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
+PyPI <https://pypi.org/project/adafruit-circuitpython-ay8912/>`_.
+To install for current user:
+
+.. code-block:: shell
+
+    pip3 install adafruit-circuitpython-ay8912
+
+To install system-wide (this may be required in some cases):
+
+.. code-block:: shell
+
+    sudo pip3 install adafruit-circuitpython-ay8912
+
+To install in a virtual environment in your current project:
+
+.. code-block:: shell
+
+    mkdir project-name && cd project-name
+    python3 -m venv .venv
+    source .env/bin/activate
+    pip3 install adafruit-circuitpython-ay8912
+
+Installing to a Connected CircuitPython Device with Circup
+==========================================================
+
+Make sure that you have ``circup`` installed in your Python environment.
+Install it with the following command if necessary:
+
+.. code-block:: shell
+
+    pip3 install circup
+
+With ``circup`` installed and your CircuitPython device connected use the
+following command to install:
+
+.. code-block:: shell
+
+    circup install adafruit_ay8912
+
+Or the following command to update an existing version:
+
+.. code-block:: shell
+
+    circup update
+
+Usage Example
+=============
+
+.. code-block:: python
+
+    import time
+    import board
+    import audiobusio
+    from adafruit_ay8912.ay8912_emulator import AY8912
+    from adafruit_ay8912.vgm_player import VGMFile
+
+    audio = audiobusio.I2SOut(board.D9, board.D10, board.D11)
+
+    VGM_FILE = "song.vgz"   # .vgm or .vgz both work
+    vgm = VGMFile(VGM_FILE)
+
+    ay = AY8912(sample_rate=22050, clock_rate=vgm.clock_hz)
+    ay.begin(audio)
+    vgm.play(ay)
+
+    last_status = time.monotonic()
+
+    while vgm.playing:
+        vgm.update()
+        now = time.monotonic()
+        if now - last_status >= 5.0:
+            last_status = now
+            print("  %.0fs / %.0fs (%d%%)" % (
+                vgm.elapsed, vgm.duration, int(vgm.progress * 100)))
+
+    ay.reset()
+
+Documentation
+=============
+API documentation for this library can be found on `Read the Docs <https://docs.circuitpython.org/projects/ay8912/en/latest/>`_.
+
+For information on building library documentation, please check out
+`this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.
+
+Contributing
+============
+
+Contributions are welcome! Please read our `Code of Conduct
+<https://github.com/adafruit/Adafruit_CircuitPython_AY8912/blob/HEAD/CODE_OF_CONDUCT.md>`_
+before contributing to help this project stay welcoming.

adafruit_circuitpython_ay8912-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+adafruit_ay8912/ay8912_emulator.py,sha256=ah437jIiNVHjmqmd6ABcqn8GlyN4H7ffU4w6ZD8BYYs,15107
+adafruit_ay8912/vgm_player.py,sha256=nzc9HUrEEmyEO0u63U2moxl1cxHV9XZ9RLoh73bf8zw,12792
+adafruit_circuitpython_ay8912-1.0.0.dist-info/licenses/LICENSE,sha256=0JsO0yQOspYeKuhk2Y_s1wan9NO0DYeWSRJBrYJdeko,1100
+adafruit_circuitpython_ay8912-1.0.0.dist-info/METADATA,sha256=V2dS0jaW1EQzsvXOElK6ZMg8-2WY2FKrnRmKAocv0Sk,4696
+adafruit_circuitpython_ay8912-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+adafruit_circuitpython_ay8912-1.0.0.dist-info/top_level.txt,sha256=5hB9mo7MFFlBGB-11CcR1ZIe6tcFtBfN4WHeJ_yTF7E,16
+adafruit_circuitpython_ay8912-1.0.0.dist-info/RECORD,,

adafruit_circuitpython_ay8912-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

adafruit_circuitpython_ay8912-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Liz Clark for Adafruit Industries
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adafruit_circuitpython_ay8912-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+adafruit_ay8912