Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

# Builder

*** ** * ** ***

```
class Builder
```

|---|---|
| [kotlin.Any](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-any/index.html) ||
| ↳ | [android.media.AudioFormat.Builder](https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#) |

Builder class for `https://developer.android.com/reference/kotlin/android/media/AudioFormat` objects. Use this class to configure and create an AudioFormat instance. By setting format characteristics such as audio encoding, channel mask or sample rate, you indicate which of those are to vary from the default behavior on this device wherever this audio format is used. See `https://developer.android.com/reference/kotlin/android/media/AudioFormat` for a complete description of the different parameters that can be used to configure an `AudioFormat` instance.

`https://developer.android.com/reference/kotlin/android/media/AudioFormat` is for instance used in `https://developer.android.com/reference/kotlin/android/media/AudioTrack#AudioTrack(android.media.AudioAttributes,%20android.media.AudioFormat,%20kotlin.Int,%20kotlin.Int,%20kotlin.Int)`. In this constructor, every format characteristic set on the `Builder` (e.g. with `https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#setSampleRate(kotlin.Int)`) will alter the default values used by an `AudioTrack`. In this case for audio playback with `AudioTrack`, the sample rate set in the `Builder` would override the platform output sample rate which would otherwise be selected by default.

## Summary

| Public constructors ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#Builder()()` Constructs a new Builder with none of the format characteristics set. |
| `https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#Builder(android.media.AudioFormat)(af: https://developer.android.com/reference/kotlin/android/media/AudioFormat!)` Constructs a new Builder from a given `https://developer.android.com/reference/kotlin/android/media/AudioFormat`. |

| Public methods ||
|---|---|
| open [AudioFormat](https://developer.android.com/reference/kotlin/android/media/AudioFormat)! | `https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#build()()` Combines all of the format characteristics that have been set and return a new `https://developer.android.com/reference/kotlin/android/media/AudioFormat` object. |
| open [AudioFormat.Builder](https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#) | `https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#setChannelAcnMask(kotlin.Int)(channelAcnMask: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)` Sets the Ambisonics channel mask. |
| open [AudioFormat.Builder](https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#) | `https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#setChannelIndexMask(kotlin.Int)(channelIndexMask: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)` Sets the channel index mask. |
| open [AudioFormat.Builder](https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#) | `https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#setChannelMask(kotlin.Int)(channelMask: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)` Sets the channel position mask. |
| open [AudioFormat.Builder](https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#)! | `https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#setEncoding(kotlin.Int)(encoding: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)` Sets the data encoding format. |
| open [AudioFormat.Builder](https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#)! | `https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#setSampleRate(kotlin.Int)(sampleRate: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)` Sets the sample rate. |

## Public constructors

### Builder

Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
Builder()
```

Constructs a new Builder with none of the format characteristics set.

### Builder

Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
Builder(af: AudioFormat!)
```

Constructs a new Builder from a given `https://developer.android.com/reference/kotlin/android/media/AudioFormat`.

| Parameters ||
|---|---|
| `af` | [AudioFormat](https://developer.android.com/reference/kotlin/android/media/AudioFormat)!: the `https://developer.android.com/reference/kotlin/android/media/AudioFormat` object whose data will be reused in the new Builder. |

## Public methods

### build

Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
open fun build(): AudioFormat!
```

Combines all of the format characteristics that have been set and return a new `https://developer.android.com/reference/kotlin/android/media/AudioFormat` object.

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/media/AudioFormat!` | a new `https://developer.android.com/reference/kotlin/android/media/AudioFormat` object |

### setChannelAcnMask

Added in [API level 37](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
open fun setChannelAcnMask(channelAcnMask: Int): AudioFormat.Builder
```

Sets the Ambisonics channel mask. The Ambisonics channel mask specifies that the audio data is in Ambisonics format, using the ACN (Ambisonics Channel Number) ordering and SN3D normalization. The mask indicates the order of the Ambisonics content and whether it is a full-sphere or horizontal-only representation.

| Parameters ||
|---|---|
| `channelAcnMask` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the Ambisonics channel mask, e.g. `https://developer.android.com/reference/kotlin/android/media/AudioFormat#CHANNEL_ACN_ORDER_1:kotlin.Int`, `https://developer.android.com/reference/kotlin/android/media/AudioFormat#CHANNEL_ACN_ORDER_1_HRZ:kotlin.Int`. |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#` | the same `Builder` instance. This value cannot be `null`. |

| Exceptions ||
|---|---|
| `java.lang.IllegalArgumentException` | if `channelAcnMask` is 0 or if a channel index mask is already set and its channel count does not match the channel count derived from `channelAcnMask`. |

### setChannelIndexMask

Added in [API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
open fun setChannelIndexMask(channelIndexMask: Int): AudioFormat.Builder
```

Sets the channel index mask. A channel index mask specifies the association of audio samples in the frame with numbered endpoint channels. The i-th bit in the channel index mask corresponds to the i-th endpoint channel. For example, an endpoint with four channels is represented as index mask bits 0 through 3. This [setChannelMask(int)](https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#channelIndexMask>description of channel
index masks</a> covers the concept in more details.
See <code><a docref=) for a positional mask interpretation.

Both `https://developer.android.com/reference/kotlin/android/media/AudioTrack` and `https://developer.android.com/reference/kotlin/android/media/AudioRecord` support a channel index mask. If a channel index mask is specified it is used, otherwise the channel position mask specified by `setChannelMask` is used. For `AudioTrack` and `AudioRecord`, a channel position mask is not required if a channel index mask is specified.

| Parameters ||
|---|---|
| `channelIndexMask` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): describes the configuration of the audio channels. For output, the `channelIndexMask` is an OR-ed combination of bits representing the mapping of `AudioTrack` write samples to output sink channels. For example, a mask of `0xa`, or binary `1010`, means the `AudioTrack` write frame consists of two samples, which are routed to the second and the fourth channels of the output sink. Unmatched output sink channels are zero filled and unmatched `AudioTrack` write samples are dropped. For input, the `channelIndexMask` is an OR-ed combination of bits representing the mapping of input source channels to `AudioRecord` read samples. For example, a mask of `0x5`, or binary `101`, will read from the first and third channel of the input source device and store them in the first and second sample of the `AudioRecord` read frame. Unmatched input source channels are dropped and unmatched `AudioRecord` read samples are zero filled. |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#` | the same `Builder` instance. This value cannot be `null`. |

| Exceptions ||
|---|---|
| `java.lang.IllegalArgumentException` | if the channel index mask is invalid or if both channel index mask and channel position mask are specified but do not have the same channel count. |

### setChannelMask

Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
open fun setChannelMask(channelMask: Int): AudioFormat.Builder
```

Sets the channel position mask. The channel position mask specifies the association between audio samples in a frame with named endpoint channels. The samples in the frame correspond to the named set bits in the channel position mask, in ascending bit order. See `https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#setChannelIndexMask(kotlin.Int)` to specify channels based on endpoint numbered channels. This [description of channel position masks](https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#channelPositionMask) covers the concept in more details.

| Parameters ||
|---|---|
| `channelMask` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): describes the configuration of the audio channels. For output, the channelMask can be an OR-ed combination of channel position masks, e.g. `https://developer.android.com/reference/kotlin/android/media/AudioFormat#CHANNEL_OUT_FRONT_LEFT:kotlin.Int`, `https://developer.android.com/reference/kotlin/android/media/AudioFormat#CHANNEL_OUT_FRONT_RIGHT:kotlin.Int`, `https://developer.android.com/reference/kotlin/android/media/AudioFormat#CHANNEL_OUT_FRONT_CENTER:kotlin.Int`, `https://developer.android.com/reference/kotlin/android/media/AudioFormat#CHANNEL_OUT_LOW_FREQUENCY:kotlin.Int` `https://developer.android.com/reference/kotlin/android/media/AudioFormat#CHANNEL_OUT_BACK_LEFT:kotlin.Int`, `https://developer.android.com/reference/kotlin/android/media/AudioFormat#CHANNEL_OUT_BACK_RIGHT:kotlin.Int`, `https://developer.android.com/reference/kotlin/android/media/AudioFormat#CHANNEL_OUT_BACK_CENTER:kotlin.Int`, `https://developer.android.com/reference/kotlin/android/media/AudioFormat#CHANNEL_OUT_SIDE_LEFT:kotlin.Int`, `https://developer.android.com/reference/kotlin/android/media/AudioFormat#CHANNEL_OUT_SIDE_RIGHT:kotlin.Int`. For output or `https://developer.android.com/reference/kotlin/android/media/AudioTrack`, channel position masks which do not contain matched left/right pairs are invalid. For input or `https://developer.android.com/reference/kotlin/android/media/AudioRecord`, the mask should be `https://developer.android.com/reference/kotlin/android/media/AudioFormat#CHANNEL_IN_MONO:kotlin.Int` or `https://developer.android.com/reference/kotlin/android/media/AudioFormat#CHANNEL_IN_STEREO:kotlin.Int`. `https://developer.android.com/reference/kotlin/android/media/AudioFormat#CHANNEL_IN_MONO:kotlin.Int` is guaranteed to work on all devices. |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#` | the same `Builder` instance. This value cannot be `null`. |

| Exceptions ||
|---|---|
| `java.lang.IllegalArgumentException` | if the channel mask is invalid or if both channel index mask and channel position mask are specified but do not have the same channel count. |

### setEncoding

Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
open fun setEncoding(encoding: Int): AudioFormat.Builder!
```

Sets the data encoding format.

| Parameters ||
|---|---|
| `encoding` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the specified encoding or default. Value is one of the following: - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_DEFAULT:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_PCM_16BIT:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_PCM_8BIT:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_PCM_FLOAT:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_AC3:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_E_AC3:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_DTS:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_DTS_HD:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_MP3:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_AAC_LC:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_AAC_HE_V1:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_AAC_HE_V2:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_IEC61937:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_DOLBY_TRUEHD:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_AAC_ELD:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_AAC_XHE:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_AC4:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_AC4_L4:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_E_AC3_JOC:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_DOLBY_MAT:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_OPUS:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_PCM_24BIT_PACKED:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_PCM_32BIT:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_MPEGH_BL_L3:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_MPEGH_BL_L4:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_MPEGH_LC_L3:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_MPEGH_LC_L4:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_DTS_UHD_P1:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_DRA:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_DTS_HD_MA:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_DTS_UHD_P2:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_DSD:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_IAMF_BASE_ENHANCED_PROFILE_AAC:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_IAMF_BASE_ENHANCED_PROFILE_FLAC:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_IAMF_BASE_ENHANCED_PROFILE_OPUS:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_IAMF_BASE_ENHANCED_PROFILE_PCM:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_IAMF_BASE_PROFILE_AAC:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_IAMF_BASE_PROFILE_FLAC:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_IAMF_BASE_PROFILE_OPUS:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_IAMF_BASE_PROFILE_PCM:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_IAMF_SIMPLE_PROFILE_AAC:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_IAMF_SIMPLE_PROFILE_FLAC:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_IAMF_SIMPLE_PROFILE_OPUS:kotlin.Int` - `https://developer.android.com/reference/kotlin/android/media/AudioFormat#ENCODING_IAMF_SIMPLE_PROFILE_PCM:kotlin.Int` |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#!` | the same Builder instance. |

| Exceptions ||
|---|---|
| `java.lang.IllegalArgumentException` |   |

### setSampleRate

Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
open fun setSampleRate(sampleRate: Int): AudioFormat.Builder!
```

Sets the sample rate.

| Parameters ||
|---|---|
| `sampleRate` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the sample rate expressed in Hz |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/media/AudioFormat.Builder#!` | the same Builder instance. |

| Exceptions ||
|---|---|
| `java.lang.IllegalArgumentException` |   |