README.commands

This is the documentation of the commands.


Please note the frequency modulation is or is not available, depending which the branch has been fetch

************************
THIS IS AN EARLY VERSION
************************


It describes all the (available) formats for all the commands. The transport modes are defined in the README.parameters file.

It gives the minimum, maximum and step values. Internally, it works as short messages using values with short mantissas and exponents (of 2). That means, even the text modes are heavily truncated. To see how, one can set an output parameters channel on the console ( -o - -F txt ) to see the actual values. The software can run using sampling rates from 3KHz to 192KHz. However, the commands are exactly the same.

The two amplitude modulation are named amplitude modulation and pulse modulation. The difference is the first one is a basic sine modulation, the second has PI/2 and 3.PI/2 hold times.

The midi (code) word is an alias of midi mapped (code). The early versions of the project uses music editing software but with a mapping between the notes and the commands.

Some nicknames are used:
* e: exponent
* m: mantissa
* c: constant added to the exponent
* v: integer value
* x: other data
* -: don't care



OF Base frequency
-----------------
midi= 0000 0eee   0mmmmmmm				c=1				midi note: C00 to G00

This is the base frequency of all the output waveforms except the continuous. The sampling rate should be at least 48KHz (or the software quits).
In case of a continuous waveform, this command has no effect. The sampling rate can be all the possible values (but it is a non sense to use the high ones).

TODO calculation formula.
The maximum frequency is eee=$7 and mmmmmmm=$7f, 2976.56Hz.
The minimum frequency is eee=0 and mmmmmmm=1, 0.183Hz
The step is not constant. At the highest frequency it is 23.44Hz. At the lowest frequency, it is 0.366Hz.



OS Main amplitude slew-rate
---------------------------
midi= 0000 1eee   0mmmmmmm				c=0				midi note: G#00 to D#0

This controls the speed of every main amplitude change, see below.
It is a slope.
It it the time the amplitude takes if the change would have been from 0 to 100%, or 100% to 0.
In case of a small change of the main amplitude, the time to reach the new value is lower.

TODO calculation formula.
The longest time is eee=0 and mmmmmmm=$1, 174s
The shortest time is eee=$7 and mmmmmmm=$7f, 2.666mS
The step is not constant. At the shortest time, it is 40uS. At the longest time, it is 87s



Modulation depth slew-rate
--------------------------
It is slightly fast. Today, it is hard-coded.



OA Main amplitude
--------------
midi= 0001 000e   0mmmmmmm				c=0					midi note: E0 or F0

Set the main amplitude from 0% to 100%.
On every change on this value the output changes using the slew-rate defined above.
The electronic version multiplies this value by a potentiometer.
The software version might, in the future, multiply by a value passed in the command line.
Since output of the software version is supposed to be sent to a file, a device etc... , there is no modifier to the main amplitude.

TODO calculation formula.
The lowest value is e=0 and mmmmmmm=0, 0
The highest value is e=1 and mmmmmmm)$7f, 100%
The step is about 0.79% or 0.395%, regardless the value.



NN No operation
---------------
midi= 0001 0010   0vvvvvvv				c=N.A.			midi note: A#0
vvvvvv is every value except $1111111

This does not do anything. The value is not treated in the software but it is passed to the commands outputs.
The purposes are:
* Reserve some room for a manual edition of a binary file.
* Make a kind of TTL or step display, especially with the -N 0 option of the output command



Abort
-----
midi= 0001 0010   01111111				c=N.A.			midi note: A#0 

This input commands channel is discarded. If all of them are discarded or have reach an end of stream, the program quits.
The main purpose is to run a partial scenario for test.
The value is the time before leave (not yet implemented).



 
FA, AA, BA Modulation depth
---------------------------------
midi= 0001 0xxx   0vvvvvvv				c=N.A.		
  xxx=011 for the frequency modulation						midi note: A#0
  xxx=100 for the amplitude modulation						midi note: G#0
  xxx=101 for the pulse modulation							midi note: A0

Set the depth from 0% if the value vvvvvvv is 0, to 100% if the value vvvvvvv is 127.
The step is about 0.79%, regardless the value.
If the modulation depth is 0, the output of the modulator is always its input signal untouched.
If the modulation depth is 100%, the output of the modulator is between 0 and the its input signal according with the modulation.



BM, AM Modulation mode
----------------------
midi= 0001 0110   0000 0xvv				c=N.A.			midi note: A#0
xx=0 for the pulse modulation BM
xx=1 for the amplitude modulation AM
vv = 00 using a sine from -1 to +1 translated into 0 to +1 \n
vv = 01 using the absolute value of a sine from 0 to +1, be careful freq is double!\n
vv = 10 using opposite of the absolute value translated into 0 to +1, be careful freq is double!\n
vv = 11 is reserved

Set how the sine of the modulation is used. This computation gives always a value between 0 and +1.
If it is +1, the modulation left its input untouched.
If it is 0, the modulation reduces its input according with the modulation depth. 100% depth means the output is 0, 0% depth means the output is left untouched.




FP, OP, BP, AP Relative phase shift
--------------------------------
midi= 0001 0110   00xx vvvv				c=N.A.			midi note: A#0 
 xx=00 for the frequency modulation
 xx=01 for the base signal OP
 xx=10 for the pulse modulation BP
 xx=11 for the amplitude modulation AP

Shifts the phase of the signal by vvvv times PI/8. It( is added to the actual value.
This should be used with caution as it breaks the assumption of this project to avoid drops. The user may want to set the volume to 0 or change by multiple invocations until to reach the goal.



FO, OO, BO, AO Absolute phase set
-----------------------------
midi= 0001 0110   01xx vvvv				c=N.A.			midi note: A#0 
xx=00 for the frequency modulation
xx=01 for the base signal OP
xx=10 for the pulse modulation BP
xx=11 for the amplitude modulation AP

Sets the phase of the signal to vvvv times PI/8. It overwrite the actual value.
This should be used with caution as it breaks the assumption of this project to avoid drops. The user may want to set the volume to 0. Changing by multiple invocations until to reach the goal is tricky as the time runs between the invocations.



FF frequency modulation
-----------------------
midi= 0001 0111   0vvvvvvv				c=N.A.			midi note: B0

Sets the fre'quency modulation frequency. It works (and is independent) with all the possible sampling rates.

TODO calculation formula.
The maximum frequency is TODO
The minimum frequency is TODO
The step is TODO




AF Amplitude modulation frequency
---------------------------------
midi= 0001 1eee   0mmmmmmm				c=0				midi note: C1 to  G1

Sets the amplitude modulation frequency. It works (and is independent) with all the possible sampling rates.

TODO calculation formula.
The maximum frequency is eee=$7 and mmmmmmm=$7f, 186.035Hz.
The minimum frequency is eee=0 and mmmmmmm=1, 0.01144Hz
The step is not constant. At the highest frequency it is 1.465Hz. At the lowest frequency, it is.



BF Pulse modulation frequency
-----------------------------
midi= 0010 00ee   0mmmmmmm				c=0				midi note: G#1 to  B1

Sets the pulse modulation frequency. It works (and is independent) with all the possible sampling rates.

TODO calculation formula.
The maximum frequency is ee=$3 and mmmmmmm=$7f, 106.306Hz.
The minimum frequency is ee=0 and mmmmmmm=1, 0.01144Hz
The step is not constant. At the highest frequency it is 1.465Hz. At the lowest frequency, it is.


BH, BI pulse modulation high or low hold time
---------------------------------------------
midi= 0010 xxee  0mmmmmmm				c=6
xx=01 for the high hold									midi note: C2 to D#2
xx=10 for the low hold									midi note: E2 to  B2

The pulse modulation has a capability to holds at PI/2 and 3.PI/2 for a certain time

TODO calculation formula.
TODO minimum and maximums.


Reserved
--------
midi= 0010 11ee   0mmmmmmm				c=0



Reserved, not allowed
---------------------
midi= 0--- ----   1--- ---- 


Reserved, not allowed
---------------------
midi= 1--- ----   0--- ---- 


Reserved, not allowed
---------------------
midi= 1--- ----   1--- ----