Playrec

Multi-channel Matlab Audio

Getting Started

Before the playrec utility can be used it must first be compiled. This is not ideal but allows the utility to be used on as many platforms and with as many APIs as possible. Provided Matlab is installed, no other software needs to be purchased to achieve this on any platform, and when using Octave then no software needs to be purchased. The following steps try to cover all scenarios, but if you have any problems please use the forum or contact me. After compiling, an overview of how to use Playrec is given in usage with the documentation giving information on all available commands.

1. Download and unzip the latest version of the Playrec source and examples, available from the download section.
2. Download and unzip the latest PortAudio v19 stable release files, available from the download section of the PortAudio website. This can be unzipped anywhere, although unzipping into the 'playrec/lib' directory (created in step 1) should simplify compilation later.
3. If ASIO support is required and can be used on the target platform then the ASIO SDK needs to be downloaded and unzipped, available by agreeing to the license on the Steinberg website. This can be unzipped anywhere, although unzipping into the 'playrec/lib' directory (created in step 1) should simplify compilation later.
4. The steps now differ slightly for each platform: Windows, Mac, Linux.

Windows

The following steps are specific to compiling Playrec on Windows in either Matlab or Octave and continue on from the general steps above:

5. If DirectSound support is required then the DirectX SDK needs to be downloaded and installed, available from the DirectX section of the Microsoft MSDN website. Make a note of where this is installed as this will be required during compilation.
6. If WASAPI support is required then either the latest Microsoft Windows Vista SDK or the SDK supplied with Visual Studio 2008 is required. The Vista SDK is available from the Microsoft website. To reduce the installation size, only 'Windows Vista Headers and Libraries' under the 'Developer Tools' option needs to be selected during the installation process. Make a note of where this is installed as this will be required during compilation. Visual Studio 2008 Express Edition is also available for free from the Microsoft website.
7. Open Matlab or Octave and set the current directory to that of the playrec directory created in step 1.
8. To compile Playrec an external compiler with C++ support is required. For example this could be Microsoft Visual C++, or Microsoft Visual C++ Express 2005 (available for free download), or Microsoft Visual C++ Express 2008 (also available for free download). Alternatively the compiler shipped as part of the free Windows Vista SDK can be used (available from the Microsoft website). This is installed by selecting both 'Visual C++ Compilers' and 'Windows Development Tools' under the 'Developer Tools' option during the installation process. If no compiler is previously installed then the last of these is the smallest to download but also probably the least useful for doing anything else. Other compilers should also work so please let me know if you have managed to do this.
   
   Matlab needs to be configured to use the external compiler, using the command mex -setup. If this does not correctly detect the compiler then it can be configured manually by modifying the configuration file mexopts.bat. The base version of this file is in the preference directory (use prefdir in Matlab to find where this is). Alternatively this base version can be overriden by placing a file with the same name in the current directory. An example of this file that seems to work with a number of Microsoft Visual C++ compilers and versions of Matlab can be downloaded from the download section.
   
   Octave may need to be configured to use the external compiler, depending on how the compiler was initially installed. The script configure_octave_mex may be useful in doing this by supplying as arguments the path to the compiler install directory (eg 'C:\Program Files\Microsoft Visual Studio 8\VC') followed by the path to the Platform SDK (see later).
9. Run compile_playrec and select the required APIs to use. In Octave the default value is given in square brackets. Where possible the required paths will have been automatically completed with paths to the relevant files (eg the PortAudio path to the path where the PortAudio files were unzipped). Where this has not happened the paths need to be completed manually. Depending on the configuration in mexopts.bat there may not be a need to specify a Platform SDK path so initially try without. If it is required then it will need to be something like 'C:\Program Files\Microsoft SDKs\Windows\v6.0' or 'C:\Program Files\Microsoft Visual Studio 8\VC\PlatformSDK'.
10. In Matlab click Compile to start compilation, in Octave compilation will start after the final prompt has been answered. If verbose was selected then the output from the compiler will be displayed in the Command Window. If all is successful then there should be a file called playrec.dll, playrec.mexw32 or playrec.mex in the current directory - this is the MEX file for the utility. As with '.m' files, this must be either in the current directory or a directory in the path list to be able to use it. To check the file has been compiled correctly type playrec('about') to view information on the utility, or run test_playrec (available as part of the playrec scripts download) to try outputting sound. If either works then everything should have built correctly. Please use the forum or contact me if you are having any problems.

Mac

The following steps are specific to compiling Playrec on Macs and continue on from the general steps above. Playrec has not been tested using Octave on Macs, so please let me know if you have tried this.

5. Open Matlab and set the current directory to that of the playrec directory created in step 1.
6. To compile Playrec an external compiler with C++ support is required. Using the command mex -setup select the gcc compiler, installed as part of Apple's developer tools.
7. Run compile_playrec and select the required APIs to use. Where possible the text boxes will have been automatically completed with paths to the relevant files (eg the PortAudio text box to the path where the PortAudio files were unzipped). Where this has not happened the paths need to be completed manually.
8. Choose the required options using the checkboxes and then click compile. If verbose was selected then the output from the compiler will be displayed in the Matlab Command Window. If all is successful then there should be a file called playrec.mexmac or playrec.mexmaci in the current directory - this is the MEX file for the utility. As with '.m' files, this must be either in the current directory or a directory in the path list to be able to use it. To check the file has been compiled correctly type playrec('about') to view information on the utility, or run test_playrec (available as part of the playrec scripts download) to try outputting sound. If either works then everything should have built correctly. Please use the forum or contact me if you are having any problems.

Linux

At the moment Playrec has only had limited testing on Linux, although it has successfully been used in both Matlab and Octave by following similar steps to those for Macs. If you have a suitable system to try this on then please let me know how you get on either via the forum or by contacting me.