{"record":{"id":"a20777d604a1e5a9","repo":"pion/webrtc","slug":"invalid-opus-packet","errorCode":null,"errorMessage":"invalid Opus packet","messagePattern":"invalid Opus packet","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/media/oggwriter/oggwriter.go","lineNumber":55,"sourceCode":"\tidPageSignature                    = \"OpusHead\"\n\tcommentPageSignature               = \"OpusTags\"\n\tdefaultVendor                      = \"pion\"\n\tpageHeaderSignature                = \"OggS\"\n\tpageHeaderSize                     = 27\n\tmaxOggPageSegments                 = 255\n\tnoGranulePosition                  = ^uint64(0)\n\tmaxUint32Length                    = uint64(1<<32 - 1)\n)\n\nvar (\n\terrFileNotOpened        = errors.New(\"file not opened\")\n\terrOutputNotOpened      = errors.New(\"output not opened\")\n\terrInvalidNilPacket     = errors.New(\"invalid nil packet\")\n\terrDuplicateTrackSSRC   = errors.New(\"duplicate Ogg track SSRC\")\n\terrDuplicateTrackSerial = errors.New(\"duplicate Ogg track serial\")\n\terrTracksStarted        = errors.New(\"cannot add Ogg tracks after writing has started\")\n\terrPacketSSRCMismatch   = errors.New(\"RTP packet SSRC does not match Ogg track SSRC\")\n\terrInvalidOpusPacket    = errors.New(\"invalid Opus packet\")\n\terrInvalidChannelCount  = errors.New(\"invalid channel count\")\n\terrInvalidChannelMap    = errors.New(\"invalid channel mapping\")\n\terrInvalidOpusTags      = errors.New(\"invalid OpusTags\")\n)\n\ntype pageRewriter interface {\n\tio.Seeker\n\tio.WriterAt\n}\n\ntype writerConfig struct {\n\tsampleRate     uint32\n\tchannelMapping channelMapping\n\tpageRewriter   pageRewriter\n\topusTags       OpusTags\n}\n\ntype trackConfig struct {","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/pion/webrtc/blob/8c25dc09fa9e7c09aac4309ead88093d760432b0/pkg/media/oggwriter/oggwriter.go#L37-L73","documentation":"errInvalidOpusPacket is returned by opusPacketSampleCount when an RTP payload is not a parseable Opus packet: either the payload is empty or the computed sample count (samples per frame × frame count from the TOC byte) exceeds maxOpusPacketSamples. The writer needs a valid duration per packet to advance the Ogg granule position.","triggerScenarios":"Writing an RTP packet whose payload is empty; an Opus packet whose TOC-implied frame count yields a sample count above the maximum allowed per packet.","commonSituations":"Corrupt or truncated RTP payloads from a lossy network; a codec misconfiguration sending non-Opus data to the writer; hand-crafted packets in tests that violate Opus TOC rules; writing keep-alive/DTMF-style empty payloads.","solutions":["Drop packets with empty payloads before calling WriteRTP","Validate the Opus TOC byte / frame count before writing","Confirm the RTP stream is actually Opus-encoded (correct payload type)","Update the source encoder — it is producing out-of-spec Opus packets"],"exampleFix":"// before\ntrack.WriteRTP(pkt) // pkt.Payload is empty -> errInvalidOpusPacket\n// after\nif len(pkt.Payload) > 0 {\n    if err := track.WriteRTP(pkt); err != nil {\n        log.Printf(\"skip packet: %v\", err)\n    }\n}","handlingStrategy":"validation","validationCode":"func writableOpusPayload(payload []byte) bool {\n    if len(payload) == 0 {\n        return false\n    }\n    // TOC byte: config(5) | stereo(1) | code(2)\n    code := payload[0] & 0x03\n    if code == 3 && len(payload) < 2 { // code 3 requires frame count byte\n        return false\n    }\n    return true\n}","typeGuard":null,"tryCatchPattern":"err := track.WriteRTP(pkt)\nif err != nil && strings.Contains(err.Error(), \"invalid Opus packet\") {\n    log.Printf(\"dropping malformed opus packet: %v\", err)\n    return nil // drop, keep recording\n}","preventionTips":["Drop empty RTP payloads before writing","Validate the Opus TOC byte and frame count","Ensure the negotiated payload type is Opus","Sanitize/repair packets from lossy transports before writing"],"tags":["opus","rtp","validation","media"],"backgroundTag":"invalid-packet-format","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"}