| CARVIEW |
YM2149-rs
Chiptune Sound Synthesis in Pure Rust
A comprehensive ecosystem for YM2149/AY-3-8910 sound chip emulation, supporting SNDH, YM, AY formats with real-time visualization and Bevy plugin support.
Who Is This For?
From demoscene veterans to curious newcomers
Demoscene Enthusiasts & Chiptune Artists
Play back your entire collection of YM, SNDH, AY, and Arkos Tracker files with authentic sound reproduction — in the terminal, browser, or your next retro-inspired project.
Game Developers
Drop authentic PSG audio into Bevy games with a single plugin. Playlists, crossfades, visualizations, and audio-reactive gameplay hooks included.
Emulator Authors
A clean, well-tested YM2149 core with configurable backends. Integrate the chip into your Atari ST, CPC, or custom system emulator.
Curious Learners
Explore how classic sound chips work. The codebase is documented, tested, and designed to be readable — perfect for learning low-level audio programming.
Machines That Defined an Era
The YM2149/AY-3-8910 powered these legendary platforms
Technical Highlights
Not a wrapper around C code — pure Rust from chip to speaker
Cycle-Accurate Core
Precise emulation of all PSG features — envelopes, noise, mixer, SID voice, Sync Buzzer, and digi-drum effects.
Multi-PSG Support
Run multiple YM2149 chips in parallel — natively supported via Arkos Tracker for authentic dual/triple-chip music.
68000 CPU Emulation
Full Motorola 68000 emulation for SNDH playback — runs original Atari ST music drivers cycle-accurately.
Seven File Formats
YM (1-6), YMT1/YMT2, GIST (.snd), Arkos Tracker (.aks), ZXAY/EMUL (.ay), and SNDH with LHA/ICE decompression.
Browser Ready
Compact WebAssembly module (147KB) runs in any modern browser with Web Audio API support.
Production Ready
165+ tests, documented APIs, real-world demoscene fixtures, and continuous integration.
Architecture
Modular layers from hardware emulation to game integration
About the YM2149
The sound chip that defined an era of home computing and gaming
History
The YM2149F is a Programmable Sound Generator (PSG) manufactured by Yamaha, virtually identical to General Instrument's AY-3-8910 from 1978. These chips became the voice of an entire generation of home computers.
Found in legendary machines like the Atari ST, Amstrad CPC, ZX Spectrum 128, and MSX, the YM2149 created the distinctive sound of 1980s gaming and the demoscene.
Despite its simple 3-channel square wave design, composers and programmers pushed the chip far beyond its intended capabilities, creating techniques that still inspire chiptune artists today.
YM2149F vs AY-3-8910
While often considered identical, the Yamaha YM2149F has subtle but important differences from the original GI AY-3-8910:
Specifications
| Sound Channels | 3 square wave |
| Noise Generator | 1 (shared) |
| Envelope Generator | 1 (shared) |
| Tone Period | 12-bit (0-4095) |
| Volume Levels | 16 register / 32 DAC |
| Envelope Shapes | 8 unique (16 register values) |
| Clock (Atari ST) | 2 MHz |
| Frequency Range | 30 Hz - 125 kHz |
Chip Architecture
Tone Generators
Three independent square wave generators (A, B, C), each with a 12-bit period register controlling frequency from ~30Hz to ultrasonic ranges.
Noise Generator
A 17-bit Linear Feedback Shift Register (LFSR) produces pseudo-random noise. The 5-bit period register controls the "color" of the noise.
Envelope Generator
A single shared envelope generator with 8 unique shapes (16 register values map to 8 patterns). The YM2149 uses 32-step resolution (5-bit DAC) for smoother envelopes than the AY-3-8910's 16 steps.
Register Map
| Reg | Name | Bits | Description |
|---|---|---|---|
| R0 | Tone A Fine | 7-0 | Channel A period low byte |
| R1 | Tone A Coarse | 3-0 | Channel A period high nibble |
| R2 | Tone B Fine | 7-0 | Channel B period low byte |
| R3 | Tone B Coarse | 3-0 | Channel B period high nibble |
| R4 | Tone C Fine | 7-0 | Channel C period low byte |
| R5 | Tone C Coarse | 3-0 | Channel C period high nibble |
| R6 | Noise Period | 4-0 | Noise generator period (0-31) |
| R7 | Mixer / I/O | 7-0 | I/O direction (7-6), Noise (5-3), Tone (2-0) enable (active low) |
| R8 | Amplitude A | 4-0 | Volume (0-15) or envelope mode (bit 4) |
| R9 | Amplitude B | 4-0 | Volume (0-15) or envelope mode (bit 4) |
| RA | Amplitude C | 4-0 | Volume (0-15) or envelope mode (bit 4) |
| RB | Envelope Fine | 7-0 | Envelope period low byte |
| RC | Envelope Coarse | 7-0 | Envelope period high byte |
| RD | Envelope Shape | 3-0 | CONT/ATT/ALT/HOLD (8 unique shapes) |
| RE | I/O Port A | 7-0 | Parallel I/O data port A |
| RF | I/O Port B | 7-0 | Parallel I/O data port B |
Demoscene Effects & Techniques
Programmers and musicians discovered ways to push the YM2149 far beyond its original design, creating effects that seemed impossible on such simple hardware.
Sync-Buzz
Hardware Envelope EffectBy synchronizing the envelope generator with the tone generator, musicians could create rich, buzzing timbres with overtones.
DigiDrum
Sample PlaybackBy rapidly updating volume registers at high frequencies, the chip can play back digitized samples like drum hits or speech.
SID Voice
Software Waveform SynthesisInspired by the C64's SID chip, this technique uses rapid volume changes to synthesize custom waveforms.
Timer Effects
Hardware Timer AbuseUsing the Atari ST's MFP timers to update registers mid-frame enables multiplexing more than 3 channels.
Arpeggio
Rapidly cycling through notes at 50Hz to simulate chords on a single channel.
Portamento
Smooth pitch slides between notes by incrementing the period register.
Vibrato
Oscillating the pitch slightly using a sine or triangle LFO for expressive leads.
PWM Simulation
Alternating between two detuned tones to simulate pulse width modulation.
Ring Modulation
Mixing tone and noise generators for metallic, bell-like timbres.
Multi-PSG
Using multiple YM2149 chips for up to 12 channels.
Features
Everything you need to work with classic chiptune sound chips
Accurate Emulation
Cycle-accurate YM2149F/AY-3-8910 emulation with all envelope shapes, noise generator, and mixer configurations.
Multiple Formats
Support for SNDH, YM, AY, AKS (Arkos Tracker), and GIST formats. Play thousands of classic chiptunes.
Real-time Visualization
Beautiful oscilloscope, spectrum analyzer, and channel visualization in both CLI and WebAssembly.
CLI Player
Full-featured terminal player with TUI visualization, playlist support, and keyboard controls.
WebAssembly
Run in any browser with our WASM build. No installation required, just pure chiptune goodness.
Bevy Integration
Native Bevy game engine plugin for easy integration of chiptune audio in your Rust games.
Bevy Integration
First-class Bevy game engine support with ECS-native architecture
use bevy::prelude::*;
use bevy_ym2149::{Ym2149Plugin, Ym2149Playback};
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_plugins(Ym2149Plugin::default())
.add_systems(Startup, setup)
.run();
}
fn setup(mut commands: Commands) {
commands.spawn(Camera2d::default());
commands.spawn(Ym2149Playback::new("music/theme.ym"));
}Playback Control
Play, pause, restart, volume control, looping, and per-channel muting through ECS components.
Playlist & Crossfade
Sequential track playback with seamless crossfade transitions. Supports .ymplaylist asset files.
Adaptive Music States
Graph-based state machine for switching tracks based on game events (menu, gameplay, boss, etc.).
Pattern Triggers
Fire events when channel amplitude/frequency matches criteria. Perfect for rhythm games and audio-reactive visuals.
Direct Synth Control
YmSynthController for direct PSG register access. Create custom SFX and procedural audio.
Visualization Plugin
bevy_ym2149_viz adds oscilloscope, spectrum, and song status UI components with ready-to-use builders.
Rich Event System
TrackStarted, TrackFinished, PlaybackFrameMarker, BeatHit, ChannelSnapshot events for reactive gameplay.
Multiple Instances
Spawn multiple independent Ym2149Playback entities for layered audio, music + SFX, or A/B testing.
Audio Bridge
Route playback through Bevy's audio graph for effects processing, spatial audio, and mixing.
Retro game with chiptune soundtrack
Demoscene intro with synced audio
Bevy + YM2149 in action
cargo add bevy_ym2149 bevy_ym2149_viz
CLI Replayer
Terminal-based chiptune player with real-time visualization
Real-time oscilloscope and spectrum
Interactive playlist with search
Multi-Format
YM, SNDH, AY, AKS formats with automatic detection
Visualization
Per-channel oscilloscope, spectrum analyzer, note display
Playlist
Browse directories, search, navigate with keyboard
Controls
Channel muting, volume, prev/next track
Command Line Usage
ym-replayer song.ym
ym-replayer ~/music/chiptunes
ym-replayer --no-color-filter song.sndh
Supports: YM (YM2-YM6), AKS, AY, SNDH
Keyboard Controls
cargo install ym2149-replayer-cli
Crates
Modular architecture - use only what you need
Quick Start
Get started with just a few lines of code
use ym2149_core::Ym2149;
fn main() {
// Create a new YM2149 instance
let mut chip = Ym2149::new(2_000_000);
// Set channel A frequency to 440Hz (A4)
chip.write_register(0, 0x7E); // Period low
chip.write_register(1, 0x01); // Period high
// Enable channel A, set volume
chip.write_register(7, 0x3E); // Mixer
chip.write_register(8, 0x0F); // Volume
// Generate samples
let sample = chip.generate();
}About the Author
Demoscene contributor in the early-to-mid 1990s on the Atari ST, and developer of the SidSound Designer — the first soundchip editor on the Atari ST that enabled up to three SID voices simultaneously, pushing the YM2149 far beyond its original design.
The YM2149's characteristic buzzy warmth, its quirky envelope tricks, and the creative constraints it imposed left a lasting impression. Three decades later, this project is both a tribute to that era and a modern toolkit for anyone who wants to explore or use these sounds today.
30+ years of continuous software development — from assembly on 16-bit machines to Rust on modern systems. Tech Lead, Engineering Manager, and passionate Open Source contributor.
External References
Essential resources for chiptune enthusiasts and developers
SNDH Archive
The largest collection of Atari ST chiptunes in SNDH format. Thousands of songs from the demoscene era.
sndh.atari.orgAY Project
ZX Spectrum and Amstrad CPC music archive. AY/EMUL format songs and the Ay_Emul player.
bulba.untergrund.netLeonard's YM Resources
Original YM file format documentation and tools by Leonard/Oxygene. The definitive YM reference.
leonard.oxg.free.frAcknowledgements
This project stands on the shoulders of giants
Arnaud Carré (Leonard/Oxygene)
Creator of StSound, AtariAudio, and the YM file format. His cycle-accurate YM2149 emulation and SNDH player served as invaluable inspiration for this project's architecture. A true legend of the Atari ST demoscene.
Archive Maintainers
The SNDH Archive maintainers for preserving thousands of Atari ST chiptunes, and the AY Project team for keeping the ZX Spectrum music heritage alive. Without their dedication, much of this music would have been lost to time.
Demoscene & Rust Communities
The Atari ST demoscene for three decades of incredible music and art that defined an era. The Rust community for creating a language that makes systems programming both safe and enjoyable.
Sebastian Magri
For unwavering moral support and encouragement throughout the development of this project. Sometimes the most valuable contribution is believing in someone's vision.