file_id.diz
AKS Format 1.0
--------------
The AKS format is generated by the Arkos Tracker. I will be very concise here : it is simply an XML file that is GZIPed (WinRAR should be able to uncompress it).
It includes the AKI format which is used for the Instruments.
Explode the file and have fun, it's very easy to understand :).Arkos Tracker 1.0 Player Format
-------------------------------
By Targhan/Arkos.
This document talks about the format of the generated binary music. NOT the ones saved as AKS file.
These files are very optimised :
- One used Tracks and Special Tracks are encoded.
- Once necessary parts of the Tracks are encoded (if Track1 has data till the 127th line, but the Linker only uses 64 lines among them, only 64 lines will be encoded).
- Only used Instruments are encoded (so their number varies from the ones in the AKS format. First one found is the first one encoded).
- All strings information is lost (song name, author, instruments names...).
- The binary format used is optimised in both room and speed for the player.
Note that there is always at least one Track, one Special Track, and one Instrument (the 0th, system reserved) coded.
The 0th Instrument represents the empty sound, which is used by RST, but also by sounds when they stop.
All Pitches are signed, coded on 16 bits.
All Pitches are Period based. Which means that the lower they are, the higher the sound. Positive Pitch = Portamento down.
All Arpeggios are signed, coded on 8 bits. Note based. Higher arpeggio means higher note.
All address are ABSOLUTE, not relative. This is done to increase the speed of the player. This also means that a song generated in &4000 won't work if loaded in any other address.
About the Instruments
---------------------
An Instrument is composed of a list of "sounds". A Sound can be considered Non-Hard (with no use of Hardware Envelope) and Hard.
To stop an Instrument, we consider it Hard, and there's a flag inside to make the Instrument stop. In fact it never really "stops". Either we redirect the Instrument pointer to an empty Instrument (the 0 is reserved, especially used for that), or we point inside the Instrument to make it loop from any Sound.
Hard Sounds can mean : Stop/Loop, Software Dependent, Hardware Dependent, or Independent.
Software Dependent is the STarKos (on CPC) primary way of working. It uses the note of the score (=Auto mode), which give him a Software Frequency (PSG Register 0/1, 2/3 or 4/5). An Arpeggio is added, as well as a Pitch (both optional). A Shift value (called "Ratio" in Arkos Tracker) is then applied to it to get the Hardware Frequency. Hardware Frequency = Software Frequency / 2^shift. Easy and fast to calculate. A Hardware Pitch can then be applied on the Hardware Frequency before it is send to the PSG. Special effects may use this.
The Software Frequency can also be manual (contrary to Auto mode), in which case the user enters the Frequency. It this case, Arpeggio and Pitch are not authorised. The Hardware Frequency is however calculated from the Software Frequency given.
On top of that, can be added Noise.
Note that the Sound Channel is always open in Software Dependent mode.
Hardware Dependent is quite new. It is the exact opposite to the Software Dependent. The note read in the scroll defines the Hardware Frequency (Arpeggio and Pitch, or Manual Hardware Frequency are here too), which is multiplied by 2^shift to get the Software Frequency, to which is added a Software Pitch (optional). This is the "HardSync" option of STarKos, Software Pitch being the "Finetune". The particularity of this mode is that the Software Frequency is a multiple of the Hardware Frequency, resulting in very "stable", sync sound. Adding a little Software Pitch allows the user to master the desync he wants.
Once again, the Sound is always On.
Independent mode is new. Both Software and Hardware frequency are independent (hence the name). Both read the note from the score, or can be manually setted. This is most useful to have one note in Software, and have one note five half-note higher in Hardware for example (or the opposite !), which can result in two sounds blent in one. It is also the only Hard mode in which you can cut the Sound, and thus using the Hardware Frequency only.
-------------------------------------------------------------------
Header
------
DB "AT10"
DB SampleChannel (1,2,3)
DB*3 YM Clock (little endian. 1000000=CPC, 1750000=Pentagon 128K, 1773400=ZX Spectrum/MSX, 2000000=Atari ST, or any other in case of custom frequency).
DB ReplayFrequency(0=13hz,1=25hz,2=50hz,3=100hz,4=150hz,5=300hz)
DB Speed (>=1)
Instruments Table
-----------------
dw Instruments Chunk Size (not including this Word)
{
dw Pointers on Instruments
} * nbInstruments
{
ds InstrumentData (see the Instrument structure below)
} * nbInstruments
Instrument0 is ALWAYS coded. It represents the empty sound, which is used by RST, but also by sounds when they stop.
Pre-Linker
----------
First comes a unique bloc, just before the real Linker, and only used at the initialisation of the song. It is used to optimise the Looping of the song.
DB First Height
DB Transposition1
DB Transposition2
DB Transposition3
DW Special Track
Linker
------
{
DB PatternState :
b5 = New Special Track ?
b4 = New Height ?
b3 = New Transposition 3 ?
b2 = New Transposition 2 ?
b1 = New Transposition 1 ?
b0 = Song over ?
if b0 = 1 :
dw Pointeur on Linker to loop. Restart reading.
if b0 = 0 :
DB Transposition 1 if Transposition1?
DB Transposition 2 if Transposition2?
DB Transposition 3 if Transposition3?
DW Track1
DW Track2
DW Track3
DB Height if New Height?.
DW Special Track if New Special Track?
} * Length + 1 (+1 because the Loop item has to be added to the list).
SpecialTracks
-------------
DB Data
b0 = Data (1) or Wait (0)
If Wait :
b7-b1 = Wait b7-b1 lines. (1=1 line, 0=128 lines)
If Data :
b1 = Speed (0) or Digidrum (1) ?
b7-b2 = Value. If value = 0, escape code : read next byte to know value.
If Escape Code :
{
DB Value
}
Note : 7 bits are enough to cover the whole track. Warning, 0 possible (1=1 line, 0=128 lines).
Note : Speed and digidrum > 0. 0 = Escape code, used to encode number > #3f, which are rare, but allowed by the software.
Tracks
------
Possible cases :
Wait
Note + New/Same Instrument
Note + New/Same Instrument + Volume
Note + New/Same Instrument + Pitch
Note + New/Same Instrument + Volume + Pitch
Volume
Pitch
Volume + Pitch
RST
DB Data
b0 = Full Optimisation ? (Note only (Escape code possible), Pitch to 0, no Volume, same Instrument). Parameters = 0.
Si b0=1 :
b7-b1 = 0=Escape Code. 1-127 = Note (0-126). Parameters = 0.
Si b0=0:
b7-b1 =
0-31 = Wait Lines. 0=End Patt (not tested, =128) 1=1 line... Parameters = 0.
32 (after decrease : 0) = Escape Code for Note. Parameters = 1.
33-127 (after decrease : 0-94) = Note. Parameters = 1.
If No Note, but Volume/Pitch, Note = any value (0 by convention, so 33 here). Parameters = 1 (and flag Note? below = 0).
RST = any Note (0 by convention, so 33 here) with NewInstrument? = 1 and Instrument = 0 (empty Instrument).
If Escape Code :
DB Note (0->143).
If Parameters = 1 :
76543210
pnivvvvo
DB Parameters
p = New Pitch ?
n = Note ?
i = New Instrument ? Only tested if Note? = 1.
v = Inverted Volume if Volume?=1. %0000 if Volume? is off.
o = Volume ?
DW Pitch if Pitch=1.
DB Instrument if NewInstrument=1.
If Instrument = 0 -> RST
Instruments
-----------
Header
------
DB Speed (1-256(=0)). Warning, the editor must increase the value when generating.
DB Retrig? (0 for No, #FE for Yes. #FE is used to convert a NOP/RET Z into CP #C8, so DO NOT CHANGE THIS VALUE).
Data
----
The following corresponds to ONE Sound of the Instrument. An Instrument can be composed of virtually infinite of these, though most sounds will just have a few :).
DB FirstByte
if b0=0, NON-HARD sound. If b0=1, HARD Sound.
NON HARD Sound
--------------
76543210
pavvvvn0
p = Pitch?
a = Arpeggio?
v = Volume
n = Second Byte needed? Needed when Noise, or Manual frequency, or noise with no sound.
If (Second Byte needed? = 0) and (Volume > 0) : It means : Sound? = 1, Noise? = 0, Manual Frequency = 0. So, a normal sound can be coded in 1 byte.
However, If Pitch and arpeggio are present, we have to read them !
If (Second Byte needed? = 0) and (Volume = 0) : No need to read anything else. It means : Sound? = 0, Noise? = 0. To optimise, useless to set Volume to 0, just cut the channel.
If (Second Byte needed? = 1) :
{
76543210
-dsnnnnn
d = Manual Frequency? (if 1, Arpeggio and Pitch not coded).
s = Sound? If 0, just manage Noise and that's it.
n = Noise (0=no noise. >0=noise)
}
If Manual Frequency? = 1 : read Manual Frequency WORD (0 to #FFF). Do not read the Arpeggio and Pitch.
else
{
If Pitch? = 1 : read Pitch WORD (-#FFF to #FFF).
If Arpeggio? = 1 : read Arpeggio BYTE (-#5F to #5F).
}
HARD Sound
----------
76543210
iir1
ii = Dependency : 00=Hardware Dependent 01=Software Dependent 10=Independent 11=LOOP SOUND
r = Retrig?
If LOOP SOUND : DW Loop Pointer. Goto Loop Pointer (after the header), read once again.
If the sound is over, we loop on the 0th sound (of several iterations to optimise).
If the sound loops, we loop where it has to loop.
Software Dependent
------------------
76543210
qpam01r1
After shifting (done twice):
76543210
--qpam01
The Sound? is always 1.
q = Hardware Pitch?
p = Pitch?
a = Arpeggio?
m = Manual Frequency? (if 1, Arpeggio and Pitch not read).
r = Retrig?
Second Byte :
76543210
nssscccc
n = Noise ?
s = Inverted Shift (7 - Editor Shift)
c = Hardware Enveloppe
If Manual Frequency? : DW Manual Frequency
else
{
If Pitch? : DW Pitch
If Arpeggio? : DB Arpeggio
}
If Hardware Pitch? : DW Hardware Pitch
If Noise? = 1 : DB Noise
Hardware Independent
--------------------
Basically, exactly the same as Software Dependent, just switch every Software term to Hardware, and the opposite. The structure IS and SHOULD be the same, as they share some code.
76543210
qpam00r1
After shifting (done twice):
76543210
--qpam00
The Sound? is always 1.
q = Software Pitch?
p = Hardware Pitch?
a = Hardware Arpeggio?
m = Manual Hardware Frequency? (if 1, Arpeggio and Pitch not read).
r = Retrig?
Second Byte :
76543210
nssscccc
n = Noise ?
s = Inverted Shift (7 - Editor Shift)
c = Hardware Enveloppe
If Manual Hardware Frequency? : DW Manual Hardware Frequency
else
{
If Pitch? : DW Pitch
If Arpeggio? : DB Arpeggio
}
If Software Pitch? : DW Software Pitch
If Noise? = 1 : DB Noise
Independent
------------------
76543210
spam10r1
After shifting (done twice):
76543210
--spam10 (spam, ahah).
s = Sound ? If Sound? = 0, no need to take care of Software Manual Frequency, Pitch and Arpeggio.
m = Manual Frequency? (if 1, Arpeggio and Pitch not read). Manual Frequency can only be present if Sound? = 1.
a = Arpeggio?
p = Pitch?
r = Retrig?
If Sound?
{
If Manual Frequency? : DW Manual Frequency
else
{
If Pitch? : DW Pitch
If Arpeggio? : DB Arpeggio
}
}
76543210
npamcccc
n = Noise ?
p = Hardware Pitch?
a = Hardware Arpeggio?
m = Manual Hardware Frequency? (if 1, Arpeggio and Pitch not read).
c = Hardware Enveloppe
If Manual Hardware Frequency? : DW Manual Hardware Frequency
else
{
If Hardware Pitch? : DW Hardware Pitch
If Hardware Arpeggio? : DB Hardware Arpeggio
}
If Noise? = 1 : DB Noise
Arkos Tracker V1.0 Keyboard Layout
---------------------------------------
Layout is in French. If you can't reach some keys, please contact me.
Common to PatternViewer, Instrument Editor and Instrument List
--------------------------------------------------------------
0-9 (numpad and central keyboard) et A-F = numbers.
F2/F3 = Goto PatternViewer / Instrument Editor.
Escape = Stop Sound/Music.
F5 = Play Song .
F6 = Play Song From Start.
F7 = Play Pattern.
F8 = Play Pattern From Start.
/ = Decrease Octave.
* = Increase Octave.
Ctrl + + = Next instrument.
Ctrl + - = Previous instrument.
PatternViewer
-------------
Central Keyboard = Play notes.
Space = Switch Edit mode.
* (near right-shift) = Write a RST.
Scroll Lock = Switch Follow mode on/off.
Cursor = Move your cursor.
Ctrl + Left/Right = Move to Previous/Next channel.
Ctrl + Up/Down = Move to Previous/Next Pattern.
Page Up/Down = Scroll vertically.
Home/End = Jump at the beginning/end of the Pattern.
+ (chiffres du haut !) = Increase Editstep.
Shift + + (chiffres du haut !) = Decrease Editstep.
Insert/Delete = Insert/Delete a note in the current Track.
+ / - = Set the sign to +/- in the pitch.
Back = Clear note.
Shift + back = Clear whole cell.
Enter = Capture instrument under the cursor.
Ctrl + Enter = Play line under cursor.
Ctrl + C/X/V = Cut/Copy/Paste.
Ctrl + P = Paste continuously.
Ctrl + A/Q = Transpose selection up/down.
Ctrl + Shift + A/Q = Transpose selection up/down of an octave.
Ctrl + E/D = Increase/decrease selected volume.
Ctrl + T = Select current track.
Ctrl + Numpad0 = Solo/unsolo current channel.
Ctrl + Numpad1 = Mute/unmute current channel.
Instruments
-----------
Mouse + Drag up/down = Add/Subtract 1 to the value.
Mouse + Drag left/right = Duplicate value to the neighbour.
Shift + Central Keyboard = Play notes.
Insert = Insert duplicated column.
Delete = Delete column.
Shift + Insert = insert duplicated item.
Shift + Delete = delete item.
Space = Duplicate Item.
Shift + Space = Spread item.
Tab = Next component.
Shift + Tab = Previous component.
Home/End = Move cursor to the next page.
Backspace = Set value to 0.
Q = Invert sign.
Cursor Left/Right = Goto next item.
Cursor Up/Down = Next/Previous component.
Page Up/Down = Add/Subtract 1 to the value.
Shift + Page Up/Down = Add/Subtract large value.
Ctrl + E = Set Loop Start where cursor is.
Ctrl + R = Set Loop End where cursor is.
Ctrl + T = Set Loop On/Off.
Numpad . = In the Enveloppe component (before last one), switches between Volume and Hardware Envelope.
ARKOS TRACKER V1.0
------------------
Arkos Tracker is freeware. You are free to distribute, copy it, as long as you don't sell it.
Contact me (Julien Nevo aka Targhan/Arkos) for anything related to this software (bug report, suggestions...) : contact@julien-nevo.com
Check our website for more information : http://arkostracker.cpcscene.com
If you're interested in the CPCBooster : http://dirtyminds.dxm.gr
This software relies on the .Net framework, which you can download here : http://msdn.microsoft.com/fr-fr/netframework/aa569263.aspx
However, the command line tools (SKSToAKS, AKSToBIN, AKSToYM) work with Mono, so you can use them on any system that supports it.
Credits
-------
On PC side :
Tool designed and coded by Targhan/Arkos.
Graphics and additional design by SuperSylvestre/Les Sucres En Morceaux.
Thanks to Augusto Ruiz Garcia (THANKS FOR YOUR AWESOME SUPPORT !!).
Thanks to Grim for the AY volume measurements.
Thanks to Lachlan Keown and Ramlaid/Arkos for their technical advice.
Thanks to UltraSyd and No Recess for their tests.
Thanks to Syx for pointing out that the command line tools were working with Mono !
On CPC side :
Player coded by Targhan/Arkos, some optimisations provided by Grim/Arkos.
CPC PSG access based on Madram/Overlanders' trick.
Speccy port and Interruption state save/restore snippet by Grim/Arkos.
Player adapted to Spectrum/Pentagon by Grim/Arkos.
MSX Player Test source and MSX player test by WYZ.
MSX Player debugged by Syx.
You will find in this package :
- ArkosTracker.exe : The software itself.
- Formats Folder : Files inside describe the various formats used by the Arkos Tracker.
- Instruments Folder : AKI Instruments to use in your songs. These instruments are provided freely for you to use them in your song, as-is or modified.
- Manuals Folder : Manuals of the software, and how to use the player.
- SKS Songs Folder : SKS files made on STarKos (Amstrad CPC) you can load to learn how to use Arkos Tracker. Also to listen to good AY tunes ! These music were already used on other production. Please contact the author if you want to use them.
- Songs Folder : Provides songs made with Arkos Tracker.
- Sources Folder : Sources of the Z80 players you can run on 8-bit computers (Amstrad CPC, Spectrum, Pentagon 128, MSX...).
- Tools Folder :
- AKSToBIN : a command line software to converts any AKS song into a binary to use on hardware (warning, you still need .Net to use it, but works with Mono !).
- STKToAKS : a command line software to converts any STarKos songs into an AKS song (same remark as above).
- AKSToYM : a command line software to converts any AKS song into an interleaved or non-interleaved YM6 format (same remark as above).
- A DSK containing the CPCBooster Client to run on your CPC. See the section about the CPCBooster at the end of this file.
What is Arkos Tracker ?
-----------------------
Arkos Tracker is a freeware music software dedicated to the AY soundchip, which can be found in 8-bit machines like Amstrad CPC, MSX, Spectrum, Pentagon 128K and Atari ST.
It runs on any Windows with the .Net 3.5 framework installed. No plan to converting it to MacOsX and Linux are schemed.
Arkos Tracker is born from the CPC tracker called "STarKos", which I also coded. It retains most of its features, extends some, and will improve them in future versions.
I already compose on "*Insert here a PC Tracker for AY*", why should I use Arkos Tracker ?
------------------------------------------------------------------------------------------
- Arkos Tracker is more powerful. Yes it is.
- The player is the fastest. Really.
- The player is dedicated to run on Amstrad, MSX, Spectrum, or Pentagon.
- The music are light.
- It supports sound effects in a very powerful way.
- The interface is intuitive, and the software documented.
- The format of the songs and source of the player are provided.
I already compose on CPC with STarKos ! I don't need no stinkin' PC tool !
--------------------------------------------------------------------------
Well, you don't have to if you don't want to, but :
- You can listen in real time to your song on a REAL CPC while composing on PC, if you connect each other with the CPC Booster (http://dirtyminds.dxm.gr) !
- You can import any STarKos song (SKS files) in Arkos Tracker, and save them as binaries, so that you can use the new player.
What's new in 1.0 ?
-------------------
- The "Load Song" dialog can now load both AKS and SKS files at the same time.
- You use use the command line to load a song.
- Drag'n'drop possible to the Arkos Tracker executable file to load a song.
- Bug corrected : Could not close the application with the top-right cross when the player was active.
What's new in 1.0 Beta 4 ?
--------------------------
- Ability to drag'n'drop AKS, AKI, SKS files into the Arkos Tracker.
- Ability to limit the Pattern Viewer refresh rate in order to improve performance.
- Load Song and Import SKS options are now mixed into one single option.
- Corrected a bug that could make the Pattern Viewer not refreshed after having entered a volume, pitch or instrument.
- Corrected a bug that would make the player use a wrong frequency when changing the replay frequency.
- Corrected a bug that would make sounds not evolve on Speed 1 while adding them in the Pattern Viewer.
- Slight improvement of the replay routine (shouldn't be noticeable in 16 bits, but should in 8), after Dadman noticed a bug in the 8 bits replay.
- A few cycles optimisations of the player (thanks to Grim/Arkos).
- Spectrum player redesigned, corrected, and optimised by Grim/Arkos (using the "Molusk" song, max TM is 5300t, average is 2400t).
- MSX player test debugged by Syx. MSX DSK updated by Syx.
- Source of the CPCBooster client and management now included (Sources/CPCBooster).
What's new in 1.0 Beta 3 ?
--------------------------
- AKSToYM to convert an AKS Song into an YM6 format.
- A MSX2 compatible test program thanks to WYZ.
What's new in 1.0 Beta 2 ?
--------------------------
- Complete coding of the sound generating and outputing by myself. The emulation is more accurate, and will allow the implementation of samples and Sids in the future.
- Plug in your best MIDI Keyboard or any MIDI-In device, play and record your music with it !
- 150hz and 300hz replay modes are now available. They are very slightly slower than on a real CPC. Nothing you should notice...
- CPCBooster output is now very accurate.
- Ability to save Interleaved/non-Interleaved YM6 format.
- AKStoBin : a command line software to converts any AKS song into a binary to use on hardware (warning, you still need .Net to use it, but it works with Mono !).
- STKtoAKS : a command line software to converts any STarKos songs into an AKS song (same remark).
Features
--------
- 256 Patterns available.
- Each Pattern is composed of 3 tracks, one par channel.
- Manages 512 tracks, each one being reusable several times in different positions OR in the same position, why not. Memory saving !
- A Track can have a height from 0 to 127.
- Each Track can be be transposed independently.
- Each Pattern has its own height, from 0 to 127, independently of the height of the Tracks.
- 255 instruments free to use.
- Each PSG registers can be modified while creating instruments.
- Big news : instruments are divised into two channels : a Software, and Hardware one. These channels can be independant or dependent from each other. Allows using two waves at the same time !
- Frequency replay of 13, 25, 50, 100, 150 or 300 Hz.
- Digidrums are supported : it is possible to enter digidrum numbers in the "Special Tracks" (I'll explain later their use) that can be read through the external player while playing the song. However, you can't load/hear a sample inside the editor.
- It's easy to synchronise your production to the music, as your music can send "messages" through the player.
KNOWN ISSUES AND LIMITATIONS
----------------------------
- Digidrums aren't supported as they should. You can insert them, but not hear them.
- BUG : In the Instrument Editor, when right clicking on the Enveloppe diagram, a context menu appears. Do not try to select the desired option with the keyboard (cursor up/down), it will prevent you from choosing the right item unless you restart the application ! I suspect a bug in .Net, but...
Future plans
------------
- A better samples support : ability to use any sample inside the Pattern like any other instrument.
- Sid sound, Sync buzz, and stuff like that may be supported.
- A better Instrument List handling.
- Undo/Redo support.
- ... Whatever you feel would be useful !
Lexicon
-------
Arkos Tracker (AT) works the way STarKos does. It is slightly different from conventional 8-bit trackers, but the way it works is also from where come its power and efficiency (yeah). Here is how things works.
Tracks : They represent the basis of your compositions. All the notes are entered there, and you've got 512 of them. Each track is identified by its number. One Track can be up to 128 notes long.
Important note for STarKos users : Contrary to STarKos, it is NOT possible anymore to add Digidrums to Tracks, only in the Special tracks. Why ? It is needed to make the transitions with the future versions, and the way it will handle samples. Imported SKS songs using SPL will see them replaced by RST.
Patterns : This term is known to all Trackerers. A Pattern is a little sequence of a height between 1 and 128 notes. In AT, a Pattern is composed of 3 Tracks. Each Track is independant from the others, and can be used in any other Pattern. It is also possible to have two, or even three same Tracks in the same Pattern ! Modifying one Track will change the others. Along with the transpositions - one per Channel -, it is possible for example, to use one Track on Channel 1, and the exact same Track on Channel 2, transposed of an octave. If the tracks included are bigger than the Pattern height, then they'll be truncated INSIDE THIS PATTERN ONLY, which means that the 'overflowed' data aren't erased from the memory at all, they're simply not used in this Pattern. So it's possible to use half of a track in a Pattern, and the whole in another. On the opposite, a Pattern can be bigger than the Tracks inside. In this case, there's no problem, you'll find empty notes at the end of the Tracks.
Instruments : You know or guess what Instruments are, so I won't dwell on that. You have 255 instruments, from 1 to 255.
Special Tracks : These ones are new. They allow to set digidrums, and speed changes. Each Pattern has a Special Track, on top of the 3 "normal" Tracks. You have 256 Special Tracks available.
----------------
General Handling
----------------
Once you've started Arkos Tracker, you will see the main page. Let's examine each components :
The Menus
---------
File
----
- New/Open/Save Song/Save as : Pretty self-explanatory. Arkos Tracker songs are saved in AKS format, but you can also load SKS songs, which are STarKos (CPC) song. Due to the differences in the way sounds are handled, the imported SKS songs may sound a little different, but most will be converted successfully. Check the "Format" folder for more information about the AKS format.
- Open/Save Instrument : First select the Instrument to save or to be replaced by the one you want to load, and then Open/Save Instrument. Instruments are saved as AKI, and use the exact same description as in the AKS format.
- Export as WAV : Allows you to create a WAV file of your song, according to the Sample rate, Bit rate and Number of channels you want.
- Export as YM : Exports the song as an unpacked YM6, that you can load and listen to with ST Sound By Leonard/Oxygen. An option box will ask whether you want to use Interleaved or non-interleaved format. The first is preferably used if you intend to spread your music on the net, as LHA will pack it more efficiently. The second is especially used because some converters may only treat linearly stored register streams.
- Export as binary : When your song is finished, you may want to export it to use it on the real hardware in your production. First select the address where to generate the song (in hexadecimal). The length and end address are automatically calculated according to what you type. The "Export SFX only" is used to make a SFX song. These songs don't contain any musical items (save for one empty Track, and one empty Special Track). For more information, please read the "Player" file in the "Manuals".
- Setup : Useful to... set the application up. Two tabs :
"General" :
- Displays Rows In Hex : By defaut, the line index in the Pattern Viewer are displayed in Hexadecimal. You may want to see the Decimal value by unchecking this item.
- Font size in Pattern Viewer : Allows you to change the font size in the Pattern Viewer.
- Pattern Viewer refresh rate in Play mode : Slider that allows you to limit the refresh rate of the Pattern Viewer while a song is played. This is especially useful for 300hz songs on slower computer.
"Audio" :
- You can select the Sample rate, Bit rate, the number of channels used by your sound card, as well as the number of buffers used. The default is 32, which should be fine on all computers. If you hear glitches, increase this number. You can also reduce latency by decreasing it. You can select the CPCBooster as an output if your CPC has one, and the client has been run on it. Don't forget to select the right COM port ! For more information, read the paragraph about linking your PC to the CPCBooster.
Edit
----
- Song Information : You'll find here the information related the song. Most are self-explanatory, but for those which aren't :
- The DOS Name is the name used by default when generating your song. Most of you may want to use a name that the hardware DOS will be able to recognize (8 chars long, no lower case).
- SPL Channel is here to maintain the legacy of STarKos, but will disappear quite soon. As you can trigger digidrum in the Special Track, there's a question : on which channel to play them ? The musician will be able to tell the coder that information with SPL Channel (1,2 or 3).
- Initial Speed is here to maintain the legacy of STarKos, too. When you play the song from start, the Speed will take this value automatically.
- Highlight : Indicates the lines to highlight in the Pattern Viewer. According to the time measure of your song, you may want to set it to 3 or 6 for example. It is also possible to disable it.
Let's now take a look at the main windows :
Instruments List
----------------
This one is seen on the top left part of the window. In this field, you can have a list of all the Instruments you have in your song. A first tiny Instrument is always here. The selected Instrument is the one that will be used when entering notes in the Pattern, or the one being edited and played with the keyboard. You will notice three icons just below to it :
- Create a new Instrument. Quite obvious. A new Instrument is added at the end of the list.
- Duplicate : the current Instrument is duplicated into a new Instrument, added at the end of the list.
- Clear : the current Instrument is emptied (but not destroyed).
*For now*, it is not possible to completely kill an Instrument, or order them once they are created. It is also not possible to reorder the Instruments.
Equalizer
---------
Just right to the Instuments List is a volume equalizer. A blue bar means "no volume". An orange bar means that an hardware sound is used in this channel. It is quite handy to know if Hardware envelope are overlapping this way. Below each channel volume equaliser is a little light turning red if noise is used in this channel.
Below, are three buttons, corresponding to the activity of the channels. Right-click to mute the channel, left-click to solo/unsolo.
Just left to them is a little Icon called "Polyphony". More on that later.
Octave
------
It represents the base octave used when putting a note in your music, or when playing with your sound. AT octaves go from 0 to 12, but this componant only goes to 11, as the keyboard allows you to reach the next octave.
Speed
-----
Represents the current Speed of the song. You can modify it in real-time, but any Speed command inside the song (in the Special Tracks) will reset it, so use these instead.
Steps
-----
Indicates how many lines to jump after a note has been added to a Track.
Replay
------
Represents the rate at which the song is being played. Most productions will use 50hz music (which means that the music will be played 50 times per second), but you may also use 13hz or 25hz song as well, or up to 300 hz. This information is saved in your song.
Linker
------
The beast is on the bottom left corner. This one is very important : it will allow you to link each Track into each Pattern. Understand the main philosophy of AT : the content of a Pattern is independant to the Pattern itself. Each channel of a Pattern is linked to three Tracks.
For example, you could have the first Pattern linked to the Track 1 (the bass), 2 (the drums), 3 (the melody). For the second Pattern, you could use the same Drum Tracks, and a new Bass line and Melody. So you'd use new Tracks for them. The second Pattern will thus be linked to Track 4 (new bass), Track 2 (the drums, the same), and Track 5 (new melody).
On top of that, each Track in each Pattern has its own Transposition setting, which you can see by clicking on the "Switch View" button (the magnifier) just above the Linker. You can then transpose the whole Pattern of up to 15 semi-tones, or just the bass line if you want. So a single Track could be reused many times by just transposing it ! Musician will like this feature because it's handy, and coder because it saves a lot of memory.
Also, each Pattern has its own height, independently from the Tracks height. Like said earlier, if the tracks included are bigger than the Pattern height, then they'll be truncated INSIDE THIS PATTERN ONLY, which means that the 'overflowed' data aren't erased from the memory at all, they're simply not used in this Pattern. So it's possible to use half of a track in a Pattern, and the whole in another. On the opposite, a Pattern can be bigger than the Tracks inside. In this case, there's no problem, you'll find empty notes at the end of the Tracks.
Finally, the last column is reserved to Special Tracks, which can only contains Digidrum messages and Speed changes. It is possible to ignore them for a whole song if you don't need speed change !
To change a Track number, simply click on it, then enter a number between 0 and 1FF. Only hexadecimal values are accepted !
The buttons just above perform the following actions :
- Switch View : like said earlier, switches between Pattern Height + Special Track view to Transpositions view.
- Add Pattern : Duplicate the current Pattern into another one.
- Delete Pattern : Delete one Pattern. Don't worry, the Tracks it contains aren't erased from the memory, even if there's not used anymore !
- New Pattern : Will find empty and unused Tracks, and link them to a new Pattern. Very useful to create a Pattern from scratch !
- Move Pattern up : Move the pattern one rank above.
- Move Pattern down : Move the pattern one rank below.
Each Track has a name and a color, as you will see in the Pattern Editor. Its color also sets the background of the Track of the linker, and if the Track upon which is hovering your mouse has a name, it will appear as a tooltip.
Pattern Editor
--------------
The big stuff on the right part of the screen is the Pattern Editor. You'll be able to compose with it (yes, really). You can reach it by pressing F2 (but since the software displays it from the start, pressing F2 won't do a thing).
It works like in any conventional Trackers. You can move your cursor using the arrows of your keyboard, or by clicking once where you want your cursor to move. You can also select a part of the Pattern with the mouse and perform editing operations by right-clicking on it, or with the keyboard shortcuts (see below).
By pressing the Space bar, you can switch the Edit mode to on, and thus put your notes using the keyboard (WSXDC... and AéZ"... to use the next octave). Once a note is written, and cursor moves downward according to the "Steps" value we've seen before. Also, the base octave uses the value "Octave" you can see on the left corner of the screen.
You can see four columns. The first three are the Tracks for channel 1, 2 and 3, according to the Linker. Just above is a field to name the Track, and a Color box to define how beautiful your Track is. Identifying your Track by both a name and color can be very handy, especially as both these information are reported into the Linker (visually for the color, and as a tooltip for the name).
Each Track has four columns in itself. Let's take an example :
C#4 5F F +465
- The first column is the note with the octave. To reach all the notes given by the AY, AT allows you to use 12 octaves (from 0 to B). Also, a special note called "RST" (ReSeT) can be entered through the "$" key. Such note will stop all sound on the Track. Also, volume and pitch (see below) can't be entered along a RST.
- The second column is the Instrument. Unlike most limited tracker (hehe), AT gives you up to 255 Instruments, from 1 to FF. An Instrument is always linked to a note, so you can't delete one without deleting the other.
- The third column is the volume from F (full volume) to 0 (no sound). It is possible to delete Volume when you don't want to change the volume of a note. Simply put your cursor on a volume, and press Backspace. Also, note than Hardware envelope can't be modified by this volume. If your Instrument is composed of both software and hardware envelope, only the software will be decreased by your volume change.
- The fourth column is the Pitch, or Portamento. It goes from -FFF to FFF. It allows notes to slide upwards or downwards. Each note triggered resets the Pitch value of a Track.
Besides the three Tracks is a... fourth one, the Special Track, in which you can only enter in the first column :
- "D" to enter a Digidrum. These samples are numbered from 1 to FF (on the second and third column). Digidrums aren't supported for now with the editor currently, but you can intercept these values thanks to the player, and play the sample accordingly. More on this in the Player section.
- "S" to change Speed, numbered from 1 (fastest) to FF (slowest).
Plenty of shortcuts allow you to do plenty of stuff, so you HAVE to have a look at them, it will make your life better. Check the Keyboard manual.
The AY
------
We must here have a little talk about the AY capabilities, for you to be able to create great sounds. You can of course use the "factory" presets you can find on the "Instruments" folder of the Arkos Tracker, but creating them is really more cool. If you know everything about the AY, you can skip this part, as we won't fathom all its secrets here... though the terminology might be important for later.
The AY can generate one square sound on each of its three channels, each with a volume (4 bits : from 0 to 15) and a frequency (12 bits : from 0 to 4095). So if you want to have a fading-out sound, you have to give the AY all the volume it has to change (15,14,13,12,...0). That's what I will refer to as "Software envelope". The coder/musician has to tell the player what to change, when to.
It also has one (and one only) Noise generator (5 bits : from 0 to 31), which is used mostly for drums and sound effects. It can be mixed to any, or all, of the channels, but remember that at a given moment, the same noise value will be used by all the channels using the noise, as you only have one Noise generator.
But the AY also has a Hardware envelope generator. It is made to provide a little ease when programming the AY, however, it is VERY limited for its former use :
- Its job is to modify the volume of a channel, using a period given by the musician.
- The Hardware volume curve has to be chosen among 8 curves, half of which loops.
- The curve always start at an extreme value (0 or 15) to reach the other extreme (15 or 0). So you can't create transitions between given volumes.
- There is only ONE generator. So if two sounds use it, they WILL share the same Hardware envelope. Most of the time, no one uses the hardware generator on more that one channel.
So a musician will either choose to use the Software envelope, in which case he will enter all the volumes he wants to hear, OR use the Hardware envelope. Once you have activated the Hardware envelope on one Channel, you CAN NOT use the Software volume anymore, unless you deactivate the Hardware envelope of course. It is an important note.
For all these reasons, no musician uses the Hardware envelope in its former context. But there's a special trick that allow to hear what we know as "Hard sound", or "Hard bass", as they are especially efficient with low sounds.
What we do is synchronise the Software and Hardware envelope, so that the Hardware modulates the Software one... Let's say we have a note at 440hz. So our Software frequency is 440hz. To have a nice sounding "hard bass", the Hardware frequency should be a multiple of the Software frequency. Fortunately for us, multiplying by a power of 2 the Software frequency to get the Hardware frequency is something our beloved Z80 is able to do quickly.
Another nice trick is to force the Hardware software to a very high frequency. Ben Daglish used to do that a lot.
But another point remains : what Hardware curve to use ? You will probably use a looping curve, so that you just have to trigger it once. Four curves are really used a lot : the sawtooth, the triangle, and their inverted. Not a lot of option, but enough to have nice sounds.
What is the use of the remaining Hardware curves ? These will mostly be used if you want a smooth fade-out/in of a sound, but can't have it with a Software curve... Imagine your song replay-rate is at 13hz. Using a Software sound, you will only be able to modify the volume of your sound 13 times per second, which is not as smooth as it seems to be. By using an Hardware sound, all you will have to do is trigger the fade-out curve with the right frequency, and the job is done.
Another important note is about the Register 13 of the AY. It contains the Hardware envelope curve used. Whenever you use a new curve, the R13 is resetted, and the curve is retriggered. So if your sound always use curve, the R13 will be set only once, because triggering the R13 result in a trigger of the curve itself, which can sound quite harsh, so AT prevents that from happening by testing first if the R13 doesn't already contains the value you want to use. Is it however possible to force the Retrig whenever you want. Why ? To give a better attack of a bass for instance. Also, imagine you are using one note multiple times in a row. If you are always using the same note with the same curve, you won't hear the notes being triggered, because the R13 hasn't been modified, so the Hardware envelope hasn't been triggered (except for the first note). In that case, you will put a "retrig" at the beginning of your sound.
The Instrument Editor
---------------------
This is the other big stuff. Access it by pressing F3. Don't be afraid. It's simple. And friggin' powerful.
The Instrument being edited is chosen through the list on the left corner of the screen. Select one of them and have a look at the Instrument Editor.
On the top is the Instrument name. Pretty self-explanatory. "Speed" just besides is the speed at which the CPU will proceed in your sound. 0 is the fastest speed (your sound is read each frame), 255 the slowest.
The little button besides is here to hear and have fun with your sound. If you click on it, you'll hear your sound using the note written in the button ("C-3" is the default). Now that this button has focus, play with the keyboard to hear your sound on various tonalities (/ and * of the numpad to change Octave, Esc to stop the sound).
Now if you push the little "Polyphony" button near the equalisers we talked about earlier, you activate the "Polyphony" mode, in which your sound is played on every activated channel alternatively, as you play a note ! That's really a nice feature to hear your sound on two, three channels like you would have done if you were editing your song. Except that it's faster and doesn't mess with your song.
Another way to test your sound when you are editing the sounds (with your cursor inside one of the composants below) is by pressing Shift + one note of the Keyboard, and Esc to stop the sound.
Now let's have an overview of what is below.
An Arkos Tracker Instument is composed of what I will refer to "Lines", which represents each "frame" of a sound, each component if you will. An Instrument is composed of up to 256 Lines, each having a column below (yes, it's rather illogical to have lines being set in columns, but STarKos displayed Instruments in lines, not column).
So just below the scrollbar, we have :
- Lines : This indicator shows what Line is below. A Sound has at least one Line, the "00". A blue bracket-like symbol surrounds some Lines. It is actually the begin/end loop marker. As it is blue, it means that the Loop is off. Click once on it to switch it to On, showed by the green color. You can also drag'n'drop the left and right part of the marker in order to extend the looping area. A right-click on a Line number also provides a context-menu to do the same.
The End marker is actually used whether the Instrument is looping or not : it shows the End Line of the sound. So even if the Instrument seems 150 Lines long, only the part between and Line 00 and the End marker is played.
- Sound : Indicates if the Software envelope is used. If is it off and on top of that no Hardware envelope is used, will no sound be heard ? Exactly. Unless you use a Noise effect ! When the sound is off, you can still have a Hardware envelope, resulting in a very soft and still sound.
What follows concerns the Software envelope :
- Period : Well, it's the period of the Software envelope (a Period is 1/Frequency, so the higher the note, the lower the Period). On "Auto" mode (=0), the frequency is linked to what is played in the song (ie. your music !), or what note is played by yourself with the keyboard. By entering a number here (from 1 to #fff, 0=Auto), you force the period. This can be useful for special effects (like Ben Daglish's high pitched sound). If you force the period, the two following features (Arpeggio and Pitch) become disabled.
- Arpeggio : An Arpeggio is a shift in the note range. If your note is a C#3, an Arpeggio of 1 will result in a D3. Very useful to color your sound ! Values from -#7F to #7F.
- Pitch : A Pitch is a shift in the period, AFTER the Arpeggio has been performed. It is especially useful to create vibrato, or slides in your sound. Values from -#FFF to #FFF.
Let's skip the "Link" and "Ratio" for now. Just below are :
- Hardware Period, Arpeggio and Pitch. They look a lot like the features above, don't they ? Yes they are exactly the same, except that they concern the Hardware envelope, and not the Software. And as much as the Software options won't be available is the "Sound" is off, the Hardware envelope won't be available if no Hardware curve is used ! They will be triggered just below...
- Envelope : This is were you draw either your Software volume curve OR your Hardware curve. The default mode is "Volume". Left-click on a bar to draw your curve. If you want to use an Hardware curve, simply left-click and select an Hardware curve, or right-click once on a bar.
- Noise : If you want to add a white noise to your sound, simply draw your noise curve by left-clicking on a bar. Noise can be added to any Software or Hardware line, whether Sound is on or off. Actually, the only thing that can prevent a Noise from being played is putting the Volume to 0 (whether it be Software or Hardware).
And now let's look a bit higher. What follows is the most important feature of the Editor :
- Link. Each sound in Arkos Tracker can be seen as a mix of 2 envelopes : one Software, one Hardware. Most trackers will let you play with the Software one, a bit with the Hardware, but that's it. AT will allow you to play with both in three different ways :
- Link = Independant (two keyboards) : This is the default mode. In this mode, both Software and Hardware are independent (hence the two keyboards, representing the two "streams" of sound). The notes from the keyboard or the music are played independently by both "channels". In this mode, the most obvious process is to put a high Hardware Arpeggio, multiple to 12 (#C), which represents an octave. But you can also have an arpeggio of 5 (+ x*12), which will sound as if you had two notes playing at the same time ! One drawback of this mode is that the Pitch inside a pattern won't work well : the same Pitch will be used for both Software and Hardware envelope, but as they will most likely use different periods (if one of them uses Arpeggio and not the other), the periods won't be synced anymore, resulting in interference. The Independent mode is also the only mode that accepts having Sound set to Off. In this case, you can have an Hardware curve and no Software envelope (this results in a soft and "still" hard bass). Or you can have no Hardware curve, and a Noise. Drums often use this mode, as you sometimes want to have no Sound, and only Noise.
- Link = Software dependent (one keyboard above, an arrow downwards below) : This mode is the most used to make classical "Hard Bass" sound. The Hardware envelope is dependant to the Software. Software is the master, Hardware the slave. When using this mode, the "Ratio" line becomes active. What is it ? The ratio is how much the Software Period will be divised to get the Hardware period (remember : in this mode, the Hardware is dependent from the Software). To sum up : Hardware Period = Software Period / (2^ratio). Remember bis : the lower the period, the higher the note. Most of Hard Bass uses a ratio of 4 or 5. For this mode to be enabled, you MUST have an Hardware curve selected, and Sound MUST be On. One can't related to another if one is missing ! Also, note that since there is a division, precision will be lost. That's why having a high ratio gives most of the time very harsh sounds. Also, the loss of precision will result is "mwaaaaaawwwww" sound, which is wanted most the time. You will note that the Hardware Pitch is enabled : it will allow you to have a desync to the Hardware period, if you want to (so that you can control the "mwaaaww" even further).
- Link = Hardware dependent (one keyboard below, an arrow upwards above) : This mode was called "Sync" in STarKos, but is performed in Arkos Tracker in a mode straightforward way. The note you play (with the keyboard or in the music) is only given to the Hardware envelope. Then the Ratio indicates how to calcule the Software period : Software Period = Hardware Period * (2^ratio). Note here that since the Software period is a multiple of the Hardware period, there is no loss of data ! So the Software period is an exact multiple of the Software period. Which results in a perfectly "still" sound, very nice. But of course you can simulate your own desynchronization ("mwaaaah" sound) by setting a value to the Software pitch ! Note : this mode really works the best with higher notes.
Important : if there is inconsistency in your sound, then the Link is colored in red. This means that the tracker will use Independant mode instead of the mode you choose. What is an inconsistency ? It means that you asked for a specific sound, but you can't have it. For example, you wanted a Software Dependent sound, but have no Hardware curve selected ! The same if true for Hardware Dependent sound. Also, whenever you set Sound to Off, you HAVE to use Independent mode.
- Retrig : The Retrig has no effect at all if your sound doesn't use Hardware envelope ! This is an option to retrig the Hardware envelope at the beginning of the sound. This can provoke a nice sounding attack when triggering an Hardware sound several times in a row. Also, this is most useful when using a very slow Hardware envelope (for instance, a "Down" hardware curve with a period to 1000, like the sound "Hardware Volume" in the "Instruments/FXs" folder). If you want such sound to be heard more than once, you HAVE to retrig it, else the curve will continue to decrease and stay down even if you enter another note. Alternatively, you can also use the Force Retrig option, which is discussed just below...
The Hardware curve and the Retrig
---------------------------------
Now let's get into the Hardware curve that you can draw. Have some fun and try to draw a dozen of "Triangle 1" curves in a row. As you can see, the first one has a black outline. Why ? Let's experiment more : in the middle of all these curves, draw a "Saw 1" curve. It appears also with a black outline, and if right to it was a "Triangle 1" (which wasn't outlined), it is now outlined ! Whhhyyyy ??
Quite simple... Once you understand. Like I said before, the AY uses the Register 13 to know what Hardware curve to use. If you always use the same curve, you must not set the R13 each frame, because setting the R13 resets the Hardware curve (it's a behaviour of the AY, specific to this register), which is not the expected result, and will sound crappy if you're using a high Hardware frequency. So AT tests each VBL : is the current R13 the same as before ? If yes, do not set R13 again. If no, set R13 with the new value. This is what happens with the black outline : it simply means that the R13 is set here. That's what we call "Natural retrig". Whatever you want to do, this retrig will happen because it it needed. We consider the first line as a Natural Retrig, because we don't know what is the value of R13 before. However, R13 may not have actually changed if some previous sound used the same R13 value !
So that's why the "Saw 1" you added was outlined : the R13 had to be changed. And the "Triangle 1" just to the right, which was no retriggered before you put "Saw 1", is now a Natural Retrig, once again because R13 has to change.
Ready ? There's a feature above this : the Retrig itself. You can FORCE it. Like I said earlier, a Retrig can be useful if you want to "feel" the Hardware curve being triggered. It is needed for example if you intend to play the same notes with the same Hardware curve in a row.
Also, like said earlier, this is mandatory when using a very slow Hardware envelope (for instance, a "Down" hardware curve with a period to 1000, like the sound "Hardware Volume" in the "Instruments/FXs" folder). If you want such sound to be heard more than once, you HAVE to retrig it, else the curve will continue to decrease and stay down even if you enter another note.
So how to do that ? Simply left-click on the curve whose R13 you want to force, and click on "Force Retrig". This option will be written next to the curve drawing corresponding to the curve you clicked on. What happens ? The curve below appears outlined in red. Quite self-explanatory, isn't it ? If you want to remove the Retrig, left click on it and select the same curve.
How to use the CPCBooster
-------------------------
In order to hear your song in real-time on a CPC while composing with Arkos Tracker, you have to fit your CPC with a CPCBooster (http://dirtyminds.dxm.gr). Transfer the "Arkos TrackerTools.DSK" on a disc, and run the "client" file. The CPC should inform you that it is ready to receive data for the PC. Now go to the Setup, and choose the "CPCBooster" as an output. Don't forget to choose the right COM port ! Then, press OK and whatever sound you produce will be heard on the CPC. How fun !
ARKOS TRACKER - 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, Spectrum, Pentagon 128K or MSX.
- Play Sound Effects along with any music. Or Sound Effects only !
- Play music and sound effects in Assembler, or from Basic (Amstrad CPC. By CALLing the player. You can also use the Interruption mode, so that you only make one CALL, and the music plays on its own !).
- 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, on a Spectrum : max TM is 5300t, average is 2400t using the "Molusk" song !), 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 :
- Open the Assembler (F3), and load the Player.asm.
- Find the "Org #xxxx" mnemonic at the beginning of the program. change this address if you need to.
- CTRL+F9 to assemble it. You can see in the assembler output window where the player ends. Modify the "ORG" address if you think the player gets too high in memory.
- When you're done, simply save the player in a DSK, in Basic. Let's say the ORG is set to &1000, and that the code ends in &1900. Type this in Basic : SAVE"PLAYER",b,&1000,&1900-&1000,&1000. And you're ready to go !
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 :
- 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 Basic (on CPC), or under any OS, and you want some registers to be saved (by default, only the ones used by AMSDos will be saved, but you can modify that in the source). In order to secure the call, the player stops the interruptions, but restore them if needed. This is called the "BASIC" mode, or "system-friendly".
- Your production is on CPC only, most likely in Basic, and you just don't want to mess with any kind of code. A simple CALL will put the music into interruption. This is called the "INTERRUPTION" mode, and is very nice to Basic users.
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 :
PLY_Init : This one is needed once before playing the song. Without it, nothing will be heard. (DE = song address)
PLY_Play : Play one frame of the song. It can also resume the song if it had been stopped (with the function just after).
PLY_Stop : Stop the song, cut the sound.
Basic users can call these functions easily. If you have loaded your player in &4000 and your song in &5000 :
CALL &4000, &5000 : Initialize the song.
CALL &4000 + 3 : Play/resume the song.
CALL &4000 + 6 : Stop the song.
INTERRUPTION players don't exactly work this way :
PLY_InterruptionOn : Play the song (no need to initialize it). (DE = song address)
PLY_InterruptionOff : Stop the song.
PLY_InterruptionContinue : Resume the song.
Or in Basic :
CALL &4000, &5000 : Start the song.
CALL &4000 + 3 : Stop the song.
CALL &4000 + 6 : Resume the song.
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 more 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 :
- You can remove the jp PLY_Init / jp PLY_Play / jp PLY_Stop at the beginning of the code if you're directly jumping to the functions they're pointing.
- You can remove all the references to PLY_Digidrum 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 PLY_Stop function if you don't intend to stop the song !
That's it ! If you have any questions regarding this software or any suggestions, write here : contact@julien-nevo.com