{"record":{"id":"60f802af7588babd","repo":"pion/webrtc","slug":"w-invalid-family-1-mapping","errorCode":null,"errorMessage":"%w: invalid family 1 mapping","messagePattern":"%w: invalid family 1 mapping","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/media/oggwriter/oggwriter.go","lineNumber":709,"sourceCode":"}\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\nfunc cloneOpusTags(opusTags OpusTags) OpusTags {\n\topusTags.UserComments = cloneUserComments(opusTags.UserComments)\n","sourceCodeStart":691,"sourceCodeEnd":727,"githubUrl":"https://github.com/pion/webrtc/blob/8c25dc09fa9e7c09aac4309ead88093d760432b0/pkg/media/oggwriter/oggwriter.go#L691-L727","documentation":"For mapping family 1, once the mapping length (1 or 2) is recognized, the stream count, coupled count, and mapping bytes must exactly match the canonical Vorbis mono ({0}: 1/0) or stereo ({0,1}: 1/1) tables. Any other combination returns this error, wrapped around errInvalidChannelMap.","triggerScenarios":"Passing family=channelMappingFamily1 with len(mapping)==1 or 2 but inconsistent streamCount/coupledCount/mapping bytes, e.g. streamCount=1, coupledCount=0, mapping []byte{0,1}, or mapping []byte{1,0}.","commonSituations":"Swapping coupledCount with the number of channels; reordering the mapping entries (e.g. channel-swap tables); typos when hand-rolling the mapping instead of using defaults.","solutions":["Use the exact canonical tables: mono -> streams=1, coupled=0, {0}; stereo -> streams=1, coupled=1, {0,1}.","Compare your table with bytes.Equal against the canonical mapping to spot ordering issues.","Prefer defaultChannelMapping(channelCount) instead of a custom family-1 mapping.","Handle via errors.Is(err, errInvalidChannelMap) in caller diagnostics."],"exampleFix":"// before\nvalidateChannelMapping(channelMappingFamily1, 1, 0, []byte{0, 1}) // mono counts, stereo table\n// after\nvalidateChannelMapping(channelMappingFamily1, 1, 1, []byte{0, 1})","handlingStrategy":"validation","validationCode":"var canonical = map[int]struct{ s, c uint8; m []byte }{\n    1: {1, 0, []byte{0}},\n    2: {1, 1, []byte{0, 1}},\n}\nfunc matchesCanonical(n int, s, c uint8, m []byte) bool {\n    w, ok := canonical[n]; return ok && s == w.s && c == w.c && bytes.Equal(m, w.m)\n}","typeGuard":"func isCanonicalFamily1(s, c uint8, m []byte) bool {\n    if len(m) == 1 { return s == 1 && c == 0 && m[0] == 0 }\n    if len(m) == 2 { return s == 1 && c == 1 && m[0] == 0 && m[1] == 1 }\n    return false\n}","tryCatchPattern":"if err := validateChannelMapping(family, s, c, m); err != nil {\n    if errors.Is(err, errInvalidChannelMap) { /* compare against canonical {0}/{0,1} tables */ }\n    return err\n}","preventionTips":["Use bytes.Equal against {0} or {0,1} rather than hand-writing tables","Set counts to match the table: mono 1/0, stereo 1/1","Don't reorder mapping entries for channel swapping at write time","Prefer defaultChannelMapping(channelCount)"],"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"}