# AudioData

The WebCodecs [`AudioData`](#webrtc.models.audio_data.AudioData) and the dictionaries that create and copy it.

### *class* webrtc.models.audio_data.AudioDataInit(format, sample_rate, number_of_frames, number_of_channels, timestamp, data, transfer=<factory>)

Options to create an [`AudioData`](#webrtc.models.audio_data.AudioData).

See [MDN: AudioData/AudioData](https://developer.mozilla.org/en-US/docs/Web/API/AudioData/AudioData).

* **Parameters:**
  * **format** ([`webrtc.AudioSampleFormat`](../enums.md#webrtc.enums.AudioSampleFormat)) – The sample type and whether channels are interleaved or planar.
  * **sample_rate** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – The number of frames per second. It must be positive and finite.
  * **number_of_frames** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – The number of frames (samples per channel), which must be positive.
  * **number_of_channels** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – The number of channels, which must be positive.
  * **timestamp** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – The presentation time in microseconds.
  * **data** (*Buffer*) – A bytes-like buffer that holds at least the samples described above. Extra bytes are ignored. The
    buffer is copied unless it is transferred.
  * **transfer** ([`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of bytes-like buffers, optional) – Buffers to give up. When `data` is among them its
    memory is kept without copying, so it must not be modified afterwards. Transferred [`memoryview`](https://docs.python.org/3/builtins/stdtypes.html#memoryview)
    objects are released, but other buffers stay usable.

### *class* webrtc.models.audio_data.AudioDataCopyToOptions(plane_index, frame_offset=0, frame_count=None, format=None)

Options for [`AudioData.copy_to()`](#webrtc.models.audio_data.AudioData.copy_to) and [`AudioData.allocation_size()`](#webrtc.models.audio_data.AudioData.allocation_size).

See [MDN: AudioData/copyTo](https://developer.mozilla.org/en-US/docs/Web/API/AudioData/copyTo).

* **Parameters:**
  * **plane_index** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – The channel to copy when the destination format is planar. It must be 0 for an
    interleaved format, which copies all channels.
  * **frame_offset** ([`int`](https://docs.python.org/3/builtins/functions.html#int), optional) – The index of the first frame to copy, 0 by default.
  * **frame_count** ([`int`](https://docs.python.org/3/builtins/functions.html#int), optional) – How many frames to copy. By default, all frames from `frame_offset` on.
  * **format** ([`webrtc.AudioSampleFormat`](../enums.md#webrtc.enums.AudioSampleFormat), optional) – The format to convert the samples to. By default, the
    data’s own format.

### *class* webrtc.models.audio_data.AudioData(init)

A block of audio samples with their format and presentation time.

The samples are held until [`close()`](#webrtc.models.audio_data.AudioData.close) is called or a `with` block around the data ends. Data that is
garbage collected while open emits a [`ResourceWarning`](https://docs.python.org/3/builtins/exceptions.html#ResourceWarning). Data read from a track is interleaved `u8`,
`s16` or `s32`.

See [MDN: AudioData](https://developer.mozilla.org/en-US/docs/Web/API/AudioData).

* **Parameters:**
  **init** ([`AudioDataInit`](#webrtc.models.audio_data.AudioDataInit)) – The samples and their format.
* **Raises:**
  [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If the options are invalid, or the data is too small for them.

Example:

```default
data = webrtc.AudioData(
    webrtc.AudioDataInit(
        format='s16',
        sample_rate=48000,
        number_of_frames=480,
        number_of_channels=1,
        timestamp=0,
        data=bytes(960),
    )
)
```

#### *property* format *: [AudioSampleFormat](../enums.md#webrtc.enums.AudioSampleFormat) | [None](https://docs.python.org/3/builtins/constants.html#None)*

The sample type and layout, or [`None`](https://docs.python.org/3/builtins/constants.html#None) once closed.

See [MDN: AudioData/format](https://developer.mozilla.org/en-US/docs/Web/API/AudioData/format).

* **Type:**
  [`webrtc.AudioSampleFormat`](../enums.md#webrtc.enums.AudioSampleFormat), optional

#### *property* sample_rate *: [float](https://docs.python.org/3/builtins/functions.html#float)*

The number of frames per second, or 0 once closed.

See [MDN: AudioData/sampleRate](https://developer.mozilla.org/en-US/docs/Web/API/AudioData/sampleRate).

* **Type:**
  [`float`](https://docs.python.org/3/builtins/functions.html#float)

#### *property* number_of_frames *: [int](https://docs.python.org/3/builtins/functions.html#int)*

The number of frames (samples per channel), or 0 once closed.

See [MDN: AudioData/numberOfFrames](https://developer.mozilla.org/en-US/docs/Web/API/AudioData/numberOfFrames).

* **Type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int)

#### *property* number_of_channels *: [int](https://docs.python.org/3/builtins/functions.html#int)*

The number of channels, or 0 once closed.

See [MDN: AudioData/numberOfChannels](https://developer.mozilla.org/en-US/docs/Web/API/AudioData/numberOfChannels).

* **Type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int)

#### *property* duration *: [int](https://docs.python.org/3/builtins/functions.html#int)*

The duration in microseconds, rounded down, or 0 once closed.

See [MDN: AudioData/duration](https://developer.mozilla.org/en-US/docs/Web/API/AudioData/duration).

* **Type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int)

#### *property* timestamp *: [int](https://docs.python.org/3/builtins/functions.html#int)*

The presentation time in microseconds, kept after closing.

See [MDN: AudioData/timestamp](https://developer.mozilla.org/en-US/docs/Web/API/AudioData/timestamp).

* **Type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int)

#### allocation_size(options)

Computes the minimum destination size for [`copy_to()`](#webrtc.models.audio_data.AudioData.copy_to) with the same options.

See [MDN: AudioData/allocationSize](https://developer.mozilla.org/en-US/docs/Web/API/AudioData/allocationSize).

* **Parameters:**
  **options** ([`AudioDataCopyToOptions`](#webrtc.models.audio_data.AudioDataCopyToOptions)) – What to copy.
* **Returns:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int) – The number of bytes.
* **Raises:**
  * [**webrtc.InvalidStateError**](../exceptions.md#webrtc.exceptions.InvalidStateError) – If the data is closed.
  * [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If an option has the wrong type or a negative value.
  * [**webrtc.InvalidRangeError**](../exceptions.md#webrtc.exceptions.InvalidRangeError) – If the plane or the frames are out of range.
* **Return type:**
  [int](https://docs.python.org/3/builtins/functions.html#int)

#### copy_to(destination, options)

Copies samples into a buffer, converting them to another format if asked.

Float samples converted to an integer format are clamped to the range from -1 to 1 first.

See [MDN: AudioData/copyTo](https://developer.mozilla.org/en-US/docs/Web/API/AudioData/copyTo).

* **Parameters:**
  * **destination** ([`bytearray`](https://docs.python.org/3/builtins/stdtypes.html#bytearray) or writable [`memoryview`](https://docs.python.org/3/builtins/stdtypes.html#memoryview)) – The buffer to write to, at least
    [`allocation_size()`](#webrtc.models.audio_data.AudioData.allocation_size) bytes long.
  * **options** ([`AudioDataCopyToOptions`](#webrtc.models.audio_data.AudioDataCopyToOptions)) – What to copy.
* **Raises:**
  * [**webrtc.InvalidStateError**](../exceptions.md#webrtc.exceptions.InvalidStateError) – If the data is closed.
  * [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If an option has the wrong type or a negative value.
  * [**webrtc.InvalidRangeError**](../exceptions.md#webrtc.exceptions.InvalidRangeError) – If the plane or the frames are out of range, or the buffer is too small.
  * [**webrtc.NotSupportedError**](../exceptions.md#webrtc.exceptions.NotSupportedError) – If the samples can’t be converted to the format.

#### clone()

Creates another data that shares these samples without copying them. Each must be closed separately.

See [MDN: AudioData/clone](https://developer.mozilla.org/en-US/docs/Web/API/AudioData/clone).

* **Returns:**
  [`AudioData`](#webrtc.models.audio_data.AudioData) – The new data.
* **Raises:**
  [**webrtc.InvalidStateError**](../exceptions.md#webrtc.exceptions.InvalidStateError) – If the data is closed.
* **Return type:**
  [*AudioData*](#webrtc.models.audio_data.AudioData)

#### close()

Releases this data’s hold on the samples. Closing a closed data does nothing.

After that, the format and size attributes read as empty, and the methods raise
[`webrtc.InvalidStateError`](../exceptions.md#webrtc.exceptions.InvalidStateError).

See [MDN: AudioData/close](https://developer.mozilla.org/en-US/docs/Web/API/AudioData/close).