---
# System prepended metadata

title: Ayane Ayane LaCarrée

---

Some bits to move to https://github.com/slaykachu/ayane

# Ayane Ayane LaCarrée

There is a ton of (contextual) help inside the program itself, to such an extent it should always feel you are in tutorial mode.
Then, why is an external documentation needed at all?

# Sequencer a.k.a "Song Map", where you clip phrases and event.

### Edition
Return: New track in current channel
Enter: Enter new event or phrase (while be asked)
Control-Del: Delete track

### Navigation
Cursor Up/Down: Next/Previous track
Cursor Left/Right: Next/Previous phrase

Note: trying to be consistent accross tools. 

## Description

### Vertical axis

We distinguish track and channel (see [#nomenclature]).
(TODO) Several tracks can address one AY channel (e.g. software sample mixing, and more interesting exemple below). 
The other way around could make sense (multi-resolution sample dispatched on 3 channels), but isn't handled yet.

By default there are 3 tracks, one by channel as you would expect.

### Horizontal axis

The horizontal axis designates time.
There is no notion of pattern, as each phrase has its own duration and is freely placed on a track (with tick resolution).
(TODO) For easier naviguation tough, there is a concept of bar/measure that only impacts the visualisation.

### Depth axis

Well, no such thing! If you want to have two things happening at the same time, create a new track for the same channel. (TODO)
This allows:
   * External events.
   * Software mixing.
   * Replay one phrase but change just one note!
   * Replay the same phrase with different effects or different "master" volume.
   
Yes! Controllers such as 'transposition' or 'channel volume' doesn't require special handling, they are managed via the same commands you use on phrases or instruments. That's much more generic and powerful. At least that's what my neighbours say.

Ok, that would be a bit of a stretch to do a transposition with an ARP effect, so I've introduced a TRANS effect, which:
   * Does exactly the same thing under the hood player-wise.
   * Display the transposed note UI-WISE.
In compiled module they collapse to the same code and routine.

### Actions

#### Inserting an event

To insert an event on a track, press enter, pick the kind you want in the menu, and press enter again.

##### Phrase xx

Start playing phrase xx. Until next event, the phrase will be replayed in loop.

##### Sound event

Change note, volume and/or effect(s). 

##### External event xx

Send xx to pseudo-register 14. No impact on the music, it's only to trigger external event (think demo synchronisation).
TODO? Have byte/word kinds?
TODO: sticky or not? 

#### Stop

Stop a phrase (mute).

### Further possibility exemples

   * You can interrupt a phrase by another.
   * You can put the same phrase on different tracks, seperated by one or more tick for a resonnance effect.

## Phrase editor

TODO

## Instrument editor

To edit an instrument, select it via CONTROL-I and arrows, then CONTROL-ENTER.
Note1: Using CONTROL-ENTER on a phrase row will automatically enter the corresponding instrument. Then you can use CONTROL-RETURN to go back where you were.
Note2: The starkos shortcut CONTROL-f3 is handled but deprecated.


An instrument consists of rows:
```
   #  🔊 
  00  A  |PSG|     |ARP +12| |SID| |Noise 01|
  01  B  -         x         -     x
> 02  D  -                   - 
  03  D  |ARP +12| |PSG|     -
```

   - `>` is the looping point.
   - `#` is the row number.
   - 🔊 is the volume in hexa (`0` to `9` then `A` to `F`) where `0` is mute and `F` is the loudest.
   - |xxx| is an optional command and lasts until stopped (`x`) or replaced by another one.

See [Effects/Commands] for reference. The most common will be |PSG| to send the period to the AY.
It is explicitly set, as order of commands matters:
   * In line `00`, we send the base period to the PSG, apply the +12 to go to the next octave and send the new period to SID effect.  
   * In line `03`, both PSG and SID period will be the same. 

### Examples

#### Reproduce SDMA's HW-piloted sound.

The goal is the have the 'software period' aligned with the 'hardware period'.
Well, the philosophy here is different, just use the `FLOOR` command.

### The coder's corner

The guiding principle of Ayane is to help the musician, not to have a fast replay or tiny module size.
In some glorious instances, all these goals are achevied at once.
Having composable effects that can be plugged in instruments or phrases:
   * Enable crazy stuffs (several SRMs at different harmonics? Check!)
   * Ease the edition
   * Allow to quickly test stuff (e.g. you don't have to repeat an effect on each row)
   * Optimise size and replay time (aka "only pay for what you use"). For instance, if hardware period is never used, it won't encumber instrument data, and the generated player won't embed the dedicated routine (or even have to test any flag related to the effect).

## Effects/Commands

When applicable, the effects work exactly the same in sequencer, phrase or instrument.
All effects are persistent until cancelled or replaced by another effect in the same column.

### Pitch related

#### ARP xx

Modify note by xx half-tones (from -63 to +63). Wrap if overflow (i.e. no clipping). ARP commands cummulate.
For an arpeggio rendition, you must issue several ARP commands, or use an arpeggio table (not yet supported).

#### PITCH Down xx

Add xx/4 to current period.
The effect is applied on each tick. Since the base period is recomputed at each tick, it is not cummulative (for that, see glissando effect).

#### PITCH Up xx

Remove xx/4 to current period.
Same remark than for pitch down.

#### ROUND &xx

Apply `AND &xx` binary operator to the current period. Also an hommage to Floor Jansen.
The goal is to align the software period to the hardware one, which have less precision.

#### SRM-Simple (Square ring modulation)

Alternate sound on-off via control register 7. Noise flag is left as is.
So called "SID" effect on Atari ST.

Note: if you want to slightly change the period to get dynamic dephasing, use PITCH **before** using this effect.

The cumulation of several SRM-Simple is not yet supported. It will act as XOR (meaning that using two SRM with same period is useless).

For now there is no phrase editor or instrument editor, so this effect must be placed by adding a new virtual track in the sequencer.

#### SRM-Volume x (Square ring modulation, Volume)

Alternate between current volume V and (V-x) clipped at 0.
* For x = 0, no effect at all.
* For x = 15, same effect as SRM-Simple.

#### TRANS xx

Like ARP, the only difference is in the GUI: highlight transposition value and show transposed notes.

### Type of sound

!!!Warning!!! Brain dump, this section should be revisited.
E.g. most of the listed "types" should be effects, and type of sound would be reserved to high-level type (e.g. soundchip vs sample vs midi).
Oh wait, I remember now. In instruments, we need to specify PSG output as a command, to precisely control which period is used.

Exemple: PSG, Arg +12, SRM would use send the note to the PSG, then recompute the period (one octave higher) before using it for SRM effect.

#### HENV x

Send period/16 to AY hardware enveloppe. Set enveloppe type x if not already x.

#### HENV_RETRIG x 

Send period/16 to AY hardware enveloppe. Set enveloppe type x unconditionally.

#### PSG

Send the period to the AY. 

#### SRM

Send the period as SRM (SID) effect.
```

## Shortcuts


### Working anywhere

* CONTROL ESPACE: Start replay from bookmark (default: from start)
* CONTROL P: Paste row
* ESC: Stop replay

#### Block related

They all start with 'COPY'

* COPY-S:   Set start of block
* COPY-E:   Set end of block
* COPY-C:   Copy block
* COPY-V:   Paste block
* COPY-DEL: Delete block
* COPY-X:   Delete block (alternative shortcut)
* COPY-SPACE: Start block replay. 
TODO...

### Deprecated

CONTROL-f1: Jump in sequencer 
CONTROL-f2: Jump in phrase editor
CONTROL-f3: Jump in instrument editor 

