webrtc

package
v0.0.0-...-5b2bcd3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 23, 2026 License: MIT Imports: 24 Imported by: 0

README

WebRTC 支持

实现 WebRTC 相关功能,包括 SDP 交换适配器、WHIP 推流和 WHEP 拉流。

核心 API

类型/函数 说明
Muxer SDP 交换适配器,用于 WebRTC 信令协商
MuxerConfig Pion v4 ICE、端口与候选地址发布配置
NewMuxer(config) 使用显式配置创建 Muxer
WebRTCPusher WebRTC 推流器,支持 WHIP 和 BatchV2 模式
NewWHIPPusher(url, path) 创建 WHIP 推流器
NewBatchV2Pusher(url, path) 创建 BatchV2 推流器
WHEPPuller WHEP 拉流器
NewWHEPPuller(url, path) 创建 WHEP 拉流器

EventBus 支持

通过设置 Muxer.EventBus 可订阅已实现的连接结束生命周期事件:

  • Disconnecting / Disconnected

快速开始

WHIP 推流
import "cnb.cool/svn/vdk/format/webrtc"

pusher := webrtc.NewWHIPPusher("http://server:8080", "/live/stream")
defer pusher.Close()

err := pusher.WriteHeader(streams)
// 写入数据包...
WHEP 拉流
puller := webrtc.NewWHEPPuller("http://server:8080", "/live/stream")
defer puller.Close()

streams, _ := puller.Streams()
for {
    pkt, err := puller.ReadPacket()
    if err != nil {
        break
    }
    // 处理数据包
}
SDP 适配器
import (
    "cnb.cool/svn/vdk/format/webrtc"
)

muxer, err := webrtc.NewMuxer(webrtc.MuxerConfig{
    ICEServers: []webrtc.ICEServer{{
        URLs: []string{"stun:stun.example.com:3478"},
    }},
    UDPPortMin: 50000,
    UDPPortMax: 50100,
    ICEAddressRewriteRules: []webrtc.ICEAddressRewriteRule{{
        External:        []string{"203.0.113.10"},
        AsCandidateType: webrtc.ICECandidateTypeHost,
        Mode:            webrtc.ICEAddressRewriteReplace,
    }},
})
if err != nil {
    // 处理配置错误
}
defer muxer.Close()

answerSDP, err := muxer.WriteHeader(codecs, offerSDP)
// offerSDP 和 answerSDP 都是标准 raw SDP。
Muxer 配置
  • ICEServers 使用本包重导出的 ICEServer;它是 Pion v4 类型的直接 alias,调用方无需 import Pion,仍支持多个 STUN/TURN server 及各自的认证配置。为空且 DisableDefaultICEServers 为 false(零值)时,Muxer 自动注入 DefaultICEServers() 的公共 STUN fallback;显式配置会完整覆盖默认值。
  • DefaultSTUNServers() 与 DefaultICEServers() 每次都返回可独立修改的副本。当前默认 URL 为 stun:stun.cloudflare.com:3478、stun:stun.l.google.com:19302、stun:stun.nextcloud.com:443、stun:stun.stunprotocol.org:3478 与 stun:stun.sipnet.com:3478,仅包含 stun: URL,不包含需要动态用户名和凭据的 TURN 服务;STUN 不能替代受限 NAT 环境中的 TURN relay。
  • DisableDefaultICEServers: true 可禁用公共 STUN fallback,仅收集本机候选,适用于私网、隔离网络或需避免向第三方 STUN 服务发送 Binding 请求的部署。
  • UDPPortMin 与 UDPPortMax 必须同时为 0,或同时设为闭区间端口范围;相同端口值有效。
  • ICEAddressRewriteRules 使用本包重导出的 ICEAddressRewriteRule,配套常量包括 ICECandidateTypeHost、ICEAddressRewriteReplace 和 NetworkTypeUDP4,用于 NAT / 公网地址发布。它只影响 candidate 广播地址,防火墙和 NAT 转发必须相应配置。
  • WriteHeader 在返回 raw SDP answer 前等待 non-trickle ICE gathering;ICEGatherTimeout 为 0 时默认 10 秒。
  • 视频输入支持 H264 与 H265/HEVC。H265 的 AVCC 与 Annex-B access unit 会统一为 Annex-B,并在 keyframe 前发送 VPS -> SPS -> PPS。
  • H265 仅在远端 SDP offer 也声明 video/H265 时可协商;该包不执行 H265 到 H264 的转码,面向不支持 H265 的浏览器时应由上层提供转码 fallback。

相关文档

Documentation

Index

Constants

View Source
const (
	// ICECredentialTypePassword 使用用户名和密码进行 TURN 认证。
	ICECredentialTypePassword = pionwebrtc.ICECredentialTypePassword
	// ICECredentialTypeOauth 使用 OAuth token 进行 TURN 认证。
	ICECredentialTypeOauth = pionwebrtc.ICECredentialTypeOauth

	// ICECandidateTypeUnknown 表示未指定 ICE candidate 类型。
	ICECandidateTypeUnknown = pionwebrtc.ICECandidateTypeUnknown
	// ICECandidateTypeHost 表示 host ICE candidate。
	ICECandidateTypeHost = pionwebrtc.ICECandidateTypeHost
	// ICECandidateTypeSrflx 表示 server-reflexive ICE candidate。
	ICECandidateTypeSrflx = pionwebrtc.ICECandidateTypeSrflx
	// ICECandidateTypePrflx 表示 peer-reflexive ICE candidate。
	ICECandidateTypePrflx = pionwebrtc.ICECandidateTypePrflx
	// ICECandidateTypeRelay 表示 TURN relay ICE candidate。
	ICECandidateTypeRelay = pionwebrtc.ICECandidateTypeRelay

	// ICEAddressRewriteModeUnspecified 使用 Pion 的默认候选地址重写行为。
	ICEAddressRewriteModeUnspecified = pionwebrtc.ICEAddressRewriteModeUnspecified
	// ICEAddressRewriteReplace 用重写后的地址替换匹配候选。
	ICEAddressRewriteReplace = pionwebrtc.ICEAddressRewriteReplace
	// ICEAddressRewriteAppend 在保留原候选的同时追加重写后的候选。
	ICEAddressRewriteAppend = pionwebrtc.ICEAddressRewriteAppend

	// NetworkTypeUnknown 表示未指定网络类型。
	NetworkTypeUnknown = pionwebrtc.NetworkTypeUnknown
	// NetworkTypeUDP4 表示 IPv4 UDP 网络。
	NetworkTypeUDP4 = pionwebrtc.NetworkTypeUDP4
	// NetworkTypeUDP6 表示 IPv6 UDP 网络。
	NetworkTypeUDP6 = pionwebrtc.NetworkTypeUDP6
	// NetworkTypeTCP4 表示 IPv4 TCP 网络。
	NetworkTypeTCP4 = pionwebrtc.NetworkTypeTCP4
	// NetworkTypeTCP6 表示 IPv6 TCP 网络。
	NetworkTypeTCP6 = pionwebrtc.NetworkTypeTCP6
)

Variables

View Source
var (
	// ErrorNotFound 表示当前 muxer 中找不到目标流或 track。
	ErrorNotFound = errors.New("stream not found")
	// ErrorCodecNotSupported 表示输入 codec 不能映射为当前 WebRTC 发送格式。
	ErrorCodecNotSupported = errors.New("codec not supported")
	// ErrorClientOffline 表示 PeerConnection 已关闭或不可写。
	ErrorClientOffline = errors.New("client offline")
	// ErrorICEGatheringTimeout 表示单次 SDP 协商未在配置时间内完成 ICE candidate 收集。
	ErrorICEGatheringTimeout = errors.New("ICE gathering timed out")
	// ErrorHeaderAlreadyWritten 表示同一个 Muxer 已完成或正在进行 SDP 协商。
	ErrorHeaderAlreadyWritten = errors.New("WebRTC header already written")
	// Label 是默认 WebRTC track stream ID 前缀。
	Label = "track_"
)
View Source
var (
	// ErrorNotConnected 表示推流器尚未与信令服务或 PeerConnection 建立连接。
	ErrorNotConnected = errors.New("not connected to server")
	// ErrorInvalidSDP 表示信令服务返回的 SDP 不合法。
	ErrorInvalidSDP = errors.New("invalid SDP response")
	// ErrorStreamExists 表示目标流已经存在。
	ErrorStreamExists = errors.New("stream already exists")
	// ErrorStreamNotFound 表示目标流不存在。
	ErrorStreamNotFound = errors.New("stream not found")
	// ErrorProtocolNotSupported 表示当前推流协议不受支持。
	ErrorProtocolNotSupported = errors.New("protocol not supported")
)
View Source
var ErrWHEPNotReady = errors.New("whep: not ready")

ErrWHEPNotReady 表示 WHEP 拉流器尚未收到任何远端 track。

Functions

func DefaultSTUNServers

func DefaultSTUNServers() []string

DefaultSTUNServers 返回用于 Muxer 零值 fallback 的公共 STUN URL 副本。 返回值可由调用方独立修改;列表不包含需要短期凭据的 TURN 服务。

Types

type ICEAddressRewriteMode

type ICEAddressRewriteMode = pionwebrtc.ICEAddressRewriteMode

ICEAddressRewriteMode 是 Pion V4 ICEAddressRewriteMode 的直接别名,用于控制候选替换或追加。

type ICEAddressRewriteRule

type ICEAddressRewriteRule = pionwebrtc.ICEAddressRewriteRule

ICEAddressRewriteRule 是 Pion V4 ICEAddressRewriteRule 的直接别名,用于候选地址发布规则。

type ICECandidateType

type ICECandidateType = pionwebrtc.ICECandidateType

ICECandidateType 是 Pion V4 ICECandidateType 的直接别名,用于指定地址重写后的候选类型。

type ICECredentialType

type ICECredentialType = pionwebrtc.ICECredentialType

ICECredentialType 是 Pion V4 ICECredentialType 的直接别名,用于声明 TURN 认证方式。

type ICEServer

type ICEServer = pionwebrtc.ICEServer

ICEServer 是 Pion V4 ICEServer 的直接别名,用于配置 STUN/TURN 服务而无需调用方导入 Pion。

func DefaultICEServers

func DefaultICEServers() []ICEServer

DefaultICEServers 返回用于 Muxer 零值 fallback 的默认 ICE server 副本。 每次调用均返回独立的 slice;调用方可将其用作显式 ICEServers 配置。

type Muxer

type Muxer struct {
	EventBus *event.Bus // 事件总线(可选)
	// contains filtered or unexported fields
}

Muxer 将 VDK packet 写入 Pion WebRTC PeerConnection。

Muxer 维护 track 映射、ICE 状态与关闭协调;写入接口可并发读取状态,但调用方仍应按媒体顺序写包。

func NewMuxer

func NewMuxer(config MuxerConfig) (*Muxer, error)

NewMuxer 使用 Pion v4 配置创建 WebRTC muxer,并启动空闲关闭监视。 配置错误在创建时返回,避免在已有媒体订阅后才暴露无效端口范围。

func (*Muxer) Close

func (element *Muxer) Close() error

Close 关闭 PeerConnection、唤醒等待 goroutine 并发出一次断开事件。

func (*Muxer) WaitCloser

func (element *Muxer) WaitCloser()

WaitCloser 等待内部关闭信号并关闭 muxer。

媒体会话的生命期由 Pion ICE 状态和调用方 Close 决定,不能依赖可选 DataChannel 心跳,否则没有 DataChannel 的正常观看者会被错误中断。

func (*Muxer) WriteHeader

func (element *Muxer) WriteHeader(streams []av.CodecData, offerSDP string) (string, error)

WriteHeader 根据 codec 列表与 raw SDP offer 创建 raw SDP answer。 调用方负责通过自身信令通道传输 SDP;该方法在返回前完成 non-trickle ICE candidate 收集。

func (*Muxer) WritePacket

func (element *Muxer) WritePacket(pkt av.Packet) (err error)

WritePacket 将 VDK packet 写入对应 WebRTC track。

type MuxerConfig

type MuxerConfig struct {
	// ICEServers 是重导出的 Pion v4 STUN/TURN 配置,每个 server 可独立声明认证方式;非空时完全覆盖默认值。
	ICEServers []ICEServer
	// DisableDefaultICEServers 仅在 ICEServers 为空时生效;设为 true 时只收集本机候选。
	DisableDefaultICEServers bool
	// UDPPortMin 与 UDPPortMax 限制 host / server-reflexive ICE UDP 端口;均为 0 时使用系统默认。
	UDPPortMin uint16
	UDPPortMax uint16
	// ICEAddressRewriteRules 定义候选地址发布规则,例如 1:1 NAT 的外网地址替换。
	ICEAddressRewriteRules []ICEAddressRewriteRule
	// ICEGatherTimeout 限制非 trickle SDP answer 的候选收集时间;零值使用 10 秒。
	ICEGatherTimeout time.Duration
}

MuxerConfig 定义单个 WebRTC Muxer 的 Pion v4 协商与 ICE 网络约束。 配置在构造时复制,创建后不可变;零值使用 DefaultICEServers 收集 server-reflexive 候选。

func (MuxerConfig) Validate

func (config MuxerConfig) Validate() error

Validate 校验 MuxerConfig 的本地约束,不执行网络连接。

type NetworkType

type NetworkType = pionwebrtc.NetworkType

NetworkType 是 Pion V4 NetworkType 的直接别名,用于限制 ICE 候选使用的网络协议与 IP 族。

type OAuthCredential

type OAuthCredential = pionwebrtc.OAuthCredential

OAuthCredential 是 Pion V4 OAuthCredential 的直接别名,用于 OAuth TURN 凭据。

type ProtocolType

type ProtocolType string

ProtocolType 表示 WebRTC 推流信令协议类型。

const (
	// ProtocolWHIP 表示按 WHIP HTTP 信令推流。
	ProtocolWHIP ProtocolType = "whip"
	// ProtocolBatchV2 表示按 BatchV2 WebSocket 信令推流。
	ProtocolBatchV2 ProtocolType = "batchv2"
)

type PullerConfig

type PullerConfig struct {
	ICEServers       []ICEServer
	HTTPTimeout      time.Duration
	ICEGatherTimeout time.Duration
	AnswerTimeout    time.Duration
	IdleTimeout      time.Duration
	NetworkTypes     []NetworkType
	// InterfaceFilterIPs limits ICE to interfaces that own any of these IPs.
	InterfaceFilterIPs []string
	// TCPMuxListenAddr enables ICE-TCP by providing a local listener address.
	// Use ":0" to auto-assign a port.
	TCPMuxListenAddr string
	// DisableActiveTCP disables active TCP candidates. Default is false.
	DisableActiveTCP bool
	// LogCandidates enables ICE candidate logging.
	LogCandidates bool
}

PullerConfig 描述 WHEP 拉流器的 HTTP、ICE、网络与空闲控制参数。

type PusherConfig

type PusherConfig struct {
	ICEServers         []ICEServer
	ICEGatherTimeout   time.Duration
	AnswerTimeout      time.Duration
	HTTPTimeout        time.Duration
	EnableAACTranscode bool
	AACOpusBitrate     int
	IdleTimeout        time.Duration
	NetworkTypes       []NetworkType
	// TCPMuxListenAddr enables ICE-TCP by providing a local listener address.
	// Use ":0" to auto-assign a port.
	TCPMuxListenAddr string
	// DisableActiveTCP disables active TCP candidates. Default is false.
	DisableActiveTCP bool
}

PusherConfig 描述 WebRTC 推流器的信令、ICE 与音频转码参数。

type Stream

type Stream struct {
	// contains filtered or unexported fields
}

Stream 绑定单路 CodecData 与 WebRTC track 写入状态。

type WHEPPuller

type WHEPPuller struct {
	// contains filtered or unexported fields
}

WHEPPuller 通过 WHEP HTTP 信令建立 WebRTC 拉流连接。

Start 建立 PeerConnection 后,调用方可通过 Tracks 或 ReadRTP 读取远端 RTP 包。

func NewWHEPPuller

func NewWHEPPuller(serverURL, streamPath string) *WHEPPuller

NewWHEPPuller 使用默认配置创建 WHEP 拉流器。

func NewWHEPPullerWithConfig

func NewWHEPPullerWithConfig(serverURL, streamPath string, cfg PullerConfig) *WHEPPuller

NewWHEPPullerWithConfig 使用自定义配置创建 WHEP 拉流器。

func (*WHEPPuller) Close

func (p *WHEPPuller) Close(ctx context.Context) error

Close 关闭 WHEP session、PeerConnection 与底层 TCP mux listener。

func (*WHEPPuller) ReadRTP

func (p *WHEPPuller) ReadRTP(ctx context.Context) (*webrtc.TrackRemote, *rtp.Packet, error)

ReadRTP 从任一远端 track 读取下一包 RTP。

func (*WHEPPuller) Start

func (p *WHEPPuller) Start(ctx context.Context) error

Start 建立 WHEP 会话并等待远端 SDP answer。

func (*WHEPPuller) Tracks

func (p *WHEPPuller) Tracks() []*webrtc.TrackRemote

Tracks 返回当前已接收的远端 track 副本。

type WebRTCPusher

type WebRTCPusher struct {
	// contains filtered or unexported fields
}

WebRTCPusher 将 VDK muxer 写入转换为 WHIP 或 BatchV2 WebRTC 推流。

实例持有 PeerConnection、信令连接和可选 AAC→Opus 转码器;创建后应成对调用 WriteHeader 与 Stop/WriteTrailer。

func NewBatchV2Pusher

func NewBatchV2Pusher(serverURL, streamPath string) *WebRTCPusher

NewBatchV2Pusher 创建BatchV2协议推流器

func NewBatchV2PusherWithConfig

func NewBatchV2PusherWithConfig(serverURL, streamPath string, cfg PusherConfig) *WebRTCPusher

NewBatchV2PusherWithConfig 创建BatchV2协议推流器(自定义配置)

func NewWHIPPusher

func NewWHIPPusher(serverURL, streamPath string) *WebRTCPusher

NewWHIPPusher 创建WHIP协议推流器

func NewWHIPPusherWithConfig

func NewWHIPPusherWithConfig(serverURL, streamPath string, cfg PusherConfig) *WebRTCPusher

NewWHIPPusherWithConfig 创建WHIP协议推流器(自定义配置)

func (*WebRTCPusher) EnableAACTranscode

func (p *WebRTCPusher) EnableAACTranscode(enable bool, bitrate int)

EnableAACTranscode 启用 AAC → Opus 转码

func (*WebRTCPusher) GetStats

func (p *WebRTCPusher) GetStats() (webrtc.StatsReport, error)

GetStats 获取连接统计信息

func (*WebRTCPusher) SetConfig

func (p *WebRTCPusher) SetConfig(cfg PusherConfig)

SetConfig 设置推流配置(未设置项会使用默认值)

func (*WebRTCPusher) SetErrorHandler

func (p *WebRTCPusher) SetErrorHandler(handler func(error))

SetErrorHandler 设置错误回调

func (*WebRTCPusher) SetICEServers

func (p *WebRTCPusher) SetICEServers(servers []ICEServer)

SetICEServers 自定义 ICE 服务器列表

func (*WebRTCPusher) Stop

func (p *WebRTCPusher) Stop() error

Stop 停止推流

func (*WebRTCPusher) WriteHeader

func (p *WebRTCPusher) WriteHeader(streams []av.CodecData) error

WriteHeader 实现 av.Muxer 接口

func (*WebRTCPusher) WritePacket

func (p *WebRTCPusher) WritePacket(pkt av.Packet) error

WritePacket 实现 av.Muxer 接口

func (*WebRTCPusher) WriteTrailer

func (p *WebRTCPusher) WriteTrailer() error

WriteTrailer 实现 av.Muxer 接口

Source Files

  • adapter.go
  • pion_types.go
  • signal_http.go
  • webrtc_pusher.go
  • webrtc_pusher_stream_io.go
  • webrtc_pusher_stub.go
  • whep_puller.go

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址