Java SDK 接入

Java SDK 可以查询录像日期和时间段、回放多路录像、取得解码或编码媒体帧、截图、保存播放片段，并把指定范围独立导出为 MP4。

确认运行环境

SDK 公共类以 Java 8 bytecode 发布，业务工程可以按 Java 8 编译合同引用；
当前发布门禁和生产运行基线是 JDK 21。bytecode 版本不代表其他 JDK 运行时已经通过发布验证；
Apple Silicon，macOS 11.5 或更高版本；
Linux x86_64，要求 GLIBC_2.35、GLIBCXX_3.4.30、CXXABI_1.3.9 或更高版本，不支持 Alpine/musl。

SDK 使用 AccessKeyId 和 AccessKeySecret 托管鉴权。只在能够妥善保管应用密钥的运行环境中使用，不要把密钥打包到浏览器、移动 App 或交付给终端用户的程序中。

添加 Maven 依赖

xml

<repositories>
  <repository>
    <id>tirtc</id>
    <url>https://repo-sdk.tange-ai.com/repository/maven-releases/</url>
  </repository>
</repositories>

<properties>
  <tirtc.version>VERSION</tirtc.version>
  <tirtc.native.classifier>linux-x86_64</tirtc.native.classifier>
</properties>

<dependencies>
  <dependency>
    <groupId>com.tange.ai</groupId>
    <artifactId>tirtc-server</artifactId>
    <version>${tirtc.version}</version>
  </dependency>
  <dependency>
    <groupId>com.tange.ai</groupId>
    <artifactId>tirtc-server</artifactId>
    <version>${tirtc.version}</version>
    <classifier>${tirtc.native.classifier}</classifier>
    <scope>runtime</scope>
  </dependency>
</dependencies>

将 VERSION 替换为更新记录中需要接入的版本。

macOS arm64 把 classifier 改为 macos-aarch64。

创建 Client 并查询录像

Ti 云存 API 位于 com.tange.ai.tirtc.storage。每次查询、回放和导出都显式传入目标 deviceId。SDK 会按需为设备签发和刷新短期 Token。

java

import com.tange.ai.tirtc.ClientOptions;
import com.tange.ai.tirtc.storage.CloudStorageClient;
import com.tange.ai.tirtc.storage.RecordingRange;
import java.nio.file.Paths;
import java.time.Instant;
import java.time.temporal.ChronoUnit;
import java.util.List;

ClientOptions options = ClientOptions.builder()
    .appId(appId)
    .accessKeyId(accessKeyId)
    .accessKeySecret(accessKeySecret)
    .cacheDir(Paths.get("/var/lib/my-app/tirtc-cache"))
    .build();

try (CloudStorageClient client = new CloudStorageClient(options)) {
    Instant end = Instant.now();
    Instant start = end.minus(1, ChronoUnit.DAYS);
    List<RecordingRange> ranges =
        client.listRecordings(deviceId, start, end).get();

    for (RecordingRange range : ranges) {
        System.out.println(range.startTime() + " - " + range.endTime());
    }
}

App ID、Access Key ID、Access Key Secret 和绝对 cache 路径必填。普通接入省略 endpoint，使用 SDK 内置的正式服务地址。只有在开通时收到其他服务地址，才把交付的完整地址原样传入：

java

ClientOptions options = ClientOptions.builder()
    .appId(appId)
    .accessKeyId(accessKeyId)
    .accessKeySecret(accessKeySecret)
    .cacheDir(cacheDir)
    .endpoint(endpoint)
    .build();

一个进程可以创建多个 Ti 云存 Client，并为它们使用不同应用身份和 Endpoint。TiRTC 和 Ti 云存同时运行时，所有 Client 的 cache 路径和 console log 配置必须一致。

接入客户端诊断能力（推荐）

创建 Client 后，建议在开发阶段为应用预留日志上传入口。这样在需要平台协助诊断时，可以直接上传同一次复现的日志；入口设计、上传结果处理和可选的原始音视频诊断采集见接入客户端诊断能力。

选择后续能力

查询、回放、控制倍速和截图：看查询与播放录像；
把指定范围导出为 MP4：看下载录像；
所有对象、结果报告和异常语义：看 Java SDK API 说明。

CloudStorageClient、Replay、Output、Task 和临时文件都实现 AutoCloseable。优先使用 try-with-resources。已经返回给应用的 RecordingFile 和 SnapshotFile 独立于 Client，仍要保存或删除。

Java SDK 接入 ​

确认运行环境 ​

添加 Maven 依赖 ​

创建 Client 并查询录像 ​