{"record":{"id":"8be513e17a97dfb4","repo":"google/ExoPlayer","slug":"coefficient-at-index-i-is-negative","errorCode":null,"errorMessage":"Coefficient at index {i} is negative.","messagePattern":"Coefficient at index (.+?) is negative\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"library/common/src/main/java/com/google/android/exoplayer2/audio/ChannelMixingMatrix.java","lineNumber":192,"sourceCode":"        \"Default channel mixing coefficients for \"\n            + inputChannelCount\n            + \"->\"\n            + outputChannelCount\n            + \" are not yet implemented.\");\n  }\n\n  private static float[] initializeIdentityMatrix(int channelCount) {\n    float[] coefficients = new float[channelCount * channelCount];\n    for (int c = 0; c < channelCount; c++) {\n      coefficients[channelCount * c + c] = 1f;\n    }\n    return coefficients;\n  }\n\n  private static float[] checkCoefficientsValid(float[] coefficients) {\n    for (int i = 0; i < coefficients.length; i++) {\n      if (coefficients[i] < 0f) {\n        throw new IllegalArgumentException(\"Coefficient at index \" + i + \" is negative.\");\n      }\n    }\n    return coefficients;\n  }\n}\n","sourceCodeStart":174,"sourceCodeEnd":198,"githubUrl":"https://github.com/google/ExoPlayer/blob/dd430f7053a1a3958deea3ead6a0565150c06bfc/library/common/src/main/java/com/google/android/exoplayer2/audio/ChannelMixingMatrix.java#L174-L198","documentation":"ChannelMixingMatrix validates user-supplied coefficient arrays with checkCoefficientsValid and throws IllegalArgumentException for any negative value — every coefficient must be >= 0f. The restriction exists because the mixing implementation assumes non-negative gains (it cannot express phase inversion); negative gains such as the -0.707 used in some surround-downmix recipes are rejected.","triggerScenarios":"Passing a float[] containing any value < 0f to the ChannelMixingMatrix constructor (create(input, output, coefficients)) — most commonly a copy of ITU-R BS.775 downmix coefficients that use -0.7071 for surround channels.","commonSituations":"Porting a downmix matrix from another DSP library that permits negative (phase-inverting) gains; typo'd or wrap-around index math producing spurious negative floats.","solutions":["Clamp or zero out negative coefficients: use Math.abs(coef) only if phase truly does not matter for your use, otherwise set surround contributions to 0f or +gain.","Do phase inversion in a different processor that supports it (e.g. a custom AudioProcessor), keeping the ChannelMixingMatrix coefficients non-negative.","Validate the array yourself before construction to fail with a clearer message."],"exampleFix":"// before\nfloat[] bs775 = {1,0, 0,1, .707f,.707f, 0,0, -.707f,0, 0,-.707f};\nChannelMixingMatrix.create(6, 2, bs775); // throws IllegalArgumentException at index 8\n\n// after\nfloat[] nonNeg = new float[bs775.length];\nfor (int i = 0; i < bs775.length; i++) nonNeg[i] = Math.max(0f, bs775[i]);\nChannelMixingMatrix.create(6, 2, nonNeg);","handlingStrategy":"validation","validationCode":"private static float[] requireNonNegative(float[] coefficients) {\n  for (int i = 0; i < coefficients.length; i++) {\n    if (coefficients[i] < 0f) {\n      throw new IllegalArgumentException(\"Coefficient[\" + i + \"]=\" + coefficients[i] + \" must be >= 0\");\n    }\n  }\n  return coefficients;\n}\nfloat[] safe = requireNonNegative(coeffs);\nChannelMixingMatrix.create(in, out, safe);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["ChannelMixingMatrix cannot express phase inversion — clamp or drop negative gains before construction.","Sanitize ported coefficient tables from other DSP libraries (BS.775 uses -0.7071 for surrounds).","Validate array length (in*out) and finiteness (no NaN/Inf) alongside non-negativity."],"tags":["exoplayer","media3","audio","channel-mixing","validation"],"backgroundTag":null,"analyzedSha":"dd430f7053a1a3958deea3ead6a0565150c06bfc","analyzedAt":"2026-08-14T12:22:02.982Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}