a740g / qb64-mod-player

A MOD player & library for QB64-PE

QB64 MOD PLAYER

This is a MOD player and library written in QB64-PE.

It currently supports the following formats:

• ProTracker (and compatible)
• MultiTracker
• Scream Tracker

---

FEATURES

• No dependency on third party libraries
• Everything is statically linked (no shared library dependency)
• Easy plug-&-play API optimized for demos & games
• Cross-platform (works on Windows, Linux & macOS)
• Support all MOD types (1 - 99 channels, 31 samples etc.)
• Support all MOD effects
• Demo player that shows how to use the library

USAGE

• Clone the repository to a directory of your choice
• Open Terminal and change to the directory using an appropriate OS command
• Run git submodule update --init --recursive to initialize, fetch and checkout git submodules
• Open QB64MODPlayer.bas in the QB64-PE IDE and press F5 to compile and run
• To use the library in your project add the Toolbox64 repositiory as a Git submodule

API

' Main Player API
FUNCTION MODPlayer_GetName$
FUNCTION MODPlayer_GetOrders~%
FUNCTION MODPlayer_GetPosition&
FUNCTION MODPlayer_GetType$
SUB MODPlayer_GoToNextPosition
SUB MODPlayer_GoToPreviousPosition
FUNCTION MODPlayer_IsLooping%%
FUNCTION MODPlayer_IsPaused%%
FUNCTION MODPlayer_IsPlaying%%
FUNCTION MODPlayer_LoadFromDisk%% (fileName AS STRING)
FUNCTION MODPlayer_LoadFromMemory%% (buffer AS STRING)
SUB MODPlayer_Loop (state AS _BYTE)
SUB MODPlayer_Pause (state AS _BYTE)
SUB MODPlayer_Play
SUB MODPlayer_SetPosition (position AS _UNSIGNED INTEGER)
SUB MODPlayer_Stop
SUB MODPlayer_Update (bufferTimeSecs AS SINGLE)
' Sample Mixer API
FUNCTION SoftSynth_BytesToFrames~& (bytes AS _UNSIGNED LONG, bytesPerSample AS _UNSIGNED _BYTE, channels AS _UNSIGNED _BYTE)
SUB SoftSynth_Finalize
FUNCTION SoftSynth_GetActiveVoices~&
FUNCTION SoftSynth_GetBufferedSoundTime#
FUNCTION SoftSynth_GetGlobalVolume!
FUNCTION SoftSynth_GetMasterVolume!
FUNCTION SoftSynth_GetSampleRate~&
FUNCTION SoftSynth_GetTotalSounds~&
FUNCTION SoftSynth_GetTotalVoices~&
FUNCTION SoftSynth_GetVoiceBalance! (voice AS _UNSIGNED LONG)
FUNCTION SoftSynth_GetVoiceFrequency~& (voice AS _UNSIGNED LONG)
FUNCTION SoftSynth_GetVoiceVolume! (voice AS _UNSIGNED LONG)
FUNCTION SoftSynth_Initialize%%
FUNCTION SoftSynth_IsInitialized%%
SUB SoftSynth_LoadSound (snd AS LONG, buffer AS STRING, bytesPerSample AS _UNSIGNED _BYTE, channels AS _UNSIGNED _BYTE)
FUNCTION SoftSynth_PeekSoundFrameByte%% (snd AS LONG, position AS _UNSIGNED LONG)
FUNCTION SoftSynth_PeekSoundFrameInteger% (snd AS LONG, position AS _UNSIGNED LONG)
FUNCTION SoftSynth_PeekSoundFrameSingle! (snd AS LONG, position AS _UNSIGNED LONG)
SUB SoftSynth_PlayVoice (voice AS _UNSIGNED LONG, snd AS LONG, position AS _UNSIGNED LONG, mode AS LONG, startFrame AS _UNSIGNED LONG, endFrame AS _UNSIGNED LONG)
SUB SoftSynth_PokeSoundFrameByte (snd AS LONG, position AS _UNSIGNED LONG, frame AS _BYTE)
SUB SoftSynth_PokeSoundFrameInteger (snd AS LONG, position AS _UNSIGNED LONG, frame AS INTEGER)
SUB SoftSynth_PokeSoundFrameSingle (snd AS LONG, position AS _UNSIGNED LONG, frame AS SINGLE)
SUB SoftSynth_SetGlobalVolume (volume AS SINGLE)
SUB SoftSynth_SetMasterVolume (volume AS SINGLE)
SUB SoftSynth_SetTotalVoices (voices AS _UNSIGNED LONG)
SUB SoftSynth_SetVoiceBalance (voice AS _UNSIGNED LONG, balance AS SINGLE)
SUB SoftSynth_SetVoiceFrequency (voice AS _UNSIGNED LONG, frequency AS _UNSIGNED LONG)
SUB SoftSynth_SetVoiceVolume (voice AS _UNSIGNED LONG, volume AS SINGLE)
SUB SoftSynth_StopVoice (voice AS _UNSIGNED LONG)
SUB SoftSynth_Update (frames AS _UNSIGNED LONG)

FAQ

Why a MOD player in QB64?

• Just for learning and fun! Long answer: I have seen plenty of MOD players code and libraries in C & C++ but very little in other languages. I know about some JavaScript, Java and C# ones. But, I am not a fan of those languages. I learnt to code on DOS using QuickBASIC and then graduated to C & C++. So, QuickBASIC always had a special place in my heart. Then, I found QB64 on the internet and the rest is history. As far as I know this is the first of it's kind. Let me know if there are any other MOD players written in pure QB64.

Can you implment feature x / y?

• With the limited time I have between my day job, home and family, there is only so much I can do. I do maintain a list of TODO (see below). However, those do not have any set deadlines. If you need something implemented, submit a GitHub issue about it or do it yourself and submit a PR.

I found a bug. How can I help?

• Let me know using GitHub issues or fix it yourself and submit a PR!

Can this be used in a game / demo?

• Absolutely. The player UI code included in a great example.

You keep saying QB64-PE with miniaudio backend. Where is it?

• Glad you asked! IT, XM, S3M & MOD support is built into QB64-PE v3.1.0+.

I see that the miniaudio backend version of QB64-PE already has MOD, S3M, XM, IT, RADv2 & MIDI support. Why should I care about this?

• Honestly, you should not! The MOD re-player in QB64-PE with miniaudio backend uses Libxmp-lite and as such is good enough for most use cases. This is just something that I made just to see what can be done using just QB64-PE. If you want to see what MOD files are made of and what makes them tick, then by all means, have at it. There are some interesting things in the code for people who care about this kind of stuff. Also, my MOD re-player is more accurate than the one in Libxmp-lite... I hope. 😉

NOTES

• This requires the latest version of QB64-PE
• When you clone a repository that contains submodules, the submodules are not automatically cloned by default
• You will need to use the git submodule update --init --recursive to initialize, fetch and checkout git submodules

BIBLIOGRAPHY

• MOD Player Tutorial by FireLight
• S3M Player Tutorial by FireLight
• Noisetracker/Soundtracker/Protracker Module Format by Andrew Scott
• MODFIL10.TXT by Thunder
• Protracker Module from MultimediaWiki
• Scream Tracker 3 Module from MultimediaWiki
• S3M Format by ModdingWiki
• Scream Tracker 3 module from Solve the File Format Problem
• MultiTracker Module (MTM) Format by Renaissance
• Manual: Effect Reference from OpenMPT Wiki
• Weasel audio library by Warren Willmey
• Digital Audio Mixing Techniques by jedi / oxygen
• Writing Mixing Routines by BYTERAVER/TNT
• Audio Mixer Tutorial by benhenshaw

ASSETS

• Icon by Tsukasa-Tux (Azrael Jackie Lockheart)