pion/webrtc · error

%w: unsupported family 1 channel count

Error message

%w: unsupported family 1 channel count

What it means

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.

Source

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

	}

	return nil
}

func validateVorbisChannelMapping(streamCount, coupledCount uint8, mapping []byte) error {
	var wantStreams, wantCoupled uint8
	var wantMapping []byte
	switch len(mapping) {
	case 1:
		wantStreams = 1
		wantCoupled = 0
		wantMapping = []byte{0}
	case 2:
		wantStreams = 1
		wantCoupled = 1
		wantMapping = []byte{0, 1}
	default:
		return fmt.Errorf("%w: unsupported family 1 channel count", errInvalidChannelMap)
	}
	if streamCount != wantStreams || coupledCount != wantCoupled || !bytes.Equal(mapping, wantMapping) {
		return fmt.Errorf("%w: invalid family 1 mapping", errInvalidChannelMap)
	}

	return nil
}

func cloneChannelMapping(mapping channelMapping) channelMapping {
	mapping.mapping = append([]byte(nil), mapping.mapping...)

	return mapping
}

func defaultOpusTags() OpusTags {
	return OpusTags{Vendor: defaultVendor}
}

View on GitHub (pinned to 8c25dc09fa)

Solutions

1. Reduce the track to mono or stereo audio before writing.
2. Split multichannel audio into multiple mono/stereo tracks.
3. Use family 255 with custom stream counts only if the writer's constraints allow it (still streamCount=1).
4. Check errors.Is(err, errInvalidChannelMap) to confirm it is a mapping validation failure.

Example fix

// before
validateChannelMapping(channelMappingFamily1, 3, 3, []byte{0,1,2,3,4,5}) // 6ch not supported
// after
validateChannelMapping(channelMappingFamily1, 2, 1, []byte{0, 1}) // stereo

func supportedFamily1Len(mapping []byte) bool { n := len(mapping); return n == 1 || n == 2 }
if !supportedFamily1Len(mapping) { return errors.New("family 1 supports only mono/stereo here") }

func isMonoOrStereo(ch uint16) bool { return ch == 1 || ch == 2 }

if err := writer.AddTrack(track); err != nil {
    if errors.Is(err, errInvalidChannelMap) && strings.Contains(err.Error(), "unsupported family 1 channel count") {
        // downmix to mono/stereo and retry
    }
    return err
}

When it happens

Trigger: Passing family=channelMappingFamily1 with a mapping table of length 0 or >= 3 bytes to the channel-mapping validation used when configuring an Opus track.

Common situations: 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.

Related errors

• %w: stream count must be one
• %w: coupled count exceeds stream count
• %w: channel map entry is out of range
• %w: invalid family 2 mapping
• %w: invalid family 1 mapping

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