# 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