pion/webrtc · error

invalid channel mapping

Error message

invalid channel mapping

What it means

errInvalidChannelMap is wrapped by fmt.Errorf in oggwriter's channel-mapping validation helpers for the Opus comment header. It fires when a caller-supplied Opus channel mapping is invalid: an unsupported mapping family (only families 1, 2, and 255 are accepted), stream count not equal to one, coupled count exceeding stream count, or a mapping table entry pointing to a channel outside the decoded channel count.

Source

Thrown at pkg/media/oggwriter/oggwriter.go:57

func validateChannelMappingFamily(family uint8) error {
	switch family {
	case channelMappingFamily1, channelMappingFamily2, channelMappingFamily255:
		return nil
	default:
		return fmt.Errorf("%w: unsupported family %d", errInvalidChannelMap, family)
	}
}

func validateChannelMappingLayout(streamCount, coupledCount uint8, mapping []byte) error {
	if len(mapping) == 0 || len(mapping) > math.MaxUint8 {
		return errInvalidChannelCount
	}
	if streamCount != 1 {
		return fmt.Errorf("%w: stream count must be one", errInvalidChannelMap)
	}
	if coupledCount > streamCount {
		return fmt.Errorf("%w: coupled count exceeds stream count", errInvalidChannelMap)
	}

	decodedChannels := int(streamCount) + int(coupledCount)
	for _, channel := range mapping {
		if channel != math.MaxUint8 && int(channel) >= decodedChannels {
			return fmt.Errorf("%w: channel map entry is out of range", errInvalidChannelMap)
		}
	}

	return nil
}

View on GitHub (pinned to 8c25dc09fa)

Solutions

1. Use a supported channel mapping family: 1, 2, or 255
2. Ensure streamCount is 1 and coupledCount <= streamCount
3. Keep every mapping-table entry either 255 (silent) or an index < streamCount+coupledCount
4. Build the mapping with the helper API instead of hand-assembling raw values

When it happens

Trigger: Thrown at pkg/media/oggwriter/oggwriter.go:57 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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