opus头必须位于ogg逻辑流首页且为opushead结构体，魔数为"opus"，需校验version、channel_count等字段并手动按小端序解析，多流场景须遍历serialno匹配。
Opus头在OGG中不是独立帧，而是封装在OpusHead逻辑流首页
OGG不是简单容器，而是基于页（page）的复用格式。Opus音频的编码头信息（采样率、声道数、预跳采样数等）不存于每个音频包，而只出现在逻辑流的第一个ogg_packet里，且必须是OpusHead结构体（RFC 7845 定义）。直接读取ogg_sync_buffer()拿到的数据块，若没按页边界对齐、没识别ogg_stream_packetout()是否返回首包，就容易把普通音频数据误当头解析。
实操建议：
- 必须用
ogg_sync_pageout()先提取完整页，再用ogg_stream_pagein()送入流解复用器，最后调ogg_stream_packetout()逐个取包 - 首个成功取出的
ogg_packet，其packet[0]必须是0x4f（'O'），packet[1]是0x70（'p'），packet[2]是0x75（'u'），packet[3]是0x73（'s'）——这是OpusHead魔数，缺一不可 - 不要跳过
packet[8]开始的version字段（应为0x01），旧版libopus曾容忍非法版本，但合规解析器必须校验
解析OpusHead结构体时，字节序和字段偏移极易出错
OpusHead是小端序、无对齐的固定布局结构，但C++中若用struct直接reinterpret_cast，会因编译器填充或平台字节序导致崩溃或乱值。例如output_gain字段在偏移0x0a处占2字节，若结构体未显式#pragma pack(1)，GCC/Clang可能在前字段后插入填充字节。
实操建议：
- 手动按偏移取字段：用
uint8_t* head = packet->packet，再用le16toh(*(uint16_t*)(head + 10))读output_gain（需<endian.h></endian.h>或自实现小端转主机序） -
channel_count在head[9]，但实际声道映射需结合head[12]（stream_count）和head[13]（coupled_count）推导，不能仅看该字节 - 预跳（pre-skip）值在
head[10]–head[11]，单位是样本点，不是毫秒；播放起始位置要从解码后第一帧减去该值，否则开头有爆音
libogg + libopus组合解析时，op_test_open()不等于能正确提取头
很多示例用op_test_open()判断文件是否Opus，但它只检查页内魔数和流类型，并不验证OpusHead字段合法性（比如stream_count大于channel_count）。结果是函数返回成功，但后续op_read()解码时因头信息矛盾而静音或崩溃。
实操建议：
- 调用
op_test_open()后，必须立即用op_head()获取OggOpusFile*关联的OpusHead指针，并手动校验：head->channel_count > 0 && head->channel_count preskip - 若使用底层
ogg_stream_state自行复用，注意ogg_stream_init()后必须等ogg_stream_packetout()返回非零才进入头解析，否则packet内容未就绪 - Windows下若链接静态
libogg，需确保OGG_EXPORT宏定义一致，否则ogg_sync_state内存布局错位，ogg_sync_buffer()返回缓冲区长度异常
多流OGG（如Opus+Vorbis混流）中，OpusHead可能不在第一页
OGG允许单物理文件含多个逻辑流（stream），每个流有独立serialno。Opus流未必是第一个被写入的流——比如封装工具先写封面图片（FLAC或OPUS元数据流），再写音频流。此时ogg_stream_init()绑定错误serialno，会导致永远取不到OpusHead。
实操建议：
- 遍历所有页，对每个新出现的
serialno调用ogg_stream_init()，再尝试ogg_stream_pagein()+ogg_stream_packetout()，直到某个流的首包匹配OpusHead魔数 - 用
ogg_page_serialno()提取页的serialno，而非依赖流初始化顺序 - libopusfile的
op_test_callbacks()支持自定义IO回调，可在此回调中记录每个流的serialno与类型，避免盲目试探
真正难的不是读出16个字节的头，而是确认这16个字节属于哪个流、有没有被其他流污染、字段值是否在Opus规范约束范围内——这些细节不写进日志，运行时几乎无法定位。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
