audio
About audio
GIT access
Download/Files
News
Check results
Package R docs
|
About audio
| What is audio |
| |
audio is an R package that adds the capability to play and record audio to R. It adds a flexible driver infrastructure such that arbitrary audio drivers can be used. Currently audio in form of PCM samples is supported for recording and playback. Also WAVE (aka .WAV) audio file format is supported.
Release versions of audio can be obtained from CRAN - usually install.packages("audio") in R will do the trick. The current development version can be downloaded from the files section.
|
| What's new? |
|
2011/01/14 - audio 0.1-4 released. It provides fixes for the WMM driver ensuring better compatibility with Windows 7.
2008/09/23 - audio 0.1-0 released. It is the first public release. It has built-in audio drivers for Mac OS X and Windows. Those have been successfully tested. It also includes an experimental PortAudio driver that was originally meant to be the only driver since it purportedly supports all architectures, but it never worked properly so we decided to write our own native drivers. (We are looking for volunteers to provide a better PortAudio driver.)
|
| Installation |
|
Use install.packages("audio") in R to install. There are no special needs on Mac OS X and Windows, but users of other unix systems may want to install PortAudio library.
|
| Documentation |
|
See audio package documentation for details. The most simple use is to play back sound or record audio.
library(audio)
play(sin(1:10000/20)) # play a short sound of a fixed frequency
The sound is played asynchronously, so you're back on the R console while the sound is being played. You can use the audioInstance objects that is returned by play and record to control the audio operation.
a <- play(sin(1:100000/20))
a
# Audio player instance 63b770 of AudioUnits (Mac OS X) driver (macosx).
wait(a) # wait for the playback to finish
rewind(a)
resume(a) # play again
Analogously, it's possible to record audio:
# record 8000 samples at 8000Hz (1 sec), mono (1 channel)
a <- record(8000, 8000, 1)
wait(a) # wait for the recording to finish
x <- a$data # get the result
x[1:10] # show first ten samples
#sample rate: 8000Hz, mono, 16-bits
# [1] 0.018100981 0.017364085 0.016479610 0.013326526 0.010764275 0.011048204
# [7] 0.010541249 0.010892886 0.007960078 0.006703259
close(a); rm(a) # you can close the instance at this point
play(x) # play back the result
# amplify and crop the signal
y <- x * 2
y[y < -1] <- -1
y[y > 1] <- 1
# play the amplified signal
play(y)
The objects returned by record are of class audioSample which is essentially a numeric vector (for mono) or numeric matrix with two rows (for stereo). Valid values are between -1 and 1. Regular numeric operations can be performed on such objects as seen in the previous example. Audio samples have additional attributes rate (sample rate in Hz) and bits (resolution in bits). The latter is optional and used only for storage.
|
| Writing audio drivers |
|
audio provides an infrastrcture for arbitrary audio drivers. Although the built-in drivers should be sufficient for the majority of users, additional audio drivers can be loaded. An audio driver is simply a shared object (.so, .dylib or .dll depending on the paltform) that implements and exports at least one function create_audio_driver which returns a pointer to the audio_driver_t type (a structure) as defined in driver.h. It is currently defined as follows:
typedef struct audio_driver {
unsigned int length; /* length of the driver structure, i.e., sizeof(audio_driver_t) */
const char *name; /* short identifier */
const char *descr; /* description */
const char *copyright; /* copyright (optional) */
struct audio_instance *(*create_player)(SEXP source, float rate, int flags);
struct audio_instance *(*create_recorder)(SEXP target, float rate, int channels, int flags); /* (optional) */
int (*start)(struct audio_instance *); /* start recording/playback */
int (*pause)(struct audio_instance *); /* pause recording/playback */
int (*resume)(struct audio_instance *); /* resume previously paused recording/playback */
int (*rewind)(struct audio_instance *); /* move the pointer in the source/target to the beginning */
int (*wait)(struct audio_instance *, double timeout);/* Note: the instance may be NULL for global wait */
int (*close)(struct audio_instance *); /* close the instance, may release underlying audio objects */
void (*dispose)(struct audio_instance *); /* must free the instance pointer and all internally allocated memory/objects */
} audio_driver_t;
The pivotal entries are create_player and create_recorder which create an audio instance, i.e. an object that can be used to influence the recording or playback. Each audio instance must conform at least to the audio_instance structure, but it can have additional elements (see built-in drivers for examples). The structure is allocated (usually from the heap) in create_player or create_recorder and must be freed by dispose. The recording/playback may not start until start is called. Drivers should be able to recover from reaching the end of input, i.e. rewind followed by resume should result in repeated playback/recording. Playback loop is supported via APFLAG_LOOP and should be implemented even though the R interface doesn't expose that feature (yet).
|
|