torchaudio.save

torchaudio.save(uri: Union[str, PathLike], src: Tensor, sample_rate: int, channels_first: bool = True, format: Optional[str] = None, encoding: Optional[str] = None, bits_per_sample: Optional[int] = None, buffer_size: int = 4096, backend: Optional[str] = None, compression: Optional[Union[float, int]] = None) → None

Save audio data to file using TorchCodec’s AudioEncoder.

Note

As of TorchAudio 2.9, this function relies on TorchCodec’s encoding capabilities under the hood. It is provided for convenience, but we do recommend that you port your code to natively use torchcodec’s AudioEncoder class for better performance: https://docs.pytorch.org/torchcodec/stable/generated/torchcodec.encoders.AudioEncoder. Because of the reliance on Torchcodec, the parameters format, encoding, bits_per_sample, buffer_size, and backend, are ignored and accepted only for backwards compatibility. To install torchcodec, follow the instructions at https://github.com/pytorch/torchcodec#installing-torchcodec.

Parameters

• uri (path-like object) – Path to save the audio file. The file extension determines the format.

• src (torch.Tensor) – Audio data to save. Must be a 1D or 2D tensor with float32 values in the range [-1, 1]. If 2D, shape should be [channel, time] when channels_first=True, or [time, channel] when channels_first=False.

• sample_rate (int) – Sample rate of the audio data.

• channels_first (bool, optional) – Indicates whether the input tensor has channels as the first dimension. If True, expects [channel, time]. If False, expects [time, channel]. Default: True.

• format (str or None, optional) – Audio format hint. Not used by TorchCodec (format is determined by file extension). A warning is issued if provided. Default: None.

• encoding (str or None, optional) – Audio encoding. Not fully supported by TorchCodec AudioEncoder. A warning is issued if provided. Default: None.

• bits_per_sample (int or None, optional) – Bits per sample. Not directly supported by TorchCodec AudioEncoder. A warning is issued if provided. Default: None.

• buffer_size (int, optional) – Not used by TorchCodec AudioEncoder. Provided for API compatibility. A warning is issued if not default value. Default: 4096.

• backend (str or None, optional) – Not used by TorchCodec AudioEncoder. Provided for API compatibility. A warning is issued if provided. Default: None.

• compression (float, int or None, optional) – Compression level or bit rate. Maps to bit_rate parameter in TorchCodec AudioEncoder. Default: None.

Raises

• ImportError – If torchcodec is not available.

• ValueError – If input parameters are invalid.

• RuntimeError – If TorchCodec fails to encode the audio.

Note

• TorchCodec AudioEncoder expects float32 samples in [-1, 1] range.

• Some parameters (format, encoding, bits_per_sample, buffer_size, backend)

are not used by TorchCodec but are provided for API compatibility. - The output format is determined by the file extension in the uri. - TorchCodec uses FFmpeg under the hood for encoding.