vdk

VDK — Video Development Kit

Go 流媒体开发工具包 — 协议接入、编解码与流编排；生产交付请以 stable 能力为边界，实验/占位能力见下文说明。

核心能力

能力边界说明

• stable
  • format.RegisterAll() 稳定协议集（mp4/ts/rtmp/rtsp/flv/aac/srt/hls 本地输出）
  • stream / pkg/manager / pkg/streammgr 的单进程流会话治理
  • pkg/recording.LocalStorage 与本地 ts/mp4/flv 分段录制
  • pkg/cluster.StaticDiscovery
• 条件能力
  • 转码能力：stream.Transcode / Builder.Transcode() 在非 CGO 模式下调用系统 ffmpeg 可执行文件；cgo/pipeline / cgo/sdk 提供帧级 FFmpeg 绑定，pkg/abr 提供 HLS 多档位执行链。
  • ABR (pkg/abr)：HLS 多档位输出已落地，依赖系统 ffmpeg；DASH 仍按 fail-fast 边界处理。
  • 多云录制 (pkg/recording)：S3/MinIO/GCS XML API 对象存储已落地最小真实 I/O，依赖对象存储凭证与网络。
  • 集群发现 (pkg/cluster)：Consul Agent HTTP API、etcd v3 JSON gateway、Kubernetes ConfigMap 后端已落地最小真实实现，依赖可达后端、Token/RBAC 与 TTL 策略。
• not implemented / fail-fast
  • ABR DASH 输出：pkg/abr 当前仅承诺 HLS 多档位输出，DASH 仍 fail-fast。

生产交付建议

• 能力选型：以 stable/conditional 能力为生产边界；ABR HLS、S3/GCS 录制后端与 Consul/Etcd/K8s 发现为最小真实落地能力，仍需按环境配置 ffmpeg、对象存储凭证、服务发现后端与 RBAC。
• 运行时治理：优先使用显式 handler registry 或 CLI composition root，避免在业务层散落 format.RegisterAll()。
• 部署形态：当前 cmd/vdk serve 适合单进程、单节点、边车式交付；不承诺分布式控制面、高可用选主、持久化会话恢复。
• 存储与目录：HLSDir / 录制目录应挂载到持久卷；不要将临时目录直接视为生产持久层。
• 网络与暴露：生产环境建议将 HTTP/RTMP 暴露在反向代理或 LB 后，并由外层统一处理 TLS、鉴权、限流与审计。
• 交付门禁：仓库 CI 已增加 gofmt / go vet / go test ./... / go test -race ./... / ffmpeg7 build-tag / CLI 本地媒体 E2E / coverage smoke / govulncheck。
• 观测性：cmd/vdk serve 已补齐 logging.level / logging.format / metrics / livez|readyz 接缝；生产环境仍应统一接入外部日志、指标与追踪系统。

CI 质量门禁

仓库内置 Go CI（见 .github/workflows/go-ci.yml），默认执行：

• gofmt -l：格式一致性
• go vet ./...：静态分析
• go test ./...：全模块回归
• go test -race ./...：并发数据竞争扫描
• go test -tags ffmpeg7 ./...：CGO/FFmpeg 条件路径验证
• scripts/e2e_cli_local.sh：本地媒体 probe/transcode/HLS CLI E2E
• go test -cover ./...：覆盖率 smoke
• govulncheck ./...：依赖与标准库漏洞扫描

建议将上述门禁视为所有变更合并前的最低门槛。

快速开始

安装

go get cnb.cool/svn/vdk@latest

第三方导入与 CGO 构建矩阵

常用环境准备：

# Ubuntu/Debian
sudo apt-get install -y pkg-config libavcodec-dev libavformat-dev libavutil-dev libswresample-dev libswscale-dev

# macOS
brew install ffmpeg pkg-config

# 条件路径验证
CGO_ENABLED=1 go test -tags ffmpeg7 ./...

CLI 工具

go install cnb.cool/svn/vdk/cmd/vdk@latest

# 探测流信息
vdk probe rtsp://example.com/live/stream

# 封装转换/复制（不重编码）
vdk transcode -i input.mp4 -o output.flv

# 启动流媒体服务
vdk serve -c config.yaml

# 性能基准测试
vdk benchmark

Builder API — 流式构建

package main

import (
	"context"
	"time"

	"cnb.cool/svn/vdk/format"
	"cnb.cool/svn/vdk/stream"
)

func main() {
	format.RegisterAll()

	s, err := stream.New().
		Name("cam-01").
		Input("rtsp://admin:pass@192.168.1.100/live").
		WithTimeout(10 * time.Second).
		LowLatency().
		Output("rtmp://cdn.example.com/live/cam-01").
			WithTimeout(5 * time.Second).
			Done().
		Output("srt://backup.example.com:9000").
			SRTConfig(120*time.Millisecond, "", "live/cam-01").
			Done().
		Build()
	if err != nil {
		panic(err)
	}

	s.OnEvent(func(e stream.EventData) {
		switch e.Event {
		case stream.EventReconnecting:
			println("重连中...")
		case stream.EventError:
			println("错误:", e.Error.Error())
		}
	})

	if err := s.Run(context.Background()); err != nil {
		panic(err)
	}
}

转码能力边界

stream.Transcode / TranscodeWithConfig / QuickTranscode.Run 与 Builder.Transcode() 已重构为系统 ffmpeg 执行层，默认不依赖 CGO；通过 TranscodeConfig.FFmpegPath、TranscodeBuilder.FFmpegPath() 或环境变量 VDK_FFMPEG_PATH 指定可执行文件。需要帧级内存控制、深度硬件上下文或自定义 pipeline 时使用 cnb.cool/svn/vdk/cgo/sdk / cgo/pipeline，ABR 多档位 HLS 使用 pkg/abr。

低级 API — Demux/Mux

package main

import (
	"cnb.cool/svn/vdk/av/avutil"
	"cnb.cool/svn/vdk/format"
)

func main() {
	format.RegisterAll()

	demuxer, err := avutil.Open("rtsp://example.com/live")
	if err != nil {
		panic(err)
	}
	defer demuxer.Close()

	muxer, err := avutil.Create("output.mp4")
	if err != nil {
		panic(err)
	}
	defer muxer.Close()

	streams, _ := demuxer.Streams()
	muxer.WriteHeader(streams)
	avutil.CopyPackets(muxer, demuxer)
	muxer.WriteTrailer()
}

事件系统

av/event 包提供协议传输层的通用事件机制，14 种事件类型覆盖连接全生命周期。

package main

import (
	"fmt"

	"cnb.cool/svn/vdk/av/event"
	"cnb.cool/svn/vdk/format/srt"
)

func main() {
	conn, err := srt.Dial("srt://relay.example.com:9000?streamid=live/test")
	if err != nil {
		panic(err)
	}
	defer conn.Close()

	// 通过 EventBus 监听事件
	conn.EventBus = event.NewBus()

	conn.EventBus.On(event.Connected, func(d event.Data) {
		fmt.Printf("[%s] 已连接: %s\n", d.Protocol, d.URL)
	})

	conn.EventBus.On(event.StreamReady, func(d event.Data) {
		fmt.Printf("流就绪, codec 数量: %d\n", len(d.Codec))
	})

	conn.EventBus.On(event.Stats, func(d event.Data) {
		if stats, ok := d.Stats.(srt.Stats); ok {
			fmt.Printf("RTT: %dms, 丢包率: %.2f%%\n",
				stats.RTT.Milliseconds(), stats.PacketLossRate*100)
		}
	})

	conn.EventBus.On(event.Error, func(d event.Data) {
		fmt.Printf("错误: %v\n", d.Error)
	})

	// OnAll 接收所有事件
	conn.EventBus.OnAll(func(d event.Data) {
		fmt.Printf("[%s] %s @ %s\n", d.Protocol, d.Event, d.Time.Format("15:04:05"))
	})
}

Hook 包装器 — 自动发射事件

import "cnb.cool/svn/vdk/av/event"

// 将任意 DemuxCloser 包装为带事件的 HookDemuxer
hooked := event.WrapDemuxer(demuxer,
	event.WithProtocol("rtsp"),
	event.WithURL("rtsp://example.com/live"),
	event.WithDirection("subscribe"),
)

hooked.On(event.StreamReady, func(d event.Data) {
	fmt.Println("codec 就绪:", d.Codec)
})

streams, err := hooked.Streams() // 自动发射 StreamReady

事件类型一览

项目结构

vdk/
├── av/                         # 核心抽象层
│   ├── av.go                   #   Muxer, Demuxer, CodecData, Packet 接口
│   ├── event/                  #   事件系统 (Bus, HookDemuxer, HookMuxer)
│   ├── pktque/                 #   包队列与 Filter (WaitKeyFrame, FixTime)
│   ├── pubsub/                 #   发布/订阅 Queue (fan-out)
│   ├── avutil/                 #   Handler 注册, Open/Create 辅助函数
│   ├── avconv/                 #   格式转换辅助
│   └── transcode/              #   转码器包装
├── codec/                      # 编解码器
│   ├── h264parser/             #   H.264 解析 (SplitNALUs, SPS, CodecData)
│   ├── h265parser/             #   H.265/HEVC 解析
│   ├── aacparser/              #   AAC 解析
│   ├── opusparser/             #   Opus 解析
│   ├── vp9parser/              #   VP9 解析
│   ├── av1parser/              #   AV1 解析
│   ├── vvc/                    #   VVC/H.266
│   ├── flac/                   #   FLAC
│   ├── mp3/                    #   MP3
│   ├── ac3/                    #   AC-3
│   ├── mjpeg/                  #   MJPEG
│   ├── webp/, avif/, heif/     #   图片格式
│   └── fake/                   #   测试用假编码器
├── format/                     # 协议与容器
│   ├── rtmp/                   #   RTMP (Dial, Server, Conn + EventBus)
│   ├── rtsp/                   #   RTSP Client + EventBus
│   ├── rtspv2/                 #   RTSPv2 Client, ProxyConn/Server 轻量骨架 + EventBus
│   ├── srt/                    #   SRT (Dial/DialContext/DialConfig, Config, Stats + EventBus)
│   ├── rist/                   #   RIST (Sender, FEC, Stats, BridgeEvents)
│   ├── webrtc/                 #   WebRTC Muxer, WebRTCPusher (WHIP/BatchV2), WHEPPuller
│   ├── webrtcv3/               #   WebRTC v3 兼容导入路径（后端使用 Pion v4）
│   ├── gb28181/                #   GB/T 28181 SIP + PS 解封装
│   ├── ndi/                    #   NDI 协议框架
│   ├── dvrip/                  #   DVR-IP Client + EventBus
│   ├── hls/                    #   HLS Muxer
│   ├── flv/                    #   FLV Muxer, Demuxer, Prober
│   ├── mp4/                    #   MP4 Muxer, Demuxer
│   ├── mp4f/                   #   fMP4 Muxer (fragmented)
│   ├── mp4m/                   #   MP4 Muxer, Demuxer (扩展)
│   ├── fmp4/                   #   fMP4 MovieFragmenter
│   ├── mkv/                    #   MKV Demuxer
│   ├── ts/                     #   MPEG-TS Muxer, Demuxer
│   ├── nvr/                    #   NVR/MP4 分片录像 Muxer（demux 占位）
│   ├── aac/                    #   AAC 文件
│   ├── raw/                    #   RAW 裸流
│   └── mse/                    #   Media Source Extensions
├── stream/                     # 高级 Builder API
│   ├── builder.go              #   New(), Input(), Output(), Build(), Transcode()
│   ├── stream.go               #   Stream (Start/Stop/Pause/Resume/Run/Wait)
│   ├── ffmpeg_exec.go           #   非 CGO 系统 FFmpeg 转码执行层
│   └── enums.go                #   Protocol, VideoCodec, AudioCodec, Container, Preset...
├── pkg/                        # 功能模块
│   ├── manager/                #   流生命周期 Manager (状态机, 健康检查, 资源限制)
│   ├── streammgr/              #   批量会话 Manager (熔断, 健康监控, 集群)
│   ├── abr/                    #   ABR HLS 多档位 FFmpeg 转码
│   ├── ai/                     #   AI 增强接口与简化处理器（外部模型后端需自行接入）
│   ├── audio/                  #   音频处理 (响度标准化, 混音, 声道映射)
│   ├── subtitle/               #   字幕 (SRT/ASS/WebVTT/CEA-608/708)
│   ├── recording/              #   分段录制框架（Local/S3/MinIO/GCS XML API）
│   ├── cluster/                #   集群（Static/Consul/Etcd/K8s 服务发现）
│   ├── tracing/                #   OpenTelemetry 分布式追踪
│   ├── config/                 #   配置管理
│   └── scene/                  #   场景检测 (内容类型识别, 编码建议)
├── cgo/                        # FFmpeg CGO 绑定
│   ├── codec/                  #   编解码 (H264/H265/VP9/AV1, 硬件加速)
│   ├── filter/                 #   滤镜 (构建器, 水印, 色调映射)
│   ├── pipeline/               #   转码管道 (批量管理, 健康检查)
│   └── sdk/                    #   高级转码 SDK (引擎, 任务, 预设)
├── cmd/vdk/                    # CLI 工具 (probe, remux/transcode(copy), serve, benchmark)
├── example/                    # 示例程序
└── utils/                      # 通用工具 (位流读写, 字节序转换)

模块文档

版本路线

依赖

致谢

本项目基于 joy4 演进，感谢原作者的开创性工作。

MIT License

最后更新：2026-02-26