*About Command Line Utilities*


These simple command-line utilities are aimed at facilitating bridging the gap between musicianship and engineering. The idea is picking the simplest examples for showing how to make "writing" the sound on a computer possible, without staying on the surface. The "toolbox" includes 25+ simple programs with source code showing "what, how and why".

Why command-line utilities?

Here are but a few:


Starters


This is the "Hello, World!" for starting something with sound in C. Five little programs for producing consecutive raw values of a signal. They cannot play, but are here to help understanding how basic things work.

USAGE:
table size
sine num_cycles num_steps
sinef num_cycles num_steps destfile
siner duration frequency sampling_rate
ks duration frequency sampling_rate

Please read the README.txt file enclosed.


PartialsCatenator


Beside raw data there are also analytical documents which help musically representing and controlling the computer as instrument. One such type is the "partial tracking analysis". This UNIX utility written in plain "Hello, World!"-style C serves for appending partials from different analysis file into a single file. They only have to be of the same format, which is the old-style LISP list, as explained in SculptView help file.

USAGE:
ptcat file1 file2 ... ...filen > destfile

If you don't redirect output to a destfile, it will print on the screen.


Partials' Converters


They convert between two prevailing text formats for partial analysis data.
Here are two of them: SDIF text files are way more tricky to deal with, and often involve some rather sophisticated content interpretation. You should use SculptView or SPEAR to do the job.



Partial Tracking File Resampler


This is utility "resamples" existing patrial tracking file using uniform distance among breakpoints and cubic spline interpolation. It involves a bit more advanced math, and the number crunching code is based on the 1988 Columbia University Computer Science Dept. Technical Report CUCS-389-88 by George Wolberg: CUBIC SPLINE INTERPOLATION: A REVIEW.

USAGE:
ptfr file_name <dur>
Upon resampling completion the program will prompt for the name of a new file to save to.


SineWaveGenerator


This is a CoreAudio utility serving for ad-hoc sonification of numbers which represent arbitrary sets of partial frequencies, and for exploring how they relate to tone timbres. Also for easily demonstratning the concept of additive synthesis. Numbers are passed as a string of command line arguments, possibly followed by a - sign and an optional letter for a spectral envelope:

q for quadratic
e for exponential
b for Bessel J0
Default (no option) is linear reciprocal

USAGE:
swg freq1 freq2 ... ...freqn -[q|e|b]

Frequencies are in c.p.s [=Hz]
Pressing "Enter" starts the playback.
Sine wave sounds of chosen frequencies are being played simultaneously and single sample-precision phase-accurately.
Pressing "Enter" also stops the playback.


FloatBufferPlayer


Here is the simplest CoreAudio utility for playing plain binary files of arbitrary floating point data, which may not have been "born" as audio streams, but may have been generated elsewhere, not even as audio files. Therefore they miss their "id"-s, header, packets, encodings, audio descriptors, and all the useful, cool and hype stuff which help the format standardization in entertainment and music industry stay public, but turn even the most humble attempts of non-disciplinary thinking into acts of banging against a wall of elaborate industry standards.

USAGE:
fbp file

File has to be binary, with 32-bit floating-point values.
It will get interpreted and buffered as a stream of momentary amplitude values.
It will be played through the default audio output at the default sample rate. Volume normalizer is part of the utility, so it shouldn't blast your speakers.

Pressing "Enter" starts the playback.
Pressing "Enter" also stops the playback.

The GUI version of this program can also save the values as CAF and AIF audio files.

TextFilePlayer is a version of the same program which can read one dimensional floating point data in text format and converts it to sound; it is available in source code.

USAGE:
tfp file


FloatByteSwapper


This is a Float32 format byte-swapping utility, just in case the floating-point data you want to sonify comes in non-native endianness.

USAGE:
fbs file.fp -[option]
option n = normalize


File has to be binary, with 32-bit floating-point values.


Thread Demo


This is a dummy simulator for a multi-threading procedure similar to those commonly used for number crunching in digital synthesis. It takes desired data buffer length from command-line, checks how many CPUs are available, and generates that many threads, each with its own data buffer. Each thread performs test computation, filling its buffer with numbers until done. On joining threads, data buffers are being summed and the sums printed.

USAGE:
threads -[option]
option n = no print     to disable printing (which takes its CPU toll)

    Enter buffer length:

For getting a view on what the program does enter a small number, such as 10.
For monitoring the CPU load enter a higher number, such as 1000000.


Slightly more elaborate examples:


These programs represent a functional upgrade of the programs above. It is possible to connect the programs in the command line interface, piping output of one program int the input of the other. Source code shows implementation of redirection, event loop and signals.


RtAudio examples


Writing simple, meaningful low-level audio code can some times be a bit of challenge. These are few basic code examples in C++, using the OS-independent, portable RtAudio library and API:


Utilities work with MacOS X 10.6 and 10.7, 10.8 and 10.10 but:

NO WARRANTY


download starters ( -source only).


download PartialsCatenator (MacOS X -binary
/ source).


download Partials' Converters (MacOS X -binary
/ source).


download PartialsTrackingFileResampler (source and MacOS X binary).


download SineWaveGenerator (MacOS X -binary only).


download FloatBufferPlayer (MacOS X -binary only).


download TextFilePlayer (source and MacOS X binary).


download FloatByteSwapper (MacOS X binary
/ source).


download Thread Demo (MacOS X binary
/ source).


download pri (source code).


download com (source code).


download genetic (source code).


download siner1 (source code).


download FloatBufferPlayer1 (source and MacOS X binary).


download TextFilePlayer1 (source and MacOS X binary).


download rtsine ( -source only ).


download rtswg ( -source only ).


download rtfbp ( -source only ).


download rttfp ( -source only ).


download rtpt ( -source only ).


download rtm ( -source only ).


download rtfbp1 ( -source only).


download rttfp1 ( -source only).


and here's the GUI FloatBufferPlayer (MacOS X -binary only).


I'll post all the source code soon, together with a small tutorial in writing such simplest audio utilities.