wavaugmentate


Namewavaugmentate JSON
Version 0.2.2 PyPI version JSON
download
home_pageNone
SummaryThe package wavaugmentate makes audio signal augmentation conversions.
upload_time2024-10-06 07:17:48
maintainerNone
docs_urlNone
authorNone
requires_python>=3.9
licenseNone
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"
}
        
Elapsed time: 4.72759s