playitbyr Getting Started Support--Help, Bugs, and Documentation GitHub Sonification Resources

sonify {playitbyr}R Documentation

Create sonification objects


Creates a sonify object, the fundamental workhorse of playitbyr; this is a list containing the data.frame to be sonified, the mappings of data to sound parameters, the scaling of parameters, and additional options.


  sonify(data = NULL, mapping = sonaes(),
    scales = sonscaling(), sonlayers = NULL,
    opts = sonopts(), sonfacet = NULL)



a data.frame with the data to be sonified


This specifies the mappings of the data paramters (i.e. columns of data) to sound parameters (such as start time, duration, et cetera). It's a sonaes object, best created by sonaes.

The available sound parameters for mapping depend on what kind of sonification you're doing. This is specified by the shape_ convenience function, and the available sound parameters are documented on those help pages (see e.g. shape_scatter).


What range of the sound parameter should the data be scaled to, and how should the scaling be done? Practically, the best way to deal with tweaking scales is to add on the scale_ convenience function for whichever sound parameter you want to change, like scale_time_continuous.

If specifying manually (not recommended), this is a sonscaling object which gives the scaling function and desired parameter range from the data to each sound.


Layers allow you to specify the type of audio display, and multiple layers allow you to display different aspects of the data to play simultaneously. The best way of doing this is to add on the shape_ function that you want. Current possibilities are:


A scatterplot of notes with many aspects of the sound available for setting and mapping, generated by FM synthesis


Creates a sense of the distribution of a variable, represented by start time, using a snare drum sound


Gives a sense of the distribution of values (represented by pitch) by sampling the dataset (this can be used along with faceting to facilitate comparisons of groups).


Gives a sense of the distribution of values (represented by pitch) by sampling the dataset in increasingly narrow percentiles around the median


A layer that can use an arbitrary csound file as its orchestra (not for beginners!)

If specifying manually (not recommended), this is a single sonlayer object, or a list of sonlayer objects, that gives each layer to be rendered.


Advanced rendering options; this is easiest to use by adding on the function sonopts


playitbyr supports faceting–this splits data by the values in one of its columns and creates separate sonifications for each group, played on after another. See sonfacet for more information on how to do this.

If specifying manually (not recommended), this is a sonfacet object that gives what variables to split by.


The easiest way of building up a sonification is to create a sonify object with this function, specifying the data.frame you want sonified as the data parameter and possibly the mappings. Then, you can add on (with +) additional mappings, layers, scalings and facets later. See Arguments section for more explanation of each of these pieces, and the Examples for how you can add the pieces together to form a complete sonification.


A sonify object, which contains what is needed to render the object. If the object is completely specified, it can by rendered simply by calling the print method for the object (i.e. simply typing the name of the object at the R prompt).


When used in a loop, function, or other non-interactive use, a sonify object needs to be printed in order to actually be turned into sound. So, assign the output of this function to an object and then use print(foo) to hear the sonification.


The syntax of sonify objects is heavily based on that of ggplot objects in the ggplot2 package. See the ggplot2 web site for more information.

See Also



## A bare-bones sonify object, but one that cannot render
x <- sonify()
## Not run: x # Throws an error message

## Creating a sonification incrementally
## and with the "scale_" convenience functions
x <- sonify(iris)
x <- x + sonaes(time=Petal.Length, pitch=Petal.Width)
x <- x + shape_scatter()
x <- x + scale_pitch_continuous(c(6, 8)) + scale_time_continuous(c(0, 10))
## Not run: x # outputs sound