Building and installing Nsound

Binary installers

There are currently no binary installers.

Building The C++ Library From Source

A general overview of building Nsound from source is given here, with detailed instructions for specific platforms given separately.


Building Nsound requires the following software installed:

  1. Python 2.7.x

    On Debian and derivative (Ubuntu): python

    On Windows: the official 64-bit Python installer at is enough

    On Mac OSX: I highly recommend the MacPorts package manager to install the latest versions of Python 2.7.X, Numpy and Matplotlib .

  2. Scons

    Nsound uses this execellent build system, .

    On Windows: a 64-bit self-installer is not provied (as of 2013-12-24), you’ll have to download the source .Zip archive and do:

    python bdist_wininst

    and install it by running the dist/scons*.exe file.

  3. A C++ compiler

    To build Nsound you will need a C++ compiler.

    On Windows: you’ll need to install Visual Studio 2013+.

    On Mac OS X: you’ll need to install XCode command line tools.

Optional Prerequisites

  1. Matplotlib (Numpy, dateutil, pyparsing, six)

    For creating pretty plots, Matplotlib is used.

    Numpy and python-dateutil are a prerequisites for Matplotlib.



    On Windows: use the prebuilt 64-bit binaries from here:

    Unofficial Windows Binaries for Python Extension Packages

  2. PortAudio

    To enable audio playback through the soundcard, Nsound can use portaudio.


    On Windows, portaudio have already been statically built and provided.

  3. SWIG

    To build the Python module, SWIG generates the Python wrapper code.

    On Windows: you’ll download and unzip to C:\.

Testing that all Matplotlib dependancies are met

Usually this is only a problem for the Windows platform, since Linux and MacPorts download and install prerequisite automatically.

  1. Start a Python Shell and import matplotlib:

    >>> import matplotlib
    >>> # Try to import pylab
    >>> from matplotlib import pylab
    >>> # Try to plot something
    >>> pylab.plot([1,2,3,4], "bo-")
As you run into missing packages, donload and install them. Most of them are:
  • Numpy
  • dateutil
  • six
  • pyparsing

Compiling The C++ Library

  1. Uncompress the Nsound archive:

    $ tar xfz Nsound-0.9.4.tar.gz
  1. Execute the SCons tool:

    cd Nsound-0.9.4

SCons will query your computer for specific information about the build environment and generate a few files. It will then proceed to build the Nsound library and examples.

To get help with scons, do:

$ scons --help
scons: Reading SConscript files ...
Building with 4 threads
scons: done reading SConscript files.
usage: scons [OPTION] [TARGET] ...

SCons Options:
  -b, -d, -e, -m, -S, -t, -w, --environment-overrides, --no-keep-going,
  --no-print-directory, --print-directory, --stop, --touch
                              Ignored for compatibility.
  -c, --clean, --remove       Remove specified targets and dependencies.
  -C DIR, --directory=DIR     Change to DIR before doing anything.
  --cache-debug=FILE          Print CacheDir debug info to FILE.
  --cache-disable, --no-cache
                              Do not retrieve built targets from CacheDir.
  --cache-force, --cache-populate
                              Copy already-built targets into the CacheDir.
  --cache-show                Print build actions for files from CacheDir.
  --config=MODE               Controls Configure subsystem: auto, force,
  -D                          Search up directory tree for SConstruct,
                                build all Default() targets.
  --debug=TYPE                Print various types of debugging information:
                                count, duplicate, explain, findlibs, includes,
                                memoizer, memory, objects, pdb, prepare,
                                presub, stacktrace, time.
  --diskcheck=TYPE            Enable specific on-disk checks.
  --duplicate=DUPLICATE       Set the preferred duplication methods. Must be
                                one of hard-soft-copy, soft-hard-copy,
                                hard-copy, soft-copy, copy
  -f FILE, --file=FILE, --makefile=FILE, --sconstruct=FILE
                              Read FILE as the top-level SConstruct file.
  -h, --help                  Print defined help message, or this one.
  -H, --help-options          Print this message and exit.
  -i, --ignore-errors         Ignore errors from build actions.
  -I DIR, --include-dir=DIR   Search DIR for imported Python modules.
  --implicit-cache            Cache implicit dependencies
  --implicit-deps-changed     Ignore cached implicit dependencies.
  --implicit-deps-unchanged   Ignore changes in implicit dependencies.
  --interact, --interactive   Run in interactive mode.
  -j N, --jobs=N              Allow N jobs at once.
  -k, --keep-going            Keep going when a target can't be made.
  --max-drift=N               Set maximum system clock drift to N seconds.
  --md5-chunksize=N           Set chunk-size for MD5 signature computation to
                                N kilobytes.
  -n, --no-exec, --just-print, --dry-run, --recon
                              Don't build; just print commands.
  --no-site-dir               Don't search or use the usual site_scons dir.
  --profile=FILE              Profile SCons and put results in FILE.
  -q, --question              Don't build; exit status says if up to date.
  -Q                          Suppress "Reading/Building" progress messages.
  --random                    Build dependencies in random order.
  -s, --silent, --quiet       Don't print commands.
  --site-dir=DIR              Use DIR instead of the usual site_scons dir.
  --stack-size=N              Set the stack size of the threads used to run
                                jobs to N kilobytes.
  --taskmastertrace=FILE      Trace Node evaluation to FILE.
  --tree=OPTIONS              Print a dependency tree in various formats: all,
                                derived, prune, status.
  -u, --up, --search-up       Search up directory tree for SConstruct,
                                build targets at or below current directory.
  -U                          Search up directory tree for SConstruct,
                                build Default() targets from local SConscript.
  -v, --version               Print the SCons version number and exit.
  --warn=WARNING-SPEC, --warning=WARNING-SPEC
                              Enable or disable warnings.
                              Search REPOSITORY for source and target files.

Local Options:
  --compiler=COMPILER         Sets the install prefix for programs and
  --extra-warnings            Adds extra warning flags to CXXFLAGS
  --disable-64                Disables float64 type, uses float32 instead
  --disable-libao             Disables the libao AudioBackend
  --disable-libportaudio      Disables the libportaudio AudioBackend
  --enable-cuda               Enables Cuda accelerated functions and linking
  --disable-openmp            Disables OpenMp accelerated functions and
  --disable-python            Disables the use of matplotlib via Python, only
                                applies to C++ lib
  --static                    Builds a static C++ lib
  --prefix=PREFIX             Sets the install prefix for programs and
  --config-debug              Prints lots of debug messages during scons
                                configuration tests
  --V, --verbose              Shows full compiler command output
  --D, --DEBUG                Compile in debug mode
  --with-boost=BOOST_PREFIX   Adds the boost include path into the compiler
  --pytest                    Rebuilds python module, then runs unit tests

On Windows: Compiling Nsound From The Command Line

On Windows, rather than muck around with the System’s PATH environment variables, I recommend creating a .BAT file that will insert paths into the environment.

  1. Save this file to your doesktop windows_env64.bat

  2. Create a shortcut to the file windows_env64.bat, edit the shortcut so the target line reads like this:

    cmd /k 'C:\Users\USERNAME\Desktop\windows_env64.bat'
replacing USERNAME with your username.
  1. Modify the shortcut startup directory to be located in the nsound directory, this way you won’t have to cd to it all the time.

  2. Double click the shortcut to open a DOS box with Visual Studio, Python, and SCons in the path, so building Nsound becomes as simple as:

    C:\Users\USERNAME\Documents\nsound> scons

On Windows: Compiling Nsound C++ library Using Visual Studio

Before trying to compile Nsound with Vistual Studio, ensure that Python and SCons have been installed. There are Visual Studio build steps that will execute scons to generate some files.

Next, examine the file msvs\properties.props to ensure the path to Python is correct, the default is C:\Python27.

A Visual Studio 2010+ solution file is provide in msvs\nsound.sln. Debug builds won’t link with Python because the debug library python27_d.lib is not provided, but isn’t needed if you’re debugging Nound C++ code.


If you see this error:

LINK : fatal error LNK1181: cannot open input file ‘winmm.lib’

it may mean you are using “Visual Studio Express for Windows”. This error will go away if you install “Visual Studio Express for Windows Desktop”.

Cygwin Notes

If you run into an error message that looks something like:

python 6140 C:\cygwin\bin\python.exe: *** fatal error - unable to remap \\?\C:\cygwin\lib\python2.6\lib-dynload\time.dll to same address as parent: 0x2B0000 != 0x360000

You will need to “rebase” your Cygwin installation. To do so follow these steps:

  1. Close all Cygwin programs that may be using the cygwin.dll

  2. Ensure the Cygwin package called rebase is installed using the setup.exe program

  3. Start a Windows DOS box (not a Cygwin shell)

  4. Start an ASH shell, then run the rebaseall command by executing:

    C:\> C:\cygwin\bin\ash.exe
    $ cd /bin
    $ ./rebaseall

Compiling the Python Module


SWIG must be installed to generate the Python interface.

  1. Try compiling the C++ library first to ensure SCons and the C++ compiler are working (see step 2 above in Compiling The C++ Library).

  2. Build and install the Python module for a single user:

    python install --user
  1. Or build and install the Python module system wide:

    sudo python install
  2. Or build the Windows self-installer (Windows only):

    python bdist_wininst
  3. Test the Python module:

    import Nsound as ns
    b = ns.Buffer()
    print b

You should see the text:

Nsound.Buffer holding 0 samples

Mac OSX Notes - Use MacPorts

To enable real-time playback and plottting, install these prerequisites using the mac port project:

sudo port install swig scons py27-matplotlib portaudio swig-python py27-game py27-pip

Select the macport version of python and pip the defaults:

sudo port select python python27
sudo port select pip pip27

Linking With A Python Installed In A Non-Standard Location

Sometimes a custom built Python is installed in a non-standard location, for example:


You will need to install scons to this non-stanard location, then just run scons with this non-standard python:


The SCons build environment will ask Python’s distutils module for the location of the include directory and dynamic library paths. This should get done automatically. A SCons tool was added to brute-force check the distutils build variables to locate these paths, site_scons/site_tools/ To enable some extra debug messages, try using the --config-debug switch with scons:

$ scons --config-debug

Please report any problems you are having to Nick.

Python Errors

Sometime everything above goes well, SCons finds the libraries, compiles and links everything fine, but at runtime you may run into other errors.

Matplotlib Backend Not Set

You may see a message like:

Traceback (most recent call last):
    File "/usr/local/python2.7/lib/python2.7/site-packages/matplotlib/backends/", line 35, in do_nothing_show
        fname = frame.f_back.f_code.co_filename
AttributeError: 'NoneType' object has no attribute 'f_code'
src/Nsound/ failed to call python

This is due to the Matplotlib Backend not being set. So set a default backend edit the file matplotlibrc, and set the following:

backend : BACKEND

and replace BACKEND with something like GTKAgg, GTKCairo, CocoaAgg, MacOSX, QtAgg, WXAgg. The choice depends on the backends that are installed. To test if a specific backend is installed do:

>>> import matplotlib
>>> matplotlib.use("GTKAgg")  # Specify specific backend
>>> import matplotlib.pylab
>>> pylab.plot([1,2,3,4,3,2,1])
>>>  # Plot will appear if you selected a working GUI backend
>>> pylab.savefig("somefile.png") # Replace png with pdf or svg to
...                               # to test a file only backend

You should either see a figure window show up after the show() call or a filename written to the local directory after the savefig() call.

Installing The Nsound Python Module Via PIP

All the prerequisites still apply from above. With PIP, you won’t have to download the Nsound source code yourself.

From a shell with your build environment setup, do:

sudo pip install –user nsound

I recommend installing into your home directory by ussing the –user switch.