ym64.h File Reference

Player for the .YM64 module format (Arkos Tracker 2) More...

Go to the source code of this file.

Data Structures
struct	ym64player_t
	Player of a .YM64 file. More...
struct	ym64player_songinfo_t
	Structure containing information about a YM song. More...

Functions
void	ym64player_open (ym64player_t *player, const char *fn, ym64player_songinfo_t *info)
	Open a YM64 file for playback. More...
int	ym64player_num_channels (ym64player_t *player)
	Return the number of channels used in the mixer for playback. More...
void	ym64player_play (ym64player_t *player, int first_ch)
	Start playback of a YM file. More...
void	ym64player_duration (ym64player_t *player, int *len, float *secs)
	Read the total duration the YM module. More...
void	ym64player_tell (ym64player_t *player, int *pos, float *secs)
	Read the current position of the YM module. More...
bool	ym64player_seek (ym64player_t *player, int pos)
	Seek to a specific position in the YM module. More...
void	ym64player_stop (ym64player_t *player)
	Stop YM playback. More...
void	ym64player_close (ym64player_t *player)
	Close and deallocate the YM64 player.

Detailed Description

Player for the .YM64 module format (Arkos Tracker 2)

ym64player_t is a player of the .YM64 file format, which is based on the .YM module format, a format first popularized in the Atari ST emulator scene.

The format is based around the very popular AY-3-8910 sound chip, that was powering a few successful 8-bit consoles such as Atari ST, ZX Spectrum and Amstrad CPC. It is a 3-channel PSG with envelope support. It can produce typical 8-bit "chiptune" music scores. Nowadays, it is possible to compose soundtracks using the Arkos Tracker 2 tool, that exports in the YM format.

The YM format is a simple dump of the state of all registers of the AY chip at a fixed time step. To playback, it is necessary to emulate the AY PSG. The implementation has been carefully optimized for the N64 MIPS CPU for high-performance, so that playback typically takes less than 5% of CPU time, plus a few percents of RSP time for resampling and mixing (done by the mixer).

The YM64 is actually a valid YM file that has been simply normalized against the different existing revisions, in a way to be efficient for reproduction on N64. audioconv64 can convert YM to YM64 (or leave them as-is if they already fully compatible).

The main conversion option to pay attention too is whether the output file must be compressed or not. Compressed files are smaller but takes 18 KiB more of RDRAM to be played back and cannot be seeked.

This player is dedicated to the late Sir Clive Sinclair whose computer, powered by the AY-3-8910, helped popularize what we now call chiptune music. – Rasky

---

Data Structure Documentation

ym64player_t

struct ym64player_t

Player of a .YM64 file.

This structure holds the state a player of a YM64 module. It can be initialized using ym64player_open, and played with ym64player_play.

See the rest of this module for more functions.

Data Fields
waveform_t	wave	waveform for playback with the mixer
FILE *	f	Open file handle.
void *	decoder	Optional LHA decoder (compressed YM files)
int	start_off	Starting offset of the first audio frame.
AY8910	ay	AY8910 emulator.
uint8_t	regs[16]	Current cached value of the AY registers.
uint32_t	nframes	Number of YM audio frames.
uint32_t	chipfreq	Operating frequency of the AY chip.
uint16_t	playfreq	Frequency of an audio frame (typically 50Hz or 60Hz)
int	curframe	Current audio frame being played.
int	first_ch	First channel used in the mixer for playback.

ym64player_songinfo_t

struct ym64player_songinfo_t

Structure containing information about a YM song.

Data Fields
char	name[128]	Name of the song.
char	author[128]	Author of the song.
char	comment[128]	Comment of the song.

Function Documentation

ym64player_open()

void ym64player_open	(	ym64player_t *	player,
		const char *	fn,
		ym64player_songinfo_t *	info
	)

Open a YM64 file for playback.

Parameters

[in]	player	YM64 player to initialize
[in]	fn	Filename of the XM64 (with filesystem prefix, e.g. rom://).
[out]	info	Optional structure to fill with information on the song (pass NULL if not needed)

ym64player_num_channels()

int ym64player_num_channels

(

ym64player_t *

player

)

Return the number of channels used in the mixer for playback.

Depending on the AY emulator compile-time settings, this could be either 1 or 2 (mono or stereo). Notice that the YM64 currently mixes itself the 3 internal channels of the AY8910 chip, so only a final output stream is passed to the mixer.

Parameters

[in]

player

YM64 player

Returns

Number of mixer channels.

ym64player_play()

void ym64player_play	(	ym64player_t *	player,
		int	first_ch
	)

Start playback of a YM file.

Parameters

[in]	player	YM64 player
[in]	first_ch	First mixer channel to use for playback

ym64player_duration()

void ym64player_duration	(	ym64player_t *	player,
		int *	len,
		float *	secs
	)

Read the total duration the YM module.

The function returns the total duration of the YM module, in ticks (internal YM position) or seconds. You can pass NULL to information that you are not interested in receiving.

Parameters

[in]	player	YM64 player
[out]	len	Total duration in ticks
[out]	secs	Total duration in seconds

ym64player_tell()

void ym64player_tell	(	ym64player_t *	player,
		int *	pos,
		float *	secs
	)

Read the current position of the YM module.

The function returns the current position expressed in ticks (internal YM position), and also expressed as number of seconds. You can pass NULL to information that you are not interested in receiving.

Parameters

[in]	player	YM64 player
[out]	pos	Current position in ticks
[out]	secs	Current position in seconds

ym64player_seek()

bool ym64player_seek	(	ym64player_t *	player,
		int	pos
	)

Seek to a specific position in the YM module.

The function seeks to a new absolute position expressed in ticks (internal YM position). Notice that it's not possible to seek in a YM64 file that has been compressed. audioconv64 compresses YM files by default.

Parameters

[in]	player	YM64 player
[out]	pos	Absolute position in ticks

Returns

True if it was possible to seek, false if the file is compressed.

ym64player_stop()

void ym64player_stop

(

ym64player_t *

player

)

Stop YM playback.

The YM module will keep the current position. Use ym64player_play to continue playback.