海康 WebSocket 取流的 Python 实现,定位是分析与研究工具;生产取流用 go-client。两套实现共用同一套解析逻辑,Go 为行为基准 (ADR-0001)。
协议细节见 ../docs/protocol.md,字节级管线见 ../docs/media-pipeline.md。
| 文件 | 职责 |
|---|---|
hik_ws_client.py |
传输层:WebSocket、鉴权、封包、重连 |
hik_media.py |
媒体解析层,仅依赖标准库 |
test_hik_media.py |
回归测试 + ../samples/ 样本回放 |
demo.py |
命令行演示:取流、统计、存帧 |
play.py |
FFmpeg 解码 + OpenCV 实时显示 |
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txtPython 3.8+。hik_media.py 不需要任何依赖;hik_ws_client.py 需要 pycryptodome
(AES/RSA),play.py 另需 opencv-python 与 numpy。
python3 demo.py "wss://example.com:6014/proxy/[1111::2222]:559/openUrl/auth_token"
python3 demo.py "wss://..." --username admin --password yourpassword
python3 demo.py "wss://..." -v # 详细输出
python3 demo.py "wss://..." --reconnect # 断线自动重连
python3 demo.py "wss://..." --save-frames --output-dir ./frames
python3 play.py "wss://..." # FFmpeg 解码 + OpenCV 实时显示import asyncio
from hik_ws_client import HikMediaClient, HikConfig, parse_proxy_url
async def main():
config = parse_proxy_url("wss://host:port/proxy/ip:port/openUrl/auth")
# 或手动构造:HikConfig(proxy_host=..., proxy_port=..., proxy_path=...,
# device_ip=..., device_port=..., username="admin", password="")
client = HikMediaClient(config)
def on_frame(meta, data):
# data 是一个完整的 Annex-B 访问单元,可直接喂解码器
print(f"#{meta.frame_index} {meta.codec} {meta.width}x{meta.height} "
f"key={meta.is_key_frame} pts={meta.pts} {len(data)} bytes")
client.on_frame = on_frame
await client.run()
asyncio.run(main())| 回调 | 参数 | 说明 |
|---|---|---|
on_frame |
(FrameMeta, bytes) |
单个访问单元 + 元信息 |
on_video_data |
(bytes,) |
同样是访问单元,不带元信息;设了 on_frame 时不再触发 |
on_media_info |
(MediaInfo,) |
SDP 解析结果(容器、编码、时钟、参数集) |
on_sps |
(bytes,) |
从码流还原出的 SPS NAL(含起始码) |
on_raw_video |
(bytes,) |
去 RTP 封装、进解复用器之前的容器字节,抓流存档用 |
on_audio_data |
(bytes,) |
音频消息原样下发(未解 PES、未解码) |
on_error |
(str,) |
会话错误 |
FrameMeta:frame_index / is_key_frame / codec / width / height / pts / has_pts / timestamp_ms。has_pts 为真时 pts 是容器给的 90kHz 时间戳,否则是按到达时间合成的。
客户端交付的是完整的 Annex-B 访问单元,可直接喂解码器;本库不内置解码
(ADR-0004)。play.py 就是把
on_video_data 收到的访问单元写进 ffmpeg 的 stdin、读回 MJPEG 显示——自己接解码器时同理,
不需要再做 RTP 解包或容器解析。
cd python-client && python3 -m unittest test_hik_media -v回放仓库根 samples/ 的真机采集并断言与 Go 侧同一组帧数、关键帧数、分辨率。先在仓库根
git lfs pull,否则用例 skip(skip 等于没跑回归)。