README.md 6.92 KB
Newer Older
Soumith Chintala's avatar
Soumith Chintala committed
1
torchaudio: an audio library for PyTorch
Vincent QB's avatar
Vincent QB committed
2
========================================
Soumith Chintala's avatar
Soumith Chintala committed
3

moto's avatar
moto committed
4
5
[![Build Status](https://circleci.com/gh/pytorch/audio.svg?style=svg)](https://app.circleci.com/pipelines/github/pytorch/audio)
[![Documentation](https://img.shields.io/badge/dynamic/json.svg?label=docs&url=https%3A%2F%2Fpypi.org%2Fpypi%2Ftorchaudio%2Fjson&query=%24.info.version&colorB=brightgreen&prefix=v)](https://pytorch.org/audio/)
6

jamarshon's avatar
jamarshon committed
7
The aim of torchaudio is to apply [PyTorch](https://github.com/pytorch/pytorch) to
8
the audio domain. By supporting PyTorch, torchaudio follows the same philosophy
jamarshon's avatar
jamarshon committed
9
10
of providing strong GPU acceleration, having a focus on trainable features through
the autograd system, and having consistent style (tensor names and dimension names).
11
Therefore, it is primarily a machine learning library and not a general signal
12
processing library. The benefits of PyTorch can be seen in torchaudio through
13
having all the computations be through PyTorch operations which makes it easy
jamarshon's avatar
jamarshon committed
14
15
to use and feel like a natural extension.

16
- [Support audio I/O (Load files, Save files)](http://pytorch.org/audio/stable/)
moto's avatar
moto committed
17
18
19
  - Load a variety of audio formats, such as `wav`, `mp3`, `ogg`, `flac`, `opus`, `sphere`, into a torch Tensor using SoX
  - [Kaldi (ark/scp)](http://pytorch.org/audio/stable/kaldi_io.html)
- [Dataloaders for common audio datasets](http://pytorch.org/audio/stable/datasets.html)
20
- Common audio transforms
21
    - [Spectrogram, AmplitudeToDB, MelScale, MelSpectrogram, MFCC, MuLawEncoding, MuLawDecoding, Resample](http://pytorch.org/audio/stable/transforms.html)
22
- Compliance interfaces: Run code using PyTorch that align with other libraries
moto's avatar
moto committed
23
    - [Kaldi: spectrogram, fbank, mfcc](https://pytorch.org/audio/stable/compliance.kaldi.html)
Soumith Chintala's avatar
Soumith Chintala committed
24
25
26

Dependencies
------------
moto's avatar
moto committed
27
* PyTorch (See below for the compatible versions)
28
* [optional] vesis84/kaldi-io-for-python commit cb46cb1f44318a5d04d4941cf39084c5b021241e or above
Soumith Chintala's avatar
Soumith Chintala committed
29

30
The following are the corresponding ``torchaudio`` versions and supported Python versions.
moto's avatar
moto committed
31
32
33

| ``torch``                | ``torchaudio``           | ``python``                      |
| ------------------------ | ------------------------ | ------------------------------- |
34
| ``master`` / ``nightly`` | ``main`` / ``nightly``   | ``>=3.6``, ``<=3.9``            |
35
| ``1.9.1``                | ``0.9.1``                | ``>=3.6``, ``<=3.9``            |
moto's avatar
moto committed
36
| ``1.9.0``                | ``0.9.0``                | ``>=3.6``, ``<=3.9``            |
37
38
39
40
41
| ``1.8.0``                | ``0.8.0``                | ``>=3.6``, ``<=3.9``            |
| ``1.7.1``                | ``0.7.2``                | ``>=3.6``, ``<=3.9``            |
| ``1.7.0``                | ``0.7.0``                | ``>=3.6``, ``<=3.8``            |
| ``1.6.0``                | ``0.6.0``                | ``>=3.6``, ``<=3.8``            |
| ``1.5.0``                | ``0.5.0``                | ``>=3.5``, ``<=3.8``            |
moto's avatar
moto committed
42
43
44
| ``1.4.0``                | ``0.4.0``                | ``==2.7``, ``>=3.5``, ``<=3.8`` |


Soumith Chintala's avatar
Soumith Chintala committed
45
46
47
Installation
------------

48
### Binary Distributions
jamarshon's avatar
jamarshon committed
49

50
To install the latest version using anaconda, run:
51

52
53
54
55
```
conda install -c pytorch torchaudio
```

56
To install the latest pip wheels, run:
jamarshon's avatar
jamarshon committed
57
58

```
59
60
pip install torchaudio -f https://download.pytorch.org/whl/torch_stable.html
```
jamarshon's avatar
jamarshon committed
61

62
63
64
(If you do not have torch already installed, this will default to installing
torch from PyPI. If you need a different torch configuration, preinstall torch
before running this command.)
jamarshon's avatar
jamarshon committed
65

66
67
### Nightly build

68
Note that nightly build is built on PyTorch's nightly build. Therefore, you need to install the latest PyTorch when you use nightly build of torchaudio.
69
70

**pip**
jamarshon's avatar
jamarshon committed
71

72
```
Vincent QB's avatar
Vincent QB committed
73
pip install --pre torchaudio -f https://download.pytorch.org/whl/nightly/torch_nightly.html
jamarshon's avatar
jamarshon committed
74
75
```

76
**conda**
Mingbo Wan's avatar
Mingbo Wan committed
77
78
79
80
81

```
conda install -y -c pytorch-nightly torchaudio
```

jamarshon's avatar
jamarshon committed
82
83
### From Source

84
On non-Windows platforms, the build process builds libsox and codecs that torchaudio need to link to. It will fetch and build libmad, lame, flac, vorbis, opus, and libsox before building extension. This process requires `cmake` and `pkg-config`. libsox-based features can be disabled with `BUILD_SOX=0`.
85
The build process also builds the RNN transducer loss. This functionality can be disabled by setting the environment variable `BUILD_RNNT=0`.
86

87
88
```bash
# Linux
89
python setup.py install
90
91

# OSX
92
MACOSX_DEPLOYMENT_TARGET=10.9 CC=clang CXX=clang++ python setup.py install
93
94
95
96
97
98
99
100
101

# Windows
# We need to use the MSVC x64 toolset for compilation, with Visual Studio's vcvarsall.bat or directly with vcvars64.bat.
# These batch files are under Visual Studio's installation folder, under 'VC\Auxiliary\Build\'.
# More information available at:
#   https://docs.microsoft.com/en-us/cpp/build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line?view=msvc-160#use-vcvarsallbat-to-set-a-64-bit-hosted-build-architecture
call "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" x64 && set BUILD_SOX=0 && python setup.py install
# or
call "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat" && set BUILD_SOX=0 && python setup.py install
102
103
104
```

This is known to work on linux and unix distributions such as Ubuntu and CentOS 7 and macOS.
105
If you try this on a new system and find a solution to make it work, feel free to share it by opening an issue.
106

Soumith Chintala's avatar
Soumith Chintala committed
107
108
109
110
111
Quick Usage
-----------

```python
import torchaudio
112
113
114

waveform, sample_rate = torchaudio.load('foo.wav')  # load tensor from file
torchaudio.save('foo_save.wav', waveform, sample_rate)  # save tensor to file
Soumith Chintala's avatar
Soumith Chintala committed
115
116
```

117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
Backend Dispatch
----------------

By default in OSX and Linux, torchaudio uses SoX as a backend to load and save files.
The backend can be changed to [SoundFile](https://pysoundfile.readthedocs.io/en/latest/)
using the following. See [SoundFile](https://pysoundfile.readthedocs.io/en/latest/)
for installation instructions.

```python
import torchaudio
torchaudio.set_audio_backend("soundfile")  # switch backend

waveform, sample_rate = torchaudio.load('foo.wav')  # load tensor from file, as usual
torchaudio.save('foo_save.wav', waveform, sample_rate)  # save tensor to file, as usual
```

moto's avatar
moto committed
133
134
135
**Note**
- SoundFile currently does not support mp3.
- "soundfile" backend is not supported by TorchScript.
136

Soumith Chintala's avatar
Soumith Chintala committed
137
API Reference
Vincent QB's avatar
Vincent QB committed
138
-------------
SeanNaren's avatar
SeanNaren committed
139

140
API Reference is located here: http://pytorch.org/audio/
Vincent QB's avatar
Vincent QB committed
141

jamarshon's avatar
jamarshon committed
142
143
144
Contributing Guidelines
-----------------------

Nicolas Hug's avatar
Nicolas Hug committed
145
Please refer to [CONTRIBUTING.md](./CONTRIBUTING.md)
Vincent QB's avatar
Vincent QB committed
146
147
148
149
150
151
152

Disclaimer on Datasets
----------------------

This is a utility library that downloads and prepares public datasets. We do not host or distribute these datasets, vouch for their quality or fairness, or claim that you have license to use the dataset. It is your responsibility to determine whether you have permission to use the dataset under the dataset's license.

If you're a dataset owner and wish to update any part of it (description, citation, etc.), or do not want your dataset to be included in this library, please get in touch through a GitHub issue. Thanks for your contribution to the ML community!