{"id":6945,"library":"wavio","title":"Wavio","description":"Wavio is a Python module for reading and writing WAV files using NumPy arrays. It provides two main functions, `wavio.read` and `wavio.write`, for handling 8-, 16-, 24-, and 32-bit integer WAV files. It leverages Python's standard `wave` module and currently does not support compressed WAV files or direct floating-point WAV file output, converting floating-point input to integers. The current version is 0.0.9, with recent updates focusing on NumPy 2.0.0 compatibility.","status":"active","version":"0.0.9","language":"python","source_language":"en","source_url":"https://github.com/WarrenWeckesser/wavio","tags":["audio","wav","file-io","numpy"],"install":[{"cmd":"pip install wavio","lang":"bash","label":"Install wavio"}],"dependencies":[{"reason":"Required for array handling; version 1.21.3 or later recommended.","package":"numpy","optional":false}],"imports":[{"symbol":"wavio","correct":"import wavio"},{"note":"The primary functions are typically accessed as attributes of the imported `wavio` module, e.g., `wavio.read` and `wavio.write`.","wrong":"from wavio import read","symbol":"read","correct":"wavio.read('file.wav')"},{"note":"The primary functions are typically accessed as attributes of the imported `wavio` module, e.g., `wavio.read` and `wavio.write`.","wrong":"from wavio import write","symbol":"write","correct":"wavio.write('file.wav', data, rate)"}],"quickstart":{"code":"import numpy as np\nimport wavio\n\n# Parameters for the sine wave\nrate = 22050  # samples per second\nT = 3         # sample duration (seconds)\nf = 440.0     # sound frequency (Hz)\n\n# Create time array and sine wave data\nt = np.linspace(0, T, int(T * rate), endpoint=False)\nx = np.sin(2 * np.pi * f * t)\n\n# Write the sine wave to a 24-bit WAV file\nwavio.write(\"sine24.wav\", x, rate, sampwidth=3)\n\n# Read the WAV file back\nwav_read = wavio.read(\"sine24.wav\")\nprint(f\"Read WAV file: {wav_read.filename}\")\nprint(f\"Sample rate: {wav_read.rate} Hz\")\nprint(f\"Sample width: {wav_read.sampwidth} bytes\")\nprint(f\"Data shape: {wav_read.data.shape}\")","lang":"python","description":"This quickstart demonstrates how to generate a 3-second 440 Hz sine wave using NumPy and save it as a 24-bit WAV file, then read it back. It illustrates the basic usage of `wavio.write` and `wavio.read`."},"warnings":[{"fix":"Review the `scale` and `sampwidth` parameters in the `wavio.write` documentation for `wavio` versions 0.0.5 and later to adjust your code. Floating-point inputs now require `sampwidth` to be explicitly given.","message":"The API for `wavio.write` changed in version 0.0.5, specifically how floating-point data is scaled. Code written for 0.0.4 or earlier may produce different audio or errors.","severity":"breaking","affected_versions":"<=0.0.4"},{"fix":"Always provide the `sampwidth` parameter when writing floating-point data to control the output bit depth. Be aware of the `scale` parameter in `wavio.write` (defaulting to `[-1.0, 1.0]` mapping to the full integer range) and check for clipping warnings.","message":"Wavio does not directly support floating-point WAV files or compressed WAV files. When writing floating-point data, it is converted to integers, and if `sampwidth` is not provided, default scaling is applied. Data clipping can occur and will generate a warning.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the GitHub release notes and PyPI project description for each new version to be aware of any changes.","message":"The API of wavio functions is not considered stable, and backwards-incompatible changes may occur between releases.","severity":"deprecated","affected_versions":"All versions"},{"fix":"Ensure your environment uses Python 3.10 or newer for `wavio` version 0.0.9. Older `wavio` versions may support earlier Python versions.","message":"The library explicitly states that it requires Python 3.10 or later as of recent updates, which is a change from older versions that supported Python 3.7+ (and even 2.7 in much older releases).","severity":"gotcha","affected_versions":"<0.0.9 (pre-NumPy 2.0.0 support)"}],"env_vars":null,"search_vec":"'0.0.9':69 '16':27 '2.0.0':76 '24':28 '32':30 '8':26 'array':15 'audio':78 'bit':31 'compat':77 'compress':47 'convert':58 'current':43,66 'direct':51 'file':12,34,49,56,81 'file-io':80 'float':53,60 'floating-point':52,59 'focus':73 'function':20 'handl':25 'input':62 'integ':32,64 'io':82 'leverag':36 'main':19 'modul':6,41 'numpi':14,75,83 'output':57 'point':54,61 'provid':17 'python':5,37 'read':8 'recent':71 'standard':39 'support':46 'two':18 'updat':72 'use':13 'version':67 'wav':11,33,48,55,79 'wave':40 'wavio':1,2 'wavio.read':21 'wavio.write':23 'write':10","created_at":"2026-04-15T18:49:47.501847+00:00","updated_at":"2026-04-17T00:28:50.033616+00:00","problems":[{"fix":"pip install wavio","cause":"The `wavio` package has not been installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'wavio'"},{"fix":"Convert your data to a NumPy array using `numpy.array()` before passing it to `wavio.write`.","cause":"The `data` argument provided to `wavio.write` is not a NumPy array (e.g., it's a Python list or tuple).","error":"TypeError: Data must be a NumPy array."},{"fix":"Reshape your `data` array to be 1D (mono) or 2D (multi-channel, with channels as the second dimension) before passing it to `wavio.write`.","cause":"The input `data` array provided to `wavio.write` has more than two dimensions (e.g., 3D or higher), but `wavio` only supports 1D (mono) or 2D (stereo/multi-channel) arrays.","error":"ValueError: Data must be 1D or 2D array"},{"fix":"Ensure the WAV file is an uncompressed PCM format. If you need to process compressed formats, use a different library like `pydub` or `soundfile`.","cause":"The WAV file being read is either compressed, corrupted, or not a standard uncompressed PCM WAV file, which `wavio` (and the underlying `wave` module) does not support.","error":"wave.Error: unknown format type"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.0.9","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/WarrenWeckesser/wavio","docs":null,"changelog":null,"pypi":"https://pypi.org/project/wavio/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}