# ChannelMixingMatrix

Artifact: [androidx.media3:media3-common](https://developer.android.com/jetpack/androidx/releases/media3) [View Source](https://cs.android.com/search?q=file:androidx/media3/common/audio/ChannelMixingMatrix.java+class:androidx.media3.common.audio.ChannelMixingMatrix)

*** ** * ** ***


```
@UnstableApi
public final class ChannelMixingMatrix
```

<br />

*** ** * ** ***

An immutable matrix that describes the mapping of input channels to output channels.

The matrix coefficients define the scaling factor to use when mixing samples from the input channel (row) to the output channel (column).

Examples:

- Stereo to mono with each channel at half volume:

  ```
  [0.5 0.5]
  ```
- Stereo to stereo with no mixing or scaling:

  ```
          [1 0
  0 1]
  ```
- Stereo to stereo with 0.7 volume:

  ```
          [0.7 0
  0 0.7]
  ```

## Summary

| ### Public fields |
|---|---|
| `final int` | `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix#inputChannelCount()` |
| `final boolean` | `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix#isDiagonal()` |
| `final boolean` | `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix#isIdentity()` |
| `final boolean` | `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix#isZero()` |
| `final int` | `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix#outputChannelCount()` |

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix#ChannelMixingMatrix(int,int,float[])( int inputChannelCount, int outputChannelCount, float[] coefficients )` Creates a matrix with the given coefficients in row-major order. |

| ### Public methods |
|---|---|
| `static https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix` | `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix#createForConstantGain(int,int)( @https://developer.android.com/reference/androidx/annotation/IntRange(from = 1, to = 2) int inputChannelCount, @https://developer.android.com/reference/androidx/annotation/IntRange(from = 1, to = 2) int outputChannelCount )` Returns a default constant gain channel mixing matrix that mixes `inputChannelCount` channels into `outputChannelCount` channels. |
| `static https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix` | `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix#createForConstantPower(int,int)( @https://developer.android.com/reference/androidx/annotation/IntRange(from = 1, to = 6) int inputChannelCount, @https://developer.android.com/reference/androidx/annotation/IntRange(from = 1, to = 2) int outputChannelCount )` Returns a default constant power channel mixing matrix that mixes `inputChannelCount` channels into `outputChannelCount` channels. |
| `int` | `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix#getInputChannelCount()()` |
| `float` | `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix#getMixingCoefficient(int,int)(int inputChannel, int outputChannel)` Gets the scaling factor for the given input and output channel. |
| `int` | `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix#getOutputChannelCount()()` |
| `boolean` | `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix#isDiagonal()()` Returns whether the matrix is square and all non-diagonal coefficients are zero. |
| `boolean` | `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix#isIdentity()()` Returns whether this is an identity matrix. |
| `boolean` | `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix#isSquare()()` Returns whether the input and output channel count is the same. |
| `boolean` | `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix#isZero()()` Returns whether all mixing coefficients are zero. |
| `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix` | `https://developer.android.com/reference/androidx/media3/common/audio/ChannelMixingMatrix#scaleBy(float)(float scale)` Returns a new matrix with the given scaling factor applied to all coefficients. |

## Public fields

### inputChannelCount

```
public final int inputChannelCount
```

### isDiagonal

```
public final boolean isDiagonal
```

### isIdentity

```
public final boolean isIdentity
```

### isZero

```
public final boolean isZero
```

### outputChannelCount

```
public final int outputChannelCount
```

## Public constructors

### ChannelMixingMatrix

```
public ChannelMixingMatrix(
    int inputChannelCount,
    int outputChannelCount,
    float[] coefficients
)
```

Creates a matrix with the given coefficients in row-major order.

| Parameters |
|---|---|
| `int inputChannelCount` | Number of input channels (rows in the matrix). |
| `int outputChannelCount` | Number of output channels (columns in the matrix). |
| `float[] coefficients` | Non-negative matrix coefficients in row-major order. |

## Public methods

### createForConstantGain

```
public static ChannelMixingMatrix createForConstantGain(
    @IntRange(from = 1, to = 2) int inputChannelCount,
    @IntRange(from = 1, to = 2) int outputChannelCount
)
```

Returns a default constant gain channel mixing matrix that mixes `inputChannelCount` channels into `outputChannelCount` channels.

This method returns an identity matrix if `inputChannelCount` and `
outputChannelCount` are equal.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/IntRange(from = 1, to = 2) int inputChannelCount` | Number of input channels. |
| `@https://developer.android.com/reference/androidx/annotation/IntRange(from = 1, to = 2) int outputChannelCount` | Number of output channels. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException.html` | If no default coefficients are available for the given input and output channel counts. |

### createForConstantPower

```
public static ChannelMixingMatrix createForConstantPower(
    @IntRange(from = 1, to = 6) int inputChannelCount,
    @IntRange(from = 1, to = 2) int outputChannelCount
)
```

Returns a default constant power channel mixing matrix that mixes `inputChannelCount` channels into `outputChannelCount` channels.

This method returns an identity matrix if `inputChannelCount` and `
outputChannelCount` are equal.

Channel counts map to the following layouts:

1. \[MONO\]
2. \[FRONT_LEFT, FRONT_RIGHT\]
3. \[FRONT_LEFT, FRONT_RIGHT, FRONT_CENTER\]
4. \[FRONT_LEFT, FRONT_RIGHT, BACK_LEFT, BACK_RIGHT\]
5. \[FRONT_LEFT, FRONT_RIGHT, FRONT_CENTER, BACK_LEFT, BACK_RIGHT\]
6. \[FRONT_LEFT, FRONT_RIGHT, FRONT_CENTER, LOW_FREQUENCY, BACK_LEFT, BACK_RIGHT\]

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/IntRange(from = 1, to = 6) int inputChannelCount` | Number of input channels. |
| `@https://developer.android.com/reference/androidx/annotation/IntRange(from = 1, to = 2) int outputChannelCount` | Number of output channels. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException.html` | If no default matrix coefficients are implemented for the given input and output channel counts. |

### getInputChannelCount

```
public int getInputChannelCount()
```

### getMixingCoefficient

```
public float getMixingCoefficient(int inputChannel, int outputChannel)
```

Gets the scaling factor for the given input and output channel.

### getOutputChannelCount

```
public int getOutputChannelCount()
```

### isDiagonal

```
public boolean isDiagonal()
```

Returns whether the matrix is square and all non-diagonal coefficients are zero.

### isIdentity

```
public boolean isIdentity()
```

Returns whether this is an identity matrix.

### isSquare

```
public boolean isSquare()
```

Returns whether the input and output channel count is the same.

### isZero

```
public boolean isZero()
```

Returns whether all mixing coefficients are zero.

### scaleBy

```
public ChannelMixingMatrix scaleBy(float scale)
```

Returns a new matrix with the given scaling factor applied to all coefficients.