{"record":{"id":"46c105cb48706143","repo":"pion/webrtc","slug":"wrong-header-expected-beginning-of-stream","errorCode":null,"errorMessage":"wrong header, expected beginning of stream","messagePattern":"wrong header, expected beginning of stream","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/media/oggreader/oggreader.go","lineNumber":27,"sourceCode":"\t\"errors\"\n\t\"fmt\"\n\t\"io\"\n\t\"strings\"\n)\n\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).","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/pion/webrtc/blob/8c25dc09fa9e7c09aac4309ead88093d760432b0/pkg/media/oggreader/oggreader.go#L9-L45","documentation":"errBadIDPageType is returned when the first Ogg page of an Opus stream is not marked as the beginning-of-stream page. The library requires the ID header page to have headerType 0x02, as mandated by the Opus-in-Ogg encapsulation spec. If the stream does not start with a proper ID page, parsing cannot proceed safely.","triggerScenarios":"Calling NewWith/New on a stream whose first Ogg page header has headerType != 0x02 (validateOpusPageHeader at oggreader.go:209). Also triggered directly in tests that feed a malformed ID page.","commonSituations":"Joining a mid-stream Ogg capture (recording started after the ID page was written), trimming a file so the first page was removed, concatenating streams so the reader starts on a continuation page, or feeding the reader a non-Opus Ogg page.","solutions":["Ensure the stream begins from byte 0 with the original ID header page (headerType 0x02)","Re-record or re-mux the file so the Opus ID page is first (e.g. with ffmpeg/oggz)","Verify you are not seeking or skipping bytes before handing the reader to NewWith/New"],"exampleFix":"// before: file starts mid-stream\nf, _ := os.Open(\"trimmed.opus\")\nr, _ := oggreader.NewWith(f)\n// after: remux so ID page is first\n// ffmpeg -i trimmed.opus -c copy fixed.opus\nf, _ := os.Open(\"fixed.opus\")\nr, _ := oggreader.NewWith(f)","handlingStrategy":"validation","validationCode":"// read the first page header yourself before handing off\nhdr := make([]byte, 27)\nif _, err := io.ReadFull(f, hdr); err != nil { return err }\nif hdr[0] != 'O' || hdr[1] != 'g' || hdr[2] != 'g' || hdr[3] != 'S' { return errors.New(\"not ogg\") }\nif hdr[5]&0x02 == 0 { return errors.New(\"first page is not beginning-of-stream\") }\nf.Seek(0, io.SeekStart)","typeGuard":"func isBeginningOfStreamPage(hdr [27]byte) bool {\n    return hdr[0] == 'O' && hdr[1] == 'g' && hdr[2] == 'g' && hdr[3] == 'S' && hdr[5]&0x02 != 0\n}","tryCatchPattern":"_, hdr, err := oggreader.NewWith(f)\nif errors.Is(err, oggreader.ErrBadIDPageType) {\n    // remux/re-record: stream does not start with ID page\n}","preventionTips":["Always feed the reader from the very first byte of the file","Never seek past the ID header before constructing the reader","Use oggz/ffmpeg to validate files recorded or trimmed by your pipeline"],"tags":["ogg","opus","stream-format","audio"],"backgroundTag":"ogg-invalid-stream-header","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"}