wavio
=====
``wavio`` is a Python module that defines two functions:
* ``wavio.read`` reads a WAV file and returns an object that holds the
sampling rate, sample width (in bytes), and a numpy array containing the
data.
* ``wavio.write`` writes a numpy array to a WAV file, optionally using a
specified sample width.
The functions can read and write 8-, 16-, 24- and 32-bit integer WAV files.
The module uses the ``wave`` module in Python's standard library, so it has
the same limitations as that module. In particular, the ``wave`` module
does not support compressed WAV files, and it does not handle floating
point WAV files. When floating point data is passed to ``wavio.write`` it
is converted to integers before being written to the WAV file.
``wavio`` requires Python 3.7 or later.
``wavio`` depends on numpy (http://www.numpy.org). NumPy version 1.19.0 or
later is required. The unit tests in ``wavio`` require ``pytest``.
The API of the functions in ``wavio`` should not be considered stable. There
may be backwards-incompatible API changes between releases.
*Important notice*
In version 0.0.5, the data handling in ``wavio.write`` has been changed in
a backwards-incompatible way. The API for scaling the input in 0.0.4 was
a flexible interface that only its creator could love. The new API is
simpler, and it is hoped that it does the right thing by default in
most cases. In particular:
* When the input data is an integer type, the values are not scaled or
shifted. The only change that might happen is the data will be clipped
if the values do not fit in the output integer type.
* If the input data is a floating point type, ``sampwidth`` must be given.
The default behavior is to scale input values in the range [-1.0, 1.0]
to the output range [min_int+1, max_int], where min_int and max_int are
the minimum and maximum values of the output data type determined by
``sampwidth``. See the description of ``scale`` in the docstring of
``wavio.write`` for more options. Regardless of the value of ``scale``,
the float input 0.0 is always mapped to the midpoint of the output type;
``wavio.write`` will not translate the values up or down.
* A warning is now generated if any data values are clipped. A parameter
allows the generation of the warning to be disabled or converted to an
exception.
Examples
--------
The following examples are also found in the docstring of ``wavio.write``.
Create a 3 second 440 Hz sine wave, and save it in a 24-bit WAV file.
>>> import numpy as np
>>> import wavio
>>> rate = 22050 # samples per second
>>> T = 3 # sample duration (seconds)
>>> n = int(rate*T) # number of samples
>>> t = np.arange(n)/rate # grid of time values
>>> f = 440.0 # sound frequency (Hz)
>>> x = np.sin(2*np.pi * f * t)
`x` is a single sine wave with amplitude 1, so we can use the default
`scale`.
>>> wavio.write("sine24.wav", x, rate, sampwidth=3)
Create a file that contains the 16 bit integer values -10000 and 10000
repeated 100 times. Use a sample rate of 8000.
>>> x = np.empty(200, dtype=np.int16)
>>> x[::2] = -10000
>>> x[1::2] = 10000
>>> wavio.write("foo.wav", x, 8000)
Check that the file contains what we expect. The values are checked
for exact equality. The input was an integer array, so the values are
not scaled.
>>> w = wavio.read("foo.wav")
>>> np.all(w.data[:, 0] == x)
True
Write floating point data to a 16 bit WAV file. The floating point
values are assumed to be within the range [-2, 2], and we want the
values 2 and -2 to correspond to the full output range, even if the
actual values in the data do not fill this range. We do that by
specifying `scale=2`.
`T`, `rate` and `t` are from above. The data is the sum of two
sinusoids, with frequencies 440 and 880 Hz, modulated by a parabolic
curve that is zero at the start and end of the data.
>>> envelope = (4/T**2)*(t * (T - t))
>>> omega1 = 2*np.pi*440
>>> omega2 = 2*np.pi*880
>>> y = envelope*(np.sin(omega1*t) + 0.3*np.sin(omega2*t + 0.2))
>>> y.min(), y.max()
(-1.1745469775555515, 1.093833464065767)
Write the WAV file, with `scale=2`.
>>> wavio.write('harmonic.wav', y, rate, sampwidth=2, scale=2)
Check the minimum and maximum integers that were actually written
to the file:
>>> w = wavio.read("harmonic.wav")
>>> w.data.min(), w.data.max()
(-19243, 17921)
If we want the WAV file to use as much of the range of the output
integer type as possible (while still mapping 0.0 in the input to 0 in
the output), we set `scale="auto"`.
>>> wavio.write('harmonic_full.wav', y, rate, sampwidth=2, scale="auto")
>>> w = wavio.read('harmonic_full.wav')
>>> w.data.min(), w.data.max()
(-32768, 30517)
-----
Author: Warren Weckesser
Repository: https://github.com/WarrenWeckesser/wavio
License: BSD 2-clause (http://opensource.org/licenses/BSD-2-Clause)
Raw data
{
"_id": null,
"home_page": "https://github.com/WarrenWeckesser/wavio",
"name": "wavio",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "wav numpy",
"author": "Warren Weckesser",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/38/14/7b7fb6db2925435137ab1019e4a6e298b94e3c936e8be8e579f8a0b199ee/wavio-0.0.8.tar.gz",
"platform": null,
"description": "wavio\n=====\n\n``wavio`` is a Python module that defines two functions:\n\n* ``wavio.read`` reads a WAV file and returns an object that holds the\n sampling rate, sample width (in bytes), and a numpy array containing the\n data.\n* ``wavio.write`` writes a numpy array to a WAV file, optionally using a\n specified sample width.\n\nThe functions can read and write 8-, 16-, 24- and 32-bit integer WAV files.\n\nThe module uses the ``wave`` module in Python's standard library, so it has\nthe same limitations as that module. In particular, the ``wave`` module\ndoes not support compressed WAV files, and it does not handle floating\npoint WAV files. When floating point data is passed to ``wavio.write`` it\nis converted to integers before being written to the WAV file.\n\n``wavio`` requires Python 3.7 or later.\n\n``wavio`` depends on numpy (http://www.numpy.org). NumPy version 1.19.0 or\nlater is required. The unit tests in ``wavio`` require ``pytest``.\n\nThe API of the functions in ``wavio`` should not be considered stable. There\nmay be backwards-incompatible API changes between releases.\n\n*Important notice*\n\nIn version 0.0.5, the data handling in ``wavio.write`` has been changed in\na backwards-incompatible way. The API for scaling the input in 0.0.4 was\na flexible interface that only its creator could love. The new API is\nsimpler, and it is hoped that it does the right thing by default in\nmost cases. In particular:\n\n* When the input data is an integer type, the values are not scaled or\n shifted. The only change that might happen is the data will be clipped\n if the values do not fit in the output integer type.\n* If the input data is a floating point type, ``sampwidth`` must be given.\n The default behavior is to scale input values in the range [-1.0, 1.0]\n to the output range [min_int+1, max_int], where min_int and max_int are\n the minimum and maximum values of the output data type determined by\n ``sampwidth``. See the description of ``scale`` in the docstring of\n ``wavio.write`` for more options. Regardless of the value of ``scale``,\n the float input 0.0 is always mapped to the midpoint of the output type;\n ``wavio.write`` will not translate the values up or down.\n* A warning is now generated if any data values are clipped. A parameter\n allows the generation of the warning to be disabled or converted to an\n exception.\n\nExamples\n--------\n\nThe following examples are also found in the docstring of ``wavio.write``.\n\nCreate a 3 second 440 Hz sine wave, and save it in a 24-bit WAV file.\n\n >>> import numpy as np\n >>> import wavio\n\n >>> rate = 22050 # samples per second\n >>> T = 3 # sample duration (seconds)\n >>> n = int(rate*T) # number of samples\n >>> t = np.arange(n)/rate # grid of time values\n\n >>> f = 440.0 # sound frequency (Hz)\n >>> x = np.sin(2*np.pi * f * t)\n\n`x` is a single sine wave with amplitude 1, so we can use the default\n`scale`.\n\n >>> wavio.write(\"sine24.wav\", x, rate, sampwidth=3)\n\nCreate a file that contains the 16 bit integer values -10000 and 10000\nrepeated 100 times. Use a sample rate of 8000.\n\n >>> x = np.empty(200, dtype=np.int16)\n >>> x[::2] = -10000\n >>> x[1::2] = 10000\n >>> wavio.write(\"foo.wav\", x, 8000)\n\nCheck that the file contains what we expect. The values are checked\nfor exact equality. The input was an integer array, so the values are\nnot scaled.\n\n >>> w = wavio.read(\"foo.wav\")\n >>> np.all(w.data[:, 0] == x)\n True\n\nWrite floating point data to a 16 bit WAV file. The floating point\nvalues are assumed to be within the range [-2, 2], and we want the\nvalues 2 and -2 to correspond to the full output range, even if the\nactual values in the data do not fill this range. We do that by\nspecifying `scale=2`.\n\n`T`, `rate` and `t` are from above. The data is the sum of two\nsinusoids, with frequencies 440 and 880 Hz, modulated by a parabolic\ncurve that is zero at the start and end of the data.\n\n >>> envelope = (4/T**2)*(t * (T - t))\n >>> omega1 = 2*np.pi*440\n >>> omega2 = 2*np.pi*880\n >>> y = envelope*(np.sin(omega1*t) + 0.3*np.sin(omega2*t + 0.2))\n >>> y.min(), y.max()\n (-1.1745469775555515, 1.093833464065767)\n\nWrite the WAV file, with `scale=2`.\n\n >>> wavio.write('harmonic.wav', y, rate, sampwidth=2, scale=2)\n\nCheck the minimum and maximum integers that were actually written\nto the file:\n\n >>> w = wavio.read(\"harmonic.wav\")\n >>> w.data.min(), w.data.max()\n (-19243, 17921)\n\nIf we want the WAV file to use as much of the range of the output\ninteger type as possible (while still mapping 0.0 in the input to 0 in\nthe output), we set `scale=\"auto\"`.\n\n >>> wavio.write('harmonic_full.wav', y, rate, sampwidth=2, scale=\"auto\")\n\n >>> w = wavio.read('harmonic_full.wav')\n >>> w.data.min(), w.data.max()\n (-32768, 30517)\n\n-----\n\nAuthor: Warren Weckesser\n\nRepository: https://github.com/WarrenWeckesser/wavio\n\nLicense: BSD 2-clause (http://opensource.org/licenses/BSD-2-Clause)\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "A Python module for reading and writing WAV files using numpy arrays.",
"version": "0.0.8",
"project_urls": {
"Homepage": "https://github.com/WarrenWeckesser/wavio"
},
"split_keywords": [
"wav",
"numpy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bf0240d03e99a3d2d8d1e9392f44376f470120427ffb12483579dc7e0365f712",
"md5": "226304eb233f56a387697a3d653f9203",
"sha256": "728d5c3815a9f254dc5846cdd79168eed32aa9e4fcf9476cf232bcbe5340b5ce"
},
"downloads": -1,
"filename": "wavio-0.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "226304eb233f56a387697a3d653f9203",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9427,
"upload_time": "2023-10-07T22:49:54",
"upload_time_iso_8601": "2023-10-07T22:49:54.258067Z",
"url": "https://files.pythonhosted.org/packages/bf/02/40d03e99a3d2d8d1e9392f44376f470120427ffb12483579dc7e0365f712/wavio-0.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "38147b7fb6db2925435137ab1019e4a6e298b94e3c936e8be8e579f8a0b199ee",
"md5": "fd9c3050126095a5d771f412a8a3d2ce",
"sha256": "51c13768885d4095ba082547857502e2123905db547faebdc007e03ade18ed5d"
},
"downloads": -1,
"filename": "wavio-0.0.8.tar.gz",
"has_sig": false,
"md5_digest": "fd9c3050126095a5d771f412a8a3d2ce",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10421,
"upload_time": "2023-10-07T22:49:56",
"upload_time_iso_8601": "2023-10-07T22:49:56.002151Z",
"url": "https://files.pythonhosted.org/packages/38/14/7b7fb6db2925435137ab1019e4a6e298b94e3c936e8be8e579f8a0b199ee/wavio-0.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-07 22:49:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "WarrenWeckesser",
"github_project": "wavio",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "wavio"
}
JSON
