★ CODING ★ SOURCES ★ ARKOS TRACKER - How to use the Player ★ |
| Arkos Player | Coding Sources |
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 :
On the Sound Effects side, you'll be able to :
Also, the player is the fastest ever (25 scanlines max on a CPC !), the music are light, so why wait ? HOW TO CREATE USEABLE 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 #FFFF). Warning ! On CPC, if you want to use the Interruption mode, your song HAS TO BE generated above #3FFF, due to system limitations. If you don't intend to export a SFX music, you can skip the next chapter. 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 tickbox 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. You can either use the binary versions on the Player.dsk (CPC only. The filename provide the address on which to load the file : PLAY4000 must be loaded in &4000), or assemble the player by yourself. Here's the procedure for CPCists, with the integrated assembler of WinAPE :
Warning, as the player has some cool features, be sure to read the text at the beginning. If you want to use this player in Basic (CPC), or use the Interruption System (CPC), or use it in ASM, some short manipulations must be performed. Of course, each time you modify a value, you have to assemble the player again, and save it this way. USING THE PLAYER Though there is just one player, it can be used in three different mode :
You can switch from one mode to another by setting the constants PLY_SystemFriendly and PLY_UseFirmwareInterruptions to 0 or 1, like said in the player. An example : in the ASM mode, both must be turned to 0, so find the two constants and : PLY_SystemFriendly equ 0 PLY_UseFirmwareInterruptions equ 0 Then assemble the player (like said above), save it, and use it. For ASM and BASIC players, these three functions are always available :
Basic users can call these functions easily. If you have loaded your player in &4000 and your song in &5000 :
INTERRUPTION players don't exactly work this way :
Or in Basic :
FADE IN/OUT The player allows the volume to be modified. It provides the interface, but you'll have to set the volume by yourself. This is mode flexible and powerful this way. Set PLY_UseFades to 1. In Assembler = ld e,Volume (0=full volume, 16 or more=no volume) call PLY_SetFadeValue In Basic, if your player is loaded in &4000 = call &4000 + 9 (or + 18, see just below), Volume (0=full volume, 16 or more=no volume) WARNING ! You must call Player + 18 if PLY_UseBasicSoundEffectInterface is set to 1. That is if you're using Sound Effects in Basic. 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. Set the PLY_UseSoundEffects to 1. If you want to use sound effects in Basic, set PLY_UseBasicSoundEffectInterface to 1. Like any song, the SFX Music must be initialized, but with a specific function : In Assembler : ld de,SFXMusicAddress call PLY_SFX_Init You must also initialize the "real" music : ld de,Music CALL PLY_Init To play a sound effect, you must call the PLY_SFX_Play function. It has a lot of parameters : A = No Channel (0,1,2) L = SFX Number (>0) H = Volume (0...F) E = Note (0...143) (0 is the lowest, 143 the highest) D = Speed (0 = As original, 1...255 = new Speed (1 is the fastest)) BC = Inverted Pitch (-&FFFF -> &FFFF). 0 is no pitch (=the original sound). The higher the pitch, the lower the sound. Then : call PLY_SFX_Play To stop a sound effect : ld e,No Channel (0,1,2) call PLY_SFX_Stop To stop the sound effects on all the channels : call PLY_SFX_StopAll In Basic : call Player + 9, SFXMusicAddress to initialise the SFX Song. call Player, Music to initialise the "real" music. To play a sound effect = call Player + 12, No Channel, SFX Number, Volume, Note, Speed, Inverted Pitch. No parameter should be ommited ! To stop a sound effect = call Player + 15, No Channel (0,1,2) 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, and you don't have to create an empty "real music" plus the "SFX music". The SFX Music already contains an empty Pattern inside, so when initialising the "real music", simply use the address of the "SFX Music" : ld de,SFXMusicAddress call PLY_SFX_Init ld de,SFXMusicAddress CALL PLY_Init How to test a sound effect is over ? There is no function for that, but it's easy to code by yourself. Simply test if the word on the following address is 0 : PLY_SFX_Track1_Instrument + 1 to test if no sound effect is present on Channel 1. PLY_SFX_Track2_Instrument + 1 to test if no sound effect is present on Channel 2. PLY_SFX_Track3_Instrument + 1 to test if no sound effect is present on Channel 3. How to test a priority of a sound effect over another ? AT 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. If many people ask for it, I may provide an interface to do that. 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 PLY_Digidrum value. 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 if Events. 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 How to detect the song is over ? There is no flag made for that, but as you have the source file, it's easy to add. Once a song is over, it reaches the code just below the PLY_Linker_PT label, with a comment "Song over !". Simply add your code here, like setting a flag, or jumping to a code of your own. How to relocate the player and songs ? I provided such tools with the STarKos, but didn't here. Relocating the player isn't complicated, but I didn't provide a way to do it because the player will change a lot according to who's using it. How to do it : Assemble two players in two different address (&4000 and &8000 for example). Then compare the bytes and find the addresses that have changed. With that, build a relocation table. Relocating a song is however much more complicated. The values are all absolute, and the format of the Instrument is not that simple. I may provide a code to do that if many people request it. Can I remove parts of the code if I need memory ? Well, as long as it won't crash it, why not ? :) 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 :
That's it ! If you have any questions regarding this software or any suggestions, write here : contact@julien-nevo.com
|
