# Arkos Player Manual

Summary

Arkos Player Manual |
About Arkos Player | Arkos Player code included in CPCtelera is a modification of the original code was developed by Targhan / Arkos.
How to use the player | So you’ve got a great song ready, and you want to use it on CPC.
How to create usable files | First of all, export any AKS or SKS (STarKos) song with the Arkos Tracker “Export as binary” option in File->Export as binary.
Sound effects music | So you want to use sound effects in your production.
Using the music file | Once a binary file has been exported, you can use the player kindly given with this software.
Using the player |
Fade in / out | The player allows the global volume to be modified.
Sound Effects | Sound Effects are defined in another song (which we will be refered as “SFX Music”), exported as a “SFX Music” in the Arkos Tracker.
What if I don’t want any music, and only SFXs? | This is possible.
How to test a sound effect is over? | 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.
How to test a priority of a sound effect over another? | Arkos Tracker provides a “low level” sound effects player, but it’s up to you to manage how to trigger them.
Digidrums | Digidrums are in fact only “events” sent by the player, for you to know you must trigger something.
Random Questions |
How to detect the song is over | 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.
How to relocate songs | Relocating a song is complicated.
Can I remove parts of the code if I need memory ? | Well, as long as it won’t crash it, why not ?
Credits and Some technical details |

### About Arkos Player

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.

## How to use the player

So you’ve got a great song ready, and you want to use it on CPC. Or you have converted a STarKos song into a Arkos Tracker (AT) song, in order to use the new player. How clever you are.

This player will allow you to,

- Play any exported song on CPC
- Play Sound Effects along with any music. Or Sound Effects only!
- Play music and sound effects in C or Assembler
- Fade in / out the music.

On the Sound Effects side, you’ll be able to,

- Play any of your Sound Effects on any, or all of the 3 channels.
- Play a SFX on the note you want.
- Add Pitch if you want (it’s great if you want to add a little randomness to the sound).
- Play a SFX with the volume you want.
- Play a SFX at the speed it has been created, or faster or slower.
- Stop any SFX that has been triggered.
- Up to 255 SFXs available !

Also, the player is the fastest ever (25 scanlines max on a CPC), the music are light, so why wait ?

Summary

How to create usable files | First of all, export any AKS or SKS (STarKos) song with the Arkos Tracker “Export as binary” option in File->Export as binary.
Sound effects music | So you want to use sound effects in your production.
Using the music file | Once a binary file has been exported, you can use the player kindly given with this software.
Using the player |
Fade in / out | The player allows the global volume to be modified.
Sound Effects | Sound Effects are defined in another song (which we will be refered as “SFX Music”), exported as a “SFX Music” in the Arkos Tracker.
What if I don’t want any music, and only SFXs? | This is possible.
How to test a sound effect is over? | 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.
How to test a priority of a sound effect over another? | Arkos Tracker provides a “low level” sound effects player, but it’s up to you to manage how to trigger them.
Digidrums | Digidrums are in fact only “events” sent by the player, for you to know you must trigger something.

### How to create usable files

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”.

### Sound effects music

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.

### Using the music file

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[] = { ...

### Using the player

#### 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.

### Fade in / out

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

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.

### What if I don’t want any music, and only SFXs?

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

### How to test a sound effect is over?

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 ...
>     }

### How to test a priority of a sound effect over another?

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

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.

## Random Questions

Summary

How to detect the song is over | 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.
How to relocate songs | Relocating a song is complicated.
Can I remove parts of the code if I need memory ? | Well, as long as it won’t crash it, why not ?

### How to detect the song is over

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.

### How to relocate songs

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.

### Can I remove parts of the code if I need memory ?

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!

## Credits and Some technical details

#### Version and credits

- [21/09/2009] Arkos Tracker Player V1.01 - CPC & MSX version (by Targhan/Arkos)
- [07/04/2015] CPCtelera’s Arkos Player CPC-only version (by ronaldo / Fremos / Cheesetea / ByteRealms).
- PSG registers sendings based on Madram/Overlander’s optimisation trick. Restoring interruption status snippet by Grim/Arkos.

#### Additions to V1.01

- Small (but not useless !) optimisations by Grim/Arkos at the PLY_Track1_WaitCounter / PLY_Track2_WaitCounter / PLY_Track3_WaitCounter labels.
- Optimisation of the R13 management by Grim/Arkos.

#### Register modification

- This player modifies all these registers = hl, de, bc, AF, hl’, dE’, BC’, AF’, IX, IY.
- The Stack is used in conventional manners (Call, Ret, Push, Pop) so integration with any of your code should be seamless.
- The player does NOT modify the Interruption state, unless you use the PLY_SystemFriendly flag, which will cut the interruptions at the beginning, and will restore them ONLY IF NEEDED.

#### Fades in / out

- The player allows the volume to be modified. It provides the interface, but you’ll have to set the volume by yourself.
- Set PLY_UseFades to 1.
- In Assembler

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

#### Sound Effects

- The player manages Sound Effects. They must be defined in another song, generated as a “SFX Music” in the Arkos Tracker.
- Set the PLY_UseSoundEffects to 1.
- In Assembler:

>     ld de, SFXMusicAddress
>     call cpct_akp_SFXInit_asm   ;; to initialise the SFX Song.

- Then initialise and play the “music” song normally.
- To play a sound effect

>     ;; A = No Channel (0,1,2)
>     ;; L = Instrument Number (>0)
>     ;; H = Volume (0...F)
>     ;; E = Note (0...143)
>     ;; D = Speed (0 = As original, 1...255 = new Speed (1 is the fastest))
>     ;; BC = Inverted Pitch (-#FFFF -> FFFF). 0 is no pitch. The higher the pitch, the lower the sound.
>     call cpct_akp_SFXPlay_asm

- To stop a sound effect

>     ld a, NoChannel       ; (0,1,2)
>     call cpct_akp_SFXStop_asm

- To stop the sound effects on all the channels

>     call cpct_akp_SFXStopAll_asm

For more information, check the manual. Any question, complaint, a need to reward ? Write to con.nosp@m.tact@julien-.nosp@m.nevo.com

> extern volatile u8 cpct_akp_songLoopTimes

This is an internal variable, updated by Arkos Tracker Player, that contains the number of times the present song has looped.
Script for converting binary files to C arrays
Set to 1 if you want to save the Registers used by AMSDOS (AF’, BC’, IX, IY) which allows you to call this player in BASIC.
Sets up a music into Arkos Tracker Player to be played later on with cpct_akp_musicPlay.
Plays next music cycle of the present song with Arkos Tracker Player.
Stops playing musing and sound effects on all 3 channels.
Set to 1 to allow fades in / out.
Set to 1 if you want to use Sound Effects in your player.
Plays a concrete sound effect, using the instruments of the “SFX song” given to cpct_akp_SFXInit when initializing sound effects.
Audio Channel A (also referred as 0)
Audio Channel B (also referred as 1)
Audio Channel C (also referred as 2)
Returns the number of the instrument which is playing SFX in the selected channel (0 = Channel free / not playing SFX).

> extern volatile u8 cpct_akp_digidrumStatus

This is an internal variable, updated by Arkos Tracker Player, that is used by the player for signalling events to user code.
unsigned char (u8 = unsigned 8-bits, 1 byte )
Close