pion/webrtc · error

unsupported channel mapping family

Error message

unsupported channel mapping family

What it means

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.

Source

Thrown at pkg/media/oggreader/oggreader.go:32

const (
	pageHeaderTypeBeginningOfStream = 0x02
	pageHeaderSignature             = "OggS"

	idPageBasePayloadLength = 19
	pageHeaderLen           = 27
)

var (
	errNilStream                       = errors.New("stream is nil")
	errBadIDPageSignature              = errors.New("bad header signature")
	errBadOpusTagsSignature            = errors.New("bad opus tags signature")
	errBadIDPageType                   = errors.New("wrong header, expected beginning of stream")
	errBadIDPageLength                 = errors.New("payload for id page must be 19 bytes")
	errBadIDPagePayloadSignature       = errors.New("bad payload signature")
	errShortPageHeader                 = errors.New("not enough data for payload header")
	errChecksumMismatch                = errors.New("expected and actual checksum do not match")
	errUnsupportedChannelMappingFamily = errors.New("unsupported channel mapping family")
)

// OggReader is used to read Ogg files and return page payloads.
type OggReader struct {
	stream               io.Reader
	bytesReadSuccesfully int64
	checksumTable        *[256]uint32
	doChecksum           bool
}

// OggHeader contains Opus codec metadata parsed from an Opus ID page.
// This header is extracted from an Ogg page payload that starts with the OpusHead
// signature (the first page of an Opus stream in an Ogg container).
//
// Use OggPageHeader.OpusPacketType() to classify a page payload as OpusHead,
// and OggPageHeader.ParseOpusHeader() to parse the OpusHead payload.
//
// https://tools.ietf.org/html/rfc7845.html#section-3

View on GitHub (pinned to 8c25dc09fa)

Solutions

1. Re-encode the audio with mapping family 0 (mono/stereo) or 1 (vorbis channel order): ffmpeg -c:a libopus -mapping_family 0
2. If ambisonics is needed, downmix to stereo before ingestion
3. Extend/patch the reader to support the required family if you control the codebase

Example fix

// before
// ffmpeg -i in.opus -c:a libopus out.opus  (may keep mapping family 3)
// after
// ffmpeg -i in.opus -c:a libopus -mapping_family 0 -ac 2 out.opus

// after ParseOpusHead succeeds:
head, err := oggreader.ParseOpusHead(payload)
if err != nil { return err }
if head.ChannelMappingFamily > 2 {
    return fmt.Errorf("unsupported mapping family %d; remux with mapping_family 0 or 1", head.ChannelMappingFamily)
}

func supportsChannelMapping(family byte) bool {
    return family <= 2
}

_, hdr, err := oggreader.NewWith(f)
if errors.Is(err, oggreader.ErrUnsupportedChannelMappingFamily) {
    // downmix or re-encode input before ingestion
}

When it happens

Trigger: Parsing an OpusHead whose mapping family byte is 3 (ambisonics) or any value > 2 (oggreader.go:245-247).

Common situations: Decoding ambisonic/spatial Opus recordings (e.g. from VR/360 capture tools), exotic or future mapping families produced by newer encoders.

Related errors

• %w: ambisonics family type 3 is not supported
• bad opus tags signature
• wrong header, expected beginning of stream
• payload for id page must be 19 bytes
• bad payload signature

AI-assisted analysis of pion/webrtc@8c25dc09fa (2026-09-03). Data as JSON: /api/errors/dd50154ce4199eab. Report an issue: GitHub.