torchaudio.save_with_torchcodec

torchaudio.save_with_torchcodec(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

This function supports the same API as save(), and 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. In TorchAudio 2.9, save() will be relying on save_with_torchcodec(). Note that some parameters of save(), like format, encoding, bits_per_sample, buffer_size, and backend, are ignored by are ignored by save_with_torchcodec().

This function provides a TorchCodec-based alternative to torchaudio.save with the same API. TorchCodec’s AudioEncoder provides efficient encoding with FFmpeg under the hood.

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.