Go SDK API 说明

Go 客户端位于 module 根 package：

import tirtc "github.com/tangeai/tirtc-client-go/v2"

支持 Go 1.25、CGO_ENABLED=1 下的 macOS arm64 与 Linux amd64。SDK 只提供主动连接和接收侧能力，不创建播放器界面。

初始化与关闭

type InitOptions struct {
	AppID             string
	CacheDir          string
	Endpoint          string
	ConsoleLogEnabled bool
}

func Init(options InitOptions) error
func Shutdown() error
func UploadLogs() (string, error)

AppID 和 CacheDir 必填，CacheDir 必须是可写绝对路径。RTC 与 Ti 云存可以在同一进程使用，两者的 App ID 和 Endpoint 可以不同。同时使用时，CacheDir 和 ConsoleLogEnabled 必须一致。共享配置冲突时，后初始化的一方返回 ErrAlreadyInitialized。关闭其中一个产品不会停止另一个产品。

仍有 Connection、Output 或 RecordingTask 等活动资源时，Shutdown 返回 ErrInUse。

UploadLogs 会归档并上传日志，成功时返回 Log ID。该操作会产生网络请求，应用应在取得用户同意并满足自身隐私策略后调用。

Connection

type ConnOptions struct {
	OnStateChanged  func(state ConnState, err error)
	OnCommand       func(commandID uint32, data []byte)
	OnStreamMessage func(streamID uint8, timestamp time.Duration, data []byte)
}

func NewConn(options ConnOptions) (*Conn, error)
func (c *Conn) Connect(remoteID, token string) error
func (c *Conn) Disconnect() error
func (c *Conn) State() ConnState
func (c *Conn) SendCommand(commandID uint32, data []byte) error
func (c *Conn) SendStreamMessage(streamID uint8, timestamp time.Duration, data []byte) error
func (c *Conn) SubscribeAudio(streamID uint8) error
func (c *Conn) UnsubscribeAudio(streamID uint8) error
func (c *Conn) SubscribeVideo(streamID uint8) error
func (c *Conn) UnsubscribeVideo(streamID uint8) error
func (c *Conn) RequestVideoKeyframe(streamID uint8) error
func (c *Conn) StartRecording(options StartRecordingOptions) (*RecordingTask, error)
func (c *Conn) Close() error

Stream ID 范围为 0..15。Connect 接受请求后，连接结果通过 OnStateChanged 返回。Output 可以在连接前创建和 Attach；连接成功后，显式订阅对应 Stream 才会开始接收媒体。

关闭 Connection 前，应先停止 RecordingTask，并关闭或 Detach 所有已附着的 Output。资源仍在使用时，Close 返回 ErrInUse。

Output 与媒体帧

SDK 提供解码音频、解码视频、编码音频和编码视频四类 Output：

type AudioOutputOptions struct {
	AGCLevel       AudioProcessingLevel
	ANSLevel       AudioProcessingLevel
	Buffer         OutputBufferOptions
	OnFrame        func(frame AudioFrame)
	OnStateChanged func(state OutputState)
	OnError        func(err error)
}

type VideoOutputOptions struct {
	DecoderPreference VideoDecoderPreference
	Buffer            OutputBufferOptions
	OnFrame           func(frame VideoFrame)
	OnStateChanged    func(state OutputState)
	OnError           func(err error)
}

func NewAudioOutput(options AudioOutputOptions) (*AudioOutput, error)
func NewVideoOutput(options VideoOutputOptions) (*VideoOutput, error)
func NewEncodedAudioOutput(options EncodedAudioOutputOptions) (*EncodedAudioOutput, error)
func NewEncodedVideoOutput(options EncodedVideoOutputOptions) (*EncodedVideoOutput, error)

每类 Output 均提供 Attach(*Conn, uint8)、Detach()、State() 和 Close()。VideoOutput 还提供：

func (o *VideoOutput) TakeSnapshot() (SnapshotFile, error)

音视频帧中的 byte slice 和视频 plane 已由 SDK 复制，回调返回后仍可读取。发生背压丢帧时，下一次成功交付的帧会设置 Discontinuity=true。

保存播放内容与截图

type StartRecordingOptions struct {
	VideoStreamID uint8
	AudioStreamID *uint8
}

type RecordingFile struct {
	Path     string
	Duration time.Duration
}

type SnapshotFile struct { Path string }

func (t *RecordingTask) Stop() (RecordingFile, error)
func (f RecordingFile) Delete() error
func (f SnapshotFile) Delete() error

一次 RecordingTask 必须选择一路视频，可选一路音频；同时选择音视频时，两个 Stream ID 不能相同。MP4 从任务建立后收到的第一个可独立解码的视频关键帧开始写入；可调用 RequestVideoKeyframe 缩短等待。

一个 RecordingTask 期间，所选视频的编码格式和分辨率必须保持不变；StartRecording 不锁定分辨率。需要切换时，先结束当前 Task，并在新格式生效后创建新 Task。中途发生变化时，任务可能返回 ErrUnsupportedFormat。

H.264 或 H.265 保存为 MP4 时，输入应为不含 B 帧或其他重排序依赖的低延迟码流。不符合时，任务返回 ErrUnsupportedFormat。

多路视频需要为每路视频分别创建 RecordingTask。同一路音频可以同时传给多个任务，从而分别得到“视频 A + 音频”和“视频 B + 音频”的两个 MP4。SDK 不生成多视频轨文件，也不合成画中画。

录制和截图文件位于 SDK cache。需要长期保存时，先使用标准库复制或移动到应用目录，再调用 Delete 清理临时源文件。

错误处理

公开方法返回 error。使用 errors.Is 判断稳定错误类别；需要原始 Runtime 错误码时，使用 errors.As 取得 *tirtc.Error。

常用错误分为三类：

• 参数与生命周期：ErrInvalidArgument、ErrNotInitialized、ErrAlreadyInitialized、ErrInUse、ErrNotConnected、ErrClosed；
• 连接与授权：ErrTokenExpired、ErrPermissionDenied；
• 媒体与文件：ErrUnsupportedFormat、ErrIO、ErrNoFrame、ErrNoRecordableMedia、ErrRecordingOverrun。

回调与释放顺序

同一对象的回调串行执行，不保证不同对象之间的顺序。不要在对象自己的回调中调用等待该回调结束的 Close。正常退出时依次停止 RecordingTask、关闭 Output、关闭 Connection，最后调用 Shutdown。

构建可分发应用

go get github.com/tangeai/tirtc-client-go/v2@v2.4.1
go get -tool github.com/tangeai/tirtc-client-go/v2/cmd/tirtc-build@v2.4.1
go tool tirtc-build build --output dist/bin/app ./cmd/app

分发时保留整个 dist/ 目录。