{"record":{"id":"f3a7468f8ae83ee7","repo":"pion/webrtc","slug":"w-unsupported-family-1-channel-count","errorCode":null,"errorMessage":"%w: unsupported family 1 channel count","messagePattern":"%w: unsupported family 1 channel count","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/media/oggwriter/oggwriter.go","lineNumber":706,"sourceCode":"\t}\n\n\treturn nil\n}\n\nfunc validateVorbisChannelMapping(streamCount, coupledCount uint8, mapping []byte) error {\n\tvar wantStreams, wantCoupled uint8\n\tvar wantMapping []byte\n\tswitch len(mapping) {\n\tcase 1:\n\t\twantStreams = 1\n\t\twantCoupled = 0\n\t\twantMapping = []byte{0}\n\tcase 2:\n\t\twantStreams = 1\n\t\twantCoupled = 1\n\t\twantMapping = []byte{0, 1}\n\tdefault:\n\t\treturn fmt.Errorf(\"%w: unsupported family 1 channel count\", errInvalidChannelMap)\n\t}\n\tif streamCount != wantStreams || coupledCount != wantCoupled || !bytes.Equal(mapping, wantMapping) {\n\t\treturn fmt.Errorf(\"%w: invalid family 1 mapping\", errInvalidChannelMap)\n\t}\n\n\treturn nil\n}\n\nfunc cloneChannelMapping(mapping channelMapping) channelMapping {\n\tmapping.mapping = append([]byte(nil), mapping.mapping...)\n\n\treturn mapping\n}\n\nfunc defaultOpusTags() OpusTags {\n\treturn OpusTags{Vendor: defaultVendor}\n}\n","sourceCodeStart":688,"sourceCodeEnd":724,"githubUrl":"https://github.com/pion/webrtc/blob/8c25dc09fa9e7c09aac4309ead88093d760432b0/pkg/media/oggwriter/oggwriter.go#L688-L724","documentation":"For Vorbis-style channel mapping family 1, this writer only supports 1-channel (mono) and 2-channel (stereo) layouts; any other mapping length hits the default branch. The error wraps errInvalidChannelMap, so surround/multichannel family-1 tables (3+ channels) are not accepted here.","triggerScenarios":"Passing family=channelMappingFamily1 with a mapping table of length 0 or >= 3 bytes to the channel-mapping validation used when configuring an Opus track.","commonSituations":"Trying to record 5.1/7.1 Opus into the Ogg writer; developers assume multichannel family-1 support because the Vorbis spec defines tables for 3-8 channels, but this writer only supports mono/stereo.","solutions":["Reduce the track to mono or stereo audio before writing.","Split multichannel audio into multiple mono/stereo tracks.","Use family 255 with custom stream counts only if the writer's constraints allow it (still streamCount=1).","Check errors.Is(err, errInvalidChannelMap) to confirm it is a mapping validation failure."],"exampleFix":"// before\nvalidateChannelMapping(channelMappingFamily1, 3, 3, []byte{0,1,2,3,4,5}) // 6ch not supported\n// after\nvalidateChannelMapping(channelMappingFamily1, 2, 1, []byte{0, 1}) // stereo","handlingStrategy":"validation","validationCode":"func supportedFamily1Len(mapping []byte) bool { n := len(mapping); return n == 1 || n == 2 }\nif !supportedFamily1Len(mapping) { return errors.New(\"family 1 supports only mono/stereo here\") }","typeGuard":"func isMonoOrStereo(ch uint16) bool { return ch == 1 || ch == 2 }","tryCatchPattern":"if err := writer.AddTrack(track); err != nil {\n    if errors.Is(err, errInvalidChannelMap) && strings.Contains(err.Error(), \"unsupported family 1 channel count\") {\n        // downmix to mono/stereo and retry\n    }\n    return err\n}","preventionTips":["Downmix multichannel (5.1/7.1) audio to stereo before writing Ogg/Opus here","Split multichannel audio into multiple mono/stereo tracks","Check the writer's supported channel counts (1 or 2) before configuring","Use defaultChannelMapping for automatic valid defaults"],"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"}