I/O by Plugin

Audio I/O functions based on plugins such as file I/O supporting many file types are provided. Although the high-level API and the low-level API exist for these functions, you can do many things for file I/O with functions belong to the high-level API.

To work a plugin correctly, the file associated with the plugin exists in one of the following directories:

• ‘pluguins’ directory in the directory containing the executable (on Windows and Mac).
• ‘.sp_plugins’ directory in the home directory (recommended on Linux).
• ‘Contents/Resources/plugins’ directory in the application package known as ‘.app’ file (only on Mac OS X).

The procedure of file I/O by using the high-level API is the following:

1. Initialize spWaveInfo type.
   • Set sampling rate and bits/sample for writing.
2. Open the file by calling spOpenFilePlugin() ( spOpenFilePluginAuto() , spOpenFilePluginArg() or spOpenFilePluginArgAuto() is also available) with "r" for reading or "w" for writing.
   • For writing, specify the plugin name as the 1st argument, or specify NULL to detect the file type from the file name automatically.
   • For reading, specify the plugin name as the 1st argument if you know the file type, or specify NULL to detect the file type automatically by using a plugin's function.
   • Specify SP_PLUGIN_DEVICE_FILE for normal file I/O as the 4th argument or SP_PLUGIN_DEVICE_AUDIO for audio device I/O which is supported only on some environments.
3. Call spReadPlugin() for reading or spWritePlugin() for writing any number of times you want.
   • For a buffer of double type, spReadPluginDouble() or spWritePluginDouble() is also available.
   • For reading, you can move the position pointer by calling spSeekPlugin() .
4. Close the file by calling spCloseFilePlugin() .

As you can see, this procedure is similar to the normal procedure of file I/O in C language.

The following is a code snippet based on the procedure:

long data_length; /* The length of a buffer. */
char *input_file; /* The name of a file. */
 
double *data;
long nread;
spPlugin *i_plugin;
spWaveInfo wave_info;
 
:
 
data = xspMalloc(data_length * sizeof(double));
 
i_plugin = spOpenFilePluginArg(NULL, input_file, "r", SP_PLUGIN_DEVICE_FILE,
                               &wave_info, NULL, 0, NULL, NULL);
 
if (i_plugin != NULL) {
    /* wave_info.samp_rate : Sampling rate. */
    /* wave_info.samp_bit : Bits/sample. */
    /* wave_info.num_channel : Number of channels. */
 
    :
 
    for (i = 0;; i++) {
        if ((nread = spReadPluginDouble(i_plugin, data, data_length)) <= 0) {
            break;
        }
 
        :
 
    }
 
    spCloseFilePlugin(i_plugin);
}