/  Input & Output

IO

FileIO

OscIn

OscOut

OscMsg

Hid

HidMsg

KBHit

SerialIO

MidiIn

MidiOut

MidiMsg

MidiFileIn

Communication tools, including file input/output, Open Sound Control, MIDI, MIDI file reading, serial i/o.

IO

inherits : Event : Object

Base class for other IO classes such as FileIO, StdOut and StdErr. Besides IO.newline(), it’s unlikely you need to use this class directly.

constructors

IO()

Default constructor for IO.

member functions

void close()

Close the currently open IO.

int eof()

Return whether end-of-file has been reached; the opposite of .more().

void flush()

Write any buffered output.

int good()

Returns whether IO is ready for reading.

int mode(int flag)

Set the current IO mode; either IO.MODE_ASYNC or IO.MODE_SYNC.

int mode()

Get the current IO mode; either IO.MODE_ASYNC or IO.MODE_SYNC.

int more()

Return whether there is more to read; the opposite of .eof().

float readFloat(int flags)

Read and return the next floating point value; binary mode: 'flags' denotes the size of float to read (IO.FLOAT32 or IO.FLOAT64).

int readInt(int flags)

Read and return the next integer; binary mode: 'flags' denotes the bit-size of int (IO.INT8, IO.INT16, or IO.INT32).

string readLine()

Read until an end-of-line character.

void write(string val)

Write string 'val'.

void write(int val)

Write integer 'val'.

void write(float val)

Write floating point number 'val'.

static member functions

string newline()

Newline character; same as IO.nl().

string nl()

Newline character; same as IO.newline().

static member variables

int APPEND

Flag denoting append mode.

int ASCII

Flag denoting ASCII IO mode.

int BINARY

Flag denoting binary IO mode.

int FLOAT32

Flag denoting 32-bit floating point type.

int FLOAT64

Flag denoting 64-bit floating point type.

int INT16

Flag denoting 16-bit integer type.

int INT24

Flag denoting 24-bit integer type.

int INT32

Flag denoting 32-bit integer type.

int INT64

Flag denoting 64-bit integer type.

int INT8

Flag denoting 8-bit integer type.

int MODE_ASYNC

Flag denoting asychronous IO.

int MODE_SYNC

Flag denoting synchronous IO.

int READ

Flag denoting read mode.

int READ_WRITE

Flag denoting read/write mode.

int SINT16

Flag denoting 16-bit signed integer type.

int SINT24

Flag denoting 24-bit signed integer type.

int SINT32

Flag denoting 32-bit signed integer type.

int SINT64

Flag denoting 64-bit signed integer type.

int SINT8

Flag denoting 8-bit signed integer type.

int UINT16

Flag denoting 16-bit unsigned integer type.

int UINT24

Flag denoting 24-bit unsigned integer type.

int UINT32

Flag denoting 32-bit unsigned integer type.

int UINT64

Flag denoting 64-bit unsigned integer type.

int UINT8

Flag denoting 8-bit unsigned integer type.

int WRITE

Flag denoting write mode.


FileIO

inherits : IO : Event : Object

File input and output utilities for reading, writing, seeking, etc. See examples for usage.

examples

constructors

FileIO()

Default constructor for FileIO.

member functions

string autoExtension()

Get auto extension for "special:auto" filename generation (applicable to file writing only).

string autoPrefix()

Get auto prefix for "special:auto" filename generation (applicable to file writing only).

void autoPrefixExtension(string prefix, string extension)

Set auto prefix and extension for "special:auto" filename generation (applicable to file writing only).

void close()

Close (and flush) the currently open file.

string[] dirList()

Get an array of file names in an open directory.

int eof()

Return whether end-of-file has been reached; the opposite of .more().

string filename()

Get current filename.

void flush()

Write any buffered output to file.

int good()

Returns whether the file is ready for reading.

int isDir()

Return if the open file is a directory.

int mode(int flag)

Set file IO mode (IO.MODE_SYNC or IO.MODE_ASYNC).

int mode()

Get file IO mode (IO.MODE_SYNC or IO.MODE_ASYNC).

int more()

Return whether there is more to read; the opposite of .eof().

int open(string path)

Open a file by name (and by default in ASCII mode).

int open(string path, int flags)

Open a file by name with flags (bitwise combinations of IO.READ, IO.WRITE, IO.READ_WRITE, IO_APPEND, IO.ASCII, IO.BINARY).

float readFloat()

Read and return the next floating point value.

float readFloat(int flags)

Read and return the next floating point value; if binary mode: 'flags' denotes the size of float to read (IO.FLOAT32 or IO.FLOAT64).

int readInt(int flags)

Read and return an integer; binary mode: 'flags' specifies int size to read (IO.INT8, IO.INT16, IO.INT32 default to unsigned values; for signed integers use IO.SINT8, IO.SINT16, IO.SINT32).

string readLine()

Read and return the next line from file.

void seek(int pos)

Seek to a specified byte offset in file.

int size()

Return the size of the file in bytes, or -1 if no file is opened or if a directory is opened.

int tell()

Return the byte read offset of the file, or -1 if no file is opened.

void write(string val)

Write a string to file.

void write(int val)

Write an integer to file.

void write(int val, int flags)

Write integer value to file; binary mode: int size specified by 'flags' (IO.INT8, IO.INT16, IO.INT32).

void write(float val)

Write floating point value to file.

void write(float val, int flags)

Write floating point value to file; binary mode: flags indicate float size (IO.FLOAT32 or IO.FLOAT64).

static member functions

string expandPath(string path)

Expand platform-specific filepath to an absolute path, which is returned. On macOS and Linux expandPath() will attempt to resolve `~` or `~[username]`; on Windows expandPath() will attempt to resolve %USERNAME%. (Known issue: (macOS) expandPath currently introduced an audio click; it recommended to call expandPath() at the beginning; e.g., expanding path ahead of time could avoid a click instead of calling Machine.add() on a filepath with `~`.)


OscIn

inherits : Event : Object

Class for receiving Open Sound Control (OSC) messages. See examples for usage.

examples

constructors

OscIn()

Default constructor for OscIn.

member functions

void addAddress(string address)

Add an OSC address to receive messages from.

void listenAll()

Set OscIn to receive messages of any OSC address.

int port()

Get which port to listen on.

int port(int p)

Set which port to listen on; this will begin priming the background OSC listener on the named port. If port is set to 0, a usable port would be automatically assigned; the auto-assigned port number can be retrieved by calling .port() but may initially take some time to acquire (e.g., hundreds of milliseconds); if there is more than one OscIn client on port 0, they all will eventually share the same auto-assigned port.

int recv(OscMsg msg)

Receive the next queued incoming OSC message, returning its contents in `msg`.

void removeAddress(string address)

Stop listening on a particular OSC address.

void removeAllAddresses()

Stop listening on all OSC addresses.


OscOut

inherits : Object

Class for sending Open Sound Control (OSC) messages. See examples for usage.

examples

constructors

OscOut()

Default constructor for OscOut.

member functions

OscOut add(int i)

Add an integer value to an OSC message.

OscOut add(float f)

Add a floating-point value to an OSC message.

OscOut add(string s)

Add an string value to an OSC message.

OscOut dest(string hostname, int port)

Set the destination hostname and port for sending OSC message.

OscOut send()

Send the current OSC message.

OscOut start(string address)

Start an OSC message with a particular address.

OscOut start(string address, string host, int port)

Start an OSC message with a particular address, aimed at a destination host and port.


OscMsg

inherits : Object

Helper class for receiving the contents of an OSC message.

examples

constructors

OscMsg()

Default constructor for OscMsg.

member functions

float getFloat(int i)

Get argument (at index 'i') as a float.

int getInt(int i)

Get argument (at index 'i') as an integer.

string getString(int i)

Get argument (at index 'i') as a string.

int numArgs()

Get the number of arguments contained in this OscMsg.

member variables

string address

The OSC address string (e.g., "/foo/param").

OscArg[] args

Array of OscArgs contained in this message.

string typetag

The OSC type tag string (e.g., "iif" for int, int, float).


Hid

inherits : Event : Object

Class for interacting with human-interface devices (HIDs) such as keyboards, mice, gamepads, joysticks, etc.

examples

constructors

Hid()

Default constructor for Hid.

member functions

int can_wait()

(internal) used by virtual machine for synthronization.

int good()

Get whether a device has been successfully opened on this HID instance.

string name()

Get the name of the currently open device; return empty string ("") if no device is open on this HID instance.

int num()

Get the number of the currently open device; returns -1 if no device is open on this HID instance.

int open(int type, int num)

Open a HID device by device number ('num') and type ('type'). See static member variables for possible types.

int open(string name)

Open a HID device by name.

int openJoystick(int num)

Open a joystick/gamepad by device number.

int openJoystick(int num, int suppressErrMsg)

Open a joystick/gamepad by device number, with option (true/false) to suppress error messages.

int openKeyboard(int num)

Open a keyboard by device number.

int openKeyboard(int num, int suppressErrMsg)

Open a keyboard by device number, with option (true/false) to suppress error messages.

int openMouse(int num)

Open a mouse/trackpad by device number.

int openMouse(int num, int suppressErrMsg)

Open a mouse/trackpad by device number, with option (true/false) to suppress error messages.

int openTiltSensor()

Open a tilt-sensor by device number.

void printerr(int toPrintOrNot)

Set whether to print errors (default is YES).

int read(int type, int which, HidMsg msg)

Read the next HidMsg from device of type 'type' with device id 'which'.

int recv(HidMsg msg)

Receive the next available HidMsg.

int send(HidMsg msg)

Send a HidMsg to device; return whether the operation was successful.

static member functions

dur globalTiltPollRate(dur d)

Set tilt-sensor poll rate.

dur globalTiltPollRate()

Get tilt-sensor poll rate.

int[] readTiltSensor()

Read tilt-sensor and return as an int array.

int startCursorTrack()

Start cursor tracking; return whether the request was successful.

int stopCursorTrack()

Stop cursor tracking; return whether the request was successful.

static member variables

int ACCELEROMETER

No description available

int AXIS_MOTION

No description available

int BUTTON_DOWN

No description available

int BUTTON_UP

No description available

int DEVICE_CONNECTED

No description available

int DEVICE_DISCONNECTED

No description available

int FORCE_FEEDBACK

No description available

int JOYSTICK

No description available

int JOYSTICK_BALL

No description available

int JOYSTICK_HAT

No description available

int KEYBOARD

No description available

int LED

No description available

int MOUSE

No description available

int MOUSE_MOTION

No description available

int MOUSE_WHEEL

No description available

int TABLET

No description available

int TILT_SENSOR

No description available

int WII_REMOTE

No description available


HidMsg

inherits : Object

Helper class for receiving HID information; e.g., which key was pressed, joystick position, etc.

examples

constructors

HidMsg()

Default constructor for HidMsg.

member functions

int isAxisMotion()

Return whether this message is an axis-motion event.

int isButtonDown()

Return whether this message is a button-down event.

int isButtonUp()

Return whether this message is a button-up event.

int isHatMotion()

Return whether this message is a hat-motion event.

int isMouseMotion()

Return whether this message is a mouse-motion event.

int isWheelMotion()

Return whether this message is a wheel-motion event.

int is_axis_motion()

(Deprecated; use .isAxisMotion() instead).

int is_button_down()

(Deprecated; use .isButtonDown() instead).

int is_button_up()

(Deprecated; use .isButtonUp() instead).

int is_hat_motion()

(Deprecated; use .isHatMotion() instead).

int is_mouse_motion()

(Deprecated; use .isMouseMotion() instead).

member variables

int ascii

ASCII value associated with a keyboard key.

int axis_position

Joystick axis position (int).

float axisPosition

Joystick axis position (float).

int cursorX

Position of X-axis of pointing device.

int cursorY

Position of Y-axis of pointing device.

int deltaX

Change in X-axis of pointing device.

int deltaY

Change in Y-axis of pointing device.

int deviceNum

Device number that produced the message.

int deviceType

Device type that produced the message.

float fdata

Float data generate from the Hid device.

int hatPosition

Joystick hat position.

int idata

Integer data generated from the Hid device.

int key

Code (USB) for a keyboard key.

float scaled_axis_position

Position of the primary pointing device, scaled between 0.0 and 1.0.

float scaledCursorX

Position of X-axis of pointing device, scaled between 0.0 and 1.0.

float scaledCursorY

Position of Y-axis of pointing device, scaled between 0.0 and 1.0.

float touchSize

Multi-touch size.

float touchX

Position of X-axis of pointing device, scaled between 0.0 and 1.0.

float touchY

Position of X-axis of pointing device, scaled between 0.0 and 1.0.

int type

A number representing the message type.

time when

Time when the HidMsg occurred, relative to the start of the file.

int which

Code (platform dependent) associated with a keyboard key.

int x

Change in X-axis of pointing device (same as deltaX).

int y

Change in Y-axis of pointing device (same as deltaY).

int z

Change in Z-axis of pointing device.


KBHit

inherits : Event : Object

KBHit (terminal only) is a simple mechanism for capturing keyboard input; for a more flexible mechanism, see HID. (On Linux, KBHit does not require granting device permissions; it works out of the box.)

examples

constructors

KBHit()

Default constructor for KBHit.

member functions

int can_wait()

(internal) used by virtual machine for synthronization.

int getchar()

Get the ASCII value of the last keyboard press.

Event hit()

Return itself as an Event to wait on; this is largely unnecessary as the KBHit instance can be directly => to 'now'.

int more()

Return whether there are unprocessed KBHit events (e.g., if a user presses multiple keys at once).

void off()

Disable the KBHit.

void on()

Enable the KBHit.

void state()

Get whether the KBHit is currently enabled.


SerialIO

inherits : IO : Event : Object

Serial input/output. popularly used to communicate with systems like Arduino.

examples

constructors

SerialIO()

Default constructor for SerialIO.

member functions

int baudRate(int r)

Set baud rate.

int baudRate()

Get current baud rate.

void close()

No description available

int dataAvailable()

No description available

void flush()

Flush the IO buffer.

int getByte()

Get next requested byte.

int[] getBytes()

Get next requested number of bytes.

int[] getInts()

Get next requested number of integers.

string getLine()

Get next requested line.

SerialIO onByte()

Wait for one byte (binary mode only).

SerialIO onBytes(int num)

Wait for requested number of bytes (binary mode only).

SerialIO onFloats(int num)

Wait for requested number of floats (ASCII or binary mode).

SerialIO onInts(int num)

Wait for requested number of ints (ASCII or binary mode).

SerialIO onLine()

Wait for one line (ASCII mode only).

int open(int i, int baud, int mode)

Open serial device i with specified baud rate and mode (binary or ASCII).

string readLine()

No description available

void writeByte(int b)

Write a single byte.

void writeBytes(int[] b)

Write array of bytes.

static member functions

string[] list()

Get list of available serial devices.

static member variables

int B115200

115200 baud.

int B14400

14400 baud.

int B19200

19200 baud.

int B230400

230400 baud.

int B2400

2400 baud.

int B28800

28800 baud.

int B38400

38400 baud.

int B4800

4800 baud.

int B57600

57600 baud.

int B7200

7200 baud.

int B76800

76800 baud.

int B9600

9600 baud.


MidiIn

inherits : Event : Object

Class that can be ChucKed to now as an event. When receiving a message, an event is signaled and Midi information can be read.

examples

constructors

MidiIn()

Default constructor for MidiIn.

member functions

int can_wait()

(internal) used by virtual machine for synthronization.

int good()

Return true (1) if a device has been opened for this instance and there was no error connecting to it. Return false (0) if a device has not been opened or there was an error opening a device.

string name()

Return the Midi device's name as string.

int num()

Return the device number of the device (i.e. the number passed to MidiIn/MidiOut.open).

int open(int port)

Open Midi device using a port number.

int open(string name)

Open Midi device using the device's name.

void printerr(int print_or_not)

Set error printing (1 for on, 0 for off). On by default.

int recv(MidiMsg msg)

Return into the MidiMsg argument the next message in the queue from the device. Return 0 if the queue is empty or 1 if a message was in the queue and returned in the argument.


MidiOut

inherits : Object

Class for sending out MIDI messages. Note that channel numbers are 0-based.

examples

constructors

MidiOut()

Default constructor for MidiOut.

member functions

int channelPressure(int channel, int pressure)

Send out a channelPressure message.

int controlChange(int channel, int controller, int value)

Send out a controlChange message.

int good()

Return true (1) if a device has been opened for this instance and there was no error connecting to it. Return false (0) if a device has not been opened or there was an error opening a device.

string name()

Return the Midi device's name as string.

int noteOff(int channel, int note, int velocity)

Send out a noteOff message.

int noteOn(int channel, int note, int velocity)

Send out a noteOn message.

int num()

Return the device number of the device (i.e. the number passed to MidiIn/MidiOut.open).

int open(int port)

Open Midi device using a port number.

int open(string name)

Open Midi device using the device's name.

int pitchBend(int channel, int value)

Send out a pitchBend message.

int pitchBend(int channel, int lsb, int msb)

Send out a pitchBend message with fine and coarse values.

int polyPressure(int channel, int note, int pressure)

Send out a polyPressure message.

void printerr(int print_or_not)

Set error printing (1 for on, 0 for off). On by default.

int programChange(int channel, int program)

Send out a programChange message.

int send(int status, int data1, int data2)

Send out a MIDI message consisting of one status byte and two data bytes.

int send(MidiMsg msg)

Send out a MIDI message using a MidiMsg.


MidiMsg

inherits : Object

Creates a message for sending and receiving Midi information.

examples

constructors

MidiMsg()

Default constructor for MidiMsg.

member variables

int data1

First byte of a Midi message, usually a status byte or command byte.

int data2

Second byte of a Midi message, usually a note value.

int data3

Third byte of a Midi message, usually a velocity value.

dur when

Duration since the last MidiMsg (only valid for MidiFileIn).


MidiFileIn

inherits : Object

Class for reading data from a MIDI file.

examples

constructors

MidiFileIn()

Default constructor for MidiFileIn.

member functions

float beatsPerMinute()

Get the beats per minute (BPM) value from the MIDI file header.

float bpm()

Same as beatsPerMinute().

void close()

Close the MIDI file.

int numTracks()

Get the number of tracks in the open MIDI file.

int open(string path)

Open a MIDI file.

int read(MidiMsg msg)

Read next MIDI Event (on default track 0); return contents in 'msg'.

int read(MidiMsg msg, int track)

Read next MIDI Event on track 'track'; return contents in 'msg'.

void rewind()

Rewind MIDI reader to beginning of default track 0.

void rewind(int track)

Rewind MIDI reader to beginning of track 'track'.

int ticksPerQuarter()

Get the ticks per quarter (TPQ) value from the MIDI file header.

int tpq()

Same as ticksPerQuarter().