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.

7

File Formats

10

Crates

165+

Tests

147KB

WASM Size

100%

Pure Rust

MIT

License

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

ST

Atari ST

CPC

Amstrad CPC

ZX

ZX Spectrum 128

MSX

MSX

ARC

Arcade

VEC

Vectrex

Technical Highlights

Not a wrapper around C code — pure Rust from chip to speaker

EMULATION

Cycle-Accurate Core

Precise emulation of all PSG features — envelopes, noise, mixer, SID voice, Sync Buzzer, and digi-drum effects.

MULTI-CHIP

Multi-PSG Support

Run multiple YM2149 chips in parallel — natively supported via Arkos Tracker for authentic dual/triple-chip music.

SNDH

68000 CPU Emulation

Full Motorola 68000 emulation for SNDH playback — runs original Atari ST music drivers cycle-accurately.

FORMATS

Seven File Formats

YM (1-6), YMT1/YMT2, GIST (.snd), Arkos Tracker (.aks), ZXAY/EMUL (.ay), and SNDH with LHA/ICE decompression.

WASM

Browser Ready

Compact WebAssembly module (147KB) runs in any modern browser with Web Audio API support.

QUALITY

Production Ready

165+ tests, documented APIs, real-world demoscene fixtures, and continuous integration.

Architecture

Modular layers from hardware emulation to game integration

Applications

bevy_ym2149

Game Plugin

ym2149-wasm

Browser Player

replayer-cli

Terminal Player

Format Replayers

ym-replayer

YM1-6, YMT

sndh-replayer

SNDH + 68000

ay-replayer

AY, ZXAY

arkos-replayer

Multi-PSG

Core Emulation

ym2149-core

PSG Chip Emulation

ym2149-common

Shared Traits

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:

+

32-step envelope DAC (vs 16-step) for smoother volume ramps

+

Selectable clock divider (pin 26) - divide by 1 or 2

+

Lower power consumption - CMOS vs NMOS

~

Different volume curve - YM2149 sounds "softer"

~

2V DC offset (vs 0.2V on AY) - affects mixing

~

Envelope runs 2x faster at same period setting

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	10 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.

// Frequency formula

f = clock / (16 × period)

// Example: A4 (440Hz)

period = 284

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.

// LFSR feedback (XOR taps)

bit[0] ^ bit[2]

// Period range

0-31 (5-bit)

Envelope Generator

A single shared envelope generator with 10 unique shapes (16 register values map to 10 patterns). The YM2149 uses 32-step resolution (5-bit DAC) for smoother envelopes than the AY-3-8910’s 16 steps.

// 10 unique envelope shapes

___ /___ \\ ___ // \¯¯¯ //// /¯¯¯ //\ /___

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-R3	Tone B	12-bit	Channel B period
R4-R5	Tone C	12-bit	Channel C period
R6	Noise Period	4-0	Noise generator period (0-31)
R7	Mixer	5-0	Tone/Noise enable per channel (active low)
R8	Amplitude A	4-0	Volume (0-15) or envelope mode (bit 4)
R9-RA	Amplitude B/C	4-0	Volume or envelope mode
RB-RC	Envelope Period	16-bit	Envelope frequency period
RD	Envelope Shape	3-0	Envelope waveform (0-15)

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 Effect

By synchronizing the envelope generator with the tone generator, musicians could create rich, buzzing timbres with overtones.

// Sync-buzz setup

tone_period = N

env_period = N × 16

amplitude = 0x10

🥁

DigiDrum

Sample Playback

By rapidly updating volume registers at high frequencies, the chip can play back digitized samples like drum hits or speech.

// 4-bit sample

for s in samples:

R8 = s & 0x0F

🎹

SID Voice

Software Waveform Synthesis

Inspired by the C64’s SID chip, this technique uses rapid volume changes to synthesize custom waveforms.

// Triangle wave

vol = [0..15,14..1]

⏱️

Timer Effects

Hardware Timer Abuse

Using the Atari ST’s MFP timers to update registers mid-frame enables multiplexing more than 3 channels.

// 6 voices on 3 ch

Timer @ 15.6kHz

IRQ: swap voices

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

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

cargo install ym2149-replayer-cli

Crates

Modular architecture - use only what you need

ym2149-core

Core YM2149F/AY-3-8910 emulation with cycle-accurate sound synthesis

cargo add ym2149-core

ym2149-sndh-replayer

SNDH format player for Atari ST music with 68000 emulation

cargo add ym2149-sndh-replayer

ym2149-ym-replayer

YM file format player with support for interleaved and non-interleaved files

cargo add ym2149-ym-replayer

ym2149-ay-replayer

AY file format player for ZX Spectrum and Amstrad CPC music

cargo add ym2149-ay-replayer

ym2149-replayer-cli

Terminal-based player with TUI visualization, playlist support

cargo install ym2149-replayer-cli

ym2149-wasm

WebAssembly bindings for browser-based chiptune playback

cargo add ym2149-wasm

bevy_ym2149

Bevy game engine plugin for chiptune audio

cargo add bevy_ym2149

Live Demo

Experience YM2149 emulation directly in your browser

Loading WebAssembly...

Quick Start

Get started with just a few lines of code

MV

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.

Demoscene Atari ST Rust Open Source

External References

Essential resources for chiptune enthusiasts and developers

Acknowledgements

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.