Release 1.0.0 — Stable Release & Tooling Improvements

This version marks a major milestone for the ay8910-wrapper project, transitioning to a stable 1.0.0 release. This update focuses on improving the user experience, providing better installation options, and ensuring high-quality standards across the codebase.

🚀 Key Features & Enhancements

• Command-Line Tools: You can now install the project with dedicated CLI tools.
  • ym_player: A script to play YM music files.
  • ym_live_player: A real-time player for live emulation.
  • Installation: pip install ay8910_wrapper[tools]
• Modular Dependencies: To keep the core package lightweight, heavy dependencies like numpy and sounddevice are now optional. Use the [tools] extra to enable audio playback features.
• Improved Documentation: Complete overhaul of the documentation (README, project site, and docstrings) to reflect the new installation methods and script usage.
• Developer Experience:
  • Aligned linting rules with Python 3.9 using Ruff.
  • Enhanced CI/CD workflows for automated building and publishing.
  • Improved local test scripts for easier development.

🛠 Technical Changes

• Restructured the project to include an ay8910_wrapper.tools package.
• Updated pyproject.toml with [project.scripts] entry points.
• Added explicit error messages when attempting to use audio tools without the required optional dependencies.
• Broadened Python support coverage (3.9 to 3.14).

📦 Installation

To get everything including the playback tools:

pip install ay8910_wrapper[tools]

Or for the lightweight core emulator only:

pip install ay8910_wrapper

Release v0.9.0 - Enhanced Emulation & Live Audio Support

This major release marks a significant step forward for the ay8910_wrapper project, introducing a high-level API for real-time audio playback, multiple emulation engines, and comprehensive technical documentation.

🚀 Key Features

• Triple Emulation Engine Support:
  • Caprice32 (Amstrad CPC): Now the recommended engine, featuring high-fidelity stereo mixing and native sound synthesis.
  • Ay_Emul31 (Sergey Bulba): A C++ port of the famous tracker engine, offering accurate AY and YM volume tables for high-quality mono output.
  • MAME Legacy: Kept for historical compatibility and baseline reference.
• High-Level Playback API: Introducing .play() and .stop() methods directly on emulator classes. These methods handle the underlying audio buffer management and synchronization using sounddevice for seamless real-time playback.
• Live YM Chiptune Players:
  • ym_live_player.py: A new script demonstrating the high-level API for playing .ym files in real-time.
  • ym_player.py: Enhanced with support for both rendering to WAV and live playback across different engines.

🛠 Improvements & Fixes

• Enhanced Register Documentation: The __init__.py file now includes a complete and centralized reference for PSG registers (0-15), including detailed ASCII graphical representations of envelope shapes (Register 13) based on official data manuals.
• Multi-Platform Testing: Implementation of a robust local test runner (run_local_tests.py) ensuring compatibility across Python versions 3.9 up to 3.14.
• Modernized Build System: Migration to a uv-based environment for faster dependency management and more reliable builds.
• Refined API Reference: Complete overhaul of the MkDocs-based documentation site, providing clear examples and detailed member descriptions.

📚 Documentation

The online documentation has been expanded with:

• A new Scripts and Tools section detailing usage and options for the provided utilities.
• A centralized PSG Register Reference for developers interacting with the hardware level.
• A dedicated Contributing Guide for developers wishing to compile from source.

⚙ Installation

Install the latest version via PyPI:

pip install ay8910_wrapper

---

This release is the result of an experimental collaboration between human guidance and AI-assisted development (Gemini & Junie).

---

Full Changelog: v0.8.0...v0.9.0

Release v0.8.0

This release focuses on improving code quality, automating documentation deployment, and enhancing the overall developer experience.

🌟 Key Changes

• Automated Documentation: Integrated a new deployment pipeline to automatically publish the official documentation to GitHub Pages upon each release.
• Code Quality & Linting: Performed a major cleanup using Ruff. This includes fixing syntax errors, removing unused imports, and standardizing the import order across the entire project.
• Version Consistency: Improved the release workflow to ensure the version number is dynamically updated in pyproject.toml and correctly reported during documentation builds.
• Enhanced Project Metadata: Added official documentation links to the package metadata, making it easier to find resources via PyPI or pip show.
• Bug Fixes: Resolved a syntax issue in the test suite that was preventing proper execution in some environments.

📚 Documentation Updates

• The README.md and project links have been updated to point to the live documentation site for a better reading experience compared to raw Markdown files.

🛠 Technical Improvements

• Added pytest and pytest-cov to the development dependencies.
• Standardized the GitHub Actions environment to use Node 24 and Python 3.x.

---

Full Changelog: v0.7.3...v0.8.0

Release v0.7.3 - PyPI Launch & Robust Infrastructure

This release represents a major step forward in the project's maturity, focusing on seamless distribution via PyPI, enhanced developer documentation, and a fully automated CI/CD pipeline. Since version v0.6.2, we have transitioned from manual wheel management to a professional "Trusted Publishing" workflow.

📦 Distribution & PyPI

• Official PyPI Release: The package is now available on PyPI. Installation is as simple as pip install ay8910_wrapper.
• Trusted Publishing: Implemented automated, passwordless publishing to PyPI using OpenID Connect (OIDC) through GitHub Actions.
• Improved Metadata: Enhanced pyproject.toml with valid classifiers, project URLs (Homepage), and proper license mapping (MIT).
• Portable Documentation: Updated README.md with absolute links to ensure documentation remains accessible when viewed on PyPI.

🛠 Infrastructure & CI/CD

• Automated Publish Workflow: Renamed and upgraded the build pipeline to build_and_publish.yml, featuring multi-OS wheel generation and automatic uploads upon version tagging (v*).
• Comprehensive Testing Suite: Created tests.yml to perform linting and unit tests on every Pull Request across Windows, Linux, and macOS.
• Dependency Management: Optimized the CI environment by installing libportaudio2 on Linux runners, ensuring sounddevice works correctly during automated tests.
• Modern Tooling: Upgraded cibuildwheel to v3.4.1 for better stability and future-proofing.

📖 Developer Experience

• Detailed Contributing Guide: Added CONTRIBUTE.md featuring a complete GitHub Flow walkthrough with concrete Git commands (including upstream synchronization and conflict resolution).
• Environment Management: Standardized the use of uv for ultra-fast virtual environment setup and dependency resolution.
• Code Quality: Performed a massive cleanup of the codebase, resolving over 30 linting issues (imports, f-strings, long lines) identified by ruff.

✨ Maintenance

• License Update: Formally transitioned the project metadata to reflect the MIT License.
• Python 3.14: Verified and enabled automated builds for Python 3.14 (stable) across all platforms.
• Bug Fixes: Resolved a TOMLDecodeError on Windows and fixed position-independent code (fPIC) issues for Linux shared modules.

Release v0.6.2 - Real-Time Audio & Advanced CI Support

This release marks a significant milestone for ay8910_wrapper, moving from a pure synthesis library to a real-time capable audio engine with professional-grade CI/CD automation.

🚀 Key Features & Improvements

• New Live Audio API: Added .play() and .stop() methods to both ay8910 and ay8912_cap32 classes for effortless real-time playback using sounddevice.
• New Live Player Script: Introduced scripts/ym_live_player.py, allowing direct playback of .ym files with low latency.
• Improved macOS & Linux Compatibility: Fixed critical compilation issues on Unix-based systems by enabling POSITION_INDEPENDENT_CODE (fPIC) in the C++ core.
• Python 3.14 Support: Full compatibility and automated wheel generation for the latest Python 3.14 release across all platforms.

🛠 Infrastructure & Tooling

• Multi-OS GitHub Actions: Automated builds now generate .whl files for Windows (AMD64), Linux (manylinux), and macOS (Intel/Apple Silicon).
• Automated Testing Suite: Implemented a comprehensive CI pipeline that runs unit tests and linting (ruff) on every Pull Request to ensure code stability.
• Developer Experience:
  • Full migration to uv for faster environment management and dependency resolution.
  • Comprehensive Contributing Guide (CONTRIBUTE.md) added to help new developers join the project.

🐛 Bug Fixes & Refactoring

• Fixed a linker error on Linux 64-bit related to static library relocation.
• Resolved multiple linting issues and unused imports to maintain a clean codebase.
• Updated cibuildwheel to v3.4.1 to support modern build environments.

Release v0.5.0 - Live Audio & Internationalization

This release introduces direct audio playback capabilities, significant emulator fixes, and a complete English translation of the project's scripts and documentation.

New Features

• Direct Audio Output: Added .play() and .stop() methods to the ay8910 and ay8912_cap32 classes. This allows for real-time sound generation directly from Python using sounddevice and numpy, simulating a real AY-3-8910/8912 chip.
• YM Live Player: A new script scripts/ym_live_player.py allows users to play .YM files (including LHA-compressed ones) in real-time through the new audio API.
• Dynamic Method Injection: Improved the Python wrapper to dynamically add audio control methods to the C++-based objects, overcoming pybind11 limitations.

Bug Fixes & Improvements

• AY-3-8912 (Caprice32) Refinement:
  • Fixed the reset() method to ensure perfect silence.
  • Corrected the envelope selection bit (bit 4 of the amplitude register).
  • Improved stereo mixing logic and panning accuracy.
• Performance Optimization: Removed debug traces and std::cout calls in ay8912_cap32.cpp to prevent audio stuttering during live playback.
• Full English Translation: All scripts in the scripts/ directory, console messages, and documentation (README.md, REFERENCE.md) have been translated to English for international consistency.

Release v0.4.0 - Advanced Register Access & Improved Documentation

This release introduces direct register manipulation for both emulation engines, providing developers with low-level control over the PSG state. It also includes significant updates to the technical documentation and usage examples.

🚀 New Features

• Direct Register Access: Added get_register(reg), set_register(reg, value), and get_registers() to both MAME and Caprice32 engines.
  • MAME Engine: Supports up to 32 registers (standard + expanded modes) with automatic bit-masking for hardware-accurate behavior.
  • Caprice32 Engine: Supports 16 registers with centralized side-effect handling for period and volume updates.
• Enhanced Python API: Exposed new methods via pybind11, ensuring a consistent interface across different emulation cores.

📝 Documentation & Examples

• Comprehensive Reference Guide: Fully updated REFERENCE.md with detailed method signatures, parameter descriptions, and return types.
• Practical Usage Examples:
  • Added step-by-step guides on how to generate a simple tone.
  • Included code snippets showing how to export generated audio buffers directly to standard WAV files using Python's wave and struct modules.
• Clarified Engine Differences: Explicitly documented the differences between the mono output of the MAME engine and the interleaved stereo output of the Caprice32 engine.

🛠️ Technical Improvements

• Bit-masking Logic: Refined register write operations to ensure stored values strictly match AY-3-8910/YM2149 hardware specifications.
• Unit Test Suite Expansion: Added tests/test_registers.py to validate register read/write consistency, bit-masking accuracy, and full register bank retrieval.
• Bug Fixes: Corrected several truncated descriptions in the documentation and fixed minor inconsistencies in the Caprice32 synthesis loop initialization.

💾 Installation

Update to the latest version:

pip install ay8910_wrapper-0.4.0-cp314-cp314-win_amd64.whl

Release v0.3.0 - Dual-Engine Support & Caprice32 Integration

This major update introduces a second emulation engine based on the Caprice32 project, specifically optimized for Amstrad CPC's AY-3-8912 implementation. This version also switches the default player behavior to provide a more immersive stereo experience.

🚀 Key Features

• Caprice32 Emulation Engine: Integrated a new PSG core based on the Caprice32 emulator. This engine uses discrete synthesis logic and Sergey Bulba's volume tables for increased authenticity on CPC-specific soundtracks.
• Native Stereo Rendering: The new Caprice32 core supports 16-bit interleaved stereo output with configurable channel panning.
• Default CPC Stereo Mix: ym_player.py now defaults to the Caprice32 engine with a standard ABC stereo distribution (Channels A/B/C spread across the stereo field), providing an "out-of-the-box" authentic CPC sound.

🛠️ Improvements & API Changes

• New ay8912_cap32 Class: A dedicated C++ class exposed via pybind11 for high-performance Caprice32-style emulation.
• Dynamic Engine Selection: Updated ym_player.py with a new --mame flag to switch back to the original MAME-based mono engine if desired.
• Custom Stereo Mapping: Added set_stereo_mix(al, ar, bl, br, cl, cr) to the Python API, allowing fine-grained control over how each PSG channel is weighted between Left and Right speakers.
• Automatic Environment Detection: The player now correctly identifies and configures the appropriate number of audio channels (Mono vs Stereo) based on the selected engine.

📦 Technical Details

• Refactored ym_player.py rendering loops to handle variable channel counts and sample buffers.
• Synchronized CMake build system to include the new ay8912_cap32.cpp source.
• Improved signal stability and DC offset management in the discrete synthesis path.

💾 Installation

Update to the latest version using the pre-built wheel:

pip install ay8910_wrapper-0.3.0-cp314-cp314-win_amd64.whl

Release v0.2.0 - Improved Emulation Accuracy & New Utilities

This release focuses on improving the audio rendering accuracy to match reference recordings and provides new tools for WAV analysis and metadata management.

Key Improvements

• Enhanced Audio Centering & DC Offset: Refined the C++ emulation core (MAME-based) to handle signal centering more accurately. The output now correctly balances between "Legacy" and "Raw" modes, ensuring a stable DC offset that closely matches professional chiptune players.
• Improved Mono Mixing: Updated the internal mixer logic to better simulate the summing of AY-3-8910/YM2149 channels when using single-output configurations.
• Fixed Clock Handling: Resolved issues in ym_player.py regarding clock frequency overrides, ensuring the emulator strictly follows the timing defined in the .ym file headers.

New Features & Tools

• WAV Metadata Stripper: Added strip_wav_metadata.py to generate clean, standard WAV files without non-audio chunks (metadata), useful for byte-for-byte comparisons and strict player compatibility.
• Advanced Audio Analysis: New scripts (analyze_wav.py, compare_wav.py, check_samples.py) for detailed statistical analysis of generated audio, including amplitude peaks, DC offset detection, and dominant frequency estimation.
• LHA Support: The ym_player.py utility now natively handles compressed .ym files via the lhafile library.

Technical Changes

• Updated C++ core logic for volume table normalization.
• Refactored Python-C++ bridge (pybind11) for better flag management (AY8910_LEGACY_OUTPUT vs AY8910_SINGLE_OUTPUT).
• Cleaned up rendering loops in ym_player.py for more consistent sample generation across different frame rates (FPS).

Installation

You can install the pre-built wheel for this version:

pip install ay8910_wrapper-0.2.0-cp314-cp314-win_amd64.whl

(Note: requires Python 3.8+ and numpy, sounddevice, lhafile for full utility support)

Release v0.1.0: Initial Release

This is the first public release of the ay8910_wrapper project.

This version provides a fully functional Python wrapper around a standalone C++ AY-3-8910 emulation core, originally derived from the MAME project. It allows for easy programmatic generation of chiptune audio directly from Python.

Features

• Standalone C++ Core: The AY-3-8910 emulation code has been successfully decoupled from the MAME framework into a self-contained C++ library.
• Pybind11 Wrapper: A clean Python interface to the C++ core, allowing for easy instantiation and control of the sound chip.
• High-Level Audio Generation: Includes a generate() method to easily render a specific number of audio samples.
• YM File Player: A command-line script (ym_player.py) is included in the scripts directory. It can play .ym music files, with built-in support for LHA decompression, making it easy to play files directly from popular chiptune archives.
• Modern Python Packaging: The project is structured with pyproject.toml and CMake for easy building and distribution using tools like uv and pip.