THE PROGRAMMING LANGUAGE ======================== Note: please read this section carefully before experimenting, because you can lock up your machine with the synthsound programming language (as with any other language) The programming language is used for controlling the volume/pitch/vibrato/ waveforms/arpeggio/etc... of the synthsound. It consist of simple keywords, of which some have an argument. The programming is done using two lists of commands/numbers. These lists are displayed through a small window below the right waveform display. First there are line numbers in decimal and hex (two leftmost columns). The middle column contains the volume sequence, while the rightmost is the waveform/pitch sequence. volume ctrl seq | line | waveform ctrl seq | | | 00 00 40 00 01 01 END END These lists are both max. 127 ($7F) entries long. The list is always terminated with "END" instruction (it's automatically there so you don't have to do that). You can scroll the list with cursor up/down -keys. The cursor can be moved horizontally using the cursor left/right -keys. There are six possible cursor locations (3 for both lists). When entering commands, the cursor should be on the leftmost position of that list. Values are entered by pointing the cursor over the value to be changed and entering a new value. Commands and numbers are entered with keyboard. You can insert entries to the list with the Return-key (or clicking Ins-gadget), and delete using Del (or clicking Del-gadget). JMP commands are renumbered when entries are inserted or deleted. ALL NUMBERS IN THE SEQUENCE LISTS ARE HEXADECIMAL. Just remember this, and you have no problems (fingers crossed :^) Also, the editing (Esc) must be on before the lists can be changed. First, let's examine some example sequences: This is a volume sequence: 00 40 <= set initial volume to 64 (hex $40, did you already forget?) 01 CHD <= command, that means "Set volume change down speed" 02 03 <= argument (speed = 3) 03 END Here's another: 00 00 <= initial volume = 0 01 CHU <= Command: Set volume change up 02 07 <= speed = 7 03 WAI <= Command: Wait 04 10 <= wait 10 pulses 05 CHU <= Set volume change up 06 00 <= speed = 0 -> stop changing volume 07 WAI <= Wait 08 70 <= 70 pulses 09 CHD <= Cmd: Set volume change down 0A 01 <= speed = 1 (slow) 0B END Third: 00 40 <= vol = $40 01 30 <= vol = $30 (without command, the values are volume changes) 02 20 <= vol = $20 03 END And fourth, finally: 00 40 <= vol = $40 01 CHD <+ <= change down speed.. 02 01 | <= ..= 1 03 WAI | <= Wait.. 04 20 | <= ..20 05 CHU | <= change up 06 01 | <= ..1 07 WAI | <= Wait.. 08 20 | <= ..20 again 09 JMP | <= Jump (= goto) 0A 01 -+ <= to line number 01 0B END Now some wform/pitch sequences. Wform/pitch sequence is the "mastersequence" while the volume sequence is a kind of "slave sequence". First: (the simplest case) 00 00 <= set waveform #00 01 END A bit more complex: 00 VBS <= set vibrato speed 01 40 <= speed = $40 02 VBD <= set vibrato depth 03 02 <= depth = 2 04 00 <= waveform #00 05 END And very complex: 00 ARP <= start arpeggio sequence 01 00 \ 02 03 arpeggio values 0, 3, 7 (minor chord) 03 07 / 04 ARE <= end arpeggio sequence 05 VBD <= vibrato depth 06 06 <= 6 07 VBS <= vibrato speed 08 40 <= $40 09 00 <= set waveform #0 0A 01 <= set waveforms 01 - 0A (one timing pulse/waveform) 0B 02 | | 0C 03 \ / 0D 04 \_/ 0E 05 0F 06 10 07 11 08 12 09 13 0A and back to #01... 14 08 15 07 16 06 17 05 18 04 19 03 1A 02 1B 01 1C JMP <= jump 1D 09 <= to position 09 (restart waveform changing) 1E END ----------------------------------------------------------------------------- You can learn a lot by examining the example synthsounds and by experimenting. Now, some reference... About timing ŻŻŻŻŻŻŻŻŻŻŻŻ For both sequence lists, most of the commands are fetched, executed, and the next command is immediately fetched. There are also some commands that wait for the next timing pulse, this is important because the computer would otherwise send all its time executing the sequence lists (and would hang up). You should take care that all loops contain a command, that waits for the next timing pulse. These commands are WAI (Wait), vol chg (plain number in the volume list) and set waveform (plain number in pitch/wform list). For example, the following loops will hang up your computer: 00 JMP 00 CHU <-+ command CHU doesn't wait 01 00 01 02 | ... 02 JMP | 03 00 --+ While the following would not: 00 20 00 WAI 01 JMP 01 02 02 00 02 JMP 03 00 Execution speed ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The synthsound handling routine is called once every interrupt. This means that the handling is usually done 6 times/note (can be changed with secondary tempo, see main docs). Both lists have an execution speed, that is the speed of the operation. When the speed is 1, the next command is fetched/pitch changed etc. on every interrupt. If the speed was 2, it would happen every second interrupt (runs two times slower). The initial execution speed can be set with the two speed gadgets. During executing, the speed can be changed with command SPD. VOLUME SEQUENCE LIST COMMANDS ============================= 1. Set volume Command: --- Keyboard: --- (key needed to enter the command) This is the default command (no command identifier). It sets the absolute volume of the synthsound. It should be 00 - 40. Note that the relative track volumes are not used in synthsounds (mostly because of performance reasons). Example: 00 30 ;volume = $30 01 10 ;volume = $10 ... 2. End sequence Command: END Keyboard: --- This command terminates the volume sequence list. It's always there and automatically inserted. You can't insert commands past this one. 3. Set volume change down speed Command: CHD Keyboard: D This command sets the speed, in which volume is decreased each timing pulse. The volume starts changing automatically after this command. To stop automatic volume sliding, issue this command with speed 00. Example: 00 CHD 01 05 ;speed = 5 ... 10 CHD 11 00 ;speed = 0 -> stop sliding 4. Set volume change up speed Command: CHU Keyboard: U This command is like CHD, except it sets the volume change up. 5. Wait Command: WAI Keyboard: W This command waits for specified amount of timing pulses (pause). Example: 03 WAI 04 10 ;wait for 16 ($10) pulses to occur 6. Jump Command: JMP Keyboard: J Causes an immediate jump to another position of the volume list. Example: 05 JMP 06 0A ;jump forward to line 0A 7. Jump waveform sequence Command: JWS Keyboard: Shift-J This command causes a jump in the waveform sequence. This can be used for example, to trigger a pitch change at the end of the vol seq list. Note that this DOESN'T cause a jump TO waveform sequence. Example: 04 JWS 05 0F ;Cause jump in waveform sequence list 8. Halt Command: HLT Keyboard: H This has the same effect with command END (halt execution), but it can be inserted in the middle of the sequence list. Example: 03 HLT 04 04 ;some other code (can be accessed with JMP instruction, for ... example) 9. Set speed Command: SPD Keyboard: S Sets the execution speed. Example: 0A SPD 0B 01 ;speed = 1 (fastest) ... (The following commands require OctaMED V2.00 / MED V3.20 or later.) 10. One-shot envelope Command: EN1 Keyboard: E This command allows you to draw the shape of the envelope with the mouse. When the end of the envelope is reached, nothing occurs. 02 40 03 EN1 04 05 Waveform 05 is used as an envelope. Note that the envelope execution starts on next interrupt, so the volume is initialized to $40. The envelope waveform must always be 128 bytes long!! 11. Looping envelope Command: EN2 Keyboard: Shift-E This works like command EN1, except that when the end is reached, execution will start again from the beginning. WAVEFORM/PITCH SEQUENCE LIST COMMANDS ===================================== 1. Set waveform Command: --- Keyboard: --- This command is used to indicate the waveform number (starting from 00). After this instruction, the execution stops until next timing pulse occurs. Don't use waveform numbers that are higher than the actual number of the last wform. Example: 00 00 ;wform 00 01 01 ;wform 01 ... 2. End sequence Command: END Keyboard: --- This command terminates the wform/pitch sequence list. It's always there and automatically inserted. You can't insert commands past this one. 3. Set pitch change down speed Command: CHD Keyboard: D This command sets the sliding speed for sliding pitch down. The sliding automatically starts after this command and stops, when speed is set to zero. Example: 00 CHD 01 03 ;set speed to 3 ... 4. Set pitch change up speed Command: CHU Keyboard: U Just like previous, but slides pitch up. 5. Wait Command: WAI Keyboard: W This command waits for specified amount of timing pulses (pause). Example: 03 WAI 04 02 ;wait for 2 pulses to occur 6. Jump Command: JMP Keyboard: J Causes an immediate jump to another position of the wform/pitch list. Example: 05 JMP 06 0A ;jump forward to line 0A 7. Jump volume sequence Command: JVS Keyboard: Shift-J This command causes a jump to happen in the volume sequence. Can be used e.g. for triggering volume changes after some wform event. Example: 09 JVS 0A 00 ;start volume sequence from the beginning 8. Halt Command: HLT Keyboard: H This has the same effect with command END (halt execution), but it can be inserted in the middle of the sequence list. Example: 03 HLT 04 04 ;some other code (can be accessed with JMP instruction, for ... example) 9. Set speed Command: SPD Keyboard: S Sets the execution speed. Example: 0A SPD 0B 01 ;speed = 1 (fastest) ... 10. Begin arpeggio definition Command: ARP Keyboard: A This command starts the arpeggio sequence. The following values are the arpeggio offsets from the base note. The arpeggio sequence is terminated with ARE-command. The arpeggio starts automatically after the sequence is defined. Example: 03 ARP ;start arpeggio 04 00 ;offset values 05 04 06 07 07 0A 08 ARE ;end arpeggio definition 11. End arpeggio definition Command: ARE Keyboard: E Ends an arpeggio definition. See above. 12. Set vibrato depth Command: VBD Keyboard: V This command is used to set the vibrato depth (00 - 7F). Example: 02 VBD 03 04 ;set depth to 4 13. Set vibrato speed Command: VBS Keyboard: Shift-V This command sets the vibrato speed (00 - 7F). Both speed and depth must be nonzero for vibrato to occur. Example: 02 VBD 03 04 ;depth = 4 04 VBS 05 30 ;speed = 30 14. Reset pitch Command: RES Keyboard: R This command resets the pitch of the note to its initial pitch. (The following command requires OctaMED V2.00 / MED V3.20 or later.) 15. Set vibrato waveform Command: VWF Keyboard: Shift-W Sets the vibrato waveform. The argument is the number of wform. The waveform should always be 32 bytes long!! Note that it's actually played reversed (use the Rev gadget to reverse it). By default, sine wave is used. Example: 00 VBD 01 06 02 VBS 03 40 04 VWF 05 04 ;use wform number 04 as vibrato waveform ============================================================================= Synthsound handling commands in the songs: Command E in the songs controls the MIDI pan, if used with MIDI, but with synthsounds, it is used to trigger a jump in the wform/pitch sequence list. For example, if you wanted to decrease the pitch of the sound after a certain point, your wform/pitch sequence could look like this: 00 VBS 01 40 02 VBD 03 06 04 00 ;play wform 00 05 HLT 06 CHD ;pitch changing entry point 07 02 08 END Now you could compose a track like this: C-2 3000 ;this is the previous synthsound --- 0000 --- 0000 --- 0E06 ;cause a jump to position 06 (pitch starts to slide down) --- 0000 ... With command JVS, you could make the command affect volume sequence too. Hold/Decay: =========== Hold/Decay work well with synthsounds too. The decay value in synthsounds is, however, a jump address in the volume sequence list. When the decay should start, the execution will jump to this entry in the vol seq list. This means that you can handle the decay on any way you want. You can also make it affect the pitch/wforms using the command JWS. Example volume sequence list: 00 40 ;volume 01 HLT ;end 02 CHD ;decay handling (entry point) -> cause decay 03 03 04 END The decay value for this synthsound should be 2. When you save/load synthsounds, the decay values are saved/loaded with the instrument. ============================================================================= HYBRID SOUNDS ŻŻŻŻŻŻŻŻŻŻŻŻŻ Hybrid sounds are much like synthsounds, except that there are no waveform pieces. Instead, there's a normal sample. All commands of the synthsound handling programming language can be used with hybrid sounds. There's only one thing you should know: Don't use "Set waveform". Because there's only a single waveform, there's no need for that (and it wouldn't work anyway).