     [file macros.texi not included]

Introduction
************

The Audio toolkit is a set of functions for manipulating MIDI devices and files for GNU Octave

Installing and loading
**********************

The Audio toolkit must be installed and then loaded to be used.

It can be installed in GNU Octave directly from octave-forge, or can be installed in an off-line mode via a downloaded tarball.

The toolkit has a dependency on the RTMIDI library (https://github.com/thestk/rtmidi), so it must be installed in order to successfully install the toolkit.

For Fedora: yum install rtmidi-devel

For Ubuntu: apt install librtmidi-dev

The toolkit must be then be loaded once per each GNU Octave session in order to use its functionality.

Windows install
===============

If running in Windows, the package may already be installed, to check run:

     pkg list audio

Otherwise it can be installed by installing the requirements and then using the online or offline install method.

Online Direct install
=====================

With an internet connection available, the Audio package can be installed from octave-forge using the following command within GNU Octave:

     pkg install -forge audio

The latest released version of the toolkit will be downloaded and installed.

Off-line install
================

With the Audio toolkit package already downloaded, and in the current directory when running GNU Octave, the package can be installed using the following command within GNU Octave:

     pkg install audio-2.0.4.tar.gz

Loading
=======

Regardless of the method of installing the Audio toolkit, in order to use its functions, the toolkit must be loaded using the pkg load command:

     pkg load audio

The toolkit must be loaded on each GNU Octave session.

Basic Usage Overview
********************

The Audio package must be loaded each time a GNU Octave session is started:

     pkg load audio

The Audio toolkit provides 3 main types of MIDI functionality:

Device functions
     These are functions that directly allow opening, sending and receiving MIDI messages.

Controller functions
     Functions that provide a layer on top of the device functions for using MIDI controls.

File functions
     Basic functions that allow read and write of MIDI files.

To read and write to a MIDI device, a MIDI device object must be created, using the name or id of a known MIDI device as provided by the mididevinfo function.

MIDI devices can then be read using the midisend and midireceive functions that use midimsg type to encapsulate the MIDI data.

     % list the midi devices
     devs = mididevinfo

     % open a midi device, specifying the first input and output MIDI device
     dev = mididevice("input", devs.input{1}.ID, "output", devs.output{1}.ID)

     % receive data and echo it through the output port
     while true
       msg = midireceive(dev, 1);
       if !isempty(msg)
         midisend(msg);
       endif
     endwhile

An overview of the package can be displayed by running help audio

Help for each function can be displayed by  help thefunctionname

ie:

     help mididevice

Function Reference
******************

The functions currently available in the Audio toolkit are described below:

     [file functions.texi not included]

     [file gpl.texi not included]