You are here:

Quick Music

QuickMusic was designed to handle the heavy lifting away from music files, allowing each piece of music to be very small, while also being versatile enough to support a wide range of instruments, configurations, and even lyrics. Because of this, QuickMusic itself is unfortunately a bit large compared to other music players. However, since almost all QMU files will be very small, this is aimed at having there be less loading time overall instead of the initial file being tiny.

This is also designed to work with or without QuickOS. See the NOQUICKOS configuration value to use this outside of QuickOS.

Functions

QuickMusic::Load

Load details about a piece of music in memory.

QuickMusic::Play

Starts playing the loaded piece of music, or unpauses if the current piece is paused.

QuickMusic::Stop

Stops playing the current piece of music.

QuickMusic::Pause

Pauses the current piece of music if it is playing.

QuickMusic::Clear

Clears all memory details of the loaded piece of music in memory.

QuickMusic::Mask

Masks channels from being used in music, immediately silencing them.

QuickMusic::HandleVBI

Call this in a custom VBI every time to have the music update as necessary.

Zero Page Values

QuickMusic::ZP_State

Byte, State data for QuickMusic. Test the high bit to see if anything is playing.

QUICKMUSIC_ZPSTATEFLAGS::Paused: Set if the active piece is paused. This is the second high bit.
QUICKMUSIC_ZPSTATEFLAGS::Playing: Set if the active piece is playing. This is the high bit.

QuickMusic::ZP_ActivePiece

Address, The address of the active piece being handled. This may be set even if the last attempted piece failed. See if LastErrorCode's high bit is clear to test if a valid piece is available.

QuickMusic::ZP_MeasureOffset

Byte, The offset into the current measure in note periods. Do not modify this.

QuickMusic::ZP_SystemFrame

INTERNAL USE ONLY: Address, The address of the active system frame data.

QuickMusic::ZP_ActiveFrame

INTERNAL USE ONLY: Address, The address of the active note frame.

QuickMusic::ZP_Temp

INTERNAL USE ONLY: 4 bytes, Temporary data as needed.

Values

QuickMusic::CallBack

Address, A call back to use when a code call back occurs in the piece. 0 to ignore. See CallBackData for up to 2 bytes of data being passed in from the piece.

WARNING: This WILL get called while in the VBI handler! Keep it very simple, preferably setting a value being tested in a main program loop instead.

QuickMusic::CallBackData

2 Bytes, Data values that the QMU file can pass to the call back.

QuickMusic::KaraokeScreen

Address, Where to display the 20-byte karaoke data. 0 to ignore karaoke output.

QuickMusic::AUDCTLShadow

Byte, A shadow for POKEY's AUDCTL. If QuickOS is used, this will be set to just point to QuickOS::AUDCTLShadow instead and won't exist in QuickMusic itself.

QuickMusic::AUDCTL2Shadow

Byte, A shadow for a secondary POKEY's AUDCTL.

This is never used if a second POKEY isn't supported.

Internal Data Values

Don't modify these values directly. They are exposed for QMU players to be able to list additional data about the music being played.

QuickMusic::Memory

Word, The amount of memory detected, in KB. Requires QuickBank to be accurate.

QuickMusic::LastErrorCode

Byte, The last load error code encountered. This is only updated when using QuickMusic::Load. See Load Error Codes for details.

QuickMusic::FrameCounter

Byte, A counter for the number of frames that have happened since the last event.

QuickMusic::PlayRate

Byte, The current play rate, in frames per period.

QuickMusic::NumVoice

Byte, The number of voices in this piece.

QuickMusic::NumInstrument

Byte, The number of instruments in this piece.

QuickMusic::NumNoteTable8

Byte, The number of 8-bit note tables.

QuickMusic::NumNoteTable16

Byte, The number of 16-bit note tables.

QuickMusic::NumSystemFrame

Byte, The number of system frames.

QuickMusic::NumKaraoke

Byte, The number of karaoke strings.

QuickMusic::NumMeasure

Byte, The number of measures in this piece.

QuickMusic::Measure

Byte, Which measure is currently being used. 1-based. This is 0 if not playing something.

QuickMusic::NextMeasure

Byte, The next measure to play. This is used internally to control repeats.

QuickMusic::MeasureLength

Byte, The number of note periods in the current measure.

QuickMusic::Verse

Byte, The verse currently playing. Generally only used for karaoke text and repeats. 0-based.

QuickMusic::AddDataFlags

Byte, Additional data available in the piece. You won't need to use this.

QuickMusic::FullData

Address, The full internal data used by QuickMusic. This is for players or debug access to internal data, such as note tables, instruments, etc.

QuickMusic::Version

DWord, The version of QuickMusic. This is in $xxyyzzaa format matching version x.y.z.a. As always, the data is stored little endian, so version 1.2.3.4 would be $04, $03, $02, $01 in memory. In general, just access QuickMusic::FULLVERSION instead when assembling QuickMusic files.

Load Error Codes

The full list of error codes would go here, for use in a QMU player for determining problems when trying to load a piece of music.

Configuration

All of the following are defined in Config/QuickMusic.inc, and are accessed under QuickMusic_Config.

Main Configuration

QuickMusic_Config::ZeroPageStart

Default: QuickOS::ZP_FullOSEnd

ZP Address, The first zero page entry to use.

QuickMusic_Config::StartAddress

Default: $1000

Address, The start address for this module.

QuickMusic_Config::DataAddress

Default: 0

Address, Where the data begins in memory. Use a 0 to include it just after the module itself.

QuickMusic_Config::INCLUDEDATAINBINARY

Default: 0

Boolean, >0 to include the data in output binary. This is necessary if the module has other data or code after it. This does nothing if DataAddress is non-zero.

QuickMusic_Config::ERRORTESTTYPE

Default: 0

Byte, The type of error testing to do.

0

Minimal. Best for releases or uses in games, but invalid music data may cause QuickMusic to crash.

1

General. Useful for loading music files and getting general errors to fail, such as testing if your music files are ready for release.

This adds quite a bit of additional code.

2

Full. This tests all sorts of extra details to very thoroughly test all of the data in each file loaded. This should only be used in an editor or general-use player.

This adds a LOT of additional code.

QuickMusic_Config::INITIALAUDCTL

Default: $00

Byte, The initial AUDCTL value to use whenever resetting/initializing the music system.

Max Allocation Counts

QuickMusic_Config::MAXVOICE

Default: 4

Byte, The maximum number of voices to support. 1 to 8 are supported, but going above 4 requires having double POKEYs.

Voices add a significant amount of memory usage each.

QuickMusic_Config::MAXINSTRUMENT

Default: 10

Byte, The maximum number of instruments to support. 1 to 128 are supported.

Allocates 6 * MAXINSTRUMENT bytes.

QuickMusic_Config::MAXVOLUMEADJUST

Default: 20

Byte, The maximum volume adjust events allowed in an instrument.

Changing this doesn't change memory usage and it is only used to test against bad data.

This should never be greater than 125.

QuickMusic_Config::MAXAUTOVIBRATO

Default: 10

Byte, The maximum auto vibrato table entries allowed in an instrument.

Changing this doesn't change memory usage, but larger auto-vibrato tables cost more cycles to

handle for those voices.

This should never be greater than 80.

QuickMusic_Config::MAXNOTETABLE8

Default: 8

Byte, The maximum number of 8-bit note tables to support. 0 to 128 are supported.

If 0, 8-bit instruments are not supported.

This or MAXNOTETABLE16 must be non-zero.

Allocates 2 * MAXNOTETABLE8 bytes.

QuickMusic_Config::MAXNOTETABLE16

Default: 4

Byte, The maximum number of 16-bit note tables to support. 0 to 128 are supported.

If 0, 16-bit instruments are not supported.

This or MAXNOTETABLE8 must be non-zero.

Allocates 2 * MAXNOTETABLE16 bytes.

QuickMusic_Config::MAXSYSTEMFRAME

Default: 40

Byte, The maximum number of system frames to support. 1 to 128 are supported.

Allocates 2 * MAXSYSTEMFRAME bytes, or 2 bytes per system frame.

QuickMusic_Config::MAXNOTEFRAME

Default: 40

Byte, The maximum number of note frames to support per voice. 1 to 128 are supported.

Allocates 2 * MAXVOICE * MAXNOTEFRAME bytes, or 2 bytes per note frame per voice.

QuickMusic_Config::MAXMEASURE

Default: 80

Byte, The maximum number of measures to support. 1 to 128 are supported.

Allocates 2 * MAXMEASURE bytes, or 2 bytes per measure.

QuickMusic_Config::MAXKARAOKESTRING

Default: 40

Byte, The maximum number of karaoke strings to support. 0 to 128 are supported.

If 0, karaoke support is completely disabled.

Allocates 2 * MAXKARAOKESTRING bytes, or 2 bytes per karaoke string.

Double POKEY Support

QuickMusic_Config::DOUBLEPOKEY

Default: 0

Boolean, >0 if there is support for two POKEYs, doubling the channels and voices available.

QuickMusic_Config::INITIALIZEAUDCTL2

Default: $00

Byte, The initial AUDCTL2 value to use whenever resetting/initializing the music system. This gets set before AUDCTL in case only one POKEY exists. It isn't used if DOUBLEPOKEY is clear.

Special Configuration

These are additional values to set before creating your instance of QuickMusic that govern how some things work internally.

NOQUICKOS

Any, If defined, QuickOS is not available. This lets QuickMusic operate without it.

QUICKMUSIC_CONFIGPATH

String, This is used to let QuickMusic know the path to use to access the local config files. It is relative to the Include/ subdirectory under QuickMusic.

This is optional if QuickOS is used and QUICKOS_CONFIGPATH can be used for both.

QuickMusic File Format (QMU)

The QMU file format will be included later.

Change Log

This is only here temporarily.

v0.2.0.0

2023-01-28

Added separate PAL support for play rate in the header and with QMU_SYSTEMCOMMAND::SetPlayRate.

This required a new version of QMU file, hence the minor version update.
Added QuickMusic::Pause support, as well as continuing via QuickMusic::Play.
Slimmed down Load with QuickMusic_Config::ERRORTESTTYPE of 0.
Removed Status and StatusCallBack. These don't make sense to support.

v0.1.0.0

2023-01-17

INITIAL VERSION

Not actually released, but this was used in Atlan Roland's Ultima V alpha build.