| Name | audiostretchy JSON |
| Version |
1.3.5
JSON |
| download |
| home_page | https://github.com/twardoch/audiostretchy |
| Summary | AudioStretchy is a Python library and CLI tool that which performs fast, high-quality time-stretching of WAV/MP3 files without changing their pitch. Works well for speech, can time-stretch silence separately. AudioStretchy is a wrapper around the audio-stretch C library by David Bryant. |
| upload_time | 2023-07-06 12:15:44 |
| maintainer | |
| docs_url | None |
| author | Adam Twardoch |
| requires_python | >=3.8 |
| license | BSD-3-Clause |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
# AudioStretchy
AudioStretchy is a Python library and CLI tool that which performs fast, high-quality time-stretching of WAV/MP3 files without changing their pitch. Works well for speech, can time-stretch silence separately. The library is a wrapper around David Bryant’s [audio-stretch](https://github.com/dbry/audio-stretch) C library.
_Version: 1.3.5_
## Features
- Fast, high-quality time stretching of audio files without changing their pitch
- Adjustable stretching ratio from 0.25 to 4.0
- Cross-platform: Windows, macOS, and Linux
- Supports WAV files and file-like objects. With `[all]` installation, also supports MP3 files and file-like objects
- With `[all]` installation, also supports resampling
**Time-domain harmonic scaling (TDHS)** is a method for time-scale modification of speech (or other audio signals), allowing the apparent rate of speech articulation to be changed without affecting the pitch-contour and the time-evolution of the formant structure. TDHS differs from other time-scale modification algorithms in that time-scaling operations are performed in the time domain (not the frequency domain).
The core functionality of this package is provided by David Bryant’s excellent [audio-stretch C library](https://github.com/dbry/audio-stretch) that performs fast, high-quality TDHS on WAV in the ratio range of 0.25 (4× slower) to 4.0 (4× faster).
The library gives very good results with speech recordings, especially with modest stretching at the ratio between 0.9 (10% slower) and 1.1 (10% faster). AudioStretchy is a Python wrapper around that library. The Python package also offers some additional, optional functionality: supports MP3 (in addition to WAV), and allows you to preform resampling.
## Demo
Below are links to a short audio file (as WAV and MP3), with the same file stretched at 1.2 (20% slower):
| Input | Stretched |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| [`audio.wav`](https://github.com/twardoch/audiostretchy/raw/main/tests/audio.wav) | [`audio-1.2.wav`](https://github.com/twardoch/audiostretchy/raw/main/tests/audio-1.2.wav) |
| [`audio.mp3`](https://github.com/twardoch/audiostretchy/raw/main/tests/audio.mp3) | [`audio-1.2.mp3`](https://github.com/twardoch/audiostretchy/raw/main/tests/audio-1.2.mp3) |
## Installation
### Full installation
To be able to **stretch** and **resample** both **WAV** and **MP3** files, install AudioStretchy using `pip` like so:
```
python3 -m pip install audiostretchy[all]
```
This installs the package and the pre-compiled `audio-stretch` libraries for macOS, Windows and Linux.
This also installs optional dependencies:
- for MP3 support: [pydub](https://pypi.org/project/pydub/) on macOS, [pymp3](https://pypi.org/project/pymp3/) on Linux and Windows
- for resampling: [soxr](https://pypi.org/project/soxr/)
On macOS, you also need to install [HomeBrew](https://brew.sh/) and then in Terminal run:
```bash
brew install ffmpeg
```
### Minimal installation
To only be able to **stretch** **WAV** files (no resampling, no MP3 support), install AudioStretchy with minimal dependencies like so:
```
python3 -m pip install audiostretchy
```
This only installs the package and the pre-compiled `audio-stretch` libraries for macOS, Windows and Linux.
### Full development installation
To install the development version, use:
```
python3 -m pip install git+https://github.com/twardoch/audiostretchy#egg=audiostretchy[all]
```
## Usage
### CLI
```
audiostretchy INPUT_WAV OUTPUT_WAV <flags>
POSITIONAL ARGUMENTS
INPUT_PATH
The path to the input WAV or MP3 audio file.
OUTPUT_PATH
The path to save the stretched WAV or MP3 audio file.
FLAGS
-r, --ratio=RATIO
The stretch ratio, where values greater than 1.0 will extend the audio and
values less than 1.0 will shorten the audio. From 0.5 to 2.0, or with `-d`
from 0.25 to 4.0. Default is 1.0 = no stretching.
-g, --gap_ratio=GAP_RATIO
The stretch ratio for gaps (silence) in the audio.
Default is 0.0 = uses ratio.
-u, --upper_freq=UPPER_FREQ
The upper frequency limit for period detection in Hz. Default is 333 Hz.
-l, --lower_freq=LOWER_FREQ
The lower frequency limit. Default is 55 Hz.
-b, --buffer_ms=BUFFER_MS
The buffer size in milliseconds for processing the audio in chunks
(useful with `-g`). Default is 25 ms.
-t, --threshold_gap_db=THRESHOLD_GAP_DB
The threshold level in dB to determine if a section of audio is considered
a gap (for `-g`). Default is -40 dB.
-d, --double_range=DOUBLE_RANGE
If set, doubles the min/max range of stretching.
-f, --fast_detection=FAST_DETECTION
If set, enables fast period detection, which may speed up processing but
reduce the quality of the stretched audio.
-n, --normal_detection=NORMAL_DETECTION
If set, forces the algorithm to use normal period detection instead
of fast period detection.
-s, --sample_rate=SAMPLE_RATE
The target sample rate for resampling the stretched audio in Hz (if installed
with `[all]`). Default is 0 = use sample rate of the input audio.
```
### Python
```python
from audiostretchy.stretch import stretch_audio
stretch_audio("input.wav", "output.wav", ratio=1.1)
```
In this example, the `input.wav` file will be time-stretched by a factor of 1.1, meaning it will be 10% longer, and the result will be saved in the `output.wav` file.
For advanced usage, you can use the `AudioStretch` class that lets you open and save files provided as paths or as file-like BytesIO objects:
```python
from audiostretchy.stretch import AudioStretch
audio_stretch = AudioStretch()
# This needs [all] installation for MP3 support
audio_stretch.open(file=MP3DataAsBytesIO, format="mp3")
audio_stretch.stretch(
ratio=1.1,
gap_ratio=1.2,
upper_freq=333,
lower_freq=55,
buffer_ms=25,
threshold_gap_db=-40,
dual_force=False,
fast_detection=False,
normal_detection=False,
)
# This needs [all] installation for soxr support
audio_stretch.resample(sample_rate=44100)
audio_stretch.save(file=WAVDataAsBytesIO, format="wav")
```
## Changelog
- v1.3.5: fix for MP3 writing
- v1.3.2: fix for MP3 opening
- v1.3.0: actually working on Windows as well
- v1.2.x: working on macOS and Linux
## License
- [Original C library code](https://github.com/dbry/audio-stretch): Copyright (c) 2022 David Bryant
- [Python code](https://github.com/twardoch/audiostretchy): Copyright (c) 2023 Adam Twardoch
- Python code written with assistance from GPT-4
- Licensed under the [BSD-3-Clause license](./LICENSE.txt)
Raw data
{
"_id": null,
"home_page": "https://github.com/twardoch/audiostretchy",
"name": "audiostretchy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Adam Twardoch",
"author_email": "adam+github@twardoch.com",
"download_url": "https://files.pythonhosted.org/packages/6b/cc/cf145bc1ddf186fa48cd3e66829be11dfe7c3a7b7e07e8d3bad0b7dd8136/audiostretchy-1.3.5.tar.gz",
"platform": "any",
"description": "# AudioStretchy\n\nAudioStretchy is a Python library and CLI tool that which performs fast, high-quality time-stretching of WAV/MP3 files without changing their pitch. Works well for speech, can time-stretch silence separately. The library is a wrapper around David Bryant\u2019s [audio-stretch](https://github.com/dbry/audio-stretch) C library. \n\n_Version: 1.3.5_\n\n## Features\n\n- Fast, high-quality time stretching of audio files without changing their pitch\n- Adjustable stretching ratio from 0.25 to 4.0\n- Cross-platform: Windows, macOS, and Linux\n- Supports WAV files and file-like objects. With `[all]` installation, also supports MP3 files and file-like objects\n- With `[all]` installation, also supports resampling\n\n**Time-domain harmonic scaling (TDHS)** is a method for time-scale modification of speech (or other audio signals), allowing the apparent rate of speech articulation to be changed without affecting the pitch-contour and the time-evolution of the formant structure. TDHS differs from other time-scale modification algorithms in that time-scaling operations are performed in the time domain (not the frequency domain).\n\nThe core functionality of this package is provided by David Bryant\u2019s excellent [audio-stretch C library](https://github.com/dbry/audio-stretch) that performs fast, high-quality TDHS on WAV in the ratio range of 0.25 (4\u00d7 slower) to 4.0 (4\u00d7 faster). \n\nThe library gives very good results with speech recordings, especially with modest stretching at the ratio between 0.9 (10% slower) and 1.1 (10% faster). AudioStretchy is a Python wrapper around that library. The Python package also offers some additional, optional functionality: supports MP3 (in addition to WAV), and allows you to preform resampling.\n\n## Demo\n\nBelow are links to a short audio file (as WAV and MP3), with the same file stretched at 1.2 (20% slower):\n\n| Input | Stretched |\n| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |\n| [`audio.wav`](https://github.com/twardoch/audiostretchy/raw/main/tests/audio.wav) | [`audio-1.2.wav`](https://github.com/twardoch/audiostretchy/raw/main/tests/audio-1.2.wav) |\n| [`audio.mp3`](https://github.com/twardoch/audiostretchy/raw/main/tests/audio.mp3) | [`audio-1.2.mp3`](https://github.com/twardoch/audiostretchy/raw/main/tests/audio-1.2.mp3) |\n\n\n## Installation\n\n### Full installation\n\nTo be able to **stretch** and **resample** both **WAV** and **MP3** files, install AudioStretchy using `pip` like so:\n\n```\npython3 -m pip install audiostretchy[all]\n```\n\nThis installs the package and the pre-compiled `audio-stretch` libraries for macOS, Windows and Linux. \n\nThis also installs optional dependencies: \n\n- for MP3 support: [pydub](https://pypi.org/project/pydub/) on macOS, [pymp3](https://pypi.org/project/pymp3/) on Linux and Windows\n- for resampling: [soxr](https://pypi.org/project/soxr/)\n\nOn macOS, you also need to install [HomeBrew](https://brew.sh/) and then in Terminal run: \n\n```bash\nbrew install ffmpeg\n```\n\n### Minimal installation\n\nTo only be able to **stretch** **WAV** files (no resampling, no MP3 support), install AudioStretchy with minimal dependencies like so: \n\n```\npython3 -m pip install audiostretchy\n```\n\nThis only installs the package and the pre-compiled `audio-stretch` libraries for macOS, Windows and Linux. \n\n### Full development installation\n\nTo install the development version, use:\n\n```\npython3 -m pip install git+https://github.com/twardoch/audiostretchy#egg=audiostretchy[all]\n```\n\n## Usage\n\n### CLI\n\n```\naudiostretchy INPUT_WAV OUTPUT_WAV <flags>\n\nPOSITIONAL ARGUMENTS\n INPUT_PATH\n The path to the input WAV or MP3 audio file.\n OUTPUT_PATH\n The path to save the stretched WAV or MP3 audio file.\n\nFLAGS\n -r, --ratio=RATIO\n The stretch ratio, where values greater than 1.0 will extend the audio and \n values less than 1.0 will shorten the audio. From 0.5 to 2.0, or with `-d` \n from 0.25 to 4.0. Default is 1.0 = no stretching.\n -g, --gap_ratio=GAP_RATIO\n The stretch ratio for gaps (silence) in the audio. \n Default is 0.0 = uses ratio.\n -u, --upper_freq=UPPER_FREQ\n The upper frequency limit for period detection in Hz. Default is 333 Hz.\n -l, --lower_freq=LOWER_FREQ\n The lower frequency limit. Default is 55 Hz.\n -b, --buffer_ms=BUFFER_MS\n The buffer size in milliseconds for processing the audio in chunks \n (useful with `-g`). Default is 25 ms.\n -t, --threshold_gap_db=THRESHOLD_GAP_DB\n The threshold level in dB to determine if a section of audio is considered \n a gap (for `-g`). Default is -40 dB.\n -d, --double_range=DOUBLE_RANGE\n If set, doubles the min/max range of stretching.\n -f, --fast_detection=FAST_DETECTION\n If set, enables fast period detection, which may speed up processing but \n reduce the quality of the stretched audio.\n -n, --normal_detection=NORMAL_DETECTION\n If set, forces the algorithm to use normal period detection instead \n of fast period detection.\n -s, --sample_rate=SAMPLE_RATE\n The target sample rate for resampling the stretched audio in Hz (if installed \n with `[all]`). Default is 0 = use sample rate of the input audio.\n```\n\n### Python\n\n```python\nfrom audiostretchy.stretch import stretch_audio\n\nstretch_audio(\"input.wav\", \"output.wav\", ratio=1.1)\n```\n\nIn this example, the `input.wav` file will be time-stretched by a factor of 1.1, meaning it will be 10% longer, and the result will be saved in the `output.wav` file.\n\nFor advanced usage, you can use the `AudioStretch` class that lets you open and save files provided as paths or as file-like BytesIO objects: \n\n```python\nfrom audiostretchy.stretch import AudioStretch\n\naudio_stretch = AudioStretch()\n# This needs [all] installation for MP3 support\naudio_stretch.open(file=MP3DataAsBytesIO, format=\"mp3\") \naudio_stretch.stretch(\n ratio=1.1,\n gap_ratio=1.2,\n upper_freq=333,\n lower_freq=55,\n buffer_ms=25,\n threshold_gap_db=-40,\n dual_force=False,\n fast_detection=False,\n normal_detection=False,\n)\n# This needs [all] installation for soxr support\naudio_stretch.resample(sample_rate=44100) \naudio_stretch.save(file=WAVDataAsBytesIO, format=\"wav\")\n```\n\n## Changelog\n\n- v1.3.5: fix for MP3 writing\n- v1.3.2: fix for MP3 opening\n- v1.3.0: actually working on Windows as well\n- v1.2.x: working on macOS and Linux\n\n## License\n\n- [Original C library code](https://github.com/dbry/audio-stretch): Copyright (c) 2022 David Bryant\n- [Python code](https://github.com/twardoch/audiostretchy): Copyright (c) 2023 Adam Twardoch\n- Python code written with assistance from GPT-4\n- Licensed under the [BSD-3-Clause license](./LICENSE.txt)\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "AudioStretchy is a Python library and CLI tool that which performs fast, high-quality time-stretching of WAV/MP3 files without changing their pitch. Works well for speech, can time-stretch silence separately. AudioStretchy is a wrapper around the audio-stretch C library by David Bryant.",
"version": "1.3.5",
"project_urls": {
"Documentation": "https://pyscaffold.org/",
"Homepage": "https://github.com/twardoch/audiostretchy"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7546f59c8ff4d5d2953deafe067be0c6e807f8c181f1226f60a948eb45f7cd4e",
"md5": "9a8d25086b0bbd43528a774960825583",
"sha256": "17f65d4e5e8f08c75d3add851edca5751a3925d7b46b92e65d81842d4bf10dc9"
},
"downloads": -1,
"filename": "audiostretchy-1.3.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9a8d25086b0bbd43528a774960825583",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 105495,
"upload_time": "2023-07-06T12:15:43",
"upload_time_iso_8601": "2023-07-06T12:15:43.117378Z",
"url": "https://files.pythonhosted.org/packages/75/46/f59c8ff4d5d2953deafe067be0c6e807f8c181f1226f60a948eb45f7cd4e/audiostretchy-1.3.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6bcccf145bc1ddf186fa48cd3e66829be11dfe7c3a7b7e07e8d3bad0b7dd8136",
"md5": "8e90315790ef469652c9850e064e46d9",
"sha256": "54a4d593304bd21bbd15c90b131cb134a1cef8153862f8a3af505e8be9c9fc01"
},
"downloads": -1,
"filename": "audiostretchy-1.3.5.tar.gz",
"has_sig": false,
"md5_digest": "8e90315790ef469652c9850e064e46d9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 1778880,
"upload_time": "2023-07-06T12:15:44",
"upload_time_iso_8601": "2023-07-06T12:15:44.470751Z",
"url": "https://files.pythonhosted.org/packages/6b/cc/cf145bc1ddf186fa48cd3e66829be11dfe7c3a7b7e07e8d3bad0b7dd8136/audiostretchy-1.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-06 12:15:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "twardoch",
"github_project": "audiostretchy",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "audiostretchy"
}
