{"id":23343245,"url":"https://github.com/rec/wavemap","last_synced_at":"2025-04-10T02:21:40.687Z","repository":{"id":62588298,"uuid":"323688944","full_name":"rec/wavemap","owner":"rec","description":"🌊 mmap massive audio files as numpy 🌊","archived":false,"fork":false,"pushed_at":"2024-02-14T14:43:14.000Z","size":4108,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-05-01T19:21:07.519Z","etag":null,"topics":["audio-processing","numpy","wav"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rec.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG","contributing":null,"funding":"FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"rec"}},"created_at":"2020-12-22T17:17:41.000Z","updated_at":"2024-01-31T09:28:21.000Z","dependencies_parsed_at":"2024-11-16T04:46:04.674Z","dependency_job_id":null,"html_url":"https://github.com/rec/wavemap","commit_stats":{"total_commits":99,"total_committers":1,"mean_commits":99.0,"dds":0.0,"last_synced_commit":"cd188421a1c9322722655e49f1f9d1c0ee90f570"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rec%2Fwavemap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rec%2Fwavemap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rec%2Fwavemap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rec%2Fwavemap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rec","download_url":"https://codeload.github.com/rec/wavemap/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248143123,"owners_count":21054709,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio-processing","numpy","wav"],"created_at":"2024-12-21T06:13:38.585Z","updated_at":"2025-04-10T02:21:40.664Z","avatar_url":"https://github.com/rec.png","language":"Python","readme":"🌊 Memory map WAVE files into numpy arrays 🌊\n----------------------------------------------\n\n.. image:: https://raw.githubusercontent.com/rec/wavemap/master/wavemap.png\n   :alt: WaveMap logo\n\nManipulate huge WAVE or RAW files as numpy matrices - even if they are too\nlarge to fit into memory.\n\nMemory mapping is a technique where files on disk are directly mapped to\nlocations in memory and use the same logic as swap space does.\n\nSamples from a WAVE or RAW audio file are directly memory mapped to entries in\na ``numpy`` array, letting you manipulate very large audio files as if they\nall fit into memory at one time, and even directly change samples on disk.\n\nTypical usage:\n\n.. code-block:: python\n\n    import wavemap\n\n    wm = wavemap('test.wav', 'r+')  # r+ means read/write\n    # Now you have a numpy matrix that you can use like any other\n\n    wm /= 2\n    # Each sample in the file is scaled by half.\n\nAPI\n===\n\n``wavemap()``\n~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: python\n\n  wavemap(\n       filename: str,\n       mode: str='r',\n       order: Union[str, NoneType]=None,\n       always_2d: bool=False,\n       dtype: Union[numpy.dtype, NoneType]=None,\n       shape: Union[NoneType, int, tuple]=None,\n       sample_rate: int=0,\n       roffset: int=0,\n       warn: Union[Callable, NoneType]='\u003cfunction warn:  print to stderr\u003e',\n  )\n\n(`wavemap/__init__.py, 56-121 \u003chttps://github.com/rec/wavemap/blob/master/wavemap/__init__.py#L56-L121\u003e`_)\n\n    Memory map a WAVE file to a ``numpy`` array\n\n    Return an instance of ``ReadMap`` or ``WriteMap``, depending on\n    ``mode``.\n\nARGUMENTS\n  filename\n    The name of the file being mapped\n\n  mode\n    The file is opened in this mode.\n    Must be one of ``'r'``, ``'r+'``, ``'c'``, ``'w+'``\n\n    In mode ``'r'``, the default, the file is opened read-only and\n    the ``numpy.darray`` is immutable.\n\n    In mode ``'r+'``, the file is opened read-write and changes to the\n    ``numpy.darray`` are automatically applied to the file.\n\n    In mode ``'c'``, \"copy-on-write\", the file is opened read-only, but\n    the ``numpy.darray`` is *not* immutable: changes to the array are\n    instead stored in memory.\n\n    In mode ``'w+'``, \"write\", the file is opened for write, and overwrites\n    whatever else is there.\n\n  order\n    Samples usually get laid out in into a ``numpy.darray`` with``\n    shape=(N, C)`` where ``N`` is the number of audio frames, and ``C`` is\n    the number of channels.\n\n    This is called column major order, but this can be toggled by\n    setting the ``order`` parameter to ``F`` for Fortan or row-major row.\n\n    See https://stackoverflow.com/questions/27266338/\n\n  always_2d\n    If ``False``, the default, mono WAVE files with only one channel\n    get special treatment and are mapped to a one-dimensional vector\n    with ``size=(N,)``.\n\n    If ``True``, mono WAVE files are treated the same as any other file\n    and are mapped to a two-dimensional matrix with ``size=(N, 1)``.\n\n  dtype\n    The numpy datatype of the samples in the file.\n\n  shape\n    The shape of the resulting numpy.darray. Can be a tuple, or a positive\n    integer, or ``None``.\n\n  sample_rate\n    The sample rate in Hz (cycles per second)\n\n  roffset\n    How many bytes in the file after the WAV data\n\n  warn\n    Programmers are sloppy so quite a lot of real-world WAVE files have\n    recoverable errors in their format.  ``warn`` is the function used to\n    report those recoverable errors.  By default, it's set to print to\n    ``sys.stderr`` but setting it to ``None`` disables errors entirely, or\n    you can pass your own callback in\n\nClass ``wavemap.RawMap``\n~~~~~~~~~~~~~~~~~~~~~~~~\n\n(`wavemap/raw.py, 14-67 \u003chttps://github.com/rec/wavemap/blob/master/wavemap/raw.py#L14-L67\u003e`_)\n\n\"Memory map raw audio data from a disk file into a numpy matrix\n\n``wavemap.RawMap.__new__()``\n____________________________\n\n.. code-block:: python\n\n  wavemap.RawMap.__new__(\n       cls,\n       filename: str,\n       dtype: numpy.dtype,\n       shape: Union[tuple, int, NoneType]=None,\n       mode: str='r',\n       offset: int=0,\n       roffset: int=0,\n       order: Union[str, NoneType]=None,\n       always_2d: bool=False,\n       warn: Union[Callable, NoneType]='\u003cfunction warn:  print to stderr\u003e',\n  )\n\n(`wavemap/raw.py, 17-67 \u003chttps://github.com/rec/wavemap/blob/master/wavemap/raw.py#L17-L67\u003e`_)\n\nMemory map raw audio data from a disk file into a numpy matrix\n\nARGUMENTS\n  cls\n    Think of this as ``self``.  (This is because you need to implement ``__new__``\n    and not ``__init__`` when deriving from ``np.darray``.)\n\n  filename\n    The name of the file being mapped\n\n  dtype\n    The numpy datatype of the samples in the file.\n\n  shape\n    The shape of the resulting numpy.darray. Can be a tuple, or a positive\n    integer, or ``None``.\n\n  mode\n    The file is opened in this mode.\n    Must be one of ``'r'``, ``'r+'``, ``'c'``, ``'w+'``\n\n    In mode ``'r'``, the default, the file is opened read-only and\n    the ``numpy.darray`` is immutable.\n\n    In mode ``'r+'``, the file is opened read-write and changes to the\n    ``numpy.darray`` are automatically applied to the file.\n\n    In mode ``'c'``, \"copy-on-write\", the file is opened read-only, but\n    the ``numpy.darray`` is *not* immutable: changes to the array are\n    instead stored in memory.\n\n    In mode ``'w+'``, \"write\", the file is opened for write, and overwrites\n    whatever else is there.\n\n  offset\n    How many bytes in the file before the WAV data\n\n  roffset\n    How many bytes in the file after the WAV data\n\n  order\n    Samples usually get laid out in into a ``numpy.darray`` with``\n    shape=(N, C)`` where ``N`` is the number of audio frames, and ``C`` is\n    the number of channels.\n\n    This is called column major order, but this can be toggled by\n    setting the ``order`` parameter to ``F`` for Fortan or row-major row.\n\n    See https://stackoverflow.com/questions/27266338/\n\n  always_2d\n    If ``False``, the default, mono WAVE files with only one channel\n    get special treatment and are mapped to a one-dimensional vector\n    with ``size=(N,)``.\n\n    If ``True``, mono WAVE files are treated the same as any other file\n    and are mapped to a two-dimensional matrix with ``size=(N, 1)``.\n\n  warn\n    Programmers are sloppy so quite a lot of real-world WAVE files have\n    recoverable errors in their format.  ``warn`` is the function used to\n    report those recoverable errors.  By default, it's set to print to\n    ``sys.stderr`` but setting it to ``None`` disables errors entirely, or\n    you can pass your own callback in\n\nClass ``wavemap.ReadMap``\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\n(`wavemap/read.py, 18-84 \u003chttps://github.com/rec/wavemap/blob/master/wavemap/read.py#L18-L84\u003e`_)\n\nMemory-map an existing WAVE file into a numpy vector or matrix\n\n``wavemap.ReadMap.__new__()``\n_____________________________\n\n.. code-block:: python\n\n  wavemap.ReadMap.__new__(\n       cls: Type,\n       filename: str,\n       mode: str='r',\n       order: Union[str, NoneType]=None,\n       always_2d: bool=False,\n       warn: Union[Callable, NoneType]='\u003cfunction warn:  print to stderr\u003e',\n  )\n\n(`wavemap/read.py, 21-84 \u003chttps://github.com/rec/wavemap/blob/master/wavemap/read.py#L21-L84\u003e`_)\n\nMemory-map an existing WAVE file into a numpy matrix.\n\nARGUMENTS\n  cls\n    Think of this as ``self``.  (This is because you need to implement ``__new__``\n    and not ``__init__`` when deriving from ``np.darray``.)\n\n  filename\n    The name of the file being mapped\n\n  mode\n    The file is opened in this mode.\n    Must be one of ``'r'``, ``'r+'`` and ``'c'``.\n\n    In mode ``'r'``, the default, the file is opened read-only and\n    the ``numpy.darray`` is immutable.\n\n    In mode ``'r+'``, the file is opened read-write and changes to the\n    ``numpy.darray`` are automatically applied to the file.\n\n    In mode ``'c'``, \"copy-on-write\", the file is opened read-only, but\n    the ``numpy.darray`` is *not* immutable: changes to the array are\n    instead stored in memory.\n\n  order\n    Samples usually get laid out in into a ``numpy.darray`` with``\n    shape=(N, C)`` where ``N`` is the number of audio frames, and ``C`` is\n    the number of channels.\n\n    This is called column major order, but this can be toggled by\n    setting the ``order`` parameter to ``F`` for Fortan or row-major row.\n\n    See https://stackoverflow.com/questions/27266338/\n\n  always_2d\n    If ``False``, the default, mono WAVE files with only one channel\n    get special treatment and are mapped to a one-dimensional vector\n    with ``size=(N,)``.\n\n    If ``True``, mono WAVE files are treated the same as any other file\n    and are mapped to a two-dimensional matrix with ``size=(N, 1)``.\n\n  warn\n    Programmers are sloppy so quite a lot of real-world WAVE files have\n    recoverable errors in their format.  ``warn`` is the function used to\n    report those recoverable errors.  By default, it's set to print to\n    ``sys.stderr`` but setting it to ``None`` disables errors entirely, or\n    you can pass your own callback in\n\nClass ``wavemap.WriteMap``\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n(`wavemap/write.py, 12-115 \u003chttps://github.com/rec/wavemap/blob/master/wavemap/write.py#L12-L115\u003e`_)\n\n\"Memory-map a new wave file into a new numpy vector or matrix\n\n``wavemap.WriteMap.__new__()``\n______________________________\n\n.. code-block:: python\n\n  wavemap.WriteMap.__new__(\n       cls: Type,\n       filename: str,\n       dtype: numpy.dtype,\n       shape: Union[NoneType, int, tuple],\n       sample_rate: int,\n       roffset: int=0,\n       warn: Union[Callable, NoneType]='\u003cfunction warn:  print to stderr\u003e',\n  )\n\n(`wavemap/write.py, 15-85 \u003chttps://github.com/rec/wavemap/blob/master/wavemap/write.py#L15-L85\u003e`_)\n\n        Open a memory-mapped WAVE file in write mode and overwrite any existing\n        file.\n\nARGUMENTS\n  cls\n    Think of this as ``self``.  (This is because you need to implement ``__new__``\n    and not ``__init__`` when deriving from ``np.darray``.)\n\n  filename\n    The name of the file being mapped\n\n  dtype\n    The numpy datatype of the samples in the file.\n\n  shape\n    The shape of the resulting numpy.darray. Can be a tuple, or a positive\n    integer, or ``None``.\n\n  sample_rate\n    The sample rate in Hz (cycles per second)\n\n  roffset\n    How many bytes in the file after the WAV data\n\n  warn\n    Programmers are sloppy so quite a lot of real-world WAVE files have\n    recoverable errors in their format.  ``warn`` is the function used to\n    report those recoverable errors.  By default, it's set to print to\n    ``sys.stderr`` but setting it to ``None`` disables errors entirely, or\n    you can pass your own callback in\n\n``wavemap.convert()``\n~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: python\n\n  wavemap.convert(\n       arr: numpy.ndarray,\n       dtype: Union[numpy.dtype, NoneType],\n       must_copy: bool=False,\n  )\n\n(`wavemap/convert.py, 6-77 \u003chttps://github.com/rec/wavemap/blob/master/wavemap/convert.py#L6-L77\u003e`_)\n\nReturns a copy of a numpy array or matrix that represents audio data in\nanother type, scaling and shifting as necessary.\n\nARGUMENTS\n  arr\n    A numpy darray representing an audio signal\n\n  dtype\n    The numpy dtype to convert to - none means \"no conversion\"\n\n  must_copy\n    If true, ``arr`` is copied even if it is already the requested type\n\n(automatically generated by `doks \u003chttps://github.com/rec/doks/\u003e`_ on 2021-02-23T14:37:02.652534)\n","funding_links":["https://github.com/sponsors/rec"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frec%2Fwavemap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frec%2Fwavemap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frec%2Fwavemap/lists"}