Struct ym_file_parser::YmSong

pub struct YmSong {
    pub version: YmVersion,
    pub created: Option<NaiveDateTime>,
    pub song_attrs: SongAttributes,
    pub title: String,
    pub author: String,
    pub comments: String,
    pub chipset_frequency: u32,
    pub frame_frequency: u16,
    pub loop_frame: u32,
    pub frames: Box<[YmFrame]>,
    pub dd_samples: Box<[u8]>,
    pub dd_samples_ends: [usize; 32],
    /* private fields */
}

The YM music file.

The YM-file consist of YmFrames that represent the state of the AY/YM chipset registers and contain additional information about special effects.

Depending on the YmSong::version special effects are being encoded differently.

Fields

version: YmVersion

YM-file version.

created: Option<NaiveDateTime>

The last modification timestamp of the YM-file from the LHA envelope.

song_attrs: SongAttributes

The song attributes.

title: String

The song title or a file name.

author: String

The song author.

comments: String

The comment.

chipset_frequency: u32

The number of cycles per second of the AY/YM chipset clock.

frame_frequency: u16

The number of frames played each second.

loop_frame: u32

The loop frame index.

frames: Box<[YmFrame]>

The AY/YM state frames.

dd_samples: Box<[u8]>

DIGI-DRUM samples.

dd_samples_ends: [usize; 32]

DIGI-DRUM sample end indexes in YmSong::dd_samples.

Implementations

impl YmSong

pub fn parse_any<R, S>(rd: R, file_name: S) -> Result<YmSong>where R: Read + Seek, S: Into<String>,

Attempts to parse an YM-file that can be either compressed or uncompressed, from the given stream source.

Provide file_name which will be used as a fallback song title.

Returns an instance of YmSong on success.

pub fn parse_unpacked<R, S>(rd: R, file_name: S) -> Result<YmSong>where R: Read + Seek, S: Into<String>,

Attempts to parse an uncompressed YM-file from the given stream source.

Provide file_name which will be used as a fallback song title.

Returns an instance of YmSong on success.

pub fn parse<R: Read>(rd: R) -> Result<YmSong>

Attempts to parse a compressed YM-file from the given stream source.

Returns an instance of YmSong on success.

impl YmSong

pub fn reset(&mut self)

Resets the state of the player.

pub fn cursor(&self) -> u32

Returns the current frame cursor value.

pub fn produce_next_ay_frame<F: FnMut(f32, u8, u8)>(&mut self, rec: F) -> bool

Produces the changes to the AY/YM chipset registers for the current frame indicated by the cursor and advances the cursor forward one frame.

Provide a function that receives 3 arguments:

• The timestamp as a cycle relative to the current frame, where 0.0 is the beginning of a frame. The timestamp will be always larger than 0.0 and less than the value returned from YmSong::frame_cycles.
• The modified register’s number [0, 13].
• The modified register’s new value.

The changes are always being provided in the ascending order of the timestamp.

Returns true if this was the last frame before the cursor has been set to the loop frame. Otherwise returns false.

This method can be used to populate changes to the AY/YM chipset or an emulator, to play the YM-file song.

impl YmSong

pub fn new( version: YmVersion, frames: Box<[YmFrame]>, loop_frame: u32, title: String, created: Option<NaiveDateTime> ) -> YmSong

Creates a new instance of YmSong from the given frames and other meta data.

pub fn with_meta(self, author: String, comments: String) -> YmSong

Returns YmSong with the author and comments set from the given arguments.

pub fn with_samples( self, song_attrs: SongAttributes, dd_samples: Box<[u8]>, dd_samples_ends: [usize; 32] ) -> YmSong

Returns YmSong with the song_attrs, dd_samples and dd_samples_ends set from the given arguments.

pub fn with_frequency( self, chipset_frequency: u32, frame_frequency: u16 ) -> YmSong

Returns YmSong with the chipset_frequency and frame_frequency set from the given arguments.

pub fn song_duration(&self) -> Duration

Returns the song duration.

pub fn clock_frequency(&self) -> f32

Returns the AY/YM chipset clock frequency.

pub fn frame_cycles(&self) -> f32

Returns the number of AY/YM chipset clock cycles of a single music frame.

pub fn timer_interval(&self, divisor: NonZeroU32) -> f32

Calculates the timer interval in clock cycles, from the given divisor.

pub fn sample_data_range(&self, sample: usize) -> Range<usize>

Returns the indicated sample data range in the YmSong::dd_samples for the given sample.

Panics

Panics if sample value is not below MAX_DD_SAMPLES.

Trait Implementations

impl Clone for YmSong

fn clone(&self) -> YmSong

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for YmSong

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.