AYAY Kaeppttn (aka SID tracker) manual

[BSC]

Here's a short description on how the player basically works:

The instruments work quite differently from what you might know from other trackers. It had to be that way to have fast access to instrument data while still
offering quite flexible instruments. Not everything is possible yet, though, like AY noise (register 6 based) and hardware envelopes. I have a couple of ideas and
are also open to suggestions.

Well, the instrument are based on 4 tables. Each table modifies one characteristic of the sound. All numbers are signed 8 bit hex, so FF is -1, FE is -2 and so on. 80 is special because it means jump (see below). The tables are:

   
• the semi tone offset on the current note (offset table), i.e. the value from that table will be added to the current note (which is kind of octave * 12 + note). This enables arpeggios etc.
• the notes pitch (vibrato table), i.e. the value from that table will be added to the pitch that has been deduced after any semi tone offset has been added. (The pitch for each semi tone is taken from a lookup table). This enables vibrato etc.
• the wave form to use (wavefrm). Only on the SID voice. For AY voices, it could be used for noise or other things...). The value here is actually just a memory address hi byte, so there better be valid sample data (which is true for all the pre-defined instruments).
• the volume (volume). The values there are upside down, i.e. are actually what is to be subtracted from the max volume (15). 0 means full volume (15), 1 is 14, 2 is 13 and so on. That's likely to change into a way ppl are more used to (at least for display) but is easier for the player to apply when playing the SID voice (it just has to subtract the current volume table value from the sample value)

Each instrument is defined by 5 values (likely to grow in the future) which are the AY target register number (only relevant on the SID voice) and the 4 tables I just mentioned.
The target AY register number (e.g. 8, 9 or 10 for wave playback) is the one into which the values from the wave table (depending on the current wave form) will be written.
The other 4 values represent the start position into the offset, vibrato, wavefrm and volume tables respectively. When an instrument starts to play, those 4 values are used to initialize
the player which will then look up the actual values from each of the tables and advance to the next row after each frame. Unless there'a a jp (jump) command which will cause the
pointer into that table to jump to the row number that comes after the jp command. So to create a major chord arpeggio in the semi tone table (at position 20), you'd put the values
00 04 07 for the chord and 80 20 to jump back to position 20. This is how all the tables work and this table walking will be done for all 4 tables for each instrument, on each voice, each frame.
I think you will get the point when you disable AY playback and play (jam) around with some of the pre-defined SID instruments.. There's also currently no way to create new instruments.
You have to modify any of the existing ones.

The tracks consist of a (non fixed) number of rows representing a note to play. Each row consists of 3 (or 4 if you view note and octave to be distinct) columns representing
the note and octave (i.e. C#5 means a C sharp on octave 5), the duration of that note/row (sadly, also in hex, but there's manifold remedies possible) and the instrument number.
There are 2 kinds of special rows currently. SLD (tone slide) and END (of track), see below. The duration is counted in "ticks" or frames or roughly 1/50 second, so a note with
a length of 32 (which is the hex representation of 50) will last one second. The maximum (visible and editable) track length is currently hard-coded to 32 rows.

The sequences consist of a list of track numbers to play on each voice. And track number FF (which does or should not exist) means "end of sequence" and will cause that sequence
to jump to the beginning. There's currently no way to start from any point within a sequence other than 0, i.e. when starting playback the song will always play from the beginning.
It's not supposed to stay that way but it's not so easy to start from anywhere because tracks can be of different lengths, thus playing back from e.g. position 10 on all sequences
might yield funny and most likely unwanted results (unless all tracks on all voices are equally long).


Here's a short manual describing the keys of each mode in the tracker.

There are 4 modes: instrument params, instrument lists, track lists (sequence), track

General keys (in all modes)

   
• ctrl D - redraw the screen (in case it gets messed up)
• ctrl R - reset AY (actually plays a chr$(7) beep)
• ctrl Y - toggle AY voices playback. On the screen you'll see "AY replay: " and 0 or 1. When 0, only the SID voice will play
• space (except for instrument mode, see there) - play the song. Currently, the song will always be played from the beginning, regardless of which track is edited or where the cursor was in the track list
• ESC - stop playback
• f1 - toggle AY voice A (On the screen you'll see AYa: 0 or 1)
• f2 - toggle voice B
• f3 - toggle voice C
• f5 - decrement octave (screen: top left)
• f8 - increment octave
• f4 - decrement instrument no. (which is also the instrument that will be used when entering notes in the track editor)
• f7 - increment instrument no. will wrap after the first / last instrument
• manual keys: just like in most other trackers, the largest part of the keyboard is used to represent two manuals of piano keys. The lower manual starts (on my german keyboard, but you get the point I hope) at Y (note C), S is C#, X is D, D is D# (sic) and so on until , and . (comma and dot) and the upper manual (one octave higher) starts at Q (note C), 2 is C#, w is D, 3 is D# and so on.. It's probably easier for you to just try it out.

Instrument params mode (top left):

   
• cursor left / right - jump between target register, offset, vibrato, wavefrm and volume.
• cursor up / down - decrease / increase the current value. Changes here will not be reflected in the instrument lists (switch the instrument to see the effect)
• enter - enter a 2 digit hex value at the current position. ESC will cancel editing

Instrument list mode (below the instrument params):

   
• space - set table position to cursor, e.g. when on position 03 on the offset column, this will be used as the start position into the offset table.
• cursor left / right - jump between offset, vibrato, wavefrm and volume column. When on the wavefrm column, the current wave form will be drawn to the right
• cursor up / down - move within the current column. it will always display 10 rows and scroll when you touch the upper / lower edge
• enter - enter a 2 digit hex value at the current position. ESC will cancel editing, the cursor will advance to the next row when a valid value was entered. Enter 80 to create a jump (jp) command
• ctrl + cursor up / down - increment / decrement the value at the current position

Sequence mode:

   
• cursor left / right - jump between the columns representing the wave, AYa, AYb and AYc voices. Will not wrap at the edge and will also memorize the current row of each column (as opposed to the instrument editor where the row will be preserved on column change)
• cursor up / down - move within the current column. it will always display 10 rows and does currently NOT scroll when you touch the upper / lower edge
• enter - enter a 2 digit hex value (see Instrument mode for details)
• ctrl + cursor up / down - increment / decrement the value at the current position

Track mode:

   
• cursor up / down - move within the track rows. it will always display 9 rows and scroll when you touch the upper / lower edge
• cursor left / right - jump between the note (and octave), duration and instrument columns
• ctrl + cursor up / down - jump 8 rows up or down
• f6 - switch to the previous track. The current number and total number of tracks will be shown above the track, i.e. current / total (and it's address in memory)
• f9 - switch to the next track. It will wrap at the edges
• enter - 2 digit hex value input and advance to the next row. ESC will cancel
• ctrl N - create new track. You will see the memory info area in the lower right corner change
• ctrl E - store EndOfTrack command, i.e. END in the note/octave column. When played, the row before the END will be the last one of that track
• ctrl R - will enter (repeat) the last value that was entered and advance to the next row. good to enter long rows of the same duration value, for example
• ctrl P (or CLR) - clear the current row, i.e. all 3 columns will be reset
• ctrl Q - store a slide command (SLD) instead of a note. The duration column works as always, the instrument column stores the slide offset

I will update this post whenever there's any relevant changes and I would also like to know if the description of how the instruments work is understandable and, if not,
what I could do to make it easier to grasp. Every time I said "currently" in this post implies that this is not meant to last for eternity and I either do already have ideas as
to how this can be extended, fixed, improved or am at least aware that it can't stay like this. But I am still open to suggestions, wishes etc.


So: please throw your thoughts at me!

[BSC]

please throw your thoughts at me!

Any thoughts to throw? I figure that the editing facilities are really fiddly and slow and all that,
but I think it's still worth to climb that learning curve..

[arnoldemu]

My thought is:

I wish I could put this into a demo or game right now. But I don't have anything ready for it just yet.
I will definitely use it.

[arnoldemu]

Another thought:

Make a tune and submit it to a party like Revision

Or does it require a standalone player for that rather than being played in a tracker?

[ralferoo]

Make a tune and submit it to a party like Revision

There was a SID-ish tune on the Speccy. It was nowhere near as nice as the sounds your program can make...

[arnoldemu]

@BSC: Another thought:

You have created a tracker which prooves SID sound is possible on a standard CPC. In fact, it's more than that, it's a SID-like sound but better because of the adjustable waveforms. And it's more than just a tune and a player, it's a full tracker so people can create tunes themselves. Not like a tech demo for example.

In the near future I want to make a standalone player for it and use it in a game. It will probably be on a title screen.

[BSC]

I wish I could put this into a demo or game right now. But I don't have anything ready for it just yet.
I will definitely use it.

Good to hear! But no hurry, as it's still not complete anyway and the whole stand alone player thing is yet to do.

[BSC]

Another thought:

Make a tune and submit it to a party like Revision

Or does it require a standalone player for that rather than being played in a tracker?

AFAIK the Revision compo was called "Oldschool executable", but it shouldn't be too hard to create an executable
from the current tracker (they won't show the screen anyway). But I am not a composer, just a converter / cover guy.
Real talented guys like McKlain or UltraSyd would have to do that.

[BSC]

@BSC: Another thought:

You have created a tracker which prooves SID sound is possible on a standard CPC. In fact, it's more than that, it's a SID-like sound but better because of the adjustable waveforms. And it's more than just a tune and a player, it's a full tracker so people can create tunes themselves. Not like a tech demo for example.

In the near future I want to make a standalone player for it and use it in a game. It will probably be on a title screen.

Thanks for your kind words, but I have to disagree on the completeness: Right now it's actually more of a tech demo and less of a full tracker.
Most of the work that's still missing is already thought through, but it has yet to be coded And the file format is also not yet defined because
some of the memory related things are still undecided. I think I should create some issues on github to cover all the open things.

[Overflow]

Any thoughts to throw?

Ok, let´s throw some thoughts! (or rather: write again but for everyone on the forum)


About the tracker, can't comment anything except that composers are required. For motivation or to go on designing the tool, you need some end-users using the tool. Or/unless: see next point, turn it into a tech demo.


About the core/engine itself: if there isn't any wish from end-users/composers, you could go on to get a fully usable player as a tech demo. Two main paths:


1) The first path is to emphasize on the sound only, i.e. designing your own music-disk, and adding some fancy fx during the songs. I may be someone to help you with optimizing the sid-engine and adding some constant-time fx. Not now and not soon, since I'm working on my own work first and exclusively. Then? we'll see.


2) The second path is demo-fx-oriented: let´s say a famous and talented coder wishes to integrate your sid-engine in his top-notch demo yet to be released. Great for motivation on the 2 sides. Many difficulties to solve, which includes synchronizing the screens and the songs so that sid-voices are switched on and off during all the demo (to allow heavy precalculation or trackloading or big fx which are not compatible with the sid-engine). Definitely not for me, the challenge is too high for a retired coder without ambition; better have a look towards the young generation.


About the tech-demo and/or the sid-player: it has been years since some people work on such idea. See also New release of Sid player
There are also (10 years?) old rumours about Madram working on a numerous channels sid-engine. I would suggest you contact him since he's back, to know a bit about his old work. We are all of the same family, you should try to ask.


As an another extreme path to follow, there's something which could please the end-users/composers: change your mind and modify your tracker so that it is ctc-ay compatible. For composers: 6 channels! For you coder: much more easier way to out to the 2 ay-chips.


That's all!
Oliverflow

[BSC]

About the core/engine itself: if there isn't any wish from end-users/composers, you could go on to get a fully usable player as a tech demo.

I think I am stuck in a chicken-and-egg-question like situation: The engine itself is actually ready to be used as a (basic) player. But there are a couple of unsolved issues (see BetaSoftCologne/AYAY · GitHub) in the tracker which also affect the player and which currently render the tracker almost unusable for ppl other than me. If those things are not in the tracker, there's no sense in having them in the player. And if they are in the tracker then I have to do all the additional work to make a "compiler" or something which yields a player that can make use of all the new things in the tracker. And I think there should be input from other composers before I go on coding. So far I only got McKlain to speak his mind. It was quite valuable but I bet there's more ...

1) The first path is to emphasize on the sound only, i.e. designing your own music-disk, and adding some fancy fx during the songs. I may be someone to help you with optimizing the sid-engine and adding some constant-time fx. Not now and not soon, since I'm working on my own work first and exclusively. Then? we'll see.

Yes, that's the most likely path right now.. And I guess I will be ready to continue on the tracker when you are done on your own work ;-)

2) The second path is demo-fx-oriented: let´s say a famous and talented coder wishes to integrate your sid-engine in his top-notch demo yet to be released. Great for motivation on the 2 sides. Many difficulties to solve, which includes synchronizing the screens and the songs so that sid-voices are switched on and off during all the demo (to allow heavy precalculation or trackloading or big fx which are not compatible with the sid-engine). Definitely not for me, the challenge is too high for a retired coder without ambition; better have a look towards the young generation.

You are right. That's going to be tough and only extremely talented coders will be able to deliver. Too bad we don't have those kind of coders currently ;-) And I am also intensely gazing at the young generation (and into the direction of Rhino )

About the tech-demo and/or the sid-player: it has been years since some people work on such idea. See also New release of Sid player
There are also (10 years?) old rumours about Madram working on a numerous channels sid-engine. I would suggest you contact him since he's back, to know a bit about his old work. We are all of the same family, you should try to ask.

But the SID player from this Thomson guy is very different. It's very impressive and I like that someone made it but it doesn't allow you to have SID voices on the CPC.

I know about Madrams engine and I also contacted him on PnP, but he seems to be extremely busy (or offline or not interested or switched to Amiga) and hasn't replied yet. Family *sigh*

As an another extreme path to follow, there's something which could please the end-users/composers: change your mind and modify your tracker so that it is ctc-ay compatible. For composers: 6 channels! For you coder: much more easier way to out to the 2 ay-chips.

That might be something I'll do for the sheer fun of it in a very very far away future (or much much earlier in case Professor Farnsworth finally invents the day-prolonging-machine). Apart from that I think this will result in an even more exotic tracker and given the sparse amount of active composers on the CPC and the fact that anyone wanting to make music on 6 channels PLUS anyone wanting to listen to it would need that device: even to me that sounds too twisted right now.

So, as it seems, I am still on my own with this thing and will be for the rest of the year (I bet). And I am also very busy with a lot of other things atm. But - I tell you! - 2015 will be the year of the Kaeppttn!

[Overflow]

@BSC: I believe we wrote down all the content of our last mails.

(...) And I guess I will be ready to continue on the tracker when you are done on your own work ;-)

I should be busy until Easter next year... ->

(...) So, as it seems, I am still on my own with this thing and will be for the rest of the year (I bet).

-> ... so your bet might be a win.

I know about Madrams engine and I also contacted him on PnP, but he seems to be extremely busy (or offline or not interested or switched to Amiga) and hasn't replied yet.

Or eventually finalizing his SID-player with Shap which could explain no answer.

For all those points, waiting 'til next year is wise imho.

[madram]

I'd like to work on AyAy Kaeppttn with August (OvL! summer of code), so let me share some ideas for the potential users to comment/improve.

Tables, tables everywhere !

Key points: simplicity, flexibility, powerility.

Let's start with arpeggio example. Starkos's lack of arpeggio tables is clearly a PITA. But it's also nice to be able to set arpeggios in the instrument itself. My take for this later point: use the same principle in the instrument editor than in pattern editor. I.e. enable a custom arpeggio via an 'arpeggio command' followed by the table number.

Actually, the instrument editor would share most of effects with pattern editor. We could see an instrument as a "macro" combining the activations of several effects.

Another example. If we want to change noise table inside the pattern itself, instead a special hack command (C in Soundtrakker, if I recall well), both in pattern and instrument we would use the same command to use a dedicated noise table.

* Advantage 1: best of both worlds.
* Advantage 2: the loop period for each table is independent.
* Optimization-wise (replay code), it's mixed. We had to handle more pointers. But when the effect stops (or if it's not used at all), we can save the whole operation (instead of processing a zero-filled sequence). Anyway it doesn't matter much, replaying can be optimized while 'compiling' the module, or by using an AYC-like stream.

To be continued.

[madram]

Sequencer and tracks/phrases.

Key points: uniformity, flexibility, relativity.

I like the idea of tracks in Starkos and phrases in LSDJ.
Let's use the later naming, and add a custom touch.
A phrase is typically where you enter notes and effects. The speed at which each row "scrolls" is determined by the so-called (in Soundtrakker) delay. One nice idea in LSDJ is the ability to use an alternating delay (eg 5 for even rows, 7 for odd ones). In any case, it would be great to be able to change this delay phrase-wise.
At the end of the phrase, a flag would indicate auto-looping or not.

Ok, looping is pretty dumb. Often, we want some variations, and/or interleave new stuff. I'll address these points in a few moment.

In the sequencer, we poke phrase numbers. But for full generality, we may trigger them at any time. E.g. :


0.00.0   0    1    2
0.64.0             3
0.96.0   4         5


In this example, if phrase 0 is 128 rows long, it will be cut at timestep 0.96.0 to be replaced by phrase 4. Phrase 1 may be 32 rows long and loop, etc.

A cool thing would be to enter commands in the sequencer just like in phrases. So you can trigger volume change, vibrato, transposition, etc in an uniform way.

   
• Use case number #1 : reverb/echo effect, by playing the same phrase on two distinct voices, with a slight shift.

Actually I see two ways to achieve that.
1/ By re-triggering the phrase (0 here) one tick later.


0.00.0    0    1     
0.00.1              0


2/ With a special command (delaying following notes)


0.00.0    0    1     0 SD1

   
• Use case number #2 : you've understood how the sequencer would allow to replay a phrase with transposition, or vibrato, etc. What about replaying a phrase with another instrument ?

I've suggested to BSC the ability to leave instrument undefined, so we've just have to set it in the sequencer.
Of course, this doesn't apply when instruments are interleaved in one phrase. But for both this concern and the ability to add other variations on a repeated phrase, I have discovered a truly remarkable solution which this forum box is too small to contain.

Next time, I'd like to discuss to a way to insert a triplet (terzina) without messing with delay.

[madram]

Dumping my thoughts, part 6.

I think Soundtracker and/or Starkos import is almost mandatory to have! To reshap(e) old unused modules, and to compose easily until AyAy catches up.

[Technical detail] Handling periods on 16 bits instead of 12 would allow finer control of vibrato/portamento. The player may add e.g. 0.625 each tick at very little cost.
Also, SID effect can take advantage of this greater precision. The resolution remains poor (64µs vs 8µs) but for high notes the average period will be closer to real period.
Maybe 14 or 15 bits is a good compromise.

[Technical detail 2] Linked "lists" are a neat way to manage tables, both for player (nothing special to do to handle looping. That's what Targhan -being a neat boy- does in its player) and for editor, allowing quick table updates (insertion and deletion).

Once again, in my book, memory/CPU consumption are not an issue in the editor. I would rather sacrifice them for gained features.

Which leads us to the following request: live editing of an instrument/table while a section is playing.

[madram]

Effects applied to effects.

Key points : joy, power, meta.

Some FX come with parameter updatable at each tick. E.g. an enhanced 'SID' effect would allow to manually control duty cycle (from 0: 0% to 255: 100%). But filling a table of such parameter is tedious. So, we should allow to apply an 'effect' (vibrato, slide) to the parameter itself.
NB : since we define a vibrato by its speed and amplitude, the center of the range should be set independently. E.g. for [50;100] vibrato range, set base value to 75 beforehand.
By default, Vibrato/slide effects are applied to note's period. I don't see yet the best way to link them to an arbitrary parameter.

[madram]

TODO

So I plan to update AYAY's UI by using this set of routines : SongInterface - ORGAMS

Then there are these routines to code. It might be tricky depending on how much the data structure is adapted to fit the suggested views.
On the other hand, I can also adapt things on my side, given solid arguments !

Anyone willing to participate ? Ask not what Kaeppttn can do for you, ask what you can do for Kaeppttn.

[HAL6128]

How can we support?

[madram]

Glad you asked !

There are four modules which can be worked on independently :
1/ The UI, using the routines described in link above (aka 'song interface').
2/ .128 to AYAY converter, using this same set of routines.
3/ The code of the routine themselves, modifying the song data.
4/ The player, based on song data.

BSC is more likely to work on 4, but I don't know if he is still in town.

For now, song data don't quite fit the table-based structure I've suggested.
The first step is either to agree on the 'song interface' or to propose something better/closer to existing structure (but my take is to make it easier for the user, not for the coder).
Then, anyone can work on 1/ and 2/.

We must also choose whether we modify the way the song is encoded (cf BSC's 1st message in this thread). Doing so would make 3/ trivial but require to work on 4/.
The other option amounts for 3/ to do on the fly translation in both ways.

About the UI, I wish to make it data controlled, i.e. a generic engine and tables to describe screen display and interactions.
But some parts may still be done separatly (e.g. X-MASS compatible file selector).

Reminder, current source code is here: GitHub - BetaSoftCologne/AYAY: AYAY Kaeppttn! The ultimate tracker for your

[roudoudou]

About the UI, I wish to make it data controlled, i.e. a generic engine and tables to describe screen display and interactions.
But some parts may still be done separatly (e.g. X-MASS compatible file selector).

Is there anything started? Specifications? Requirements?


A flexible UI may be reused for any other project. This should be a separate project.

[madram]

[Edit : updated requirements]

No spec yet, except for field editor (in french) : http://orgams.wikidot.com/notes#toc0

Requirements :
   * All UI description (layout, keymap, etc...) must be data driven (declarative mini-language with simple operators).
   * System friendly (don't use EXX / EX AF)
   * All-terrain (mustn't use firmware). We may use firmware key manager in first version.
   * Done on CPC if I must be involved in the code. (Orgams has text import/export).
   * Screen-size agnostic (i.e. can be overscan or other custom format)
   * Textmode based for maximum efficiency.
   * But open for mixed mode (sprites, pixel-precise placement, proportional fonts)
   * Can handle mix of 1 to 4 bytes-wide fonts in any mode.
 

My take is to iteratively replace AYAY's code, starting by pattern editor, by an increasingly capable UI engine.

Orgams already contains some helper routines (fast text display, decimal display, ...).

[TFM]

BTW: Sorry for getting off-topic, but since some homepages closed: Where can I get the last version of Orgams?

[madram]

Last beta here : http://orgams.wikidot.com/local--files/working/orgams-160526-Codigo-Con-CPC-betai.hfe
Release notes near the top of Working - ORGAMS

You can now burn Orgedit.rom in any firmware-visible slot, and the others at any place.

[TFM]

Thanks! Awesome! 

[madram]

Oh! Another advantages to be able to use an arpeggio table from the instrument or the phrase itself:

   
• allow to play arpeggio in two subtly different ways: called from the instrument, it will be re-triggered at each note. Set once in the phrase, it will run independently.
• we may mix 2 tables, e.g. a chord in the phrase, and a +12 attack in the instrument.