tirtc-devtools-cli 0.2.4 → 0.3.0

package/README.md

@@ -57,8 +57,10 @@ node products/cli/bin/tirtc-devtools-cli.js --json device start \
 ```
 
 `device start` 默认持续运行直到用户结束进程；需要自动化限时时再显式传
-`--duration-ms <ms>`。prepared asset 会按完整音视频轨循环，任一轨到达源文件末尾时
-audio/video 同步回到源头并保持 PTS 继续递增。
+`--duration-ms <ms>`。运行期间 CLI 会把启动、listener ready、client 连接 / 断开、
+首个音视频包与周期运行状态写到 stderr；`--json` 的结构化 envelope 仍只写 stdout。
+prepared asset 会按完整音视频轨循环，任一轨到达源文件末尾时 audio/video 同步回到
+源头并保持 PTS 继续递增。
 
 `device start` 的启动成功条件是 device listener 已就绪；客户端是否已经扫码连接不属于
 device 启动失败条件。没有 client 时命令会继续常驻，直到用户结束进程或显式
@@ -70,6 +72,11 @@ native role 失败时，`reason_code` 与 `failed_stage` 仍是主失败事实
 只说明失败现场日志是否已上传。上传成功时，CLI JSON 与 `summary.json` 会包含
 可用于后续抓取的 `log_id`。
 
+`device start` 与 `client start` 启动的 native role 默认 echo 收到的 command：
+收到任意 command 后，用同一个 command id 与同一 payload 原样回发。CLI 不新增
+额外控制命令或开关；`summary.json` 与 `--json` envelope 会包含 `command_echo`
+evidence，用于确认 command 收发面已被覆盖。
+
 打包入口：
 
 ```sh

package/USAGE.md

@@ -131,6 +131,11 @@ By default `device start` keeps running until the process is stopped. Use
 full audio/video source cycle; when either track reaches the source end, both
 tracks restart from offset 0 while PTS keeps increasing.
 
+While the device process is running, CLI writes human-readable lifecycle logs to
+stderr: startup, listener readiness, client connect/disconnect, first audio/video
+packet, and periodic running status. With `--json`, the final machine-readable
+envelope remains on stdout.
+
 `device start` is considered started once the device listener is ready. A
 missing client is not a device startup failure. Without a connected client, the
 process remains resident until it is stopped or an explicit `--duration-ms`
@@ -141,6 +146,10 @@ provided. That file is a local handoff artifact for CLI client, runtime sample
 smoke, and validation automation. The token in that bootstrap is intended for
 one client connection.
 
+`device start` starts a native role that echoes every received command with the
+same command id and payload. No extra CLI command or option is required.
+`summary.json` and the `--json` envelope include `command_echo` evidence.
+
 `bootstrap.json` is not a mobile SDK connection protocol. For phone debugging,
 use token/license QR today; a full session QR or deeplink is a separate product
 slice.
@@ -155,6 +164,11 @@ node products/cli/bin/tirtc-devtools-cli.js --json client start \
 
 Client writes `summary.json`, `events.jsonl`, runtime logs, and `render/first-video-frame.*` for `frame_dump`.
 
+The native client role also echoes every received command with the same command
+id and payload. `summary.json` and the `--json` envelope include `command_echo`
+evidence, so command receive and reply coverage is visible in normal CLI
+artifacts.
+
 `client start --bootstrap` is meant for the local computer-to-computer DevTools
 flow. Mobile clients should not be required to fetch a local JSON file from the
 developer machine.

package/dist/cli/src/index.js

@@ -139,6 +139,10 @@ Missing flags are read from TIRTC_DEVICE_ID, TIRTC_DEVICE_SECRET_KEY, and TIRTC_
 
 device start succeeds once the device listener is ready. It keeps running without a client until
 the process is stopped or an explicit --duration-ms deadline is reached.
+Runtime lifecycle logs are written to stderr. With --json, the final envelope remains on stdout.
+
+The native device role echoes every received command with the same command id and payload.
+summary.json and the --json envelope include command_echo evidence.
 
 bootstrap.json is a local handoff artifact for client/sample/validation automation.
 It is only written when --client-token-json is provided.
@@ -170,6 +174,9 @@ Examples:
 
 bootstrap.json is expected to come from a local device start run.
 For mobile device debugging, use token/license QR or a future session QR/deeplink.
+
+The native client role echoes every received command with the same command id and payload.
+summary.json and the --json envelope include command_echo evidence.
 `)
     .action((commandOptions) => {
     runAndExit((0, role_driver_1.runClientStart)(commandOptions, getCliOptions()));

package/dist/cli/src/role_driver.js

@@ -11,6 +11,7 @@ const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const embedded_paths_1 = require("./embedded_paths");
+const role_live_log_1 = require("./role_live_log");
 const defaultAudioStreamId = 10;
 const defaultVideoStreamId = 11;
 const defaultConnectTimeoutMs = 10000;
@@ -166,7 +167,11 @@ function redactRequestValue(value) {
     }
     const result = {};
     for (const [key, child] of Object.entries(value)) {
-        if (key === 'license' || key === 'token' || key === 'client_token' || key === 'secret_key') {
+        if (key === 'license' ||
+            key === 'token' ||
+            key === 'client_token' ||
+            key === 'device_secret_key' ||
+            key === 'secret_key') {
             result[key] = '[REDACTED]';
         }
         else {
@@ -312,8 +317,8 @@ function buildDeviceRequest(roots, artifactRoot, options) {
         role: 'device',
         endpoint: deviceIdentity.endpoint,
         identity: {
-            license: deviceIdentity.deviceId + ',' + deviceIdentity.deviceSecretKey,
             device_id: deviceIdentity.deviceId,
+            device_secret_key: deviceIdentity.deviceSecretKey,
         },
         bootstrap,
         streams: {
@@ -402,7 +407,58 @@ function buildClientRequest(roots, artifactRoot, options) {
         probe: { app_id: appId },
     };
 }
-function runDriver(request, artifactRoot, roots) {
+function installSignalForwarding(child, liveLog) {
+    const signals = ['SIGINT', 'SIGTERM'];
+    const removers = [];
+    let forwardedCount = 0;
+    for (const signal of signals) {
+        const handler = () => {
+            forwardedCount += 1;
+            liveLog.signalForwarded(signal);
+            if (!child.killed) {
+                child.kill(forwardedCount > 1 ? 'SIGKILL' : signal);
+            }
+        };
+        process.on(signal, handler);
+        removers.push(() => process.off(signal, handler));
+    }
+    return () => {
+        for (const remove of removers) {
+            remove();
+        }
+    };
+}
+function spawnDriverProcess(driverPath, args, stdoutFd, stderrFd, liveLog) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = child_process_1.default.spawn(driverPath, args, {
+                stdio: ['ignore', stdoutFd, stderrFd],
+            });
+        }
+        catch (error) {
+            const normalized = error instanceof Error ? error : new Error(String(error));
+            liveLog.processError(normalized);
+            resolve({
+                status: null,
+                signal: null,
+                error: normalized,
+            });
+            return;
+        }
+        let spawnError;
+        const removeSignalHandlers = installSignalForwarding(child, liveLog);
+        child.once('error', (error) => {
+            spawnError = error;
+            liveLog.processError(error);
+        });
+        child.once('close', (code, signal) => {
+            removeSignalHandlers();
+            resolve({ status: code, signal, error: spawnError });
+        });
+    });
+}
+async function runDriver(role, request, artifactRoot, roots) {
     const platform = resolveRuntimePlatform();
     const driverPath = resolveDriverPath(roots, platform);
     const runtimeRoot = resolveRuntimeRoot(roots, platform);
@@ -428,26 +484,41 @@ function runDriver(request, artifactRoot, roots) {
     }
     const requestTempDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'tirtc-devtools-cli-request-'));
     const requestPath = path_1.default.join(requestTempDir, 'request.json');
+    const summaryPath = path_1.default.join(artifactRoot, 'summary.json');
+    fs_1.default.rmSync(summaryPath, { force: true });
+    fs_1.default.rmSync(path_1.default.join(artifactRoot, 'events.jsonl'), { force: true });
     writeJson(requestPath, request);
     writeJson(path_1.default.join(artifactRoot, 'request.redacted.json'), redactRequestValue(request));
     const stdoutFd = fs_1.default.openSync(path_1.default.join(artifactRoot, 'stdout.log'), 'w');
     const stderrFd = fs_1.default.openSync(path_1.default.join(artifactRoot, 'stderr.log'), 'w');
-    const result = child_process_1.default.spawnSync(driverPath, [
-        '--request', requestPath,
-        '--runtime-root', runtimeRoot,
-        '--asset-root', assetRoot,
-        '--artifact-root', artifactRoot,
-    ], {
-        stdio: ['ignore', stdoutFd, stderrFd],
+    const liveLog = (0, role_live_log_1.startRoleLiveLog)({
+        role,
+        artifactRoot,
+        request,
+        runtimeRoot,
+        assetRoot,
     });
-    fs_1.default.closeSync(stdoutFd);
-    fs_1.default.closeSync(stderrFd);
-    fs_1.default.rmSync(requestTempDir, { recursive: true, force: true });
-    const summaryPath = path_1.default.join(artifactRoot, 'summary.json');
+    let result = { status: null, signal: null };
+    try {
+        result = await spawnDriverProcess(driverPath, [
+            '--request', requestPath,
+            '--runtime-root', runtimeRoot,
+            '--asset-root', assetRoot,
+            '--artifact-root', artifactRoot,
+        ], stdoutFd, stderrFd, liveLog);
+        liveLog.processExit(result.status, result.signal);
+    }
+    finally {
+        fs_1.default.closeSync(stdoutFd);
+        fs_1.default.closeSync(stderrFd);
+        fs_1.default.rmSync(requestTempDir, { recursive: true, force: true });
+        liveLog.stop();
+    }
     if (!pathExists(summaryPath)) {
         const message = result.error instanceof Error
             ? result.error.message
-            : 'driver exited without summary: status=' + String(result.status);
+            : 'driver exited without summary: status=' + String(result.status) +
+                ' signal=' + String(result.signal ?? 'none');
         if (result.error) {
             throw new RoleCommandError('artifact_write_failed', 'artifact', roleFailedExitCode, message);
         }
@@ -472,7 +543,7 @@ async function runRole(role, commandOptions, options) {
         const request = role === 'device' ?
             buildDeviceRequest(roots, artifactRoot, commandOptions) :
             buildClientRequest(roots, artifactRoot, commandOptions);
-        const summary = runDriver(request, artifactRoot, roots);
+        const summary = await runDriver(role, request, artifactRoot, roots);
         const summaryPath = path_1.default.join(artifactRoot, 'summary.json');
         const data = {
             status: summary.status,
@@ -486,6 +557,7 @@ async function runRole(role, commandOptions, options) {
             failed_stage: failedStage(summary),
             log_id: summary.log_upload?.log_id,
             log_upload: summary.log_upload,
+            command_echo: summary.command_echo,
         };
         if (summary.exit_code === 0 && summary.status === 'completed') {
             printEnvelope(options, 0, 'OK', data);

package/dist/cli/src/role_live_log.d.ts

@@ -0,0 +1,17 @@
+export type RoleLiveLogOptions = {
+    role: 'device' | 'client';
+    artifactRoot: string;
+    request: Record<string, unknown>;
+    runtimeRoot: string;
+    assetRoot: string;
+    heartbeatIntervalMs?: number;
+    pollIntervalMs?: number;
+    emit?: (message: string) => void;
+};
+export type RoleLiveLogHandle = {
+    processError(error: Error): void;
+    processExit(code: number | null, signal: NodeJS.Signals | null): void;
+    signalForwarded(signal: NodeJS.Signals): void;
+    stop(): void;
+};
+export declare function startRoleLiveLog(options: RoleLiveLogOptions): RoleLiveLogHandle;

package/dist/cli/src/role_live_log.js

@@ -0,0 +1,305 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startRoleLiveLog = startRoleLiveLog;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const defaultHeartbeatIntervalMs = 5000;
+const defaultPollIntervalMs = 500;
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function nestedRecord(root, key) {
+    return asRecord(root[key]);
+}
+function nestedString(root, first, second) {
+    const value = second === undefined ? root[first] : nestedRecord(root, first)[second];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function nestedNumber(root, first, second) {
+    const value = second === undefined ? root[first] : nestedRecord(root, first)[second];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function payloadString(payload, key) {
+    const value = payload[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function payloadNumber(payload, key) {
+    const value = payload[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function payloadBoolean(payload, key) {
+    const value = payload[key];
+    return typeof value === 'boolean' ? value : undefined;
+}
+function formatDurationMs(ms) {
+    if (ms < 1000) {
+        return String(ms) + 'ms';
+    }
+    return (ms / 1000).toFixed(1) + 's';
+}
+function formatDurationUs(us) {
+    if (us === undefined) {
+        return undefined;
+    }
+    return formatDurationMs(Math.round(us / 1000));
+}
+function sessionIndex(payload) {
+    return payloadNumber(payload, 'session_index');
+}
+function appendField(parts, name, value) {
+    if (value !== undefined) {
+        parts.push(name + '=' + String(value));
+    }
+}
+function makeNoopHandle() {
+    return {
+        processError: () => undefined,
+        processExit: () => undefined,
+        signalForwarded: () => undefined,
+        stop: () => undefined,
+    };
+}
+function startRoleLiveLog(options) {
+    if (options.role !== 'device') {
+        return makeNoopHandle();
+    }
+    const emit = options.emit ?? ((message) => console.error(message));
+    const startedAt = Date.now();
+    const eventsPath = path_1.default.join(options.artifactRoot, 'events.jsonl');
+    const summaryPath = path_1.default.join(options.artifactRoot, 'summary.json');
+    const request = options.request;
+    const stats = {
+        listenerReady: false,
+        sessionsStarted: 0,
+        sessionsEnded: 0,
+        firstAudioSessions: new Set(),
+        firstVideoSessions: new Set(),
+    };
+    let processedLineCount = 0;
+    let stopped = false;
+    const log = (message) => {
+        emit('[device] ' + message);
+    };
+    const media = nestedRecord(request, 'media');
+    const codec = payloadString(nestedRecord(media, 'video'), 'codec') ??
+        nestedString(request, 'video_codec') ?? 'unknown';
+    const sourcePath = payloadString(nestedRecord(media, 'source'), 'path') ?? options.assetRoot;
+    const durationMs = nestedNumber(request, 'run', 'duration_ms');
+    const deviceId = nestedString(request, 'identity', 'device_id') ?? 'unknown';
+    const endpoint = nestedString(request, 'endpoint') ?? 'unknown';
+    log('starting device driver device_id=' + deviceId +
+        ' endpoint=' + endpoint +
+        ' codec=' + codec +
+        ' artifact_root=' + options.artifactRoot);
+    log('source=' + sourcePath + ' runtime_root=' + options.runtimeRoot);
+    if (durationMs === undefined) {
+        log('resident mode enabled; waiting for client connections until the process is stopped');
+    }
+    else {
+        log('bounded mode enabled duration=' + formatDurationMs(durationMs));
+    }
+    const emitHeartbeat = () => {
+        const elapsed = Date.now() - startedAt;
+        const parts = [
+            'running',
+            'elapsed=' + formatDurationMs(elapsed),
+            'listener=' + (stats.listenerReady ? 'ready' : 'starting'),
+            'sessions=' + String(stats.sessionsStarted) + '/' + String(stats.sessionsEnded),
+            'active_session=' + (stats.activeSession ?? 'none'),
+            'first_audio_sessions=' + String(stats.firstAudioSessions.size),
+            'first_video_sessions=' + String(stats.firstVideoSessions.size),
+        ];
+        appendField(parts, 'last_event', stats.lastEventKind);
+        log(parts.join(' '));
+    };
+    const emitEventLog = (event) => {
+        const kind = typeof event.kind === 'string' ? event.kind : undefined;
+        if (!kind) {
+            return;
+        }
+        const payload = asRecord(event.payload);
+        stats.lastEventKind = kind;
+        if (event.level === 'error') {
+            const reason = payloadString(payload, 'reason_code') ?? 'unknown';
+            log('driver event failed kind=' + kind + ' reason_code=' + reason);
+        }
+        switch (kind) {
+            case 'connection.listen.done':
+                stats.listenerReady = true;
+                log('listener ready; waiting for client connections');
+                break;
+            case 'bootstrap.write.done':
+                log('bootstrap written path=' + (payloadString(payload, 'path') ?? 'unknown'));
+                break;
+            case 'connection.connect.done': {
+                const session = sessionIndex(payload);
+                if (session !== undefined) {
+                    stats.sessionsStarted = Math.max(stats.sessionsStarted, session);
+                    stats.activeSession = session;
+                }
+                log('client connected session=' + (session ?? 'unknown'));
+                break;
+            }
+            case 'connection.session.start': {
+                const session = sessionIndex(payload);
+                if (session !== undefined) {
+                    stats.activeSession = session;
+                }
+                log('media session started session=' + (session ?? 'unknown'));
+                break;
+            }
+            case 'media.audio_send.start': {
+                const parts = ['audio input started'];
+                appendField(parts, 'session', sessionIndex(payload));
+                appendField(parts, 'stream_id', payloadNumber(payload, 'stream_id'));
+                appendField(parts, 'codec', payloadString(payload, 'codec'));
+                appendField(parts, 'sample_rate_hz', payloadNumber(payload, 'sample_rate_hz'));
+                log(parts.join(' '));
+                break;
+            }
+            case 'media.video_send.start': {
+                const parts = ['video input started'];
+                appendField(parts, 'session', sessionIndex(payload));
+                appendField(parts, 'stream_id', payloadNumber(payload, 'stream_id'));
+                appendField(parts, 'codec', payloadString(payload, 'codec'));
+                log(parts.join(' '));
+                break;
+            }
+            case 'media.asset_cycle.config': {
+                const parts = ['asset cycle ready'];
+                appendField(parts, 'session', sessionIndex(payload));
+                appendField(parts, 'audio_packets', payloadNumber(payload, 'audio_packet_count'));
+                appendField(parts, 'video_packets', payloadNumber(payload, 'video_packet_count'));
+                appendField(parts, 'cycle_duration', formatDurationUs(payloadNumber(payload, 'cycle_duration_us')));
+                log(parts.join(' '));
+                break;
+            }
+            case 'media.audio_send.session_first_packet': {
+                const session = sessionIndex(payload);
+                if (session !== undefined) {
+                    stats.firstAudioSessions.add(session);
+                }
+                const parts = ['first audio packet sent'];
+                appendField(parts, 'session', session);
+                appendField(parts, 'pts_us', payloadNumber(payload, 'pts_us'));
+                appendField(parts, 'bytes', payloadNumber(payload, 'bytes'));
+                log(parts.join(' '));
+                break;
+            }
+            case 'media.video_send.session_first_packet': {
+                const session = sessionIndex(payload);
+                if (session !== undefined) {
+                    stats.firstVideoSessions.add(session);
+                }
+                const parts = ['first video packet sent'];
+                appendField(parts, 'session', session);
+                appendField(parts, 'codec', payloadString(payload, 'codec'));
+                appendField(parts, 'key_frame', payloadBoolean(payload, 'is_key_frame'));
+                appendField(parts, 'pts_us', payloadNumber(payload, 'pts_us'));
+                appendField(parts, 'bytes', payloadNumber(payload, 'bytes'));
+                log(parts.join(' '));
+                break;
+            }
+            case 'connection.session.end': {
+                const session = sessionIndex(payload);
+                if (session !== undefined) {
+                    stats.sessionsEnded = Math.max(stats.sessionsEnded, session);
+                    if (stats.activeSession === session) {
+                        stats.activeSession = undefined;
+                    }
+                }
+                const disconnected = payloadBoolean(payload, 'disconnected');
+                const elapsed = payloadNumber(payload, 'elapsed_ms');
+                const parts = [disconnected ? 'client disconnected' : 'client session ended'];
+                appendField(parts, 'session', session);
+                appendField(parts, 'first_audio', payloadBoolean(payload, 'sent_first_audio'));
+                appendField(parts, 'first_video', payloadBoolean(payload, 'sent_first_video'));
+                appendField(parts, 'elapsed', elapsed === undefined ? undefined : formatDurationMs(elapsed));
+                log(parts.join(' '));
+                break;
+            }
+            case 'connection.wait.no_client': {
+                const reason = payloadString(payload, 'reason') ?? 'unknown';
+                const elapsed = payloadNumber(payload, 'elapsed_ms');
+                log('no client connected before stop reason=' + reason +
+                    (elapsed === undefined ? '' : ' elapsed=' + formatDurationMs(elapsed)));
+                break;
+            }
+            case 'driver.execution.finished': {
+                const status = payloadString(payload, 'status') ?? 'unknown';
+                const exitCode = payloadNumber(payload, 'exit_code');
+                const reason = payloadString(payload, 'reason_code') ?? 'unknown';
+                log('driver finished status=' + status +
+                    ' exit_code=' + String(exitCode ?? 'unknown') +
+                    ' reason_code=' + reason);
+                break;
+            }
+            default:
+                break;
+        }
+    };
+    const pollEvents = (flushPartial = false) => {
+        if (!fs_1.default.existsSync(eventsPath)) {
+            return;
+        }
+        let text = '';
+        try {
+            text = fs_1.default.readFileSync(eventsPath, 'utf8');
+        }
+        catch {
+            return;
+        }
+        const lines = text.split(/\r?\n/);
+        const completeLineCount = text.endsWith('\n')
+            ? lines.length - 1
+            : (flushPartial ? lines.length : lines.length - 1);
+        for (let index = processedLineCount; index < completeLineCount; index += 1) {
+            const line = lines[index]?.trim();
+            if (!line) {
+                continue;
+            }
+            try {
+                emitEventLog(JSON.parse(line));
+            }
+            catch {
+                if (flushPartial) {
+                    log('skipped malformed driver event line=' + String(index + 1));
+                }
+            }
+        }
+        processedLineCount = Math.max(processedLineCount, completeLineCount);
+    };
+    const pollTimer = setInterval(() => pollEvents(false), options.pollIntervalMs ?? defaultPollIntervalMs);
+    const heartbeatTimer = setInterval(emitHeartbeat, options.heartbeatIntervalMs ?? defaultHeartbeatIntervalMs);
+    return {
+        processError: (error) => {
+            pollEvents(true);
+            log('driver process error message=' + error.message);
+        },
+        processExit: (code, signal) => {
+            pollEvents(true);
+            const elapsed = Date.now() - startedAt;
+            log('process exited code=' + String(code ?? 'null') +
+                ' signal=' + String(signal ?? 'none') +
+                ' elapsed=' + formatDurationMs(elapsed) +
+                ' summary=' + summaryPath);
+        },
+        signalForwarded: (signal) => {
+            log('forwarding signal=' + signal + ' to native driver');
+        },
+        stop: () => {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            clearInterval(pollTimer);
+            clearInterval(heartbeatTimer);
+            pollEvents(true);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-devtools-cli",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "private": false,
   "main": "dist/cli/src/index.js",
   "types": "dist/cli/src/index.d.ts",

package/vendor/runtime/linux-x64/include/tirtc/audio.h

@@ -101,7 +101,7 @@ typedef struct TirtcAudioOutputMetricsSnapshot {
  *
  * The snapshot is a caller-owned value copy. Zero-initialized fields mean the output has not yet
  * observed a matching runtime fact or only cached zero-state is available. This diagnostic API is
- * intended for UI/debug visibility and logs, not for playback control decisions.
+ * intended for UI/debug visibility and logs, not for output control decisions.
  */
 typedef struct TirtcAudioOutputDebugSnapshot {
   TirtcMediaCodec codec;

package/vendor/runtime/linux-x64/include/tirtc/transport.h

@@ -289,17 +289,6 @@ typedef struct TirtcTransportConnCallbacks {
  */
 TirtcError tirtc_transport_init(void);
 
-/**
- * @brief Enable/disable transport debug mode.
- *
- * When enabled, transport backend sets verbose vendor SDK log level during runtime init
- * and applies it immediately if runtime is already initialized.
- *
- * @param enabled Non-zero to enable debug mode, zero to disable.
- * @return Operation status.
- */
-TirtcError tirtc_transport_enable_debug(uint8_t enabled);
-
 /**
  * @brief Uninitialize transport runtime.
  *

package/vendor/runtime/linux-x64/include/tirtc/trp.h

@@ -25,19 +25,12 @@ typedef struct TirtcInitOptions {
 
 } TirtcInitOptions;
 
-typedef enum TirtcMediaSendPolicy {
-
-  TIRTC_MEDIA_SEND_POLICY_ON_REQUEST = 0,
-
-  TIRTC_MEDIA_SEND_POLICY_AUTO_ON_CONNECTED = 1,
-} TirtcMediaSendPolicy;
-
 typedef struct TirtcConnServiceStartOptions {
-  const char* license;
+  const char* device_id;
 
-  uint32_t max_connections;
+  const char* device_secret_key;
 
-  TirtcMediaSendPolicy media_send_policy;
+  uint32_t max_connections;
 } TirtcConnServiceStartOptions;
 
 typedef struct TirtcConnConnectOptions {

package/vendor/runtime/linux-x64/include/tirtc/video_io_apple.h

@@ -20,8 +20,17 @@ typedef enum TirtcVideoAppleWindowSlot {
   TIRTC_VIDEO_APPLE_WINDOW_SLOT_RIGHT = 2,
 } TirtcVideoAppleWindowSlot;
 
+typedef enum TirtcVideoAppleCameraFacing {
+  TIRTC_VIDEO_APPLE_CAMERA_FACING_FRONT = 0,
+  TIRTC_VIDEO_APPLE_CAMERA_FACING_BACK = 1,
+} TirtcVideoAppleCameraFacing;
+
 typedef int (*TirtcVideoAppleOnPixelBufferFn)(void* pixel_buffer, void* user_data);
 
+typedef struct TirtcVideoAppleAvFoundationVinOptions {
+  TirtcVideoAppleCameraFacing camera_facing;
+} TirtcVideoAppleAvFoundationVinOptions;
+
 typedef struct TirtcVideoAppleCoreVideoVoutOptions {
   TirtcVideoAppleVoutTarget target;
   TirtcVideoAppleOnPixelBufferFn on_pixel_buffer;
@@ -35,6 +44,11 @@ typedef struct TirtcVideoAppleCoreVideoVoutOptions {
   uint32_t window_height;
 } TirtcVideoAppleCoreVideoVoutOptions;
 
+TirtcError tirtc_video_apple_create_avfoundation_vin(TirtcVideoVin** out_vin);
+TirtcError tirtc_video_apple_avfoundation_vin_set_options(
+    TirtcVideoVin* vin, const TirtcVideoAppleAvFoundationVinOptions* options);
+TirtcError tirtc_video_apple_avfoundation_vin_get_actual_facing(
+    TirtcVideoVin* vin, TirtcVideoAppleCameraFacing* out_camera_facing);
 TirtcError tirtc_video_apple_create_core_video_vout(TirtcVideoVout** out_vout);
 TirtcError tirtc_video_apple_core_video_vout_set_options(
     TirtcVideoVout* vout, const TirtcVideoAppleCoreVideoVoutOptions* options);

package/vendor/runtime/linux-x64/manifest.txt

@@ -1,9 +1,9 @@
 platform=linux-x64
 profile=full
-staged_at_utc=2026-05-03T15:04:13Z
+staged_at_utc=2026-05-07T08:43:43Z
 source_sdk=/Users/allenfeng/Development/Repositories/tirtc-nexus/tirtc-matrix/.build/sdk/linux-x64
 
-bfc096be1484ac2b1c2776ccabfa2a4c6a982e869abf875192ff06fad85e82ca  include/tirtc/audio.h
+59ba10e0b7cc679d625d3e8c536e3e234b3173091b9859956252fe3dd631b774  include/tirtc/audio.h
 6d972ccfe150a3b4f2d7f18fa92b3ade9210c1c8bb754d061ac6b7997b59e2cb  include/tirtc/audio_codec.h
 7bacbdb2d8bb10d6444036a8fef42f2a8e3ea34dfc38e165ee678d61f189db41  include/tirtc/audio_frame.h
 fb8ea35263167c33487bd3aa503c26ed2dfbf97877f7bda92c10065cd5c97c13  include/tirtc/audio_io.h
@@ -21,25 +21,25 @@ ae805545a9515edc9b94262e72ad2c7b7d649288166f4daeb450d8a55e82ae0b  include/tirtc/
 7e2f7f81afe37e22f5414d9db32438edd948ff775230c3a0a17ff9ac1a0b560e  include/tirtc/media_codec.h
 ca63fe4fa0c787f20923e264e116fa6d7cb8194a227c03be4e9843d0ce5a9864  include/tirtc/media_downlink.h
 e64191a39004165cdcd11b2ca824af34d4bfe02f7ec3c3101fa9291f56488c30  include/tirtc/media_uplink.h
-489f6c9caa3e4094566b660ef0a002a39c66c1956ef0a1bdb6eacca3798c849a  include/tirtc/transport.h
-bb9c1bf46f2ab51a9f7adb211276c8563b09e7968031c0c6abeebc0eddd66acb  include/tirtc/trp.h
+93b85272f8fa606e048e40c0bd353440a46459180afcdaddd15b9a028dc26173  include/tirtc/transport.h
+b932f3e930057843751e66d6b4eb9d8440ecdfd6634fd941abbe260eccfa056c  include/tirtc/trp.h
 92b3db6e2cb02265ad5db01881edce9d4e095b1dadf449dce5d8bb5362957e33  include/tirtc/video_codec.h
 e51379666c199588cc33279ccf52248035d1cae3d1d468b1615ebf29f0b39c9c  include/tirtc/video_frame.h
 2a02645d82c58d433c7306a9f0bcd31d0f3e560b63822f7e80919761b81a6284  include/tirtc/video_io.h
 9930dce5e8e2b12a1ab28ee91f3fb46f6cf3487e515ea2b4ec0e00009bd5f070  include/tirtc/video_io_android.h
-005114b9213ec826e18d11eca4b9d65cce2ca0e7c781f03d85292365d9d5dfdd  include/tirtc/video_io_apple.h
+f22127424d5978ab0644209b6c25c24e19e320dd2fbda6634e6344597ff7e2be  include/tirtc/video_io_apple.h
 cae0bbeb884e5466a56da15182c78cc22baab6c743f349a58d3595f623333585  include/tirtc/video_io_harmony.h
 65b5d24fe3a6bc2a299a2220148a153ba4eb0955a49c1c3baabf1fdfed8aabdd  include/tirtc/video_io_windows.h
 8cd6b66bea14890a665cc317f8572429b2c3e4463773f8b77c1e4dc30a4a8747  include/tirtc/video_processing.h
 ceb7cdd45efae57e5bd53d4177cb20c4a0cb9917fcdd23127b050d69c8b919ac  lib/libTiRTC.a
 b1f4135025cb8e8520a14268d831b9998920a4239f84bb6b409d0e4909fd5bee  lib/libcrypto.a
 296ba0b5efa9d2ac49e3bf278c5d467b31436e73fbc608b736e974bcf9759bde  lib/libmatrix_runtime_audio.a
-88f9c545943e4ef80024baf3620e91817ec16a4fea60b0e8c7887a0a41dc9d1b  lib/libmatrix_runtime_facade.a
+695c398eabef4f4227f1e7d7c8a46f3854b66e90d981d2580b664bf244977417  lib/libmatrix_runtime_facade.a
 ec7bbf8e8744c6645a441a28e24e0645906152cc987d6fcca16af3c3badba940  lib/libmatrix_runtime_foundation_http.a
-71f395eb5a15a8c65a702bb4b7996aebe69d8381fdd540cfc39a339dc148c69b  lib/libmatrix_runtime_foundation_logging.a
-8964ab2d93bf0fd4ee6666459ffec53cd35b07288fccc0d46e042e60b8466d4f  lib/libmatrix_runtime_media.a
-93dd81cfb9ed8aef29bfa3fb9d18aaed140ac25d00beeff1a0156a9333afa8a5  lib/libmatrix_runtime_transport.a
-ac7b85780c75b5d0c3abf1c5293181739a0fceeb2ad8fa930f98bd86bba5daa2  lib/libmatrix_runtime_video.a
+e41012346b8200eb6a722afc2e916f6365d32698768e1d176874a23add644b2c  lib/libmatrix_runtime_foundation_logging.a
+357a15ebff6afcf0c97073d19624434e62454ed463212d0d0298af2f370a7742  lib/libmatrix_runtime_media.a
+41baae4526a1798e154c0e158a9539adc417d06e0e8193adab0c1a85cf784501  lib/libmatrix_runtime_transport.a
+59476bb5dc78b9c89cb0663fe4490ad260625332fdc68cd83a3d52abf0f31b10  lib/libmatrix_runtime_video.a
 511d521f7972df3993e5976d6e2dbcad7a6fbce9be15071274d0cbd9d51157f5  lib/libssl.a
 a67ec9034848ef24a1b17671e444daa62a8f9e6b8319a1e932593908720ff2a1  lib/libwebrtc_apm.a
 700e455255897e3cffab13ca593a6e4d9d11383ae609215cbbd6043a63d47161  lib/libxlog.a

package/vendor/runtime/macos-arm64/include/tirtc/audio.h

@@ -101,7 +101,7 @@ typedef struct TirtcAudioOutputMetricsSnapshot {
  *
  * The snapshot is a caller-owned value copy. Zero-initialized fields mean the output has not yet
  * observed a matching runtime fact or only cached zero-state is available. This diagnostic API is
- * intended for UI/debug visibility and logs, not for playback control decisions.
+ * intended for UI/debug visibility and logs, not for output control decisions.
  */
 typedef struct TirtcAudioOutputDebugSnapshot {
   TirtcMediaCodec codec;

package/vendor/runtime/macos-arm64/include/tirtc/transport.h

@@ -289,17 +289,6 @@ typedef struct TirtcTransportConnCallbacks {
  */
 TirtcError tirtc_transport_init(void);
 
-/**
- * @brief Enable/disable transport debug mode.
- *
- * When enabled, transport backend sets verbose vendor SDK log level during runtime init
- * and applies it immediately if runtime is already initialized.
- *
- * @param enabled Non-zero to enable debug mode, zero to disable.
- * @return Operation status.
- */
-TirtcError tirtc_transport_enable_debug(uint8_t enabled);
-
 /**
  * @brief Uninitialize transport runtime.
  *

package/vendor/runtime/macos-arm64/include/tirtc/trp.h

@@ -25,19 +25,12 @@ typedef struct TirtcInitOptions {
 
 } TirtcInitOptions;
 
-typedef enum TirtcMediaSendPolicy {
-
-  TIRTC_MEDIA_SEND_POLICY_ON_REQUEST = 0,
-
-  TIRTC_MEDIA_SEND_POLICY_AUTO_ON_CONNECTED = 1,
-} TirtcMediaSendPolicy;
-
 typedef struct TirtcConnServiceStartOptions {
-  const char* license;
+  const char* device_id;
 
-  uint32_t max_connections;
+  const char* device_secret_key;
 
-  TirtcMediaSendPolicy media_send_policy;
+  uint32_t max_connections;
 } TirtcConnServiceStartOptions;
 
 typedef struct TirtcConnConnectOptions {

package/vendor/runtime/macos-arm64/include/tirtc/video_io_apple.h

@@ -20,8 +20,17 @@ typedef enum TirtcVideoAppleWindowSlot {
   TIRTC_VIDEO_APPLE_WINDOW_SLOT_RIGHT = 2,
 } TirtcVideoAppleWindowSlot;
 
+typedef enum TirtcVideoAppleCameraFacing {
+  TIRTC_VIDEO_APPLE_CAMERA_FACING_FRONT = 0,
+  TIRTC_VIDEO_APPLE_CAMERA_FACING_BACK = 1,
+} TirtcVideoAppleCameraFacing;
+
 typedef int (*TirtcVideoAppleOnPixelBufferFn)(void* pixel_buffer, void* user_data);
 
+typedef struct TirtcVideoAppleAvFoundationVinOptions {
+  TirtcVideoAppleCameraFacing camera_facing;
+} TirtcVideoAppleAvFoundationVinOptions;
+
 typedef struct TirtcVideoAppleCoreVideoVoutOptions {
   TirtcVideoAppleVoutTarget target;
   TirtcVideoAppleOnPixelBufferFn on_pixel_buffer;
@@ -35,6 +44,11 @@ typedef struct TirtcVideoAppleCoreVideoVoutOptions {
   uint32_t window_height;
 } TirtcVideoAppleCoreVideoVoutOptions;
 
+TirtcError tirtc_video_apple_create_avfoundation_vin(TirtcVideoVin** out_vin);
+TirtcError tirtc_video_apple_avfoundation_vin_set_options(
+    TirtcVideoVin* vin, const TirtcVideoAppleAvFoundationVinOptions* options);
+TirtcError tirtc_video_apple_avfoundation_vin_get_actual_facing(
+    TirtcVideoVin* vin, TirtcVideoAppleCameraFacing* out_camera_facing);
 TirtcError tirtc_video_apple_create_core_video_vout(TirtcVideoVout** out_vout);
 TirtcError tirtc_video_apple_core_video_vout_set_options(
     TirtcVideoVout* vout, const TirtcVideoAppleCoreVideoVoutOptions* options);

package/vendor/runtime/macos-arm64/manifest.txt

@@ -1,9 +1,9 @@
 platform=macos-arm64
 profile=full
-staged_at_utc=2026-05-03T15:02:29Z
+staged_at_utc=2026-05-07T08:41:46Z
 source_sdk=/Users/allenfeng/Development/Repositories/tirtc-nexus/tirtc-matrix/.build/sdk/macos-arm64
 
-bfc096be1484ac2b1c2776ccabfa2a4c6a982e869abf875192ff06fad85e82ca  include/tirtc/audio.h
+59ba10e0b7cc679d625d3e8c536e3e234b3173091b9859956252fe3dd631b774  include/tirtc/audio.h
 6d972ccfe150a3b4f2d7f18fa92b3ade9210c1c8bb754d061ac6b7997b59e2cb  include/tirtc/audio_codec.h
 7bacbdb2d8bb10d6444036a8fef42f2a8e3ea34dfc38e165ee678d61f189db41  include/tirtc/audio_frame.h
 fb8ea35263167c33487bd3aa503c26ed2dfbf97877f7bda92c10065cd5c97c13  include/tirtc/audio_io.h
@@ -21,13 +21,13 @@ ae805545a9515edc9b94262e72ad2c7b7d649288166f4daeb450d8a55e82ae0b  include/tirtc/
 7e2f7f81afe37e22f5414d9db32438edd948ff775230c3a0a17ff9ac1a0b560e  include/tirtc/media_codec.h
 ca63fe4fa0c787f20923e264e116fa6d7cb8194a227c03be4e9843d0ce5a9864  include/tirtc/media_downlink.h
 e64191a39004165cdcd11b2ca824af34d4bfe02f7ec3c3101fa9291f56488c30  include/tirtc/media_uplink.h
-489f6c9caa3e4094566b660ef0a002a39c66c1956ef0a1bdb6eacca3798c849a  include/tirtc/transport.h
-bb9c1bf46f2ab51a9f7adb211276c8563b09e7968031c0c6abeebc0eddd66acb  include/tirtc/trp.h
+93b85272f8fa606e048e40c0bd353440a46459180afcdaddd15b9a028dc26173  include/tirtc/transport.h
+b932f3e930057843751e66d6b4eb9d8440ecdfd6634fd941abbe260eccfa056c  include/tirtc/trp.h
 92b3db6e2cb02265ad5db01881edce9d4e095b1dadf449dce5d8bb5362957e33  include/tirtc/video_codec.h
 e51379666c199588cc33279ccf52248035d1cae3d1d468b1615ebf29f0b39c9c  include/tirtc/video_frame.h
 2a02645d82c58d433c7306a9f0bcd31d0f3e560b63822f7e80919761b81a6284  include/tirtc/video_io.h
 9930dce5e8e2b12a1ab28ee91f3fb46f6cf3487e515ea2b4ec0e00009bd5f070  include/tirtc/video_io_android.h
-005114b9213ec826e18d11eca4b9d65cce2ca0e7c781f03d85292365d9d5dfdd  include/tirtc/video_io_apple.h
+f22127424d5978ab0644209b6c25c24e19e320dd2fbda6634e6344597ff7e2be  include/tirtc/video_io_apple.h
 cae0bbeb884e5466a56da15182c78cc22baab6c743f349a58d3595f623333585  include/tirtc/video_io_harmony.h
 65b5d24fe3a6bc2a299a2220148a153ba4eb0955a49c1c3baabf1fdfed8aabdd  include/tirtc/video_io_windows.h
 8cd6b66bea14890a665cc317f8572429b2c3e4463773f8b77c1e4dc30a4a8747  include/tirtc/video_processing.h
@@ -35,13 +35,13 @@ cae0bbeb884e5466a56da15182c78cc22baab6c743f349a58d3595f623333585  include/tirtc/
 8db86d6714264047e8fd4086ddd7315722d675749719e6175f89eb5a636b48a1  lib/libTiRTC.a
 b39daee6a3d39bf0ca20c45084601133c4198de8dca848dcff6dd9c70ae99016  lib/libcrypto.a
 c052857ef315e3d61db9c862cad10709a3a6b2487dc41799cbe4d74a805de875  lib/libcrypto.dylib
-8b75c9fa50c130ba795929904bb623ed5d3431185cc317a9f446d8e57eaaa351  lib/libmatrix_runtime_audio.a
-d4b7fe1d7020602511ad464c0b73294d5f9f65805dd8c3a180e58e8a49826be7  lib/libmatrix_runtime_facade.a
-217ecd0bc12629678682848acdfee5b9a4b32c55077d6b60f6b46e142e313717  lib/libmatrix_runtime_foundation_http.a
-cc55fc4bcac36a395d594c9085845a418e07f4102c4eb551e4f69fe3297c8df3  lib/libmatrix_runtime_foundation_logging.a
-c5e2c47a2dea31abf6ad18be3474f87e1961742672b9ac5f423789d3d09bf0d7  lib/libmatrix_runtime_media.a
-09b6ca2483b2c64d2d8e849d7ea781e7fdfe7f53a05d5ed11ef5e81e6f926fd2  lib/libmatrix_runtime_transport.a
-015e99fcd2ed8cca7b8bd3b98830d2cd5b88ce4801e8080c0cd907d43e42ac38  lib/libmatrix_runtime_video.a
+accd2ae1d507620e79a137fb3251bda8e4fd6323053c520d43cd4b2e8ae6b845  lib/libmatrix_runtime_audio.a
+22063c50d962a70929ab890ce53c4b66dc166e6e4855b77346619d6547080f1e  lib/libmatrix_runtime_facade.a
+77f99950767a60f8b950acae0988ecc4c835a599f530ad1a158de32d2131f61d  lib/libmatrix_runtime_foundation_http.a
+182c56ff2263a8c5e392e1a49adc367a438cfda61d35b93db3861689fc03ca4c  lib/libmatrix_runtime_foundation_logging.a
+fc95129eabfb9cb46e17276cf1814e60d47f67991ea97128a32e6520b5b23674  lib/libmatrix_runtime_media.a
+1d9ef883017e5a489191b02744aa81a74d4bc7ea2f1379e7e0c593b1e23ac731  lib/libmatrix_runtime_transport.a
+339c27670947c3a546eedc1464f3d88998ba74434ce8ec0d0090f28bd0a140a3  lib/libmatrix_runtime_video.a
 c11c65d373a127028350c41fa58cd2d1223f2b5d70a84e13b115d90daaba25ca  lib/libssl.a
 ef1c1104bbdd2528ed7b958fb7252bd6249875f92300b0c9577d6c4bd6c0d88a  lib/libssl.dylib
 e14e846e43d64e240fa0e5745bf4e702b79d0f2442e7f768beb990610735c71b  lib/libtgrtc.dylib