Cycle-accurate Yamaha YM2149 tooling for Rust — from raw PSG emulation and YM/YMT/SNDH importers to Arkos Tracker playback, CLI/export pipelines, Bevy integrations, visualization stacks, and a one-click WASM demo.

► Launch Web Player

Experience authentic Atari ST chiptune music directly in your browser! The WebAssembly player features:

• ✨ Full YM2-YM6 and SNDH format support with LHA/ICE decompression
• 🎮 Play/Pause/Stop controls with progress bar
• 🔊 Volume control and channel muting (A/B/C)
• 📊 Real-time metadata display
• 📦 Compact WASM module
• 🎯 Cycle-accurate YM2149 emulation (ported from Leonard/Oxygene's AtariAudio)

Naming: Bevy-focused crates follow bevy_ym2149_*, while core/backends/replayers use the ym2149-* prefix.

• ✅ Hardware-faithful: cycle-accurate YM2149 emulation (ported from Leonard/Oxygene's AtariAudio), precise envelope, noise, mixer, SID, Sync Buzzer, digi-drum behaviours
• 📁 ZXAY/EMUL AY: bundled replayer with Z80 CPU emulation for the Project AY catalogue
• 🎹 SNDH support: native Atari ST music via 68000 CPU + MFP 68901 timer + STE DAC emulation
• 🧰 CLI ready: stream YM/AKS/AY/SNDH files in the terminal with real-time visualization
• 🎵 Native Bevy audio: seamless integration via Decodable trait with pull-based sample generation
• 🛰️ Configurable Bevy subsystems: playlists, crossfade decks, music state graphs, channel events, diagnostics, audio bridge
• 🖼️ Visualization stack: drop-in oscilloscope, spectrum bars, progress HUD, and demoscene showcase based on the viz crate
• 🧪 Well-tested: cargo test --workspace (165+ tests) plus example scenes to validate runtime flows
• 🪄 Gameplay hooks: Bevy plugin ships marker events, audio-reactive metrics, and PSG one-shot SFX events

Arkos Tracker is the de-facto “modern” workflow for YM2149/AY musicians: it blends a classic step-sequencer with a visual instrument designer, supports multiple PSGs per song, and lets composers mix hardware envelopes with software macros. Native support matters because:

• Multi-PSG music – Arkos sequences can target two or more AY chips; our replayer handles that natively, both in the CLI and Bevy.
• Modern authoring tools – Musicians can stay in the Arkos editor (PC/Mac) and drop the .aks export straight into any crate in this repo—no external tracker runtime or C++ bridge required.
• Feature parity – Hardware effects (Sync Buzzer, DigiDrum, SID), custom arps, and per-channel envelopes all map to the same PSG core shared with YM/AY playback.
• Cross-target builds – The same Rust replayer powers desktop, web (WASM), and Bevy integrations, so Arkos rips behave identically everywhere.

In short: Arkos lets artists work with modern ergonomics, and this workspace lets those songs run anywhere Rust does.

[dependencies]
# Core emulator only (minimal dependencies)
ym2149 = "0.7"

# With streaming audio output
ym2149 = { version = "0.7", features = ["streaming"] }

# YM file parsing and playback
ym2149-ym-replayer = "0.7"

use ym2149_ym_replayer::{load_song, ChiptunePlayer, ChiptunePlayerBase, PlaybackMetadata};

fn main() -> anyhow::Result<()> {
    let data = std::fs::read("song.ym")?;
    let (mut player, summary) = load_song(&data)?;

    // Use the unified ChiptunePlayerBase interface for playback
    player.play();
    let samples = player.generate_samples(summary.samples_per_frame as usize);

    // Access metadata via ChiptunePlayer trait (extends ChiptunePlayerBase)
    let meta = player.metadata();
    println!("{} by {} • {} frames", meta.title(), meta.author(), summary.frame_count);
    Ok(())
}

# Real-time playback with scope overlay
cargo run -p ym2149-replayer-cli -- examples/ym/ND-Toxygene.ym

# Play SNDH files from the Atari ST demoscene
cargo run -p ym2149-replayer-cli -- examples/sndh/Mad_Max/Buzzer.sndh

# Play GIST sound effects (.snd)
cargo run -p ym2149-gist-replayer --example player -- examples/gist/alien.snd

# Interactive demo with Bevy visualization
cargo run -p bevy_ym2149_examples --example basic_example

use ym2149_ym_replayer::{load_song, export::export_to_wav_default, export::ExportConfig};

fn main() -> anyhow::Result<()> {
    let data = std::fs::read("song.ym")?;
    let (mut player, info) = load_song(&data)?;

    // Export to WAV (feature: export-wav)
    export_to_wav_default(&mut player, info, "output.wav")?;

    Ok(())
}

Note: MP3 export was removed because the system-dependent LAME/Autotools toolchain proved too brittle. Export WAV instead and transcode externally (e.g. ffmpeg -i output.wav -b:a 192k output.mp3).

use bevy::prelude::*;
use bevy_ym2149::{Ym2149Playback, Ym2149Plugin};
use bevy_ym2149_viz::Ym2149VizPlugin;

fn main() {
    App::new()
        .add_plugins((DefaultPlugins, Ym2149Plugin::default(), Ym2149VizPlugin::default()))
        .add_systems(Startup, |mut commands: Commands| {
            commands.spawn(Camera2d);
            commands.spawn(Ym2149Playback::new("assets/music/song.ym")).insert(Name::new("Tracker"));
        })
        .run();
}

Need a reference scene? cargo run --example advanced_example -p bevy_ym2149_examples. Want to try the browser demo? Open https://slippyex.github.io/ym2149-rs/web/simple-player.html (auto-built via GitHub Pages).

Looking for chiptunes to play? These community archives have thousands of tracks:

• crates/ym2149-core/README.md – emulator architecture, feature flags, CLI/export instructions
• crates/bevy_ym2149/README.md – plugin subsystems, playlists, music state graph, audio bridge, diagnostics
• crates/bevy_ym2149_viz/README.md – visualization builders and systems
• crates/bevy_ym2149_examples/README.md – example matrix + screenshot gallery (incl. playlist crossfade UI)
• ARCHITECTURE.md – YM + Arkos playback pipelines and layering details
• crates/ym2149-core/STREAMING_GUIDE.md – low-latency streaming details
• examples/ – curated list of .ym,.aks, .ay, and .sndh files for regression tests and the wasm demo

Need to refresh the wasm demo bundle? Run scripts/build-wasm-examples.sh from the repo root to rebuild via wasm-pack and copy the output into crates/ym2149-wasm/examples/pkg/.

# Entire workspace
cargo test --workspace

# Focus a crate
cargo test -p ym2149
cargo test -p bevy_ym2149

# Feature-specific tests
cargo test -p ym2149 --features streaming

• Rust 1.83+ (Rust 2024 edition) with cargo and rustfmt
• Audio backend libraries for CPAL/Rodio (ALSA/PulseAudio, CoreAudio, WASAPI, etc.) when testing real-time playback
• AY playback: ZX-only, firmware calls are unsupported (CPC/ROM-heavy AY files will be rejected)
• Optional tooling:
  • wasm-pack for building the web player
  • node/npm or python -m http.server for serving the WASM demo locally
  • Bevy’s native dependencies (Vulkan/Metal/DX) when running the example scenes
  • cargo-make/just if you use the provided helper scripts (optional)

ym2149-rs/
├── crates/
│   ├── ym2149-core/            # Core YM2149 chip emulator (crates.io `ym2149`)
│   ├── ym2149-common/          # Shared traits (ChiptunePlayer, PlaybackMetadata) and types
│   ├── ym2149-softsynth/       # Experimental soft synth backend implementing the backend trait
│   ├── ym2149-ym-replayer/     # YM parser + playback engine
│   ├── ym2149-arkos-replayer/  # Arkos Tracker (.aks) parser/player
│   ├── ym2149-ay-replayer/     # ZXAY/EMUL parser + Z80 runner (ZX-only; CPC AY rejected)
│   ├── ym2149-sndh-replayer/   # SNDH player with 68000 CPU + MFP timer + STE DAC emulation
│   ├── ym2149-gist-replayer/   # GIST sound effect parser and multi-voice player
│   ├── ym2149-replayer-cli/    # Terminal streamer/exporter built on the replayers
│   ├── ym2149-wasm/            # WASM bindings + browser demo
│   ├── bevy_ym2149/            # Bevy plugin (playback, playlists, crossfade, diagnostics)
│   ├── bevy_ym2149_viz/        # Optional visualization ECS systems
│   ├── bevy_ym2149_examples/   # Runnable Bevy app gallery
│   └── ym2149-bevy/            # Legacy shim that re-exports `bevy_ym2149`
├── examples/                   # YM/SNDH sample files
├── docs/                       # Web player (GitHub Pages)
├── Cargo.toml                  # Workspace configuration
└── README.md                   # You are here

Contributions are welcome! Please ensure:

• cargo fmt + cargo clippy
• cargo test --workspace
• Documentation and examples updated for new features

MIT License – see LICENSE.

• Leonard/Oxygene (Arnaud Carré) – YM format specification, ST-Sound reference material, and the AtariAudio C++ implementation that forms the basis of our YM2149 core emulation
• Atari ST + demoscene community – for the original tunes, SNDH archive, and documentation
• Rust audio and Bevy ecosystems – rodio/cpal, Bevy ECS, and community inspiration