{"record":{"id":"09159ab82029129b","repo":"pion/webrtc","slug":"w-coupled-count-exceeds-stream-count","errorCode":null,"errorMessage":"%w: coupled count exceeds stream count","messagePattern":"%w: coupled count exceeds stream count","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/media/oggwriter/oggwriter.go","lineNumber":662,"sourceCode":"\nfunc validateChannelMappingFamily(family uint8) error {\n\tswitch family {\n\tcase channelMappingFamily1, channelMappingFamily2, channelMappingFamily255:\n\t\treturn nil\n\tdefault:\n\t\treturn fmt.Errorf(\"%w: unsupported family %d\", errInvalidChannelMap, family)\n\t}\n}\n\nfunc validateChannelMappingLayout(streamCount, coupledCount uint8, mapping []byte) error {\n\tif len(mapping) == 0 || len(mapping) > math.MaxUint8 {\n\t\treturn errInvalidChannelCount\n\t}\n\tif streamCount != 1 {\n\t\treturn fmt.Errorf(\"%w: stream count must be one\", errInvalidChannelMap)\n\t}\n\tif coupledCount > streamCount {\n\t\treturn fmt.Errorf(\"%w: coupled count exceeds stream count\", errInvalidChannelMap)\n\t}\n\n\tdecodedChannels := int(streamCount) + int(coupledCount)\n\tfor _, channel := range mapping {\n\t\tif channel != math.MaxUint8 && int(channel) >= decodedChannels {\n\t\t\treturn fmt.Errorf(\"%w: channel map entry is out of range\", errInvalidChannelMap)\n\t\t}\n\t}\n\n\treturn nil\n}\n\nfunc validateFamilySpecificChannelMapping(\n\tfamily uint8,\n\tstreamCount uint8,\n\tcoupledCount uint8,\n\tmapping []byte,\n) error {","sourceCodeStart":644,"sourceCodeEnd":680,"githubUrl":"https://github.com/pion/webrtc/blob/8c25dc09fa9e7c09aac4309ead88093d760432b0/pkg/media/oggwriter/oggwriter.go#L644-L680","documentation":"validateChannelMappingLayout returns this when coupledCount is greater than streamCount. In the Opus mapping family format, coupledCount is the number of stereo (coupled) streams and must not exceed the total number of streams; with streamCount fixed at 1 in this writer, only coupledCount of 0 or 1 is valid. The error wraps errInvalidChannelMap.","triggerScenarios":"Calling the channel-mapping validation path with coupledCount > streamCount, e.g. streamCount=1 and coupledCount=2, or passing coupledCount=1 with streamCount=0.","commonSituations":"Misreading the Opus spec where coupled counts enumerate stereo decoders: developers set coupledCount equal to the number of coupled channels (2) instead of the number of coupled streams (1); also occurs when counts are accidentally swapped with each other or with channelCount.","solutions":["Ensure coupledCount <= streamCount, with streamCount=1 use coupledCount 0 (mono) or 1 (stereo).","Remember coupledCount counts streams (each covering 2 channels), not individual channels.","Use the library defaults from defaultChannelMapping for 1 or 2 channel audio.","Guard with errors.Is(err, errInvalidChannelMap) for diagnostics."],"exampleFix":"// before\nvalidateChannelMapping(family, 1, 2, mapping) // coupled=2 > streams=1\n// after\nvalidateChannelMapping(family, 1, 1, mapping)","handlingStrategy":"validation","validationCode":"func validCoupledCount(streams, coupled uint8) bool { return coupled <= streams }\nif !validCoupledCount(cfg.StreamCount, cfg.CoupledCount) { return errors.New(\"coupled count exceeds stream count\") }","typeGuard":"func isCoupledCountInRange(m ChannelMapping) bool { return m.CoupledCount <= m.StreamCount }","tryCatchPattern":"if err := writer.Configure(mapping); err != nil {\n    if errors.Is(err, errInvalidChannelMap) { /* log mapping fields and fix counts */ }\n    return err\n}","preventionTips":["Remember coupledCount counts stereo streams, not channels","Keep coupledCount 0 (mono) or 1 (stereo) since streamCount must be 1","Never swap streamCount and coupledCount variables","Use the library's default mapping for 1-2 channel audio"],"tags":["go","ogg","opus","channel-mapping","validation"],"backgroundTag":"invalid-opus-channel-mapping","analyzedSha":"8c25dc09fa9e7c09aac4309ead88093d760432b0","analyzedAt":"2026-09-03T21:56:56.182Z","contentChangedAt":"2026-09-03T21:56:56.182Z","schemaVersion":2},"datasetVersion":"2026-09-11T07:07:21.782Z"}