Name | wavaugmentate JSON |
Version |
0.2.2
JSON |
| download |
home_page | None |
Summary | The package wavaugmentate makes audio signal augmentation conversions. |
upload_time | 2024-10-06 07:17:48 |
maintainer | None |
docs_url | None |
author | None |
requires_python | >=3.9 |
license | None |
keywords |
augmentation
wav
ml
dl
audio
sound
|
VCS |
|
bugtrack_url |
|
requirements |
No requirements were recorded.
|
Travis-CI |
No Travis.
|
coveralls test coverage |
No coveralls.
|
# **Wavaugmentate** 0.2.2
**Multichannel Audio Signal Augmentation Module**
![alt text](./pictures/title_image.png)
The module makes audio signal augmentation conversions. It provides the *MultiChannelSignal*, *SignalAugmentation* classes and *wavaug-cli* console utility.
- *MultiChannalSignal* provides basic operations with multi-channel signals.
- *SignalAugmentation* helps to perform augmentation of multi-channel signals for AI models learning purpose.
PyPi: https://pypi.org/project/wavaugmentate
GitHub: https://github.com/chetverovod/wavaugmentate
# Installation
```shell
pip install wavaugmentate
```
# Input Data
WAV-file or NumPy array.
```
Array shape: (num_channels, num_samples).
```
# Output Data
Same types as in section [Input_data](#Input_data).
# Augmentation Methods
1. Amplitude (volume change, inversion).
1. Time shift.
1. Echo.
1. Adding noise.
1. Time stretching. (**not implemented**)
1. Tempo change. (**not implemented**)
1. Pitch shift. (**not implemented**)
1. Adding silence.
1. Frequency masking. (**not implemented**)
1. Time masking. (**not implemented**)
1. Combinations of methods.
# Additional Functionality
1. Generation multichannel tonal signals of desired frequency, amplitude, durance.
2. Generation multichannel speech-like signals of desired formants frequency, amplitude, durance.
# Interfaces
Signal augmentation can be applied by two ways:
1. As python module *Mcs*, *Aug* classes methods.
2. As console application *wavaugmentate* with CLI interface options.
## Python Module
Example 1 (procedural approach):
```Python
from wavaugmentate.mcs import MultiChannelSignal as Mcs
from wavaugmentate.aug import SignalAugmentation as Aug
# File name of original sound.
file_name = "./outputwav/sound.wav"
# Create Mcs-object.
mcs = Mcs()
# Read WAV-file to Mcs-object.
mcs.read(file_name)
# Change quantity of channels to 7.
mcs.split(7)
# Create augmentation object.
aug = Aug(mcs)
# Apply delays.
# Corresponds to channels quantity.
delay_list = [0, 150, 200, 250, 300, 350, 400]
aug.delay_ctrl(delay_list)
# Apply amplitude changes.
# Corresponds to channels quantity.
amplitude_list = [1, 0.17, 0.2, 0.23, 0.3, 0.37, 0.4]
aug.amplitude_ctrl(amplitude_list)
# Augmentation result saving by single file, containing 7 channels.
aug.get().write(sound_aug_file_path)
# Augmentation result saving to 7 files, each 1 by channel.
# ./outputwav/sound_augmented_1.wav
# ./outputwav/sound_augmented_2.wav and so on.
aug.get().write_by_channel(sound_aug_file_path)
```
Original signal is shown on picture:
![Initial signal](./pictures/example_1_original_signal.png)
Output signal with augmented data (channel 1 contains original signal without changes):
![Augmented signal](./pictures/example_1_augmented_signal.png)
The same code as chain of operations, Example 2:
```Python
from wavaugmentate.mcs import MultiChannel as Mcs
from wavaugmentate.aug import SignalAugmentation as Aug
# File name of original sound.
file_name = "./outputwav/sound.wav"
delay_list = [0, 150, 200, 250, 300, 350, 400]
amplitude_list = [1, 0.17, 0.2, 0.23, 0.3, 0.37, 0.4]
# Apply all transformations of Example 1 in chain.
ao_obj = Aug(Mcs().rd(file_name))
ao_obj.splt(7).dly(delay_list).amp(amplitude_list).get().wr(
"sound_augmented_by_chain.wav"
)
# Augmentation result saving to 7 files, each 1 by channel.
ao_obj.get().wrbc("sound_augmented_by_chain.wav")
```
## CLI
use for help:
```
wavaug-cli -h
```
command line interface provides the same functionality.
Example 3 (procedural approach):
```shell
wavaug-cli -i ./test_sounds/test_sound_1.wav -o ./outputwav/out.wav -d "100, 200, 300, 400"
wavaug-cli -i ./outputwav/out.wav -o ./outputwav/out.wav -a "0.1, 0.2, 0.3, 0.4"
```
Example 4 (OOP approach):
```shell
wavaug-cli -c 'rd("./test_sounds/test_sound_1.wav").dly([100, 200, 300, 400]).amp([0.1, 0.2, 0.3, 0.4]).wr("./outputwav/sound_delayed.wav")'
```
## How To
### Single file to several augmented
Amplitudes and delays will be augmented by code shown in example 5.
Example 5 (single file augmentation):
```Python
from wavaugmentate.mcs import MultiChannel as Mcs
from wavaugmentate.aug import SignalAugmentation as Aug
file_name = "./outputwav/sound.wav"
mcs = Mcs()
mcs.rd(file_name) # Read original file with single channel.
file_name_head = "sound_augmented"
# Suppose we need 15 augmented files.
aug_count = 15
for i in range(aug_count):
signal = Aug(mcs.copy())
# Apply random amplitude [0.3..1.7) and delay [70..130)
# microseconds changes to each copy of original signal.
signal.amp([1], [0.7]).dly([100], [30])
name = file_name_head + f"_{i + 1}.wav"
signal.get().write(name)
```
# Unit Tests
Just run:
```shell
export PYTHONPATH='./src/wavaugmentate'
python3 -m pytest
```
Test coverage:
```
---------- coverage: platform linux, python 3.11.4-final-0 -----------
Name Stmts Miss Cover
----------------------------------------------
common_test_functions.py 15 0 100%
test_mcs_class.py 385 0 100%
test_wavaugmentate.py 293 0 100%
wavaugmentate.py 507 38 93%
----------------------------------------------
TOTAL 1200 38 97%
```
# Reference
MCS - multi channel signal, it is NumPy array with shape (M_channels, N_samples).
| #| *Mcs* class method | CLI option | Method alias | Description |
|--|------------------------|---------------------------------|-----------------|------------------------|
|1 | read(path) | -c 'rd(path)' | rd | Read MCS from WAV-file.|
|2 | write(path) | -c 'wr(path)' | wr | Save MCS to WAV-file. |
|3 | file_info(path) | --info | info | Returns WAV-file info. |
|4 | - | -i path | - | Input WAV-file path. |
|5 | - | -o path | - | Output WAV-file path. |
|6 | amplitude_ctrl([c1,c2..cm]) | -a "c1,c2..Cm" | amp | Change amplitudes of channels. |
|7 | delay_ctrl([t1,t2..tm]) | -d "t1,t2..tm" | dly | Add delays to channels. |
|8 | echo _ctrl([t1,t2..tm],[c1,c2..cm]) |-d "t1,t2..tm / c1,c2..Cm"| echo |Add echo to channels. |
|9 | noise_ctrl([c1,c2..cm]) | -n "c1,c2..Cm" | ns | Add normal noise to channels. |
|10| copy | - | cpy | Makes copy of MCS. |
|11| generate([f1,f2,f3..fm],duration,fs)|-| gen |Creates MCS and generates sine signal for each channel.|
|12| merge() | -| mrg | Merges all channels to single and returns mono MCS.|
|13| pause_detect(relative_level)|-| pdt | Searches pauses by selected levels. Returns array-mask.|
|14| pause_set(pause_map,pause_sz) | - | - | Set pauses length to selected values. Returns updated MCS.|
|15| rms() | - | rms | Returns list of RMS calculated for object channels.|
|16| side_by_side(mcs) | - | sbs | Appends channels from mcs data as new channels.|
|17| split(m_channels) | - | splt | Splits single channel to m_channels copies.|
|18| sum(mcs2) | - | sum | Adds mcs2 data channels values to object channels data sample by sample. |
|19| write_by_channel(path) | - | wrbc | Save MCS object channels to separate WAV-files. |
## Documentation
[Documentation on the Read the Docs](https://wavaugmentate.readthedocs.io/en/latest/)
For local documentation make clone of repository and look html-version of documentation (docs/_build/html/index.html):
[html-documentation](docs/_build/html/index.html)
### Rebuild Documentation
```shell
cd docs
make html
```
# Build Package
Install *builder*:
```shell
python3 -m pip install --upgrade build
```
build package:
```shell
python3 -m build
```
Raw data
{
"_id": null,
"home_page": null,
"name": "wavaugmentate",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Igor Plastov <chetverovod@gmail.com>",
"keywords": "augmentation, WAV, ML, DL, audio, sound",
"author": null,
"author_email": "Igor Plastov <chetverovod@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/45/01/56d77795ad2fc7bc2757c70ce1aa53884abb3f30121831be2cdd6e59f664/wavaugmentate-0.2.2.tar.gz",
"platform": null,
"description": "# **Wavaugmentate** 0.2.2\n**Multichannel Audio Signal Augmentation Module**\n\n![alt text](./pictures/title_image.png)\nThe module makes audio signal augmentation conversions. It provides the *MultiChannelSignal*, *SignalAugmentation* classes and *wavaug-cli* console utility.\n - *MultiChannalSignal* provides basic operations with multi-channel signals.\n - *SignalAugmentation* helps to perform augmentation of multi-channel signals for AI models learning purpose. \n\nPyPi: https://pypi.org/project/wavaugmentate\nGitHub: https://github.com/chetverovod/wavaugmentate\n\n# Installation\n```shell\npip install wavaugmentate\n```\n\n# Input Data\n\nWAV-file or NumPy array.\n```\nArray shape: (num_channels, num_samples).\n```\n# Output Data\nSame types as in section [Input_data](#Input_data).\n\n# Augmentation Methods \n1. Amplitude (volume change, inversion).\n1. Time shift.\n1. Echo.\n1. Adding noise.\n1. Time stretching. (**not implemented**)\n1. Tempo change. (**not implemented**)\n1. Pitch shift. (**not implemented**)\n1. Adding silence. \n1. Frequency masking. (**not implemented**)\n1. Time masking. (**not implemented**)\n1. Combinations of methods.\n\n# Additional Functionality\n1. Generation multichannel tonal signals of desired frequency, amplitude, durance.\n2. Generation multichannel speech-like signals of desired formants frequency, amplitude, durance.\n\n# Interfaces\nSignal augmentation can be applied by two ways:\n1. As python module *Mcs*, *Aug* classes methods.\n2. As console application *wavaugmentate* with CLI interface options.\n\n## Python Module\n\nExample 1 (procedural approach):\n```Python\nfrom wavaugmentate.mcs import MultiChannelSignal as Mcs\nfrom wavaugmentate.aug import SignalAugmentation as Aug\n\n\n# File name of original sound.\nfile_name = \"./outputwav/sound.wav\"\n\n# Create Mcs-object.\nmcs = Mcs()\n\n# Read WAV-file to Mcs-object.\nmcs.read(file_name)\n\n# Change quantity of channels to 7.\nmcs.split(7)\n\n# Create augmentation object.\naug = Aug(mcs)\n\n# Apply delays.\n# Corresponds to channels quantity.\ndelay_list = [0, 150, 200, 250, 300, 350, 400]\naug.delay_ctrl(delay_list)\n\n# Apply amplitude changes.\n# Corresponds to channels quantity.\namplitude_list = [1, 0.17, 0.2, 0.23, 0.3, 0.37, 0.4]\naug.amplitude_ctrl(amplitude_list)\n\n# Augmentation result saving by single file, containing 7 channels.\naug.get().write(sound_aug_file_path)\n\n# Augmentation result saving to 7 files, each 1 by channel.\n# ./outputwav/sound_augmented_1.wav\n# ./outputwav/sound_augmented_2.wav and so on.\naug.get().write_by_channel(sound_aug_file_path)\n\n```\nOriginal signal is shown on picture:\n![Initial signal](./pictures/example_1_original_signal.png)\n\nOutput signal with augmented data (channel 1 contains original signal without changes):\n![Augmented signal](./pictures/example_1_augmented_signal.png)\n\n\nThe same code as chain of operations, Example 2:\n\n```Python\n\nfrom wavaugmentate.mcs import MultiChannel as Mcs\nfrom wavaugmentate.aug import SignalAugmentation as Aug\n\n# File name of original sound.\nfile_name = \"./outputwav/sound.wav\"\n\ndelay_list = [0, 150, 200, 250, 300, 350, 400]\namplitude_list = [1, 0.17, 0.2, 0.23, 0.3, 0.37, 0.4]\n\n# Apply all transformations of Example 1 in chain.\nao_obj = Aug(Mcs().rd(file_name))\nao_obj.splt(7).dly(delay_list).amp(amplitude_list).get().wr(\n\"sound_augmented_by_chain.wav\"\n)\n\n# Augmentation result saving to 7 files, each 1 by channel.\nao_obj.get().wrbc(\"sound_augmented_by_chain.wav\")\n \n```\n## CLI\n\nuse for help:\n```\nwavaug-cli -h\n```\n\ncommand line interface provides the same functionality.\n\nExample 3 (procedural approach):\n```shell\nwavaug-cli -i ./test_sounds/test_sound_1.wav -o ./outputwav/out.wav -d \"100, 200, 300, 400\"\nwavaug-cli -i ./outputwav/out.wav -o ./outputwav/out.wav -a \"0.1, 0.2, 0.3, 0.4\"\n\n```\n\nExample 4 (OOP approach):\n```shell\nwavaug-cli -c 'rd(\"./test_sounds/test_sound_1.wav\").dly([100, 200, 300, 400]).amp([0.1, 0.2, 0.3, 0.4]).wr(\"./outputwav/sound_delayed.wav\")'\n\n```\n ## How To\n ### Single file to several augmented\n Amplitudes and delays will be augmented by code shown in example 5.\n\n Example 5 (single file augmentation):\n ```Python\nfrom wavaugmentate.mcs import MultiChannel as Mcs\nfrom wavaugmentate.aug import SignalAugmentation as Aug\n\nfile_name = \"./outputwav/sound.wav\"\nmcs = Mcs()\nmcs.rd(file_name) # Read original file with single channel.\nfile_name_head = \"sound_augmented\"\n\n# Suppose we need 15 augmented files.\naug_count = 15\nfor i in range(aug_count):\n signal = Aug(mcs.copy())\n # Apply random amplitude [0.3..1.7) and delay [70..130)\n # microseconds changes to each copy of original signal.\n signal.amp([1], [0.7]).dly([100], [30])\n name = file_name_head + f\"_{i + 1}.wav\"\n signal.get().write(name) \n```\n\n# Unit Tests\n\nJust run:\n```shell\nexport PYTHONPATH='./src/wavaugmentate'\npython3 -m pytest\n```\n\nTest coverage:\n```\n---------- coverage: platform linux, python 3.11.4-final-0 -----------\nName Stmts Miss Cover\n----------------------------------------------\ncommon_test_functions.py 15 0 100%\ntest_mcs_class.py 385 0 100%\ntest_wavaugmentate.py 293 0 100%\nwavaugmentate.py 507 38 93%\n----------------------------------------------\nTOTAL 1200 38 97%\n\n```\n\n# Reference\nMCS - multi channel signal, it is NumPy array with shape (M_channels, N_samples).\n| #| *Mcs* class method | CLI option | Method alias | Description |\n|--|------------------------|---------------------------------|-----------------|------------------------|\n|1 | read(path) | -c 'rd(path)' | rd | Read MCS from WAV-file.|\n|2 | write(path) | -c 'wr(path)' | wr | Save MCS to WAV-file. |\n|3 | file_info(path) | --info | info | Returns WAV-file info. |\n|4 | - | -i path | - | Input WAV-file path. |\n|5 | - | -o path | - | Output WAV-file path. |\n|6 | amplitude_ctrl([c1,c2..cm]) | -a \"c1,c2..Cm\" | amp | Change amplitudes of channels. |\n|7 | delay_ctrl([t1,t2..tm]) | -d \"t1,t2..tm\" | dly | Add delays to channels. |\n|8 | echo _ctrl([t1,t2..tm],[c1,c2..cm]) |-d \"t1,t2..tm / c1,c2..Cm\"| echo |Add echo to channels. |\n|9 | noise_ctrl([c1,c2..cm]) | -n \"c1,c2..Cm\" | ns | Add normal noise to channels. | \n|10| copy | - | cpy | Makes copy of MCS. |\n|11| generate([f1,f2,f3..fm],duration,fs)|-| gen |Creates MCS and generates sine signal for each channel.|\n|12| merge() | -| mrg | Merges all channels to single and returns mono MCS.|\n|13| pause_detect(relative_level)|-| pdt | Searches pauses by selected levels. Returns array-mask.|\n|14| pause_set(pause_map,pause_sz) | - | - | Set pauses length to selected values. Returns updated MCS.|\n|15| rms() | - | rms | Returns list of RMS calculated for object channels.|\n|16| side_by_side(mcs) | - | sbs | Appends channels from mcs data as new channels.| \n|17| split(m_channels) | - | splt | Splits single channel to m_channels copies.| \n|18| sum(mcs2) | - | sum | Adds mcs2 data channels values to object channels data sample by sample. | \n|19| write_by_channel(path) | - | wrbc | Save MCS object channels to separate WAV-files. |\n\n\n## Documentation\n\n[Documentation on the Read the Docs](https://wavaugmentate.readthedocs.io/en/latest/)\n\n\nFor local documentation make clone of repository and look html-version of documentation (docs/_build/html/index.html):\n[html-documentation](docs/_build/html/index.html)\n\n### Rebuild Documentation\n```shell\ncd docs\nmake html\n``` \n\n# Build Package \n\nInstall *builder*:\n\n```shell\npython3 -m pip install --upgrade build\n```\nbuild package:\n\n```shell\npython3 -m build\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "The package wavaugmentate makes audio signal augmentation conversions.",
"version": "0.2.2",
"project_urls": {
"Documentation": "https://wavaugmentate.readthedocs.io/en/latest/",
"Homepage": "https://github.com/chetverovod/wavaugmentate",
"Issues": "https://github.com/chetverovod/wavaugmentate/issues"
},
"split_keywords": [
"augmentation",
" wav",
" ml",
" dl",
" audio",
" sound"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "91c224aa2c5bbd2e7ec82739304d4cb5c39ee314ae3d4dc2b55bc4dc8aed0877",
"md5": "4a478382eb7578f8f95bc3251fc7cd4c",
"sha256": "e43eb7b178e980fb3ef2d1d5b848cc4d3ec5ecbca7550be01260711772befb27"
},
"downloads": -1,
"filename": "wavaugmentate-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4a478382eb7578f8f95bc3251fc7cd4c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 17659,
"upload_time": "2024-10-06T07:17:46",
"upload_time_iso_8601": "2024-10-06T07:17:46.213615Z",
"url": "https://files.pythonhosted.org/packages/91/c2/24aa2c5bbd2e7ec82739304d4cb5c39ee314ae3d4dc2b55bc4dc8aed0877/wavaugmentate-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "450156d77795ad2fc7bc2757c70ce1aa53884abb3f30121831be2cdd6e59f664",
"md5": "8ff55bd4df89a07ba583937ff2b812aa",
"sha256": "42cf0413d5f086194e384ac51aca50e9645c87f2d2a7e6663dbe926167d4daa9"
},
"downloads": -1,
"filename": "wavaugmentate-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "8ff55bd4df89a07ba583937ff2b812aa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 18136,
"upload_time": "2024-10-06T07:17:48",
"upload_time_iso_8601": "2024-10-06T07:17:48.005864Z",
"url": "https://files.pythonhosted.org/packages/45/01/56d77795ad2fc7bc2757c70ce1aa53884abb3f30121831be2cdd6e59f664/wavaugmentate-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-06 07:17:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chetverovod",
"github_project": "wavaugmentate",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "wavaugmentate"
}