Using interruption player with CPC Basic

You want to play music and maybe sound effects with AT2 in your BASIC (CPC) production. You don't want to compile anything or go into complicated details because that bothers you. We got you covered! AT2 provides a small player wrapper that can be used easily on any Basic production.

I called it an "interruption" player because it uses system interruptions. Meaning that a simple CALL will play the song in the background, allowing you to run your production in the foreground, not having to bother with the music again! Plus, the included sound effect player will turn your program into an Hollywood production. Nothing less.

If you don't want to bother and only want to have fun:

  • Open the "BasicInterruptions_CPC.dsk" in the "players\playerAkg\sources\tester" folder.
  • Run "example.bas"
  • Have fun!

Now, if you want to use your own song and sound effect:

Exporting the song

The first step is to export the song.

First, load your song. In my example, I use "A Harmless Grenade", which is in the song package of AT2.

The obvious way is to use the File > Export > Export as generic (AKG) option.

Note: AKG? Yes, the BASIC player is actually only a wrapper around the AKG (i.e. generic) player. So whenever you want to use the BASIC player, always use the AKG!

Since you don't want to compile anything (scary!), use the following options:

Things to look after:

  • Select all the subsong and PSG at the top.
  • Untick "export to several files"
  • Tick "export as... binary file (z80)
  • In "Encode to address", enter the address you want the file to be loaded in Basic. Contrary to what is written in the screenshot, write "7000", which is high enough in memory to let you have a big Basic program, but not too high because we will load the sfx and player after, and they need memory too.
  • Leave the other values as-is, they have no consequence for us now.

By clicking on OK, you can save the binary. Let's call it "music.akg".

In the future I'm sure you'll be bored to do this step manually, so I advise you to use the command line tool (in the "tools" folder), which is much faster.

Export the sound effects

This step is not mandatory, but... what is a game without sound effects?

Let's open the "SoundEffects" song, still in the AT2 package, or load your own sound effects song.

Then click on File > Export > Export sound effects (AKX).

Use the following values:

  • Make sure all the sound effects are exported (All "Export?" ticked).
  • "Export as... Binary file (z80)" must be ticked.
  • In the "encode to address", write "9000", contrary to what is shown. So that will put the sound effects just after the music, giving it about 8kb, which should be enough.

Click on Export and save the file as "sfx.akx".

Once again, this step can be automatized using the command line tool. Much faster!

Import in a DSK

Now we have the music and the sound effects. We need to put them in a DSK where you can then put a player and call it. As it sounds bothersome, we'll use a shortcut: there is already a DSK with everything in it. All you have to do is either overwrite the song and sfx on it, or simply use the current DSK and have fun with it.

Make a copy of the "BasicInterruptions_CPC.dsk" in the "players\playerAkg\sources\tester" folder.

Are presented here three ways to import your files:

ManageDsk

You can use the venerable ManageDsk from Demoniak, Windows only. Drag'n'drop the music and sound effects files, making sure that:

  • Choose BINARY when importing.
  • Set the right start address: 0x7000 for the music, 0x9000 for the sfx (don't set the Exec).

Cpcfs

This tool by Ramlaid is Windows only, command line. You can import the files by typing this:

cpcfs BasicInterruptions_CPC.dsk p music.akg,0x7000 -b -e
cpcfs BasicInterruptions_CPC.dsk p sfx.akx,0x9000 -b -e

iDsk

iDsk by Sid/Impact is a Linux/Mac command line tool doing the same thing as cpcFs above. I never used it, but it is known to work well.

How to use

So far, we have the song and the sound effects file. Open the "BasicInterruptions_CPC.dsk" in the "players\playerAkg\sources\tester" folder. The player is already compiled in 0x9500.

Simply loads the files:

10 memory &6fff
20 music=&7000
30 sfx=&9000
40 player=&9500
50 load"music.akg",music
60 load"sfx.akx",sfx
70 load"player.bin",player

So far, nothing fancy. If you don't use sound effects, simply don't load the sfx file.

Note: Make sure your music doesn't go to overwrite the sfx file, and that the sfx file doesn't grow over the player! The player is high enough in memory to be "safe", both for Basic and the system. You shouldn't have to recompile it, but you may if you want to relocate it elsewhere. Yes, it means using Rasm.

Then you simply call the player to play your song! This should be done once, but if you stop the music and want to start again, this is the command to execute. Also if you want to restart a song, or play a different subsong.

90 call player,music,0

Where "0" is the subsong number (0 being the default song).

Then, if you use sound effects, now is a good time to initialize them too. This should be done only once, at any time, before using the sound effects. Of course, if you don't use sound effects, skip this step.

100 call player+6,sfx

To stop the song, only one simple command:

call player+3

Now, let's play some sound effects!

Note that the sound effects will only be heard if the music is playing! Once the music is stopped, the sound effects will not be played! If you want sound effects but no music, simply play an empty music. See below.

To play a sound effect, one simple command:

call player+9,"sound effect number","channel","inverted volume"

The "sound effect number" starts at 1 and matches the exported sound effect in the screenshot at the top of the page.

The "channel" is 0 (left), 1 (center) or 2 (right).

The "inverted volume" is the volume, from 0 (full volume) to 16 (mute). Example:

call player+9,2,1,0

This will player the sfx 2 ("enemy explodes"), in the center channel, at full volume.

One last command. It will stop a sound effect from a channel:

call player+12,"channel"

"channel" is as above, from 0 to 2. This will stop any sound effect that is playing on the channel.

Muting the music

You might want to mute the music, or simply have no music during your production.

The latter is simple: simply generate an empty song, and start it just like shown above.

To mute the music, simply add another Subsong in your song (the main song being Subsong 0 by default) with nothing inside. Then whenever you want to mute the music, play the Subsong 1 (the muted Subsong). That's it! The only drawback is that if you want to unmute the music (and thus play Subsong 0), it will start at the beginning.

Wrapping up

That's it! This should be enough to get you started. Have fun!