{"id":30012131,"url":"https://github.com/facebookresearch/WavAugment","last_synced_at":"2025-08-05T14:02:57.318Z","repository":{"id":41504182,"uuid":"275165670","full_name":"facebookresearch/WavAugment","owner":"facebookresearch","description":"A library for speech data augmentation in time-domain","archived":true,"fork":false,"pushed_at":"2021-08-30T18:49:46.000Z","size":2037,"stargazers_count":655,"open_issues_count":5,"forks_count":59,"subscribers_count":25,"default_branch":"main","last_synced_at":"2025-02-23T00:14:17.023Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/facebookresearch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-06-26T13:43:30.000Z","updated_at":"2025-02-19T07:51:48.000Z","dependencies_parsed_at":"2022-08-21T21:21:12.740Z","dependency_job_id":null,"html_url":"https://github.com/facebookresearch/WavAugment","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/facebookresearch/WavAugment","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookresearch%2FWavAugment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookresearch%2FWavAugment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookresearch%2FWavAugment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookresearch%2FWavAugment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/facebookresearch","download_url":"https://codeload.github.com/facebookresearch/WavAugment/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookresearch%2FWavAugment/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268910448,"owners_count":24327512,"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","status":"online","status_checked_at":"2025-08-05T02:00:12.334Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-08-05T14:01:20.819Z","updated_at":"2025-08-05T14:02:57.284Z","avatar_url":"https://github.com/facebookresearch.png","language":"Python","funding_links":[],"categories":["Software","Audio"],"sub_categories":["Audio data augmentation"],"readme":"# WavAugment\n\nWavAugment performs data augmentation on audio data. \nThe audio data is represented as [pytorch](https://pytorch.org/) tensors. \n\nIt is particularly useful for speech data. \nAmong others, it implements the augmentations that we found to be most useful for self-supervised learning \n(_Data Augmenting Contrastive Learning of Speech Representations in the Time Domain_, E. Kharitonov, M. Rivière, G. Synnaeve, L. Wolf, P.-E. Mazaré, M. Douze, E. Dupoux. [[arxiv]](https://arxiv.org/abs/2007.00991)):\n\n* Pitch randomization,\n* Reverberation,\n* Additive noise,\n* Time dropout (temporal masking),\n* Band reject,\n* Clipping\n\nInternally, WavAugment uses [libsox](http://sox.sourceforge.net/libsox.html) and allows interleaving of libsox- and pytorch-based effects. \n\n### Requirements\n * Linux or MacOS\n * [pytorch](pytorch.org) \u003e= 1.7\n * [torchaudio](pytorch.org/audio) \u003e= 0.7\n\n### Installation\nTo install WavAugment, run the following command:\n```bash\ngit clone git@github.com:facebookresearch/WavAugment.git \u0026\u0026 cd WavAugment \u0026\u0026 python setup.py develop\n```\n\n### Testing\nRequires pytest (`pip install pytest`)\n\n```bash\npython -m pytest -v --doctest-modules\n```\n\n## Usage\n\nFirst of all, we provide thouroughly documented [examples](./examples/python), where we demonstrate how a data-augmented dataset interface works. We also provide a Jupyter-based [tutorial](./examples/python/WavAugment_walkthrough.ipynb) [(open in colab)](https://colab.research.google.com/github/facebookresearch/WavAugment/blob/master/examples/python/WavAugment_walkthrough.ipynb) that illlustrates how one can apply various useful effects to a piece of speech (recorded over the mic or pre-recorded).\n\n### The `EffectChain`\n\nThe central object is the chain of effects, `EffectChain`, that are applied on a `torch.Tensor` to produce another `torch.Tensor`. \nThis chain can have multiple effects composed:\n```python\nimport augment\neffect_chain = augment.EffectChain().pitch(100).rate(16_000)\n```\nParameters of the effect coincide with those of libsox (http://sox.sourceforge.net/libsox.html); however, you can also randomize the parameters by providing a python `Callable` and mix them with standard parameters:\n```python\nimport numpy as np\nrandom_pitch_shift = lambda: np.random.randint(-100, +100)\n# the pitch will be changed by a shift somewhere between (-100, +100)\neffect_chain = augment.EffectChain().pitch(\"-q\", random_pitch_shift).rate(16_000)\n```\nHere, the flag`-q` makes `pitch` run faster at some expense of the quality.\nIf some parameters are provided by a Callable, this Callable will be invoked every time `EffectChain` is applied (eg. to generate random parameters).\n\n### Applying the chain\n\nTo apply a chain of effects on a torch.Tensor, we code the following:\n```python\noutput_tensor = augment.EffectChain().pitch(100).rate(16_000).apply(input_tensor, \\\n    src_info=src_info, target_info=target_info)\n```\nWavAugment expects `input_tensor` to have a shape of (channels, length). As `input_tensor` does not contain important meta-information, such as sampling rate, we need to provide it manually.\nThis is done by passing two dictionaries, `src_info` (meta-information about the input format) and `target_info` (our expectated format for the output).\n\nAt minimum, we need to set the sampling rate for the input tensor: `{'rate': 16_000}`. \n\n### Example usage\n\nBelow is a small gist of a potential usage:\n\n```python\nimport augment\nimport numpy as np\n\nx, sr = torchaudio.load(test_wav)\n\n# input signal properties\nsrc_info = {'rate': sr}\n\n# output signal properties\ntarget_info = {'channels': 1, \n               'length': 0, # not known beforehand\n               'rate': 16_000}\n# write down the chain of effects with their string parameters and call .apply()\n# effects are specified as a chain of method calls with parameters that can be \n# strings, numbers, or callables. The latter case is used for generating randomized\n# transformations\nrandom_pitch = lambda: np.random.randint(-400, -200)\ny = augment.EffectChain().pitch(random_pitch).rate(16_000).apply(x, \\\n    src_info=src_info, target_info=target_info)\n```\n\n## Important notes\nIt often happens that a command-line invocation of sox would change effect chain. To get a better idea of what sox executes internally, you can launch it with a -V flag, eg by running:\n ```bash\nsox -V tests/test.wav out.wav reverb 0 50 100\n```\nwe will see something like:\n```\nsox INFO sox: effects chain: input        16000Hz  1 channels\nsox INFO sox: effects chain: reverb       16000Hz  2 channels\nsox INFO sox: effects chain: channels     16000Hz  1 channels\nsox INFO sox: effects chain: dither       16000Hz  1 channels\nsox INFO sox: effects chain: output       16000Hz  1 channels\n```\nThis output tells us that the `reverb` effect changes the number of channels, which are squashed into 1 channel by the `channel` effect. Sox also added `dither` effect to hide processing artifacts.\n\nWavAugment remains explicit and doesn't add effects under the hood. \nIf you want to emulate a Sox command that decomposes into several effects, we advise to consult `sox -V` and apply the effects manually. \nTry it out on some files before running a heavy machine-learning job. \n\n## Citation\nIf you find WavAugment useful in your research, please consider citing:\n```\n@article{wavaugment2020,\n  title={Data Augmenting Contrastive Learning of Speech Representations in the Time Domain},\n  author={Kharitonov, Eugene and Rivi{\\`e}re, Morgane and Synnaeve, Gabriel and Wolf, Lior and Mazar{\\'e}, Pierre-Emmanuel and Douze, Matthijs and Dupoux, Emmanuel},\n  journal={arXiv preprint arXiv:2007.00991},\n  year={2020}\n}\n```\n\n## Contributing\nSee the [CONTRIBUTING](CONTRIBUTING.md) file for how to help out.\n\n## License\nWavAugment is MIT licensed, as found in the LICENSE file.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebookresearch%2FWavAugment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffacebookresearch%2FWavAugment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebookresearch%2FWavAugment/lists"}