{"record":{"id":"dd50154ce4199eab","repo":"pion/webrtc","slug":"unsupported-channel-mapping-family","errorCode":null,"errorMessage":"unsupported channel mapping family","messagePattern":"unsupported channel mapping family","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/media/oggreader/oggreader.go","lineNumber":32,"sourceCode":"\nconst (\n\tpageHeaderTypeBeginningOfStream = 0x02\n\tpageHeaderSignature             = \"OggS\"\n\n\tidPageBasePayloadLength = 19\n\tpageHeaderLen           = 27\n)\n\nvar (\n\terrNilStream                       = errors.New(\"stream is nil\")\n\terrBadIDPageSignature              = errors.New(\"bad header signature\")\n\terrBadOpusTagsSignature            = errors.New(\"bad opus tags signature\")\n\terrBadIDPageType                   = errors.New(\"wrong header, expected beginning of stream\")\n\terrBadIDPageLength                 = errors.New(\"payload for id page must be 19 bytes\")\n\terrBadIDPagePayloadSignature       = errors.New(\"bad payload signature\")\n\terrShortPageHeader                 = errors.New(\"not enough data for payload header\")\n\terrChecksumMismatch                = errors.New(\"expected and actual checksum do not match\")\n\terrUnsupportedChannelMappingFamily = errors.New(\"unsupported channel mapping family\")\n)\n\n// OggReader is used to read Ogg files and return page payloads.\ntype OggReader struct {\n\tstream               io.Reader\n\tbytesReadSuccesfully int64\n\tchecksumTable        *[256]uint32\n\tdoChecksum           bool\n}\n\n// OggHeader contains Opus codec metadata parsed from an Opus ID page.\n// This header is extracted from an Ogg page payload that starts with the OpusHead\n// signature (the first page of an Opus stream in an Ogg container).\n//\n// Use OggPageHeader.OpusPacketType() to classify a page payload as OpusHead,\n// and OggPageHeader.ParseOpusHeader() to parse the OpusHead payload.\n//\n// https://tools.ietf.org/html/rfc7845.html#section-3","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/pion/webrtc/blob/8c25dc09fa9e7c09aac4309ead88093d760432b0/pkg/media/oggreader/oggreader.go#L14-L50","documentation":"errUnsupportedChannelMappingFamily is returned by parseChannelMapping when the OpusHead channel mapping family is not 0, 1, or 2. Family 3 (ambisonics/projection) is explicitly rejected with a wrapped message, and any other value hits the default case. The library only supports the standard and multichannel (vorbis-style) mappings.","triggerScenarios":"Parsing an OpusHead whose mapping family byte is 3 (ambisonics) or any value > 2 (oggreader.go:245-247).","commonSituations":"Decoding ambisonic/spatial Opus recordings (e.g. from VR/360 capture tools), exotic or future mapping families produced by newer encoders.","solutions":["Re-encode the audio with mapping family 0 (mono/stereo) or 1 (vorbis channel order): ffmpeg -c:a libopus -mapping_family 0","If ambisonics is needed, downmix to stereo before ingestion","Extend/patch the reader to support the required family if you control the codebase"],"exampleFix":"// before\n// ffmpeg -i in.opus -c:a libopus out.opus  (may keep mapping family 3)\n// after\n// ffmpeg -i in.opus -c:a libopus -mapping_family 0 -ac 2 out.opus","handlingStrategy":"validation","validationCode":"// after ParseOpusHead succeeds:\nhead, err := oggreader.ParseOpusHead(payload)\nif err != nil { return err }\nif head.ChannelMappingFamily > 2 {\n    return fmt.Errorf(\"unsupported mapping family %d; remux with mapping_family 0 or 1\", head.ChannelMappingFamily)\n}","typeGuard":"func supportsChannelMapping(family byte) bool {\n    return family <= 2\n}","tryCatchPattern":"_, hdr, err := oggreader.NewWith(f)\nif errors.Is(err, oggreader.ErrUnsupportedChannelMappingFamily) {\n    // downmix or re-encode input before ingestion\n}","preventionTips":["Pre-screen inputs with ffprobe for ambisonics (mapping family 3)","Enforce mapping_family 0/1 in your encoding pipeline","Document codec constraints for upstream producers"],"tags":["ogg","opus","audio-channels","unsupported-feature"],"backgroundTag":"unsupported-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"}