Installation
============

Compatibility and requirements
------------------------------

`audiomath` is compatible with Python 2.7, and with Python 3.3+.

For your own Python development, it is highly advisable to install a Python
distribution that you keep separate from whatever distribution came with
your operating system.  Anaconda_ is a good choice for this.  At any rate,
we'll assume that when we direct you to type `python` or `pip` in your
Terminal app or Command Prompt, you have figured out how to ensure that the
the correct distribution of Python is being addressed by these commands. On
Windows, the "Anaconda Prompt" is a good shortcut to use to ensure this.

`audiomath` requires the third-party package `numpy` for almost everything
it does. When you use `pip` to install `audiomath`, it will ensure `numpy`
is installed too.  On Windows, it will also install `comtypes` and `psutil`
since these are used by the `audiomath.SystemVolume` submodule.

If you want to plot sound waveforms, you will also need the third-party
package `matplotlib`.  This is optional, so it will be left to you to
`python -m pip install matplotlib` if you want it and do not already have
it.

Similarly, you may want to install the third-party package `librosa` if
you want to time-stretch or pitch-shift sounds.

Similarly, you may want to install the third-party package `audioread`
which appears to provide a more flexible and reliable way of decoding
audio from files than the (now obsolescent) built-in AVbin. If installed,
`audioread` will be used in preference to AVbin.


Normal installation
-------------------

To download the latest release from pypi.org and install it into your
Python distribution::

	python -m pip install audiomath
	
Later, when you want to upgrade an existing installation to the latest,
greatest version::

	python -m pip install --upgrade audiomath --no-dependencies


Advanced installation (from version-controlled sources)
-------------------------------------------------------

.. _git:

To work with the latest sources from the git repository, you will need
to ensure the `git` command-line tool is installed, and then::

	cd WHEREVER-YOU-WOULD-LIKE-TO-KEEP-AUDIOMATH-LONG-TERM
	git clone https://bitbucket.org/snapproject/audiomath-gitrepo
	cd audiomath-gitrepo
	git checkout origin/release --track   # creates local branch called `release`
	git checkout master   # back to master (unless you want to stay on `release`)
	python -m pip install -e .

Note the `-e` flag, which tells Python to install the repository as an
"editable" package. The repository's `master` branch is the bleeding edge,
whereas the `release` branch replicates the pypi.org releases. Use
`git checkout master` or `git checkout release` to switch between them.
In either case, when you want to upgrade to the latest version from the
server later on::

	cd audiomath-gitrepo
	git fetch
	git checkout master  && git merge   # update to the latest changes in the master branch
	git checkout release && git merge   # update to the latest changes in the release branch
	git checkout master   # (assuming you want to be working on master, go back there)

.. _Anaconda: https://www.anaconda.com/download/