ym2149_gist_replayer/
lib.rs

1//! GIST Sound File Parser and Multi-PSG Player for YM2149
2//!
3//! This crate provides a parser and player for GIST (Graphics, Images, Sound, Text)
4//! sound effect files, originally used on the Atari ST. GIST was developed by Dave Becker
5//! and distributed by Antic Software in the late 1980s.
6//!
7//! # Overview
8//!
9//! GIST sound effects are 112-byte definitions that describe complex synthesizer patches
10//! with ADSR-style envelopes for volume, frequency, and noise, plus LFO modulation for
11//! vibrato, tremolo, and noise effects.
12//!
13//! The driver processes sounds at 200 Hz (matching the Atari ST Timer C rate) and supports
14//! up to 3 simultaneous voices on a single YM2149 PSG chip.
15//!
16//! # Quick Start
17//!
18//! For simple playback, use `GistPlayer`:
19//!
20//! ```rust,no_run
21//! use ym2149_gist_replayer::{GistPlayer, GistSound};
22//!
23//! // Load and play a sound effect
24//! let sound = GistSound::load("effect.snd").unwrap();
25//! let mut player = GistPlayer::new();
26//!
27//! player.play_sound(&sound, None, None);
28//!
29//! // Generate audio samples
30//! while player.is_playing() {
31//!     let samples = player.generate_samples(882); // ~20ms at 44100 Hz
32//!     // Send samples to audio output...
33//! }
34//! ```
35//!
36//! # Low-Level API
37//!
38//! For more control, use `GistDriver` directly with a `Ym2149` chip:
39//!
40//! ```rust,no_run
41//! use ym2149::Ym2149;
42//! use ym2149_gist_replayer::{GistDriver, GistSound, TICK_RATE};
43//!
44//! let sound = GistSound::load("effect.snd").unwrap();
45//! let mut chip = Ym2149::new();
46//! let mut driver = GistDriver::new();
47//!
48//! driver.snd_on(&mut chip, &sound, None, None, -1, i16::MAX - 1);
49//!
50//! // In your audio loop, call tick() at 200 Hz
51//! while driver.is_playing() {
52//!     driver.tick(&mut chip);
53//!     // Generate samples from chip...
54//! }
55//! ```
56//!
57//! # Sound Structure
58//!
59//! Each GIST sound contains:
60//! - **Duration**: How long the sound plays in ticks (200 Hz)
61//! - **Tone parameters**: Initial frequency, envelope, and LFO settings
62//! - **Noise parameters**: Initial noise frequency, envelope, and LFO settings
63//! - **Volume envelope**: ADSR-style envelope with LFO modulation
64//!
65//! Values use 16.16 fixed-point format for smooth envelope transitions.
66
67mod gist;
68mod player;
69
70// Core types
71pub use gist::TICK_RATE;
72pub use gist::driver::GistDriver;
73pub use gist::gist_sound::GistSound;
74
75// High-level player
76pub use player::{DEFAULT_SAMPLE_RATE, GistMetadata, GistPlayer};
77
78// Re-export common traits for convenience
79pub use ym2149_common::{ChiptunePlayer, ChiptunePlayerBase, PlaybackState};
ym2149_gist_replayer/lib.rs

ym2149_gist_replayer/
lib.rs
