[Announcement] Improving I/O for correct and consistent experience

**tl;dr: how to migrate to new backend/interface in `0.7`**

* If you are using `torchaudio` in Linux/macOS environments, please use `torchaudio.set_audio_backend("sox_io")` to adopt to the upcoming changes.

* If you are in Windows environment, please set `torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = False` and reload backend to use the new interface.

* Note that this ships with some bug-fixes for formats other than 16bit signed integer WAV, so you might experience some BC-breaking changes as described in the section below.

**News**
[UPDATE] 2021/03/06
 - All the migration works have been completed on master branch.

[UPDATE] 2021/02/12
 - Added `bits_per_sample` and `encoding` argument (replaced `dtype`) to `save` function.

[UPDATE] 2021/01/29
 - Added `encoding` to `AudioMetaData`

[UPDATE] 2021/01/22
 - Added `format` argument to `load`/`info`/`save` function.
 - `bits_per_sample` to `AudioMetaData`

[UPDATE] 2020/10/21
 - Added Description of `"soundfile"` backend legacy interface.

[UPDATE] 2020/09/18
 - Added migration guide for `"soundfile"` backend.
 - Moved the phase when `"soundfile"` backend signatures change from 0.9.0 to 0.8.0 so that they match with `"sox_io"` backend, which becomes default in 0.8.0.

[UPDATE] 2020/09/17
 - Added information on deprecation of native `libsox` structures such as `signalinfo_t` and `encoding_t`.

# Improving I/O for correct and consistent experience

This is an announcement for users that we are making backward-incompatible changes to I/O functions of `torchaudio` backends from 0.7.0 release throughout 0.9.0 release.

## What is affected?

- **Public APIs**
  - `torchaudio.load`
    - [Linux/macOS] By switching the default backend from `"sox"` backend to `"sox_io"` backend in 0.8.0, loading audio formats other than 16bit signed integer WAV returns the correct tensor.
    - [Linux/macOS/Windows] The signature of `"soundfile"` backend will be change in 0.8.0 to match that of `"sox_io"` backend.
  - `torchaudio.save`
    - [Linux/macOS] By switching to `"sox_io"` backend, saving audio files will no longer degrade the data. The supported format will be restricted to the tested formats only. (please refer to [the doc](https://pytorch.org/audio/backend.html#backend) for the supported formats.)
    - [Linux/macOS/Windows] The signature of `"soundfile"` backend will be change in 0.8.0 to match that of `"sox_io"` backend.
  - `torchaudio.info`
    - [Linux/macOS/Windows] The signature of `"soundfile"` backend will be change in 0.8.0 to match that of `"sox_io"` backend.
  - `torchaudio.load_wav`
    - will be removed in 0.9.0. (`load` function with `normalize=False` will provide the same functionality)

- **Internal APIs**
The following functions/classes of `"sox"` backend were accidentally exposed and will be removed in 0.9.0. There is no replacement for them. Please use `save`/`load`/`info` functions.
  - `torchaudio.save_encinfo`
    - will be removed in 0.9.0
  - `torchaudio.get_sox_signalinfo_t`
    - will be removed in 0.9.0
  - `torchaudio.get_sox_encodinginfo_t`
    - will be removed in 0.9.0
  - `torchaudio.get_sox_option_t`
    - will be removed in 0.9.0
  - `torchaudio.get_sox_bool`
    - will be removed in 0.9.0

The signatures of the other backends are not planned to be changed within this overhaul plan.

- **Classes**
  - `torchaudio.SignalInfo` and `torchaudio.EncodingInfo`
    - will be replaced with `AudioMetaData` in 0.8.0 for `"soundfile"` backend
    - will be removed in 0.9.0

## Why

There are currently three backends in `torchaudio`. (Please refer to [the documentation](https://pytorch.org/audio/backend.html#backend) for the detail.)

`"sox"` backend is the original backend, which binds `libsox` with `pybind11`. The functionalities (`load` / `save` / `info`) of this backend are not well-tested and have number of issues. (See https://github.com/pytorch/audio/pull/726).

Fixing these issues in backward-compatible manner is not straightforward. Therefore while we were adding TorchScript-compatible I/O functions, we decided to deprecate this original `"sox"` backend and replace it with the new backend (`"sox_io"` backend), which is confirmed not to have those issues.

When we are switching the default backend for Linux/macOS from `"sox"` to `"sox_io"` backend, we would like to align the interface of `"soundfile"` backend, therefore, we introduced the new interface (not a new backend to reduce the number of public API) to `"soundfile"` backend. 

## When / What Changes

The following is the timeline for the planned changes;

| Phase | Expected Release | Expected Changes |
|:-----:|:----------------:|------------------|
|   1   | 0.7.0</br>(Oct 2020) | <ul><li>`"sox"` backend issues deprecation warning. ~#904~ </li><li>`"soundfile"` backend issues warning of expected signature change. ~#906~ </li><li>Add the new interface to `"soubdfile"` backend. ~#922~</li><li>`load_wav` function of all backends are marked as deprecated. ~#905~ </li></ul> |
|   2   | 0.8.0</br>(March 2021) | <ul><li>**[BC-Breaking]** `"sox_io"` backend becomes default backend. Function signatures of `"soundfile"` backend are aligned with `"sox_io"` backend. ~#978~ </li><li>`get_sox_XXX` functions issue deprecation warning. ~#975~ </li></ul>|
|   3   | 0.9.0            | <ul><li>`"sox"` backend is removed. ~#1311~</li><li>The legacy interface of `"soundfile"` backend is removed. ~#1311~</li><li>**[BC-Breaking]** `load_wav` functions are removed from all backends. ~#1362~ </li></ul>|

### Planned signature changes of `"soundfile"` backend in 0.8.0

The following is the planned signature change of `"soundfile"` backend functions in 0.8.0 release.

#### `info` function

`AudioMetaData` implementation can be found [here](https://github.com/pytorch/audio/blob/c388ec2b5e6b4d0b99f9c5274d597858e90f5789/torchaudio/backend/sox_io_backend.py#L9-L19). The placement of the `AudioMetaData` might be changed.

<table>
<tr><td> ~0.7.0 </td> <td> 0.8.0 </td></tr>
<tr>
<td>

```python
def info(
  filepath: str,
) ->
  Tuple[SignalInfo, EncodingInfo]
```

</td>
<td>

```python
def info(
  filepath: str,
  format: Optional[str],
) ->
  AudioMetaData
```

</td>
</tr>
</table>

#### Migration

The values returned from `info` function will be changed. Please use the corresponding new attributes.

<table>
<tr><td> ~0.7.0 </td> <td> 0.8.0 </td></tr>
<tr>
<td>

```python
si, ei = torchaudio.info(filepath)
sample_rate = si.rate
num_frames = si.length
num_channels = si.channels
precision = si.precision
bits_per_sample = ei.bits_per_sample
encoding = ei.encoding
```

</td>
<td>

```python
metadata = torchaudio.info(filepath)
sample_rate = metadata.sample_rate
num_frames = metadata.num_frames
num_channels = metadata.num_channels
bits_per_sample = metadata.bits_per_sample
encoding = metadata.encoding
```

</td>
</tr>
</table>

**Note** If the attribute you are using is missing, file a Feature Request issue.

#### `load` function

<table>
<tr><td> ~0.7.0 </td> <td> 0.8.0 </td></tr>
<tr>
<td>

```python
def load(
  filepath: str,
  # out: Optional[Tensor] = None,
      # To be removed.
      # Currently not used
      # Raise AssertionError if given
  normalization: Optional[bool] = True,
      # To be renamed to normalize.
      # Currently only accept True
      # Raise AssertionError if given
  channels_first: Optional[bool] = True,
  num_frames: int = 0,
  offset: int = 0,
      # To be renamed to frame_offset
  # signalinfo: SignalInfo = None,
      # To be removed
      # Currently not used
      # Raise AssertionError if given
  # encodinginfo: EncodingInfo = None,
      # To be removed
      # Currently not used
      # Raise AssertionError if given
  filetype: Optional[str] = None
      # To be removed
      # Currently not used
) -> Tuple[Tensor, int]
```

</td>
<td>

```python
def load(
  filepath: str,
  frame_offset: int = 0,
  num_frames: int = -1,
  normalize: bool = True,
  channels_first: bool = True,
  format: Optional[str] = None,  # only required for file-like object input
) -> Tuple[Tensor, int]
```

</td>
</tr>
</table>

##### Migration

Please change the argument names;
 - `normalization` -> `normalize`
 - `offset` -> `frame_offst`

<table>
<tr><td> ~0.7.0 </td> <td> 0.8.0 </td></tr>
<tr>
<td>

```python
waveform, sample_rate = torchaudio.load(
    filepath,
    normalization=normalization,
    channels_first=channels_first,
    num_frames=num_frames,
    offset=offset,
)
```

</td>
<td>

```python
waveform, sample_rate = torchaudio.load(
    filepath,
    frame_offset=frame_offset,
    num_frames=num_frames,
    normalize= normalization,
    channels_first=channels_first,
)
```

</td>
</tr>
</table>

#### `save` function

<table>
<tr><td> ~0.7.0 </td> <td> 0.8.0 </td></tr>
<tr>
<td>

```python
def save(
  filepath: str,
  src: Tensor,
  sample_rate: int,
  precision: int = 16,
    # moved to `bits_per_sample` argument
  channels_first: bool = True
)
```

</td>
<td>

```python
def save(
  filepath: str,
  src: Tensor,
  sample_rate: int,
  channels_first: bool = True,
  compression: Optional[float] = None,
    # Added only for compatibility.
    # soundfile does not support compression option
    # Raises Warning if not None
  format: Optional[str] = None,
  encoding: Optoinal[str] = None,
  bits_per_sample: Optional[int] = None,
)
```

</td>
</tr>
</table>

##### Migration

<table>
<tr><td> ~0.7.0 </td> <td> 0.8.0 </td></tr>
<tr>
<td>

```python
torchaudio.save(
    filepath,
    waveform,
    sample_rate,
    channels_first
)
```

</td>
<td>

```python
torchaudio.save(
    filepath,
    waveform,
    sample_rate,
    channels_first,
    bits_per_sample=16,
)
# You can also designate audio format with `format` and configure the encoding with `compression` and `encoding`. See https://pytorch.org/audio/master/backend.html#save for the detail 
```

</td>
</tr>
</table>

**BC-breaking changes**

Read and write operations on the formats other than WAV 16-bit signed integer were affected by small bugs.

Phase	Expected Release	Expected Changes
1	0.7.0 (Oct 2020)	`"sox"` backend issues deprecation warning. ~~Add deprecation warning to sox backend #904~~ `"soundfile"` backend issues warning of expected signature change. ~~Add expected BC-breaking change warning to soundfile #906~~ Add the new interface to `"soubdfile"` backend. ~~Add soundfile compatibility backend #922~~ `load_wav` function of all backends are marked as deprecated. ~~Add deprecation warnings to load_wav functions #905~~
2	0.8.0 (March 2021)	[BC-Breaking] `"sox_io"` backend becomes default backend. Function signatures of `"soundfile"` backend are aligned with `"sox_io"` backend. ~~Switch the default backend to the ones with new interfaces #978~~ `get_sox_XXX` functions issue deprecation warning. ~~Add deprecation warnings to libsox specific functions #975~~
3	0.9.0	`"sox"` backend is removed. ~~Removed legacy backends from torchaudio #1311~~ The legacy interface of `"soundfile"` backend is removed. ~~Removed legacy backends from torchaudio #1311~~ [BC-Breaking] `load_wav` functions are removed from all backends. ~~BC-Breaking: Remove deprecated load_wav functions from backends #1362~~

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

[Announcement] Improving I/O for correct and consistent experience #903

Improving I/O for correct and consistent experience

What is affected?

Why

When / What Changes

Planned signature changes of `"soundfile"` backend in 0.8.0

`info` function

Migration

`load` function

Migration

`save` function

Migration

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

~0.7.0	0.8.0
def info( filepath: str, ) -> Tuple[SignalInfo, EncodingInfo]	def info( filepath: str, format: Optional[str], ) -> AudioMetaData

Uh oh!

[Announcement] Improving I/O for correct and consistent experience #903

Description

Improving I/O for correct and consistent experience

What is affected?

Why

When / What Changes

Planned signature changes of "soundfile" backend in 0.8.0

info function

Migration

load function

Migration

save function

Migration

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Planned signature changes of `"soundfile"` backend in 0.8.0

`info` function

`load` function

`save` function