Crate bevy_ym2149 

Bevy audio plugin for YM2149 PSG emulator

This crate provides a Bevy plugin for playing YM2149 audio files with real-time visualization using the high-fidelity ym2149 emulator library.

The plugin handles all aspects of YM file playback through Bevy’s ECS architecture:

• File loading and metadata extraction
• Time-accurate frame advancement and audio generation
• Real-time visualization of channel activity
• Flexible playback control (play, pause, restart, volume)

Features

• Real-time YM2149 Audio Playback: Stream YM2-YM6 format files with cycle-accurate emulation
• Flexible Playback Control: Play, pause, restart, volume adjustment, and loop support
• Live Channel Visualization: Real-time visual feedback for all three PSG channels with frequency/note info
• Metadata Display: Automatic extraction and display of song title and artist information
• Frame-by-Frame Access: Direct access to individual playback frames for analysis
• Time-Accurate Pacing: Proper time-based frame advancement matching original YM file rate
• Audio Buffering: Ring buffer architecture for smooth, artifact-free playback
• Multiple Playbacks: Support for simultaneous independent YM file playbacks

Quick Start

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("path/to/song.ym"));
}

Playback Control

Control playback through the Ym2149Playback component:

use bevy::prelude::*;
use bevy_ym2149::Ym2149Playback;

fn playback_control(
    mut playbacks: Query<&mut Ym2149Playback>,
    keyboard: Res<ButtonInput<KeyCode>>,
) {
    for mut playback in playbacks.iter_mut() {
        if keyboard.just_pressed(KeyCode::Space) {
            if playback.is_playing() {
                playback.pause();
            } else {
                playback.play();
            }
        }
        if keyboard.just_pressed(KeyCode::ArrowUp) {
            let new_volume = (playback.volume + 0.1).min(1.0);
            playback.set_volume(new_volume);
        }
    }
}

Visualization

Visualization widgets now live in the companion crate bevy_ym2149_viz. Add Ym2149VizPlugin alongside this crate’s Ym2149Plugin and use the helpers provided there to build UI components.

Architecture

The plugin uses Bevy’s ECS with three main systems:

1. Initialization - Loads YM files and creates emulator instances
2. Playback - Advances frames using time-based pacing and generates audio
3. Visualization - Updates UI with current playback state and channel information

Audio flows through a thread-safe ring buffer from the emulator to rodio’s audio device.

Module Organization

• playback - Core playback component and state management
• plugin - Bevy plugin integration and systems
• audio_source - YM file loading and Bevy audio integration via Decodable
• bevy_ym2149_viz - Optional UI components and display helpers

Re-exports

pub use plugin::Ym2149Plugin;

pub use plugin::Ym2149PluginConfig;

pub use playback::PlaybackState;

pub use playback::Ym2149Playback;

pub use playback::Ym2149Settings;

pub use chip_state::ChipStateSnapshot;

pub use error::BevyYm2149Error;

pub use error::Result;

pub use events::PatternTriggered;

pub use events::PlaybackFrameMarker;

pub use events::TrackFinished;

pub use events::TrackStarted;

pub use music_state::MusicStateDefinition;

pub use music_state::MusicStateGraph;

pub use patterns::PatternTrigger;

pub use patterns::PatternTriggerSet;

pub use playlist::CrossfadeConfig;

pub use playlist::PlaylistMode;

pub use playlist::PlaylistSource;

pub use playlist::Ym2149Playlist;

pub use playlist::Ym2149PlaylistPlayer;

pub use synth::YmSynthController;

pub use audio_bridge::AudioBridgeBuffers;

pub use audio_bridge::AudioBridgeMix;

pub use audio_bridge::AudioBridgeMixes;

pub use audio_bridge::AudioBridgeTargets;

pub use audio_bridge::BridgeAudioDevice;

pub use audio_bridge::BridgeAudioSinks;

pub use audio_source::Ym2149AudioSource;

pub use audio_source::Ym2149Loader;

pub use audio_source::Ym2149Metadata;

pub use oscilloscope::OscilloscopeBuffer;

pub use events::AudioBridgeRequest;

pub use events::ChannelSnapshot;

pub use events::MusicStateRequest;

pub use events::PlaylistAdvanceRequest;

pub use events::YmSfxRequest;

pub use playlist::CrossfadeTrigger;

pub use playlist::CrossfadeWindow;

pub use playlist::Ym2149PlaylistLoader;

pub use playlist::advance_playlist_players;

pub use playlist::drive_crossfade_playlists;

pub use playlist::handle_playlist_requests;

pub use playlist::register_playlist_assets;

pub use music_state::process_music_state_requests;

pub use diagnostics::BUFFER_FILL_PATH;

pub use diagnostics::FRAME_POSITION_PATH;

pub use diagnostics::register as register_diagnostics;

pub use diagnostics::update_diagnostics;

Modules

audio_bridge

Audio bridge for routing YM2149 audio to custom destinations.

audio_source

YM2149 audio source asset type for Bevy

chip_state

Shared snapshot of the YM2149 register state.

constants

YM2149 Hardware Constants

diagnostics

Bevy diagnostics integration for YM2149 playback monitoring.

error

Error types for the bevy_ym2149 plugin

events

Events emitted by the YM2149 plugin during playback.

music_state

Music state machine for adaptive audio.

oscilloscope

Oscilloscope buffer for real-time waveform visualization.

patterns

Pattern-triggered gameplay hooks for YM2149 playback.

playback

Playback components and systems for YM2149 audio

playlist

Playlist support for sequential track playback.

plugin

Plugin orchestration for YM2149 playback within Bevy.

presets

Convenience helpers to wire common YM2149 plugin stacks.

psg_bank

Multi-PSG Bank for Arkos Tracker and PlayCity support

synth

Software synthesizer using the YM2149 chip emulator.

Structs

PsgBank

A bank of multiple PSG chips for expanded polyphony.

Ym2149

YM2149 Programmable Sound Generator emulator

Enums

Ym2149Error

Error types for YM2149 chip emulator operations

Traits

MetadataFields

Unified metadata trait for chiptune playback.

Ym2149Backend

Common interface for YM2149 chip backends

Functions

get_volume

YM2149 envelope DAC table (32 steps, 5-bit resolution) Get volume level for amplitude register value (0-15)