scaper


Namescaper JSON
Version 1.6.4 PyPI version JSON
download
home_pagehttps://github.com/justinsalamon/scaper
SummaryA library for soundscape synthesis and augmentation
upload_time2020-09-28 22:07:03
maintainer
docs_urlNone
authorJustin Salamon & Duncan MacConnell
requires_python
licenseBSD-3-Clause
keywords audio sound soundscape environmental dsp mixing
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # scaper

<img src="http://www.justinsalamon.com/uploads/4/3/9/4/4394963/scaper-logo_orig.png" width="400" height="108">

A library for soundscape synthesis and augmentation

[![PyPI](https://img.shields.io/pypi/v/scaper.svg)](https://pypi.python.org/pypi/scaper)
[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
[![Build Status](https://travis-ci.org/justinsalamon/scaper.svg?branch=master)](https://travis-ci.org/justinsalamon/scaper)
[![Coverage Status](https://coveralls.io/repos/github/justinsalamon/scaper/badge.svg?branch=master)](https://coveralls.io/github/justinsalamon/scaper?branch=master)
[![Documentation Status](https://readthedocs.org/projects/scaper/badge/?version=latest)](http://scaper.readthedocs.io/en/latest/?badge=latest)
[![Downloads](https://pepy.tech/badge/scaper)](https://pepy.tech/project/scaper)
[![PyPI](https://img.shields.io/badge/python-2.7%2C%203.4%2C%203.5%2C%203.6-blue.svg)]()

Please refer to the [documentation](http://scaper.readthedocs.io/) for details.

For the motivation behind scaper and its applications check out the scaper-paper:

[Scaper: A library for soundscape synthesis and augmentation](http://www.justinsalamon.com/uploads/4/3/9/4/4394963/salamon_scaper_waspaa_2017.pdf)<br />
J. Salamon, D. MacConnell, M. Cartwright, P. Li, and J. P. Bello<br />
In IEEE Workshop on Applications of Signal Processing to Audio and Acoustics (WASPAA), New Paltz, NY, USA, Oct. 2017.

## Installation

### Non-python dependencies
Scaper has one non-python dependency:
- FFmpeg: https://ffmpeg.org/

If you are installing Scaper on Windows, you will also need:
- SoX: http://sox.sourceforge.net/

On Linux/macOS SoX is replaced by [SoxBindings](https://github.com/pseeth/soxbindings) which is significantly faster, giving better runtime performance in Scaper. On these platforms SoxBindings is installed automatically when calling `pip install scaper` (see below).

#### Linux/macOS
If you're using [Anaconda](https://www.anaconda.com/distribution/) (or [miniconda](https://docs.conda.io/en/latest/miniconda.html)) to manage your python environment (recommended), you can install FFmpeg using `conda` on macOS/Linux:

```
conda install -c conda-forge ffmpeg
```

#### macOS
On macOS FFmpeg can be installed using [homebrew](https://brew.sh/):

```
brew install ffmpeg
```

#### Linux
On linux you can use your distribution's package manager, e.g. on Ubuntu (15.04 "Vivid Vervet" or newer):

```
sudo apt-get install ffmpeg
```
NOTE: on earlier versions of Ubuntu [ffmpeg may point to a Libav binary](http://stackoverflow.com/a/9477756/2007700) which is not the correct binary. If you are using Anaconda, you can install the correct version as described earlier by calling `conda install -c conda-forge ffmpeg`. Otherwise, you can [obtain a static binary from the ffmpeg website](https://ffmpeg.org/download.html).

#### Windows
On windows you can use the provided installation binaries:
- SoX: https://sourceforge.net/projects/sox/files/sox/
- FFmpeg: https://ffmpeg.org/download.html#build-windows

### Installing Scaper

The simplest way to install scaper is by using `pip`, which will also install the required python dependencies if needed. To install scaper using pip, simply run:

```
pip install scaper
```

To install the latest version of scaper from source, clone or pull the lastest version:

```
git clone git@github.com:justinsalamon/scaper.git
```

Then enter the source folder and install using pip to handle python dependencies:

```
cd scaper
pip install -e .
```
## Tutorial

To help you get started with scaper, please see this [step-by-step tutorial](http://scaper.readthedocs.io/en/latest/tutorial.html).

## Example

```python
import scaper
import numpy as np

# OUTPUT FOLDER
outfolder = 'audio/soundscapes/'

# SCAPER SETTINGS
fg_folder = 'audio/soundbank/foreground/'
bg_folder = 'audio/soundbank/background/'

n_soundscapes = 1000
ref_db = -50
duration = 10.0 

min_events = 1
max_events = 9

event_time_dist = 'truncnorm'
event_time_mean = 5.0
event_time_std = 2.0
event_time_min = 0.0
event_time_max = 10.0

source_time_dist = 'const'
source_time = 0.0

event_duration_dist = 'uniform'
event_duration_min = 0.5
event_duration_max = 4.0

snr_dist = 'uniform'
snr_min = 6
snr_max = 30

pitch_dist = 'uniform'
pitch_min = -3.0
pitch_max = 3.0

time_stretch_dist = 'uniform'
time_stretch_min = 0.8
time_stretch_max = 1.2

# Generate 1000 soundscapes using a truncated normal distribution of start times

for n in range(n_soundscapes):

    print('Generating soundscape: {:d}/{:d}'.format(n+1, n_soundscapes))

    # create a scaper
    sc = scaper.Scaper(duration, fg_folder, bg_folder)
    sc.protected_labels = []
    sc.ref_db = ref_db

    # add background
    sc.add_background(label=('const', 'noise'), 
                      source_file=('choose', []), 
                      source_time=('const', 0))

    # add random number of foreground events
    n_events = np.random.randint(min_events, max_events+1)
    for _ in range(n_events):
        sc.add_event(label=('choose', []), 
                     source_file=('choose', []), 
                     source_time=(source_time_dist, source_time), 
                     event_time=(event_time_dist, event_time_mean, event_time_std, event_time_min, event_time_max), 
                     event_duration=(event_duration_dist, event_duration_min, event_duration_max), 
                     snr=(snr_dist, snr_min, snr_max),
                     pitch_shift=(pitch_dist, pitch_min, pitch_max),
                     time_stretch=(time_stretch_dist, time_stretch_min, time_stretch_max))

    # generate
    audiofile = os.path.join(outfolder, "soundscape_unimodal{:d}.wav".format(n))
    jamsfile = os.path.join(outfolder, "soundscape_unimodal{:d}.jams".format(n))
    txtfile = os.path.join(outfolder, "soundscape_unimodal{:d}.txt".format(n))

    sc.generate(audiofile, jamsfile,
                allow_repeated_label=True,
                allow_repeated_source=False,
                reverb=0.1,
                disable_sox_warnings=True,
                no_audio=False,
                txt_path=txtfile)
```

## How to contribute

If you would like to contribute a feature and/or bugfix to this repository, please follow the following steps:

1. Create an issue describing the feature/fix.
2. I will reply on the issue thread to determine whether the feature/fix can/should be added.
3. Discuss design/implementation details in the issue thread and reach consensus.
4. Once consensus is reached (and only then), start a pull request (PR). Further discsussion can continue in the PR thread.
5. Implement feature/fix, ensuring all current unit tests pass and new tests are added to maintain 100% test coverage. Inline docstrings as well as the main docs files should also be updated accordingly.
6. Request code review once the pull request is ready for review.
7. Fix requested changes to the pull request if any. Repeat steps 5-7 until the PR is approved.
8. once the PR is approved I will merge it into master (and most likely create a new release).

IMPORTANT: please be sure to always discuss a proposed feature/fix in an issue before creating a pull request.



            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/justinsalamon/scaper",
    "name": "scaper",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "audio sound soundscape environmental dsp mixing",
    "author": "Justin Salamon & Duncan MacConnell",
    "author_email": "justin.salamon@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/f2/6e/c440455291e743d36c03f52abfc065e97d92b132b7d909870f9ab6bbe83e/scaper-1.6.4.tar.gz",
    "platform": "",
    "description": "# scaper\n\n<img src=\"http://www.justinsalamon.com/uploads/4/3/9/4/4394963/scaper-logo_orig.png\" width=\"400\" height=\"108\">\n\nA library for soundscape synthesis and augmentation\n\n[![PyPI](https://img.shields.io/pypi/v/scaper.svg)](https://pypi.python.org/pypi/scaper)\n[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)\n[![Build Status](https://travis-ci.org/justinsalamon/scaper.svg?branch=master)](https://travis-ci.org/justinsalamon/scaper)\n[![Coverage Status](https://coveralls.io/repos/github/justinsalamon/scaper/badge.svg?branch=master)](https://coveralls.io/github/justinsalamon/scaper?branch=master)\n[![Documentation Status](https://readthedocs.org/projects/scaper/badge/?version=latest)](http://scaper.readthedocs.io/en/latest/?badge=latest)\n[![Downloads](https://pepy.tech/badge/scaper)](https://pepy.tech/project/scaper)\n[![PyPI](https://img.shields.io/badge/python-2.7%2C%203.4%2C%203.5%2C%203.6-blue.svg)]()\n\nPlease refer to the [documentation](http://scaper.readthedocs.io/) for details.\n\nFor the motivation behind scaper and its applications check out the scaper-paper:\n\n[Scaper: A library for soundscape synthesis and augmentation](http://www.justinsalamon.com/uploads/4/3/9/4/4394963/salamon_scaper_waspaa_2017.pdf)<br />\nJ. Salamon, D. MacConnell, M. Cartwright, P. Li, and J. P. Bello<br />\nIn IEEE Workshop on Applications of Signal Processing to Audio and Acoustics (WASPAA), New Paltz, NY, USA, Oct. 2017.\n\n## Installation\n\n### Non-python dependencies\nScaper has one non-python dependency:\n- FFmpeg: https://ffmpeg.org/\n\nIf you are installing Scaper on Windows, you will also need:\n- SoX: http://sox.sourceforge.net/\n\nOn Linux/macOS SoX is replaced by [SoxBindings](https://github.com/pseeth/soxbindings) which is significantly faster, giving better runtime performance in Scaper. On these platforms SoxBindings is installed automatically when calling `pip install scaper` (see below).\n\n#### Linux/macOS\nIf you're using [Anaconda](https://www.anaconda.com/distribution/) (or [miniconda](https://docs.conda.io/en/latest/miniconda.html)) to manage your python environment (recommended), you can install FFmpeg using `conda` on macOS/Linux:\n\n```\nconda install -c conda-forge ffmpeg\n```\n\n#### macOS\nOn macOS FFmpeg can be installed using [homebrew](https://brew.sh/):\n\n```\nbrew install ffmpeg\n```\n\n#### Linux\nOn linux you can use your distribution's package manager, e.g. on Ubuntu (15.04 \"Vivid Vervet\" or newer):\n\n```\nsudo apt-get install ffmpeg\n```\nNOTE: on earlier versions of Ubuntu [ffmpeg may point to a Libav binary](http://stackoverflow.com/a/9477756/2007700) which is not the correct binary. If you are using Anaconda, you can install the correct version as described earlier by calling `conda install -c conda-forge ffmpeg`. Otherwise, you can [obtain a static binary from the ffmpeg website](https://ffmpeg.org/download.html).\n\n#### Windows\nOn windows you can use the provided installation binaries:\n- SoX: https://sourceforge.net/projects/sox/files/sox/\n- FFmpeg: https://ffmpeg.org/download.html#build-windows\n\n### Installing Scaper\n\nThe simplest way to install scaper is by using `pip`, which will also install the required python dependencies if needed. To install scaper using pip, simply run:\n\n```\npip install scaper\n```\n\nTo install the latest version of scaper from source, clone or pull the lastest version:\n\n```\ngit clone git@github.com:justinsalamon/scaper.git\n```\n\nThen enter the source folder and install using pip to handle python dependencies:\n\n```\ncd scaper\npip install -e .\n```\n## Tutorial\n\nTo help you get started with scaper, please see this [step-by-step tutorial](http://scaper.readthedocs.io/en/latest/tutorial.html).\n\n## Example\n\n```python\nimport scaper\nimport numpy as np\n\n# OUTPUT FOLDER\noutfolder = 'audio/soundscapes/'\n\n# SCAPER SETTINGS\nfg_folder = 'audio/soundbank/foreground/'\nbg_folder = 'audio/soundbank/background/'\n\nn_soundscapes = 1000\nref_db = -50\nduration = 10.0 \n\nmin_events = 1\nmax_events = 9\n\nevent_time_dist = 'truncnorm'\nevent_time_mean = 5.0\nevent_time_std = 2.0\nevent_time_min = 0.0\nevent_time_max = 10.0\n\nsource_time_dist = 'const'\nsource_time = 0.0\n\nevent_duration_dist = 'uniform'\nevent_duration_min = 0.5\nevent_duration_max = 4.0\n\nsnr_dist = 'uniform'\nsnr_min = 6\nsnr_max = 30\n\npitch_dist = 'uniform'\npitch_min = -3.0\npitch_max = 3.0\n\ntime_stretch_dist = 'uniform'\ntime_stretch_min = 0.8\ntime_stretch_max = 1.2\n\n# Generate 1000 soundscapes using a truncated normal distribution of start times\n\nfor n in range(n_soundscapes):\n\n    print('Generating soundscape: {:d}/{:d}'.format(n+1, n_soundscapes))\n\n    # create a scaper\n    sc = scaper.Scaper(duration, fg_folder, bg_folder)\n    sc.protected_labels = []\n    sc.ref_db = ref_db\n\n    # add background\n    sc.add_background(label=('const', 'noise'), \n                      source_file=('choose', []), \n                      source_time=('const', 0))\n\n    # add random number of foreground events\n    n_events = np.random.randint(min_events, max_events+1)\n    for _ in range(n_events):\n        sc.add_event(label=('choose', []), \n                     source_file=('choose', []), \n                     source_time=(source_time_dist, source_time), \n                     event_time=(event_time_dist, event_time_mean, event_time_std, event_time_min, event_time_max), \n                     event_duration=(event_duration_dist, event_duration_min, event_duration_max), \n                     snr=(snr_dist, snr_min, snr_max),\n                     pitch_shift=(pitch_dist, pitch_min, pitch_max),\n                     time_stretch=(time_stretch_dist, time_stretch_min, time_stretch_max))\n\n    # generate\n    audiofile = os.path.join(outfolder, \"soundscape_unimodal{:d}.wav\".format(n))\n    jamsfile = os.path.join(outfolder, \"soundscape_unimodal{:d}.jams\".format(n))\n    txtfile = os.path.join(outfolder, \"soundscape_unimodal{:d}.txt\".format(n))\n\n    sc.generate(audiofile, jamsfile,\n                allow_repeated_label=True,\n                allow_repeated_source=False,\n                reverb=0.1,\n                disable_sox_warnings=True,\n                no_audio=False,\n                txt_path=txtfile)\n```\n\n## How to contribute\n\nIf you would like to contribute a feature and/or bugfix to this repository, please follow the following steps:\n\n1. Create an issue describing the feature/fix.\n2. I will reply on the issue thread to determine whether the feature/fix can/should be added.\n3. Discuss design/implementation details in the issue thread and reach consensus.\n4. Once consensus is reached (and only then), start a pull request (PR). Further discsussion can continue in the PR thread.\n5. Implement feature/fix, ensuring all current unit tests pass and new tests are added to maintain 100% test coverage. Inline docstrings as well as the main docs files should also be updated accordingly.\n6. Request code review once the pull request is ready for review.\n7. Fix requested changes to the pull request if any. Repeat steps 5-7 until the PR is approved.\n8. once the PR is approved I will merge it into master (and most likely create a new release).\n\nIMPORTANT: please be sure to always discuss a proposed feature/fix in an issue before creating a pull request.\n\n\n",
    "bugtrack_url": null,
    "license": "BSD-3-Clause",
    "summary": "A library for soundscape synthesis and augmentation",
    "version": "1.6.4",
    "split_keywords": [
        "audio",
        "sound",
        "soundscape",
        "environmental",
        "dsp",
        "mixing"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "bd056bdc0cd0e62901d5ca11cd7e0e34",
                "sha256": "67803ada8c7e8ca1221313380be07a8d4ed1834cc3326c6ccbfd0ee6356f636a"
            },
            "downloads": -1,
            "filename": "scaper-1.6.4-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "bd056bdc0cd0e62901d5ca11cd7e0e34",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": null,
            "size": 31359,
            "upload_time": "2020-09-28T22:07:01",
            "upload_time_iso_8601": "2020-09-28T22:07:01.585382Z",
            "url": "https://files.pythonhosted.org/packages/0e/b9/cae01917ecd726c0aaeee2e73472083bcb24ee7c597cc5c36a6d11e63889/scaper-1.6.4-py2.py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "adb938eb472dc7e05b0f450f275ecc65",
                "sha256": "3125dda555e7f8a1523c3ac5199664f0f51f91b5810325bd9cb523976aae2a46"
            },
            "downloads": -1,
            "filename": "scaper-1.6.4.tar.gz",
            "has_sig": false,
            "md5_digest": "adb938eb472dc7e05b0f450f275ecc65",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 29759,
            "upload_time": "2020-09-28T22:07:03",
            "upload_time_iso_8601": "2020-09-28T22:07:03.245023Z",
            "url": "https://files.pythonhosted.org/packages/f2/6e/c440455291e743d36c03f52abfc065e97d92b132b7d909870f9ab6bbe83e/scaper-1.6.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2020-09-28 22:07:03",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": null,
    "github_project": "justinsalamon",
    "error": "Could not fetch GitHub repository",
    "lcname": "scaper"
}
        
Elapsed time: 0.15174s