1\input texinfo @c -*-texinfo-*- 2@c Copyright (c) 2019-2021, John Donoghue <john.donoghue@ieee.org> 3@c Octave Audio - Audio Toolkit for GNU octave. 4 5@c For manually generating the documentation use 6@c LANGUAGE=en makeinfo --html --no-split audio.texi 7 8@c %*** Start of HEADER 9@setfilename audio.info 10@settitle Octave Audio - Audio Toolkit for GNU octave 11@afourpaper 12@paragraphindent 0 13@finalout 14@set VERSION 2.0.4 15@c @afourwide 16@c %*** End of the HEADER 17 18@include macros.texi 19 20@c %*** Start of TITLEPAGE 21@titlepage 22@title Audio Toolkit @value{VERSION} 23@subtitle Audio and MIDI functionality for @acronym{GNU} Octave. 24@author John Donoghue 25@page 26@vskip 0pt plus 1filll 27Copyright @copyright{} 2019-2021 John Donoghue 28 29Permission is granted to make and distribute verbatim copies of 30this manual provided the copyright notice and this permission notice 31are preserved on all copies. 32 33Permission is granted to copy and distribute modified versions of this 34manual under the conditions for verbatim copying, provided that the entire 35resulting derived work is distributed under the terms of a permission 36notice identical to this one. 37 38Permission is granted to copy and distribute translations of this manual 39into another language, under the same conditions as for modified versions. 40 41@page 42@heading Distribution 43The @acronym{GNU} Octave Audio package is @dfn{free} software. 44Free software is a matter of the users' freedom to run, copy, distribute, 45study, change and improve the software. 46This means that everyone is free to use it and free to redistribute it 47on certain conditions. The @acronym{GNU} Octave Audio package 48is not, however, in the public domain. It is copyrighted and there are 49restrictions on its distribution, but the restrictions are designed to 50ensure that others will have the same freedom to use and redistribute 51Octave that you have. The precise conditions can be found in the 52@acronym{GNU} General Public License that comes with the @acronym{GNU} 53Octave Audio package and that also appears in @ref{Copying}. 54 55To download a copy of the @acronym{GNU} Octave Audio package, please visit 56@url{http://octave.sourceforge.net/audio/}. 57 58@end titlepage 59@c %*** End of TITLEPAGE 60 61@dircategory Math 62@direntry 63* Octave Audio: (audio). Audio Toolkit for Octave 64@end direntry 65 66@c %*** Start of BODY 67@contents 68@ifnottex 69@node Top 70@top Introduction 71The Audio toolkit is a set of functions for manipulating MIDI devices and files for GNU Octave 72@end ifnottex 73 74@menu 75* Installing and loading:: Installing and loading the Audio toolkit 76* Basic Usage Overview:: Basic Usage Overview 77* Function Reference:: Audio toolkit functions 78* Copying:: Copying 79* Index:: Index 80@end menu 81 82@c ------------------------------------------------------------------------- 83@node Installing and loading 84@chapter Installing and loading 85@cindex Installing and loading 86 87The Audio toolkit must be installed and then loaded to be used. 88 89It can be installed in @acronym{GNU} Octave directly from octave-forge, 90or can be installed in an off-line mode via a downloaded tarball. 91 92 93The toolkit has a dependency on the RTMIDI library (@url{https://github.com/thestk/rtmidi}), so it must be installed in order 94to successfully install the toolkit. 95 96For Fedora: @code{yum install rtmidi-devel} 97 98For Ubuntu: @code{apt install librtmidi-dev} 99 100The toolkit must be then be loaded once per each @acronym{GNU} Octave session in order to use its functionality. 101 102@section Windows install 103@cindex Windows install 104If running in Windows, the package may already be installed, to check run: 105 106@example 107pkg list audio 108@end example 109 110Otherwise it can be installed by installing the requirements and then using the online or offline install method. 111 112@section Online Direct install 113@cindex Online install 114With an internet connection available, the Audio package can be installed from 115octave-forge using the following command within @acronym{GNU} Octave: 116 117@example 118pkg install -forge audio 119@end example 120 121The latest released version of the toolkit will be downloaded and installed. 122 123@section Off-line install 124@cindex Off-line install 125With the Audio toolkit package already downloaded, and in the current directory when running 126@acronym{GNU} Octave, the package can be installed using the following command within @acronym{GNU} Octave: 127 128@example 129pkg install audio-@value{VERSION}.tar.gz 130@end example 131 132@section Loading 133@cindex Loading 134Regardless of the method of installing the Audio toolkit, in order to use its functions, 135the toolkit must be loaded using the pkg load command: 136 137@example 138pkg load audio 139@end example 140 141The toolkit must be loaded on each @acronym{GNU} Octave session. 142 143@c ------------------------------------------------------------------------- 144@node Basic Usage Overview 145@chapter Basic Usage Overview 146@cindex Basic Usage Overview 147 148The Audio package must be loaded each time a @acronym{GNU} Octave session is started: 149@example 150pkg load audio 151@end example 152 153The Audio toolkit provides 3 main types of MIDI functionality: 154 155@table @asis 156@item Device functions 157These are functions that directly allow opening, sending and receiving MIDI messages. 158@item Controller functions 159Functions that provide a layer on top of the device functions for using MIDI controls. 160@item File functions 161Basic functions that allow read and write of MIDI files. 162@end table 163 164To read and write to a MIDI device, a MIDI device object must be created, using the name or id 165of a known MIDI device as provided by the mididevinfo function. 166 167MIDI devices can then be read using the midisend and midireceive functions that use midimsg type to encapsulate the MIDI data. 168 169@example 170% list the midi devices 171devs = mididevinfo 172 173% open a midi device, specifying the first input and output MIDI device 174dev = mididevice("input", devs.input@{1@}.ID, "output", devs.output@{1@}.ID) 175 176% receive data and echo it through the output port 177while true 178 msg = midireceive(dev, 1); 179 if !isempty(msg) 180 midisend(msg); 181 endif 182endwhile 183@end example 184 185An overview of the package can be displayed by running @code{help audio} 186 187Help for each function can be displayed by @code{help thefunctionname} 188 189ie: 190@example 191help mididevice 192@end example 193 194@c ------------------------------------------------------------------------- 195@node Function Reference 196@chapter Function Reference 197@cindex Function Reference 198 199The functions currently available in the Audio toolkit are described below: 200 201@include functions.texi 202 203@c ------------------------------------------------------------------------- 204 205@include gpl.texi 206 207@c ------------------------------------------------------------------------- 208@node Index 209@unnumbered Index 210 211@printindex cp 212 213@bye 214