dobutokO2-0.35.1.0: README.markdown
Helps to create experimental music from a file (or its part) and a Ukrainian text.
It can also generate a timbre for the notes. Uses SoX inside.
***** Usage *****
-----------------
You can use it as a library or as an executable.
Please, check before executing whether there is no "x.wav", "test\*.wav",
"result\*.wav" and "end.wav" files in the current directory, because they
can be overwritten. The same can be said about "nx\*.wav" files in the directory.
For the executable you enter in the terminal:
dobutokO2 { 0 | 1 | 11 | 2 | 21 | 3 | 31 | 4 | 41 | 5 | 51 | 6 | 7 } {fileName} {Ukrainian text}
OR:
dobutokO2 { 8 | 80 | 9 | 99 | 999 }
OR:
dobutokO2 { 82 | 820 | 92 | 992 | 9992 } {volatile symbols together, e. g. "0"} {quality control, see information below}
OR:
dobutokO2 00 {beginning symbols for the filenames "fade" effect to be applied to} {quality control, see information below}
where filename is:
the full name of the file to be recorded in the current directory or
the full absolute path to the sound .wav file (or other one format
that is supported by your SoX installation) to obtain sound information from.
If the first command line argument equals to one of the numbers below, then
the program behaves as follows:
"1", or "3", or "5" -> then the executable uses the overTones functions,
so for the given parameters the overtones are the same for every call.
"2", or "4", or "6" -> then the program uses uniqOverTones functions.
"3", or "4", or "5", or "6" -> the program uses additional String to define
signs for the harmonics coefficients for overtones.
"11", or "21", or "31", or "41", or "51", or "61" -> the program works as for
the respective inputs with only the first character in the option
(e. g. for "51", this is "5"), but uses not octaves, but n-th elements sets
of consequential notes consisting of 2, 3, 4, 6, or 9 elements (called
'enky'). The usual octave is from such point of view a 12th elements set
of consequential notes. This allows to create more 'condensed' and
'narrower' compositions that being more defined can be at the
same time more precise.
"9" -> the program works with existing "result\*.wav" files and you can replace
some of them by other one(s) or their sequences. This allows to create files,
then edit them using this first command line option (possibly for several
times) and at last create a resulting melody file with "8" or "80" options.
"99" -> the program takes a filename (it is a first command line argument and it is
ignored) and the rest of the command line argument (they are treated as command
line arguments to the SoX 'play' command). Then the program prompts you to
specify the needed indeces for the "result\*.wav" files in the current
directory (e. g. they can be obtained by executing the dobutokO2 with
the first command line argument less than "8", or produced by some
other means). You can specify multiple lists of Int to select the
needed files to be played with effects. Afterwards, the program
just plays these selected files applying the specified SoX
effects to them consequently. For example:
dobutokO2 9 reverb -w
will play the selected (during execution) files with the
SoX "reverb -w" effect. For more information on effects,
please, refer to the SoX documentation.
"999" -> similarly to "99", but instead of playing the files, SoX actually
applies to them these effects and overwrites the files with the obtained ones.
It is convenient way to test the sounding effects with firstly run the
dobutokO2 with "99" first command line argument, and then, if suitable,
with "999" one. Be aware, that after running with the latter one, the
program cannot restore the files that were changed to their previous
state, so be careful while running.
In more details:
"0" -> the program just converts multiline Ukrainian text from stdin
into a String and prints it to stdout. No other arguments are used.
"00" -> the program applies "fade q 0.01 -0.0" SoX effect to every "zs\*.wav"
(or instead of them to every "zs\*.flac") file in the current directory.
The 'zs' here is specified by the second command line argument.
This allows to avoid clipping while just simply concatenating the files into
one with SoX. The mentioned clipping can be desirable in some circumstances
but generally is not necessary or is redundant. For more information,
please, refer to the SoX documentation and to that one for 'fadeAllE'
function in the DobutokO.Sound.IntermediateF module.
"1" -> basic functionality without the possibility to define individual overtones.
"11" -> the same as "1", but works with enky. See general information above.
"2" -> basic functionality with the possibility to define individual overtones.
In such a case, another text gives the other overtones.
"21" -> the same as "2", but works with enky. See general information above.
"3" -> adittionally to basic functionality gives an opportunity
to specify the signs for the harmonics coefficients for overtones
by additional String.
"31" -> the same as "3", but works with enky. See general information above.
"4" -> similarly to "2" gives an opportunity to specify the signs
for the harmonics coefficients for overtones by additional String.
"41" -> the same as "4", but works with enky. See general information above.
"5" -> additionally to that one functionality provided by "3" gives
an opportunity to specify in how many times the amplitude for
the second lower note (if any) is greater, than the amplitude
for the main note and specify the intervals to be used
for every note.
"51" -> the same as "5", but works with enky. See general information above.
"6" -> the same as "5", but you can define also overtones by an additional String.
"61" -> the same as "6", but works with enky. See general information above.
"7" -> the program behaves like for the "5" option, but generates
overtones using additional String and allows maximum control over
the parameters. Besides, all the needed information it obtains from
the singular formatted input, which can be ended with a keyboard keys
combination that means an end of input (e. g. for Unices, that is
probably Ctrl + D). '@' are separators for the input parts
for their respective parts. For more information about the
format of the single input, see:
https://drive.google.com/open?id=10Z_GRZR4TKoL5KXfqPm-t-4humuHN0O4
The file is also provided with the package as text.dat.txt.
The last two or three inputs (an input just here means
a textual input between two '@') can be omitted, the
program will work also but with less control for
the user possible.
"8" -> the program just creates from input "result\*" files the "end.wav" by
concatenating them into one. It is mostly useful after some processment
on the "result\*" files after previous execution with other lesser first
command line arguments to get the test final sound file. It can be then
listened to and probably remade again by editing the "result\*" files
and running the program with this option again. In such a case,
none from the other command line arguments is important for the
program running, so they all can be simply omitted.
"80" -> the same as "8" but with one important difference that the program if
succeeded in creation of the "end.wav" file, then removes all other "result\*"
files from the current directory, so you cannot reverse the successful action
back and try again with just the same files. In such a case, you need to
repeat all the process of creation of "result\*" files. Be aware and use
with care!
"82" -> the same as "8", but you can specify the sound quality parameters for the
resulted file and choose whether it will be in WAV or FLAC format. To specify
this additional processing information, use as a third command line argument
(after the first "82" and the volatile second one) 4 consequent symbols:
3 digits and 1 letter ('f' -- for FLAC one and 'w' for WAV one). The first
two digits are a code for rate and the third one -- a code for bit depth
('1' -- for 16 bit and '2' -- for 24 bit). The list of possible first
two digits and their corresponding frequency rate in Hz:
"11" -> 11025
"16" -> 16000
"17" -> 176400
"19" -> 192000
"32" -> 32000
"44" -> 44100
"48" -> 48000
"80" -> 8000
"96" -> 96000
The default one behaviour is equivalent to "221w".
"820" -> the same as "80", but similarly to "82" it gives you the opportunity to
specify sound quality parameters in just the same way.
"9", "99", or "999" -> see the information above.
"92", "992", or "9992" -> similar to the above line, but with the opportunity to
specify sound quality parameters in just the same way as for "82" option.
These are considered still highly experimental and not well tested,
so use them not for production.
_ -> the program behaves like for the "5" option, but generates
overtones using additional String and allows maximum control over
the parameters.
After the program executing (it takes some time) with the first command line
options except "80" there are files "result\*.wav" in the directory.
These are the resulting melody generated in their order preserved.
The program now lifts the frequencies to the octave or to the enka with the number,
which you can specify during its execution.
You can use the default values (backward compatible with the 0.2.0.0 version
if the first command line option does not consist of two digits and the last one
is not a '0' or '1') by simply pressing 'Enter' while being prompted and
the informational message contains the line about the default value.
Since the 0.21.0.0 version the package extends its library functions with
the possibility to create not only single notes or intervals of sounds playing
simultaneously but also sets of three, four, five, six, seven or more sounds
played simultaneously with their overtones. For more information, please, refer
to the documentation for the DobutokO.Sound.Functional module.
Since the 0.22.1.0 version the library functions are extended also with the
possibility to adjust volume for the overtones using generalized functions '1G'
with adjustment being represented in dB. For more information, please, refer
to the documentation for the DobutokO.Sound.Functional module.
Since the 0.23.0.0 version the library includes functions '2G': generalized
ones in the DobutokO.Sound.Functional, and DobutokO.Sound.IntermediateF, and
DobutokO.Sound.Executable modules. They allow to specify sound quality
of the resulting files using additional parameter.
Since the 0.24.0.0 version the library includes functions to work more explicitly
with f function in the DobutokO.Sound.Functional module. They are based on the
simplest (but still meaningful) multiplicative data fitting.
Since the 0.31.0.0 version the library includes functions to split the sound
into several simultaneously sounding similar ones. For more information, please,
refer to the DobutokO.Sound.Functional module.
** Note:
* Better to execute in the RAM. Need rather a lot of space on the disk for
the resulting file "end.wav" and auxiliary files (MBs) for a short sound
in the second command line arguments.
***** Examples *****
--------------------
Starting from the 0.24.0.0 version, you can refer to examples in the GitHub special
repository (https://github.com/OleksandrZhabenko/dobutokO2-examples/).
You can also see some of the generated sounds on the YouTube list:
https://www.youtube.com/playlist?list=PLuG3zSZWV7yollV9nMPcRtm3udVuYVlFS
***** Support for not Sound File Variativity Sources *****
----------------------------------------------------------
Since 0.28.0.0 version the library supports not only the sound file as a
variativity source but also other types of files. They are used through
a special reencoding using lazy bytestrings. For more information, please,
refer to DobutokO.Sound.Keyboard module.