csound-datacore : Data audification/sonification for Csound

Overview

csound-datacore provides a way to read raw data from disk, memory and screen. For the memory and X11 window reading opcodes, only Linux is supported or an OS that supports userspace reading of /proc/.../mem . Thus on platforms that do not support this, only the file reading opcodes are supported.

Requirements

Cmake >= 2.8.12
Csound with development headers >= 6.14.0
Optional: X11 with development libraries

Tested on Linux as of August 2021, Windows as of March 2024.

Installation

Create a build directory at the top of the source tree, execute cmake .., make and optionally make install as root. If the latter is not used/possible then the resulting libcsxtract library can be used with the --opcode-lib flag in Csound. eg:

mkdir build && cd build
cmake ..
make && sudo make install

Cmake should find Csound and X11 using the modules in the cmake/Modules directory and installation should be as simple as above.

Examples

Some examples are provided in the examples directory.

Opcode reference

ipids[] memps

Obtain a list of process IDs readable by the executing user.

ipids[] : array of process IDs

Sname mempsname ipid

Get the process command line or name for a given process ID if available.

ipid : the process ID
Sname : the process command line

isize mempssize ipid [, iskipzero=0]

Get the memory usage of a process, interpreted as a number of audio samples.

isize : the size in samples
ipid : the process ID
iskipzero : if non-zero, skip empty memory locations associated with the process

ifn mem2tab ipid [, iskipzero=0]

Read the memory associated with a process ID into a new function table which can be used by loscil and other such opcodes.

ifn : the function table number created
ipid : the process ID
iskipzero : if non-zero, skip empty memory locations, without this the output may contain a lot of silence depending on the process

aout memson ipid, koffset, kbuffermultiplier [, ibuffersize=441000, iskipzero=0]

Buffered memory reading and direct audio output. The buffer is only refilled when koffset changes.

aout : the sonified memory data
ipid : the process ID
koffset : position to read memory from, normalised to between 0 and 1
kbuffermultiplier : buffer read size multiplier between 0 and 1
ibuffersize : the size in samples of the buffer to read memory data into
iskipzero : if non-zero, skip empty memory locations, without this the output may contain a lot of silence depending on the process

ifn rawreadtable Sfile [, ichannels=1, istart=0, iskip=1]

Read a file from the filesystem to a new f-table, interpreting raw character data as floats according to the orchestra samplerate and bit depth of the build.

ifn : the newly created f-table containing the data read
Sfile : path of the file to read
ichannels : how many channels to interpret the raw data as (1 or 2)
istart : offset the initial read by this number of bytes
iskip : how many bytes to increment each read step by

aL [, aR] rawread Sfile [, iloop=0]

Read a file from the filesystem, interpreting raw character data as floats according to the orchestra samplerate and bit depth of the build.

aL, aR : left and right channels. If only one output is specified then the file is read as mono data, otherwise stereo.
Sfile : path of the file to read
iloop : whether to loop the reading of the file when the end is reached; 1 = loop, 0 = no loop

aout winson iwindowid

Read the contents of a X11 window and interpret pixel data as floats, outputting audio correpsonding to the orchestra samplerate and bit depth. Currently not fully implemented and iwindowid will default to the DefaultRootWindow response from X11.

aout : the resulting audio
iwindowid : the X11 window ID to inspect