Skip to content

Commit 799917e

Browse files
ElecGeekElecGeek
committed
Documentation improvement
The README has been completely rewritten. The commands codes are no longer in the params_codes.hxx (which is now an regular include file). They are in a specific README file.
1 parent ef31be9 commit 799917e

3 files changed

Lines changed: 173 additions & 45 deletions

File tree

‎README‎

Lines changed: 45 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,52 @@
1-
This project generates audio signals using some primitives.
2-
* An amplitude primitive handles a value and a slew-rate. Each time the actual amplitude is not equal to the requested amplitude, the module reaches it according to the slew-rate.
3-
* An amplitude modulation primitive is applied to the amplitude above. It is a sinusoidal based wave form. The depth is a parameter. When the sine value is +1, the output is the amplitude left untouched. When the sine is -1, the output is between 0 if the depth is 100% and the amplitude left untouched if the depth is 0%.
4-
* A second amplitude modulation is applied to the output of above. In this one, the modulation can be hold for a certain time on the top of the period and for another time on the bottom.
5-
* An output module that generates a sinusoidal or a symmetrical pulse output. The amplitude is the output of the modulation module described above. In case of the sine, only one parameter defines the frequency. In case of the pulses, a parameter defines the frequency as another one defines the pulse width.
6-
* Future modules are going to modulate the frequency
1+
This project generates independent multi channels audio signals from commands.
72

3+
There are 2 projects: a software version and an hardware version.
4+
5+
The main goal of this project is to change the parameters on the fly. That means, without any drops. If a frequency and an amplitude change, the sinusoid is faster/slower and higher/lower from the current point.
6+
All the parameters can be changed by commands, unless otherwise. In such case, the compile time or start-up is specified.
7+
8+
9+
10+
Software version
11+
----------------
12+
The first version was written using the C++03 and GCC 4.6.2. The years later, the minimal versions was raised to GCC 5.5, GCC 7.5 and GCC 8.5. The minimum is now C++17.
13+
14+
New modules or improvements are written using the last version.
15+
The legacy part remains as it, as long as there is no issues nor requests.
16+
17+
The "physical" output can be chosen, at start-up, among Jackaudio, a wave file or void.
18+
The general output volume is, today, always set to 100% but the software can set update to control this value.
19+
For each channel:
20+
* This audio is a waveform chosen, at start-up, among sine, triangle, pulse and continuous (with restrictions).
21+
* The default one is chosen at compile time.
22+
* This waveform can be frequency modulated TODO.
23+
* This waveform can amplitude modulated by two independent engines.
24+
* Some modifiers applies to some engines (see README.commands).
25+
* The volume can be changed. A commands defined slew rate applies to change quickly or smoothly.
26+
* As many as needed input commands channels can be set. There are many types (see README.parameters).
27+
* As many as needed output commands channels can be set. The purposes are: i) display in a human readable ii) store for replays iii) use the software as a remote control, especially if there is the network in between iv) test that chained inputs and output give the same result.
828

929
There is no extended documentation files.
10-
* Some data is in the code. A run of the Doxygen software, separately in the 2 folders generates the documentation in the format one wants.
11-
* Some data (mostly schematics) is in the Documentation folder. A run of the Graphviz software (dot) exports in the format one wants (about 30 are available). The work-flow exports into PNG, JPEG or PDF format. The files are in the artifact.
12-
* Some data is in the specialized README files.
30+
* Some data is in the code. A run of the Doxygen software, separately in the cpp and vhdl version folders generates the documentation in the format one wants.
31+
* Some data (mostly schematics) is in the Documentation folder. A run of the Graphviz software (dot) exports in the format one wants. The work-flow exports into PNG, JPEG or PDF format. The files are in the artifact.
32+
* Some information is in the specialized README files.
33+
34+
The commits into GitHub are up and running, but may contain bugs.
35+
36+
1337

38+
Hardware version
39+
----------------
40+
This version is on hold for some time.
41+
It is similar to the software version but:
42+
* The physical output and the audio waveform are defined at compile time.
43+
* The general output volume is a real input.
44+
* There is no output commands channels.
45+
* There is only one input commands channel of one type.
1446

47+
This version is on hold.
1548

16-
It is written in the DevOps style. Some shortcuts or quick and dirty parts are written and later cleaned up, removed or left as it. The commits into GitHub are up and running tags.
1749

50+
Others related projects
51+
-----------------------
52+
There are two not pinned fun projects in the same GitHub user that implements only the pulse audio waveform. One is a pure electronics (logic and analogue) version, the other one is the VHDL only of a full digital version.

‎README.commands‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
This is the documentation of the commands.
2+
3+
4+
THIS IS AN EARLY VERSION
5+
6+
7+
It describes all the (available) formats for all the commands. The transport modes are defined in the README.parameters file.
8+
9+
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.
10+
11+
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.
12+
13+
The midi (code) word is an alias of midi mapped (code)
14+
15+
Some nicknames are used:
16+
* e: exponent
17+
* m: mantissa
18+
* c: constant added to the exponent
19+
* v: integer value
20+
* x: other data
21+
* -: don't care
22+
23+
* 0000 0eee 0mmmmmmm c=1 C00 to G00 OF Base frequency max = 2976.56Hz step = 23.44Hz min = 0.183Hz, 5.46s step = 0.366Hz\n
24+
* 0000 1eee 0mmmmmmm c=0 G#00 to D#0 OS Main amplitude slew-rate max = 2.666mS min = 174s min step < 40uS max step = 87s\n
25+
* 0001 000e 0mmmmmmm c=1 E0 to F0 OA Main amplitude max = 254 min step = 1 max step = 2\n
26+
27+
28+
Abort
29+
-----
30+
midi= 0001 0010 0vvvvvvv c=N.A. midi note: A#0
31+
32+
This input commands channel is discarded. If all of them are discarded or have reach an end of stream, the program quits.
33+
The main purpose is to run a partial scenario for test.
34+
The value is the time before leave (not yet implemented).
35+
36+
37+
Reserved
38+
--------
39+
midi= 0001 0011 0------- c=N.A. midi note: A#0
40+
41+
42+
AA, BA Modulation depth
43+
---------------------------------
44+
midi= 0001 010x 0vvvvvvv c=N.A.
45+
x=0 for the amplitude modulation midi note: G#0
46+
x=1 for the pulse modulation midi note: A0
47+
48+
Set the depth from 0% if the value vvvvvvv is 0 to 100% if the value vvvvvvv is 127.
49+
The step is about 0.79%.
50+
If the modulation depth is 0, the output of the modulator is always its input signal untouched.
51+
If the modulation depth is 100%, the output of the modulator is between 0 and the its input signal according with the modulation.
52+
53+
54+
BM, AM Modulation mode
55+
----------------------
56+
midi= 0001 0110 0000 0xvv c=N.A. midi note: A#0
57+
xx=0 for the pulse modulation BM
58+
xx=1 for the amplitude modulation AM
59+
vv = 00 using a sine from -1 to +1 translated into 0 to +1 \n
60+
vv = 01 using the absolute value of a sine from 0 to +1, be careful freq is double!\n
61+
vv = 10 using opposite of the absolute value translated into 0 to +1, be careful freq is double!\n
62+
vv = 11 is reserved
63+
64+
Set how the sine of the modulation is used. This computation gives always a value between 0 and +1.
65+
If it is +1, the modulation left its input untouched.
66+
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.
67+
68+
69+
Reserved
70+
--------
71+
midi= 0001 0110 0000 1--- c=N.A. midi note: A#0
72+
73+
74+
OP, BP, AP Relative phase shift
75+
--------------------------------
76+
midi= 0001 0110 00xx vvvv c=N.A. midi note: A#0
77+
xx=01 for the base signal OP
78+
xx=10 for the pulse modulation BP
79+
xx=11 for the amplitude modulation AP
80+
81+
Shifts the phase of the signal by vvvv times PI/8. It( is added to the actual value.
82+
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.
83+
84+
85+
Reserved
86+
--------
87+
midi= 0001 0110 0100 vvvv c=N.A. midi note: A#0
88+
89+
90+
OO, BO, AO Absolute phase set
91+
-----------------------------
92+
midi= 0001 0110 01xx vvvv c=N.A. midi note: A#0
93+
xx=01 for the base signal OP
94+
xx=10 for the pulse modulation BP
95+
xx=11 for the amplitude modulation AP
96+
97+
Sets the phase of the signal to vvvv times PI/8. It overwrite the actual value.
98+
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.
99+
100+
101+
102+
NN No operation
103+
---------------
104+
midi= 0001 0111 0--- ---- c=N.A. midi note: B0
105+
106+
This does not do anything. The value is not treated in the software but it is passed to the commands outputs.
107+
The purposes are:
108+
* Reserve some room for a manual edition of a binary file.
109+
* Make a kind of TTL or step display, especially with the -N 0 option of the output command
110+
111+
112+
* 0001 1eee 0mmmmmmm c=0 C1 to G1 AF Amplitude modulation freq max = 186.035Hz step = 1.465Hz min = 0.01144Hz, 87.38s step 43.69s\n
113+
* 0010 00ee 0mmmmmmm c=0 G#1 to B1 BF Pulse frequency max = 106.306Hz step = 1.465Hz min = 0.01144Hz, 87.38s step 43.69s\n
114+
* 0010 01ee 0mmmmmmm c=6 C2 to D#2 BH Pulse high hold time\n
115+
* 0010 10ee 0mmmmmmm c=6 E2 to B2 BI Pulse low hold time\n
116+
* 0010 11ee 0mmmmmmm Reserved\n
117+
* \n
118+
119+
120+
Reserved, not allowed
121+
---------------------
122+
midi= 0--- ---- 1--- ----
123+
124+
125+
Reserved, not allowed
126+
---------------------
127+
midi= 1--- ---- 0--- ----
128+

‎cpp_version/params_codes.hxx‎

Lines changed: 0 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,6 @@
11
#ifndef __PARAMS_CODES__
22
#define __PARAMS_CODES__
33

4-
/* Designed for the documentation tools */
5-
/** \brief Base of the midi input and output method
6-
*
7-
* \n
8-
* Midi note binary, midi velocity, midi note music (range), mnemonic, description, limits\n
9-
* Values format: e = exponent, m = mantissa, c = constant to exponent\n
10-
* 0000 0eee 0mmmmmmm c=1 C00 to G00 OF Base frequency max = 2976.56Hz step = 23.44Hz min = 0.183Hz, 5.46s step = 0.366Hz\n
11-
* 0000 1eee 0mmmmmmm c=0 G#00 to D#0 OS Main amplitude slew-rate max = 2.666mS min = 174s min step < 40uS max step = 87s\n
12-
* 0001 000e 0mmmmmmm c=1 E0 to F0 OA Main amplitude max = 254 min step = 1 max step = 2\n
13-
* 0001 0010 0xxxxxxx na. F#0 NQ Abort. Mnemonic file is over. Channel is discarded. Value is the time before leave (not yet implemented)\n
14-
* 0001 0011 na. G0 / Reserved\n
15-
* 0001 0100 0mmmmmmm c=1 G#0 AA Amplitude modulation depth max = 127 step = 2\n
16-
* 0001 0101 0mmmmmmm c=1 A0 BA Pulse depth max = 127 step = 2\n
17-
* Modulation mode:\n
18-
* mm = 00 using a sine from -1 to +1 translated into 0 to +1 \n
19-
* mm = 01 using the absolute value of a sine from 0 to +1, be careful freq is double!\n
20-
* mm = 10 using opposite of the absolute value translated into 0 to +1, be careful freq is double!\n
21-
* 0001 0110 000000mm c=0 A#0 BM ... for the pulse signal\n
22-
* 0001 0110 000001mm c=0 A#0 AM ... for the amplitude modulation\n
23-
* 0001 0110 0001mmmm c=0 A#0 OP Phase shift of the base signal, use with caution\n
24-
* 0001 0110 0010mmmm c=0 A#0 BP Phase shift of the pulse signal, use with caution\n
25-
* 0001 0110 0011mmmm c=0 A#0 AP Phase shift of the amplitude modulation signal, use with caution\n
26-
* 0001 0110 0101mmmm c=0 A#0 OO Phase (re)set (overwrite) of the base signal, use with caution\n
27-
* 0001 0110 0110mmmm c=0 A#0 BO Phase (re)set (overwrite) overwrite of the pulse signal, use with caution\n
28-
* 0001 0110 0111mmmm c=0 A#0 AO Phase (re)set (overwrite) overwrite of the amplitude modulation signal, use with caution\n
29-
* 0001 0111 0xxxxxxx B0 NN NOP\n
30-
* 0001 1eee 0mmmmmmm c=0 C1 to G1 AF Amplitude modulation freq max = 186.035Hz step = 1.465Hz min = 0.01144Hz, 87.38s step 43.69s\n
31-
* 0010 00ee 0mmmmmmm c=0 G#1 to B1 BF Pulse frequency max = 106.306Hz step = 1.465Hz min = 0.01144Hz, 87.38s step 43.69s\n
32-
* 0010 01ee 0mmmmmmm c=6 C2 to D#2 BH Pulse high hold time\n
33-
* 0010 10ee 0mmmmmmm c=6 E2 to B2 BI Pulse low hold time\n
34-
* 0010 11ee 0mmmmmmm Reserved\n
35-
* \n
36-
* 1xxx xxxx xxxxxxxx Can not be used as it is not a midi note code
37-
*/
38-
394

405
struct midi_event {
416
unsigned char code;

0 commit comments

Comments
 (0)