Crate ym2149

Crate ym2149 

Source
Expand description

YM2149 PSG Emulator for ATARI ST

A cycle-accurate emulator of the Yamaha YM2149 Programmable Sound Generator as integrated into the ATARI ST computer. Supports MFP timer integration, VBL synchronization, and playback of YM chiptune files.

§Features

  • Cycle-accurate emulation of all 3 audio channels
  • Full envelope generator support
  • MFP Timer A/B/C integration for modulation effects
  • 50Hz VBL (Vertical Blanking) synchronization
  • YM file format parser and playback
  • Raw register dump support
  • Audio sample generation and optional streaming playback

§Crate feature flags

  • emulator (default): Core YM2149 integer-accurate emulator (ym2149)
  • ym-format (default): YM file parsing/loader (ym_parser, ym_loader, compression)
  • replayer (default): YM replayer and effects decoding (replayer)
  • visualization (default): Terminal visualization helpers (visualization)
  • streaming (opt-in): Real-time audio output (enables optional rodio dep)
  • softsynth (opt-in): Experimental software synthesizer (softsynth)

§Quick start

§Core emulator only

use ym2149::ym2149::Ym2149;
let mut chip = Ym2149::new();
chip.write_register(0, 0x1C); // Tone A Lo
chip.write_register(1, 0x01); // Tone A Hi
chip.write_register(8, 0x0F); // Volume A
chip.clock();
let sample = chip.get_sample();

§Load and play YM (no streaming)

use ym2149::replayer::PlaybackController;
use ym2149::{load_song, Ym6Player};
// Buffer-based API: pass bytes (LHA-compressed OK)
let data = std::fs::read("song.ym").unwrap();
let (mut player, summary) = load_song(&data).unwrap(); // YM2–YM6 auto-detect
player.play().unwrap();
let audio = player.generate_samples(summary.samples_per_frame as usize);

§Real-time streaming

use ym2149::replayer::PlaybackController;
use ym2149::{load_song, RealtimePlayer, StreamConfig, AudioDevice};
let data = std::fs::read("song.ym").unwrap();
let (mut player, summary) = load_song(&data).unwrap();
player.play().unwrap();
let cfg = StreamConfig::low_latency(44_100);
let stream = RealtimePlayer::new(cfg).unwrap();
let _dev = AudioDevice::new(cfg.sample_rate, cfg.channels, stream.get_buffer()).unwrap();
// push samples into the stream in a loop

§File loader (frames from files or buffers)

// From a file path
let frames = ym2149::ym_loader::load_file("song.ym").unwrap();
assert!(!frames.is_empty());

// From an in-memory buffer
let data = std::fs::read("song.ym").unwrap();
let frames2 = ym2149::ym_loader::load_bytes(&data).unwrap();
assert_eq!(frames.len(), frames2.len());

Re-exports§

pub use ym2149::Ym2149;
pub use compression::decompress_if_needed;
pub use mfp::Mfp;
pub use replayer::load_song;
pub use replayer::LoadSummary;
pub use replayer::Player;
pub use replayer::Ym6Info;
pub use replayer::Ym6Player;
pub use replayer::YmFileFormat;
pub use softsynth::SoftPlayer;
pub use streaming::AudioDevice;
pub use streaming::RealtimePlayer;
pub use streaming::RingBuffer;
pub use streaming::StreamConfig;
pub use visualization::create_volume_bar;
pub use ym_parser::effects::decode_effects_ym5;
pub use ym_parser::effects::EffectCommand;
pub use ym_parser::effects::Ym6EffectDecoder;

Modules§

compression
Compression support for YM file formats
mfp
MFP (Multi-Function Peripheral) Integration
replayer
YM Music Playback Engine Domain
softsynth
Experimental software synthesizer (non-bit-accurate)
streaming
Streaming audio playback with minimal memory consumption
visualization
Terminal Visualization Utilities
ym2149
YM2149 PSG Emulation Domain
ym_loader
YM File Loader Domain
ym_parser
File Format Support

Enums§

Ym2149Error
Error types for YM2149 emulator operations

Type Aliases§

Result
Result type for emulator operations