Getting Started

This walkthrough will take you through a clean install of the code, including optional dependencies and trying your first sonification. There are also example notebooks available on Google Colab which you can run without installing Strauss on your local system.

Installation

Strauss can be installed in different ways, depending on whether you want to develop the code or simply use it as it is. It can be installed using pip install from PyPI directly, or you can install it from a local copy of the GitHub repository, with or without the option for development.

Note

To use text-to-speech functionality see the further steps in the next section

For basic functionality, you can install directly from PyPI with pip:

pip install "strauss[default]"

Alternatively, the Strauss code can be downloaded from GitHub at the repository url

Using git make a copy of the STRAUSS repository via SSH,

git clone git@github.com:james-trayford/strauss.git strauss

or HTTPS if you don’t have SSH keys set up,

git clone https://github.com/james-trayford/strauss.git strauss

if you just want to use the code, STRAUSS may then be installed using pip, as

cd strauss
pip install ".[default]"

If you want to develop the code, you can instead use

pip install -e ".[default]"

throughout the documentation, I will refer to this as the strauss repo or code directory.

Text-to-speech

Fot text-to-speech (TTS) functionality, there are a couple of options: _system_ and _AI_ text to speech.

If you would like to use system AI, you will need to install the (as of writing) cutting-edge pyttsx3 dependency, with

pip install --no-cache-dir --extra-index-url https://test.pypi.org/simple/ pyttsx3==2.99

If you would like to use AI text-to-speech instead, you can instead install strauss requesting the optional AI-TTS dependency:

pip install "strauss[AI-TTS]"

or, for an install from a local repository copy:

pip install -e ".[AI-TTS]"

Note

The AI TTS is currently supported for python version <= 3.12.

Example jupyter notebooks/scripts

There are a number of example applications of Strauss in the example subdirectory of the strauss repo. These are in Python Notebook (.ipynb) format for an interactive, step-by-step experience. They are also provided in Python script format (.py) in the examples directory. The Python scripts can be run from the command line.

In order to run the notebook examples, first ensure that jupyter is installed on your system. These were developed in jupyter-lab, which can also be installed using pip, as:

pip install jupyterlab

Then, running jupyter-lab in the strauss should initiate the jupyter-lab server and open a browser window. Navigate to the examples directory within the jupyter-lab navigation plane, from which a number of examples can be opened and run interactively.

Running some examples

From the jupyter-lab interface, a good starting point is the SonifyingData1D.ipynb Notebook. This demonstrates various methods of representing a single 1D dataset sonically, using a single Object-type source representation. The code and instruction cells provide a step-by-step gude to setting up, rendering and saving a sonification with Strauss.

For a multivariate Event-type sonification, the StarsAppearing.ipynb notebook provides a step-by-step example, and demonstrates realistic stereo imaging for panoramic data. The output from this example was used in the “Audio Universe: Tour of the Solar System” 2021 planetarium show.

For a multivariate, multi-source example using an Object-type source representation, see the PlanetaryOrbits.ipynb Notebook, the output of which was also used in the “Audio Universe: Tour of the Solar System” planetarium show. An example of a bivariate data series sonification, described in this paper, can be found here.

In addition to the above-mentioned examples, there are a number of other Notebooks, each representing the diverse applications and uses of the Strauss code to sonify data in different ways. A more detailed overview of the example Notebooks and scripts can be found in Examples.