Go SDK API 说明
Ti 云存 API 位于：
import "github.com/tangeai/tirtc-client-go/v2/storage"媒体帧和临时文件类型与 TiRTC 根 package 共享，Ti 云存拥有独立的 Client、Replay 和 Export API。
Client 与托管鉴权
type ClientOptions struct {
AppID string
AccessKeyID string
AccessKeySecret string
CacheDir string
Endpoint string
ConsoleLogEnabled bool
}
func NewClient(options ClientOptions) (*Client, error)
func (c *Client) UploadLogs() (string, error)
func (c *Client) Close() errorApp ID、AK/SK 和可写绝对 CacheDir 必填。一个进程可以创建多个 Client，各自使用不同应用身份和 Endpoint；所有活动 Runtime 产品的 CacheDir 与 ConsoleLogEnabled 必须一致。
查询、Replay 和 Export 都显式接收 device ID。Runtime 为每台设备缓存和刷新短期 Token，Go API 不接收外部 Token。
Close 会拒绝新操作，取消所属查询和 Export，停止 Replay、解除 Output，并等待已接受的回调结束；它不会关闭其他 Client。回调内调用 Close 返回 ErrInUse。UploadLogs 同步上传共享 Runtime 日志，成功时返回 Log ID。
查询录像
func (c *Client) ListRecordingDays(
ctx context.Context, deviceID, startDate, endDate string,
) ([]RecordingDay, error)
func (c *Client) ListRecordingDaysInTimeZone(
ctx context.Context, deviceID, startDate, endDate, timeZoneID string,
) ([]RecordingDay, error)
func (c *Client) ListRecordings(
ctx context.Context, deviceID string, startTime, endTime time.Time,
) ([]RecordingRange, error)
type RecordingDay struct {
Date string
HasRecording bool
}
type RecordingRange struct {
StartTime time.Time
EndTime time.Time
}日期格式为 YYYY-MM-DD，单次日期查询最多覆盖包含首尾在内的 31 天。ListRecordingDays 默认使用 Asia/Shanghai；显式版本接收 IANA time zone。录像范围采用 UTC 左闭右开区间，结果按开始时间升序合并并裁到请求范围。单次范围查询最长 10 天；没有录像时返回非 nil 空 slice。
Context 取消会传入 Native。方法等待请求越过 I/O 清理边界后，返回可以用 errors.Is 匹配的 Context 错误。
Replay
type ReplayOptions struct {
OnTimeChanged func(time.Time)
OnCompleted func()
OnError func(error)
OnRecordingGap func(RecordingGap)
}
func (c *Client) NewReplay(deviceID string, options ReplayOptions) (*Replay, error)
func (r *Replay) Play(startTime, endTime time.Time) error
func (r *Replay) PlayAt(startTime, endTime, initialTime time.Time) error
func (r *Replay) Pause() error
func (r *Replay) Resume() error
func (r *Replay) Seek(target time.Time) error
func (r *Replay) SetSpeed(speed ReplaySpeed) error
func (r *Replay) Speed() ReplaySpeed
func (r *Replay) CurrentTime() (time.Time, bool, error)
func (r *Replay) Stop() error
func (r *Replay) StartRecording(options StartRecordingOptions) (*RecordingTask, error)
func (r *Replay) Close() error调用 Play 前至少 Attach 一个 Output。Replay 支持 0.125x、0.25x、0.5x、1x、2x、4x 和 8x；非 1x 时不输出声音。OnRecordingGap 只报告已经确认的来源缺口，本地 Output 背压不会生成录像缺口。
四类 Output 由 NewAudioOutput、NewVideoOutput、NewEncodedAudioOutput 和 NewEncodedVideoOutput 创建。每类提供 Attach(*Replay, channelID)、Detach()、State() 和 Close()；解码 Video Output 另有 TakeSnapshot()。Channel ID 范围是 0..255。
Replay Recording 必须选择一路视频，可以再选择一路音频。它只保存任务开始后实际进入所选轨道的媒体，和下面按时间范围运行的独立 Export 是不同操作。
独立导出
type ExportOptions struct {
StartTime time.Time
EndTime time.Time
VideoChannelID uint8
AudioChannelID *uint8
OnProgress func(ExportProgress)
OnRecordingGap func(RecordingGap)
}
func (c *Client) ExportRecording(
ctx context.Context, deviceID string, options ExportOptions,
) (*ExportTask, error)
func (t *ExportTask) Progress() ExportProgress
func (t *ExportTask) Cancel() error
func (t *ExportTask) Wait() (ExportResult, error)Export 不需要 Replay 或 Output。Cancel 只发送非阻塞取消请求；Wait 取得唯一终局，并等待回调与文件清理完成。扫描正常结束时，完整或部分可播放 MP4 都返回 nil error。没有可播放媒体、取消胜出或文件无法封口时返回错误，ExportResult.Report 仍保留已知事实。
type ExportResult struct {
File *RecordingFile
Report ExportReport
}
type ExportReport struct {
RequestedRange RecordingRange
CoveredDuration time.Duration
Segments []ExportSegment
Gaps []RecordingGap
UnprocessedRanges []RecordingRange
Complete bool
Termination ExportTermination
Cause error
}Complete 只在扫描结束、所选媒体没有确认缺口且没有未处理范围时为 true。Gaps 表示确认无法提供媒体的来源区间；提前结束时，尚未确认的尾部进入 UnprocessedRanges。Segments 把实际写入 MP4 的来源区间映射到输出时间线。
请求起点落在 GOP 中间时，Runtime 可以在同一段连续录像中回看前一个安全解码点，并把视频预卷写入 MP4。预卷不计入 CoveredDuration，但会计入文件时长。确认缺失的来源时间不会用黑帧或静音填充，而是从输出时间线压缩。
原始音视频诊断采集
Replay 可以按 Channel ID 采集用于问题排查的原始音视频数据：
type RawDumpOptions struct {
AudioChannelIDs []uint8
VideoChannelIDs []uint8
}
func (r *Replay) StartRawDump(options RawDumpOptions) (*RawDump, error)
func (d *RawDump) Stop() (RawDumpArchive, error)
func (d *RawDump) Close() error两个 Channel ID 列表至少填写一个。停止后检查 RawDumpArchive 的 CaptureComplete、StopReason、UnsavedPacketCount、UnsavedByteCount 和 Empty，再调用 Client.UploadLogs() 将采集文件随下一次日志上传提交。完整流程、限制和隐私要求见接入客户端诊断能力。
临时文件、错误与释放
Recording、Export 和 Snapshot 文件位于 Runtime cache。先保存到业务目录，再调用 RecordingFile.Delete() 或 SnapshotFile.Delete()。已经发布的文件所有权独立于 Task 和 Client；关闭后仍可保存和删除。
稳定错误通过 errors.Is 判断；Runtime 原始错误码通过 errors.As 取得 *storage.Error。不要在对象自己的回调中调用会等待该回调排空的 Wait、Stop 或 Close；这种重入返回 ErrInUse。
覆盖查询、Replay、Output、截图和导出完整能力的可运行程序见 Go API 示例。