ChannelMixingMatrix

Kotlin |Java

@UnstableApi
public final class ChannelMixingMatrix

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`	`inputChannelCount`
`final boolean`	`isDiagonal`
`final boolean`	`isIdentity`
`final boolean`	`isZero`
`final int`	`outputChannelCount`

Public constructors
`ChannelMixingMatrix( int inputChannelCount, int outputChannelCount, float[] coefficients )` Creates a matrix with the given coefficients in row-major order.

Public methods
`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.
`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.
`int`	`getInputChannelCount()`
`float`	`getMixingCoefficient(int inputChannel, int outputChannel)` Gets the scaling factor for the given input and output channel.
`int`	`getOutputChannelCount()`
`boolean`	`isDiagonal()` Returns whether the matrix is square and all non-diagonal coefficients are zero.
`boolean`	`isIdentity()` Returns whether this is an identity matrix.
`boolean`	`isSquare()` Returns whether the input and output channel count is the same.
`boolean`	`isZero()` Returns whether all mixing coefficients are zero.
`ChannelMixingMatrix`	`scaleBy(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
`@IntRange(from = 1, to = 2) int inputChannelCount`	Number of input channels.
`@IntRange(from = 1, to = 2) int outputChannelCount`	Number of output channels.

Throws
`java.lang.UnsupportedOperationException`	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:

[MONO]
[FRONT_LEFT, FRONT_RIGHT]
[FRONT_LEFT, FRONT_RIGHT, FRONT_CENTER]
[FRONT_LEFT, FRONT_RIGHT, BACK_LEFT, BACK_RIGHT]
[FRONT_LEFT, FRONT_RIGHT, FRONT_CENTER, BACK_LEFT, BACK_RIGHT]
[FRONT_LEFT, FRONT_RIGHT, FRONT_CENTER, LOW_FREQUENCY, BACK_LEFT, BACK_RIGHT]

Parameters
`@IntRange(from = 1, to = 6) int inputChannelCount`	Number of input channels.
`@IntRange(from = 1, to = 2) int outputChannelCount`	Number of output channels.

Throws
`java.lang.UnsupportedOperationException`	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.