Arkos Player Manual

Arkos Player code included in CPCtelera is a modification of the original code was developed by Targhan / Arkos.  This modification maintains the original spirit of Arkos Tracker and has just done changes to easily integrate it within the framework and Philosophy of CPCtelera.  Also, original code was configurable to run either on CPC or on MSX, but specific MSX code has been removed in this version.  The same was done with CPC-BASIC version.

This version does not make use of interrupts, requiring to be called manually at the correct framerate to reproduce the song.  Original comments from Targhan / Arkos have been kept unmodified, removing those referred to MSX / BASIC players or the original way to use this player (that has changed).

Original documentation from Targhan / Arkos, with some minor modification, follows.  Check this if you have special detail interest.  For a standard use from C functions, check each function’s documentation.

First of all, export any AKS or SKS (STarKos) song with the Arkos Tracker “Export as binary” option in File->Export as binary.  Export it at the address you want (from 0 to 0xFFFF).  Warning! if you want to use the Interruption mode, your song HAS TO BE generated above 0x3FFF, due to system limitations.  Namely, the range [0x0000-0x3FFF] is used by Lower ROM and shadows RAM, making any data there inaccessible.

If you don’t intend to export a SFX music, you can skip the next section.  Disable the “Export SFX only” option before clicking on “OK”.

So you want to use sound effects in your production.  These, of course, are made with AT, and it must be done in one single song dedicated to Sound Effects.  In the “Export as binary” panel is a tick-box called “Export SFX only”.  Enable it, and export the song.  Such songs will contains only the Instruments it is composed of.  All your Tracks will be cleared so that the song only contains what’s necessary (i.e. the sound effects!).

So as you’ve guess, if you want music + sound effects, you’ll need two files (one “music” file, and one “SFX” file).  Why did I do that ? Because “Music” files are very optimised, sounds are reorganised, so you’d lost track with where you put your sounds.  But most importantly, it’s very flexible this way.  Imagine you’re working on a game with 5 levels, each having a different song.  Do you want to include also all the SFXs inside these 5 songs ? Of course not !

The Instruments become your sound effects in your game / demo.  So note their number well !

What if I want to use only Sound effects, and no music?

It is possible ! This shall be explained a bit later when focusing on calling the player.

Once a binary file has been exported, you can use the player kindly given with this software.  Take a look at the examples included in examples/ folder.

In order to include the binary song in your program you may do these steps

• Convert the binary file to a C Array.  You may use cpct_bin2c script for this task.
• Include the C Array into a file in your project
• Use the file in your project calling Arkos Tracker Player’s CPCtelera C functions.  Imagine your song has been included as the C Array named “mysong”:

// Set up the song for playing
cpct_akp_musicInit(mysong);
// Main loop
while(1) {
   // Synchronize with Vertical VSYNC signal, which happens 50 times per second (frequency = 1/50)
   cpct_waitVSYNC();

   // Call music player 50 times per second, synchronized with VSYNC to have great precision
   cpct_akp_musicPlay();
}

• Important!  Your song data must be at the same location in memory that the one you choose when exporting it to binary (File->Export as binary) in Arkos Tracker.  To accomplish this, you sometimes will have to force SDCC to locate the C Array containing your song at the required place in memory.  Imagine that you wanted to locate your song at 0x0100 in memory; you can do it with this code:

__at(0x100) const unsigned char mysong[] = { ...

Though there is just one player, it can be used in three different mode

• Your production is done in Assembler.  You don’t mind if the player modifies all the registers.  If you need some registers to be saved, you will do it by yourself.  This is called the “ASM” mode.
• Your production is in C, but you want to have full control of the player.  You will manage to call the player every time, at your song’s required frequency.  This is the default way of using the player.
• Your production is either on C or ASM, but you don’t want to have fine-grained control of the player, and you just want the music to play, consuming whatever cycles it requires.  A simple call will put the music into interruption.  This is called the “INTERRUPTION” mode.  It is currently unavailable, but it will be on the near future.

At the present stage, you can use C and ASM modes, by calling to C or ASM functions directly.  When using ASM mode, if you want the player to explicitly preserve AMSDOS registers, you should enable PLY_SystemFriendly constant and recompile the library.

These are the functions available for C modes.  All of them may be called on ASM mode just by adding the suffix “_asm” to the name.  ASM mode lets you call the functions passing the parameters in registers, instead of using the stack

• cpct_akp_musicInit : Set up a new music file for reproducing
• cpct_akp_musicPlay : Reproduce a 1/nth of the song. nth depends on the frequency at which the song has been created.
• cpct_akp_stop : Stop all musing and sound effects.

The player allows the global volume to be modified.  However, this function is disabled by default, as it consumes a little more memory and CPU.  If you wanted to enable it, you should set PLY_UseFades to 1 and recompile the library.

The player provides the interface for fading, but you’ll have to set the volume by yourself.  Therefore, fading in or out consist on setting global volume progressively up or down by hand.  This is more flexible and powerful this way.

In assembler

ld a,Volume                       ;; (0=full volume, 16 or more=no volume)
call cpct_akp_setFadeVolume_asm   ;; Set the global volume

In C

u8 new_fade_volume = 1;
cpct_akp_setFadeVolume(new_fade_volume);

Sound Effects are defined in another song (which we will be refered as “SFX Music”), exported as a “SFX Music” in the Arkos Tracker.  Sound effects are activated by default in the player, but you may deactivate them by setting PLY_UseSoundEffects to 0 (if you wanted to save some memory and CPU for some reason).

Like any song, the SFX Music must be initialized, but with a specific function :

In Assembler

ld de, SFXMusicAddress      ;; DE = Pointer to SFX Music
call cpct_akp_SFXInit_asm   ;; Initialize instruments for SFX

In C

cpct_akp_SFXInit(my_music);

You may even use the same music file for music and SFX (that is, SFX will use same instruments as the music song),

ld de, musicAddress         ;; DE = pointer to music
call cpct_akp_SFXInit_asm   ;; Initialize instruments for SFX
ld de, musicAddress         ;; Make DE point to music again, as previous call may have corrupted it
call cpct_akp_musicInit     ;; Initialize instruments and music for music play

To play a sound effect, you must call the cpct_akp_SFXPlay function, which has a lot of parameters, channel_num ( A ) - Channel Number (1, 2 or 4, but better use AY_CHANNEL_A, AY_CHANNEL_B and AY_CHANNEL_C) constants. sfx_instrument ( L ) - SFX Number, that refers to the instrument to use for playing the SFX (>0) volume ( H ) - Volume from 0 to 15 (min to max) note ( E ) - Note (0...143) (0 is the lowest, 143 the highest) speed ( D ) - Speed (0 = As original, 1...255 = new Speed (1 is the fastest)) inverted pitch (BC) - BC = Inverted Pitch (-&FFFF -> &FFFF).  0 is no pitch (=the original sound).  The higher the pitch, the lower the sound.

To stop a sound effect playing on channel A,

cpct_akp_SFXStop(AY_CHANNEL_A);

To stop the sound effects on all the channels,

cpct_akp_SFXStopAll();

Obviously, SFXs are “added” to the music.  So you need to play the song to actually hear them ! Also, as they are adding another layer of sound to the player, they are consuming more CPU, especially if you’re playing SFXs on the three channels at once.

Also, note that triggering a sound over another one will cut this last one.

This is possible.  As you need a “music” to be playing in order to reproduce SFX, just initialize the music player with the SFX music you want to use.  SFX musics have a null music pattern, so no music will be played anyway.  Then initialize SFX with the same SFX music and start the player.  You will then be able to reproduce any FX sound you wanted to,

ld de, SFXMusicAddress        ;; DE = SFX Music (only instruments, no music pattern)
call cpct_akp_SFXInit_asm     ;; Initialize sound FX
ld de, SFXMusicAddress        ;; DE = SFX Music again
call cpct_akp_musicInit_asm   ;; Initialize music player with the SFX music

To test if a sound effect is over, you have to test if the channel where you reproduced your SFX is still reproducing or not.  This can be done using the cpct_akp_SFXGetInstrument.  This function returns the number of the instrument which is playing at a given sound channel, or 0 if the channel is not playing any SFX.  Then, you could do something like this,

// Check if a SFX is still playing in Channel A
if ( ! cpct_akp_SFXGetInstrument(AY_CHANNEL_A) ) {
   // ... Channel A is free (no SFX playing in) ...
} else {
   // ... A SFX is still playing on Channel A ...
}

Arkos Tracker provides a “low level” sound effects player, but it’s up to you to manage how to trigger them.  If a “bang” explosion shouldn’t be cut by a “jump” sound, then you have to manage a priority list of your sound effects.  It’s quite easy to code in your own SFX management code.

Digidrums are in fact only “events” sent by the player, for you to know you must trigger something.  For more flexibility, and as there are countless ways to play samples according to how to manage them, I chose not to include any code for playing sample.  It’s up to you.

After the song is played, simply read the cpct_akp_digidrumStatus variable.  If it’s 0, nothing happened.  Any other value means that a digidrum must be played.  The digidrum number is of course entered by the musician inside the song, so take care to communicate well how to designate the samples (for example 1=kick drum, 2=snare, ...).

One variation of the use of Digidrums is event signaling.  Imagine you want to synchronize your production with the music.  You can set “markers” in your song thanks to this.  For example, if the Digidrum “255” if played, it means that your next effect must appear.

To detect the end of a song, or the number of times it has looped, you should check the value of the global variable cpct_akp_songLoopTimes.  This global variable is set to 0 when calling cpct_akp_musicInit and updated by Arkos Player every time the song reaches its end.  Therefore, you just have to read its value to know if a song has ended / looped or how many times it has looped.

Please, take into account that cpct_akp_songLoopTimes is an u8 variable.  This means that, if a song loops more than 255 times, it will overflow and return to 0.

Relocating a song is complicated.  All data values inside the song point to absolute memory locations, and the format of the Instrument is not that simple.  The easiest way to relocate a song is to open it in Arkos Tracker and export it again to the desired new memory location address.

Well, as long as it won’t crash it, why not ? :) Arkos Traker Player and CPCtelera are distributed under GNU GPL license, that lets you do any changes that you like, provided that you distribute your modifications if you publicize your results.  Don’t forget that a lot of code is actually only assembled with conditions.  You don’t have to remove the SFX code part if PLY_UseSoundEffects is set to 0.  But,

• You can remove all the references to cpct_akp_digidrumStatus if you don’t use/need digidrums/events in your song.
• You can remove all the management of the Special Tracks if the song has no Speed change/Digidrums (from PLY_SpecialTrack_WaitCounter to PLY_SpecialTrack_Wait).
• You can remove the cpct_akp_stop function if you don’t intend to stop the song!