NxAudio.IO behaviour (nx_audio v0.3.1)

View Source

Defines a behaviour for audio backend operations

Summary

Types

audio_tensor()

A 2D tensor {channels, samples} representing audio data.

file_uri()

Defines the input for the load function, which can be a binary audio or a valid file path

io_errors()

Defines the possible errors that can occur when loading an audio file

sample_rate()

Audio sample rate in Hz

Callbacks

info(uri)

Returns the audio metadata for a given file.

load(uri, config)

Loads an audio file from a given URI and returns a tuple with the audio tensor and the sample rate.

save(uri, tensor, config)

Saves an audio tensor to a given URI.

stream!(uri, config)

Streams an audio file from a given URI and returns an enumerable with the audio tensor and the sample rate.

Functions

info(uri, config)

Retrieves metadata information about an audio file at the specified URI.

load(uri, config)

Loads an audio file from the given URI using the configured backend.

save(uri, tensor, config)

Saves an audio tensor to a file at the specified URI using the configured backend.

stream!(uri, config)

Streams an audio file from the given URI using the configured backend.

Types

audio_tensor()

@type audio_tensor() :: Nx.Tensor.t()

A 2D tensor {channels, samples} representing audio data.

file_uri()

@type file_uri() :: binary() | Path.t()

Defines the input for the load function, which can be a binary audio or a valid file path

io_errors()

@type io_errors() ::
  NxAudio.IO.Errors.FailedToExecuteBackend.t()
  | NxAudio.IO.Errors.InvalidMetadata.t()

Defines the possible errors that can occur when loading an audio file

sample_rate()

@type sample_rate() :: non_neg_integer()

Audio sample rate in Hz

Callbacks

info(uri)

@callback info(uri :: file_uri()) ::
  {:ok, NxAudio.IO.AudioMetadata.t()} | {:error, io_errors()}

Returns the audio metadata for a given file.

load(uri, config)

@callback load(uri :: file_uri(), config :: NxAudio.IO.BackendReadConfig.t()) ::
  {:ok, {audio_tensor(), sample_rate()}} | {:error, io_errors()}

Loads an audio file from a given URI and returns a tuple with the audio tensor and the sample rate.

save(uri, tensor, config)

@callback save(
  uri :: file_uri(),
  tensor :: audio_tensor(),
  config :: NxAudio.IO.BackendSaveConfig.t()
) :: :ok | {:error, io_errors()}

Saves an audio tensor to a given URI.

stream!(uri, config)

@callback stream!(uri :: file_uri(), config :: NxAudio.IO.BackendReadConfig.t()) ::
  Enumerable.t()

Streams an audio file from a given URI and returns an enumerable with the audio tensor and the sample rate.

Functions

info(uri, config)

@spec info(file_uri(), NxAudio.IO.BackendReadConfig.t()) ::
  {:ok, NxAudio.IO.AudioMetadata.t()} | {:error, io_errors()}

Retrieves metadata information about an audio file at the specified URI.

Parameters

Returns

  • {:ok, metadata} - On success, returns the audio metadata (see NxAudio.IO.AudioMetadata)
  • {:error, error} - On failure, returns an error struct

load(uri, config)

@spec load(file_uri(), NxAudio.IO.BackendReadConfig.t()) ::
  {:ok, {audio_tensor(), sample_rate()}} | {:error, io_errors()}

Loads an audio file from the given URI using the configured backend.

Parameters

Returns

  • {:ok, {tensor, sample_rate}} - On success, returns a tuple with the audio tensor and sample rate
  • {:error, error} - On failure, returns an error struct

save(uri, tensor, config)

@spec save(file_uri(), audio_tensor(), NxAudio.IO.BackendSaveConfig.t()) ::
  :ok | {:error, io_errors()}

Saves an audio tensor to a file at the specified URI using the configured backend.

Parameters

  • uri - The target file path where the audio will be saved
  • tensor - The audio tensor to save (2D tensor with channels x samples)
  • config - The configuration for saving the audio file (see NxAudio.IO.BackendSaveConfig)

Returns

  • :ok - On successful save
  • {:error, error} - On failure, returns an error struct

stream!(uri, config)

@spec stream!(file_uri(), NxAudio.IO.BackendReadConfig.t()) :: Enumerable.t()

Streams an audio file from the given URI using the configured backend.

This function returns an enumerable that can be used to process the audio data in chunks, which is useful for handling large audio files without loading them entirely into memory.

Parameters

Returns

  • An Enumerable.t() that yields audio chunks

Raises

  • Raises an error if the streaming operation fails