Metadata-Version: 2.4
Name: torchscriptworld
Version: 0.1.0
Summary: PyTorch / TorchScript WORLD vocoder (batched float32)
Author: Doaz
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/aqtq314/TorchScriptWORLD
Project-URL: Repository, https://github.com/aqtq314/TorchScriptWORLD
Project-URL: Issues, https://github.com/aqtq314/TorchScriptWORLD/issues
Keywords: vocoder,speech,pytorch,torchscript,world
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.1
Provides-Extra: qa
Requires-Dist: numpy; extra == "qa"
Requires-Dist: soundfile; extra == "qa"
Requires-Dist: pyworld; extra == "qa"
Requires-Dist: pytest; extra == "qa"
Requires-Dist: matplotlib; extra == "qa"
Provides-Extra: demo
Requires-Dist: numpy; extra == "demo"
Requires-Dist: soundfile; extra == "demo"
Dynamic: license-file

# TorchScriptWORLD - WORLD Vocoder in PyTorch and TorchScript

This repository contains a batched PyTorch port of the [WORLD vocoder](https://github.com/mmorise/World) optimized for parallel GPU computation under float32 precision. TorchScript export is also supported so that the model can be used in any TorchScript runtime (e.g., C++, .NET, Rust, Java, etc.).

The public function API's generally follow [pyworld](https://github.com/JeremyCCHsu/Python-Wrapper-for-World-Vocoder):

```python
import torch
import torchscriptworld as tsw

x = torch.randn(1, 16000)  # (batch, samples)
fs = 16000
f0, t = tsw.dio(x, fs)
f0 = tsw.stonemask(x, f0, t, fs)
# or: f0, t = tsw.harvest(x, fs)
sp = tsw.cheaptrick(x, f0, t, fs)
ap = tsw.d4c(x, f0, t, fs)
y = tsw.synthesize(f0, sp, ap, fs)

# or
f0, sp, ap = tsw.wav2world(x, fs)
```

Tensors must be batched: `(batch_size, num_samples)` / `(batch_size, num_frames, num_freqs)`. 1-D tensors are not supported.

## Install

```bash
pip install torchscriptworld
```

The only runtime dependency of the library itself is **PyTorch 2.1+**. This tree is developed and TorchScript-exported with **PyTorch 2.11**.

## Runtime Speed Overview

On a 24 s / 44.1 kHz clip, a scripted `WORLD` archive on CUDA is typically **tens of times faster** than [pyworld](https://github.com/JeremyCCHsu/Python-Wrapper-for-World-Vocoder) (float64 C++).

![Median wall time: pyworld vs torchscriptworld CPU vs GPU](https://raw.githubusercontent.com/aqtq314/TorchScriptWORLD/main/qa/results/speed.svg)

`codec` is the sum of `code_aperiodicity`, `decode_aperiodicity`, `code_spectral_envelope`, and `decode_spectral_envelope`. Time axis is **logarithmic**. Hardware, RTF, GPU memory, and pyworld agreement tables: [`qa/README.md`](qa/README.md).

## Development Status

- [x] `dio`
- [x] `harvest`
- [x] (*Manually Optimized*) `stonemask`
- [x] (*Manually Optimized*) `cheaptrick`
- [x] `d4c`
- [x] `code_aperiodicity` / `decode_aperiodicity` / `code_spectral_envelope` / `decode_spectral_envelope`
- [x] (*Manually Optimized*) `synthesize`
- [x] `wav2world` (DIO + StoneMask + CheapTrick + D4C)

Not currently planned: requiem variants; realtime synthesis.

## Demo, Tests, and Quality Assurance

Audio is **not** included. You can pass your own speech file on the command line. WORLD's [`vaiueo2d.wav`](https://github.com/mmorise/World/raw/master/test/vaiueo2d.wav) is a common short example (also in [pyworld's demo folder](https://github.com/JeremyCCHsu/Python-Wrapper-for-World-Vocoder/blob/master/demo/vaiueo2d.wav)).

```bash
python demo/demo.py --input path/to/speech.wav --output resynth.wav
python -m pytest --audio path/to/speech.wav
python -m qa --audio path/to/speech.wav
```

`demo/demo.py` also accepts `--pyworld-output` to write a pyworld resynthesis next to the torchscriptworld output.

## TorchScript Checkpoint

Pre-exported archives are attached to [GitHub Releases](https://github.com/aqtq314/TorchScriptWORLD/releases).

To export locally:

```bash
python -m torchscriptworld._export
# writes e.g. torchscriptworld-0.1.0-torch2.11.pt
```

```python
import torch
world = torch.jit.load('torchscriptworld-0.1.0-torch2.11.pt')
x = torch.randn(1, 16000)  # rank-2 required in the archive
f0, sp, ap = world(x, 16000)
y = world.synthesize(f0, sp, ap, 16000)
```

## Not Bit-exact

This is a GPU-oriented float32 port with occasional int64 calculations, not a line-by-line clone of the original C++ implementation under float64. Documented differences include:

- Reflect padding (WORLD uses replicate / edge clamp).
- CheapTrick / D4C linear smoothing uses a float32 sliding mean implemented as depthwise Conv1D instead of float64 cumulative-sum interpolation.
- CheapTrick windows are centered and truncated with `floor`-style cutoffs.
- D4C windows stay left-aligned (WORLD's centroid time origin). There is no `randn * 1e-6` floor on the windowed waveform. Unvoiced frames are filled with the default F0 during the dense batch so the smoother is not sized by the 47 Hz D4C floor, then overwritten with aperiodicity ~ 1.
- StoneMask uses one FFT size for the whole clip (WORLD picks one per frame), an analytic window derivative, and does not zero F0 above `fs/12`. The size is a power of two by default, matching WORLD's zero-padding; pass `fft_size_pow2=False` for the smallest even length that fits the window, which is cheaper but gives coarser bins.
- DIO contour repair fills unvoiced gaps as parallel wavefronts (WORLD can overwrite the next voiced section). `speed > 1` uses a truncated FIR in place of WORLD's sequential IIR.
- Harvest refinement uses one FFT size for the clip (WORLD picks one per candidate). Zero-phase F0 smoothing is WORLD's Butterworth as a truncated FIR. Contour-repair extension is a parallel per-section wavefront.

WORLD is designed for speech at **≥ 16 kHz**.

## References

WORLD (D4C edition):

1. M. Morise, F. Yokomori, and K. Ozawa, “WORLD: a vocoder-based high-quality speech synthesis system for real-time applications,” *IEICE Trans. Inf. & Syst.*, 2016.
2. M. Morise, “D4C, a band-aperiodicity estimator for high-quality speech synthesis,” *Speech Communication*, 2016.
3. M. Morise, “CheapTrick, a spectral envelope estimator for high-quality speech synthesis,” *Speech Communication*, 2015.
4. M. Morise et al., “Fast and reliable F0 estimation method based on the period extraction of vocal fold vibration,” AES 35th International Conference, 2009.
5. M. Morise, “Harvest: A high-performance fundamental frequency estimator from speech signals,” *Proc. Interspeech*, 2017.

## License

Modified BSD (3-clause), following [WORLD](https://github.com/mmorise/World). See `LICENSE`.
