tirtc-devtools-cli 0.1.0 → 0.1.2

package/README.md

@@ -56,6 +56,10 @@ node products/cli/bin/tirtc-devtools-cli.js --json send start \
   --artifact-root .build/devtools-cli/send-movie-h264
 ```
 
+`send start` 默认持续运行直到用户结束进程；需要自动化限时时再显式传
+`--duration-ms <ms>`。prepared asset 会按完整音视频轨循环，任一轨到达源文件末尾时
+audio/video 同步回到源头并保持 PTS 继续递增。
+
 打包入口：
 
 ```sh

package/USAGE.md

@@ -110,6 +110,11 @@ node products/cli/bin/tirtc-devtools-cli.js --json send start \
   --artifact-root .build/devtools-cli/send-movie-h264
 ```
 
+By default `send start` keeps running until the process is stopped. Use
+`--duration-ms <ms>` only for bounded automation. Prepared assets loop over the
+full audio/video source cycle; when either track reaches the source end, both
+tracks restart from offset 0 while PTS keeps increasing.
+
 The send role writes `bootstrap.json`. That file is a local handoff artifact for
 CLI receive, runtime sample smoke, and validation automation. The token in that
 bootstrap is intended for one receive connection.

package/dist/cli/src/index.js

@@ -8,6 +8,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const embedded_paths_1 = require("./embedded_paths");
 const media_assets_1 = require("./media_assets");
+const progress_1 = require("./progress");
 const token_command_1 = require("./token_command");
 const role_driver_1 = require("./role_driver");
 function resolveCliVersion() {
@@ -69,12 +70,19 @@ function printError(error, options) {
     return 1;
 }
 async function runAssetsPrepare(commandOptions, options) {
+    const progress = new progress_1.ProgressIndicator();
+    progress.start('Preparing media assets');
     try {
         const result = await (0, media_assets_1.prepareMediaAssets)({
             source: commandOptions.source ?? 'runtime/assets/source.mp4',
             outputRoot: commandOptions.outputRoot ?? 'runtime/assets/.workspace',
             overwrite: false,
+        }, {
+            progress: (message) => {
+                progress.update(message);
+            },
         });
+        progress.succeed(result.cache_hit ? 'Media assets cache hit' : 'Prepared media assets');
         if (options.json) {
             console.log(JSON.stringify({ code: 0, message: 'OK', data: result }));
         }
@@ -84,6 +92,7 @@ async function runAssetsPrepare(commandOptions, options) {
         return 0;
     }
     catch (error) {
+        progress.fail('Media assets prepare failed');
         return printError(error, options);
     }
 }
@@ -117,7 +126,7 @@ send.command('start')
     .option('--remote-id <id>', 'server remote id；默认读取 TIRTC_DEVICE_ID')
     .option('--source <path>', 'prepared asset root、manifest_path 或 encoded track；MP4 先运行 assets prepare')
     .option('--video-codec <codec>', 'h264|h265|mjpeg', 'h264')
-    .option('--duration-ms <ms>', 'role active 时长')
+    .option('--duration-ms <ms>', '可选自动结束时长；默认持续运行直到用户结束进程')
     .option('--connect-timeout-ms <ms>', 'service ready / connect 最大等待')
     .option('--first-packet-timeout-ms <ms>', '首包最大等待')
     .option('--bootstrap-token-json <path>', 'script/issue_devtools_token.sh --json 输出文件')
@@ -143,7 +152,7 @@ receive.command('start')
     .option('--video-stream-id <id>', '视频 stream id')
     .option('--consumer <consumer>', 'packet_dump|frame_dump', 'frame_dump')
     .option('--frame-limit <count>', 'frame_dump 帧数上限')
-    .option('--duration-ms <ms>', 'role active 时长')
+    .option('--duration-ms <ms>', '可选自动结束时长；默认由输出条件或用户结束进程')
     .option('--connect-timeout-ms <ms>', 'connect 最大等待')
     .option('--first-packet-timeout-ms <ms>', '首包最大等待')
     .option('--first-output-timeout-ms <ms>', '首帧输出最大等待')

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

@@ -17,9 +17,11 @@ type ExecFileLike = (file: string, args: string[], options: {
     stdout?: string | Buffer;
     stderr?: string | Buffer;
 }>;
+type ProgressCallback = (message: string) => void;
 type PrepareMediaAssetsOptions = {
     repoRoot?: string;
     execFile?: ExecFileLike;
+    progress?: ProgressCallback;
 };
 export declare function prepareMediaAssets(request: PrepareMediaAssetsRequest, options?: PrepareMediaAssetsOptions): Promise<PrepareMediaAssetsResult>;
 export {};

package/dist/cli/src/media_assets.js

@@ -10,6 +10,17 @@ const path_1 = __importDefault(require("path"));
 const util_1 = require("util");
 const embedded_paths_1 = require("./embedded_paths");
 const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+class PrepareMediaAssetsError extends Error {
+    reasonCode;
+    constructor(message, reasonCode) {
+        super(message);
+        this.name = 'PrepareMediaAssetsError';
+        this.reasonCode = reasonCode;
+    }
+}
+const prepareProgressPrefix = '[prepare_runtime_media_dataset] progress: ';
+const prepareErrorPrefix = '[prepare_runtime_media_dataset] error: ';
+const prepareExecMaxBuffer = 10 * 1024 * 1024;
 function resolveRepoRoot(fromDir) {
     const candidates = [
         path_1.default.resolve(fromDir, '../../..'),
@@ -36,23 +47,72 @@ function resolvePrepareScript(repoRoot) {
     }
     return path_1.default.join(repoRoot, 'runtime/script/prepare_runtime_media_dataset.sh');
 }
-function parseExecError(error) {
+function appendBounded(chunks, text, currentSize, maxSize) {
+    const nextSize = currentSize + Buffer.byteLength(text);
+    if (nextSize > maxSize) {
+        throw new Error('media assets prepare output exceeded buffer limit');
+    }
+    chunks.push(text);
+    return nextSize;
+}
+function emitProgressLine(line, progress) {
+    if (!progress || !line.startsWith(prepareProgressPrefix)) {
+        return;
+    }
+    const message = line.slice(prepareProgressPrefix.length).trim();
+    if (message.length > 0) {
+        progress(message);
+    }
+}
+function emitBufferedProgress(stderr, progress) {
+    if (!stderr || !progress) {
+        return;
+    }
+    String(stderr)
+        .split(/\r?\n/)
+        .forEach((line) => {
+        emitProgressLine(line, progress);
+    });
+}
+function stripProgressLines(message) {
+    const lines = message.split(/\r?\n/);
+    const nonProgressLines = lines.filter((line) => !line.startsWith(prepareProgressPrefix));
+    const cleaned = nonProgressLines.join('\n').trim();
+    return cleaned.length > 0 ? cleaned : message.trim();
+}
+function normalizeExecErrorMessage(message) {
+    const cleaned = stripProgressLines(message);
+    const errorLine = cleaned.split(/\r?\n/).find((line) => line.startsWith(prepareErrorPrefix));
+    const normalized = errorLine ? errorLine.slice(prepareErrorPrefix.length).trim() : cleaned;
+    const reasonMatch = normalized.match(/^([a-z][a-z0-9_]*):\s*(.+)$/);
+    if (reasonMatch) {
+        return {
+            reasonCode: reasonMatch[1],
+            message: reasonMatch[2],
+        };
+    }
+    return { message: normalized };
+}
+function parseExecError(error, progress) {
     if (!error || typeof error !== 'object') {
-        return String(error);
+        return normalizeExecErrorMessage(String(error));
     }
     const typed = error;
+    if (!typed.progressEmitted) {
+        emitBufferedProgress(typed.stderr, progress);
+    }
     const stderr = typeof typed.stderr === 'string' ? typed.stderr.trim() : typed.stderr?.toString('utf8').trim();
     if (stderr && stderr.length > 0) {
-        return stderr;
+        return normalizeExecErrorMessage(stderr);
     }
     const stdout = typeof typed.stdout === 'string' ? typed.stdout.trim() : typed.stdout?.toString('utf8').trim();
     if (stdout && stdout.length > 0) {
-        return stdout;
+        return normalizeExecErrorMessage(stdout);
     }
     if (typed.message && typed.message.length > 0) {
-        return typed.message;
+        return normalizeExecErrorMessage(typed.message);
     }
-    return 'process failed';
+    return { message: 'process failed' };
 }
 function assertPrepareRequest(request) {
     if (!request.source || request.source.trim().length === 0) {
@@ -65,6 +125,74 @@ function assertPrepareRequest(request) {
         throw new Error('media assets prepare requires non-empty --output-dir when provided');
     }
 }
+function execPrepareWithProgress(file, args, options) {
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(file, args, {
+            cwd: options.cwd,
+            env: options.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdoutSize = 0;
+        let stderrSize = 0;
+        let stderrLineBuffer = '';
+        let settled = false;
+        function rejectOnce(error) {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            child.kill();
+            reject(error);
+        }
+        child.stdout.on('data', (chunk) => {
+            try {
+                stdoutSize = appendBounded(stdoutChunks, chunk.toString('utf8'), stdoutSize, options.maxBuffer);
+            }
+            catch (error) {
+                rejectOnce(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+        child.stderr.on('data', (chunk) => {
+            const text = chunk.toString('utf8');
+            try {
+                stderrSize = appendBounded(stderrChunks, text, stderrSize, options.maxBuffer);
+            }
+            catch (error) {
+                rejectOnce(error instanceof Error ? error : new Error(String(error)));
+                return;
+            }
+            stderrLineBuffer += text;
+            const lines = stderrLineBuffer.split(/\r?\n/);
+            stderrLineBuffer = lines.pop() ?? '';
+            lines.forEach((line) => {
+                emitProgressLine(line, options.progress);
+            });
+        });
+        child.on('error', (error) => {
+            rejectOnce(error);
+        });
+        child.on('close', (code, signal) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (stderrLineBuffer.length > 0) {
+                emitProgressLine(stderrLineBuffer, options.progress);
+            }
+            const stdout = stdoutChunks.join('');
+            const stderr = stderrChunks.join('');
+            if (code === 0) {
+                resolve({ stdout, stderr });
+                return;
+            }
+            const error = new Error(signal ? `process killed by signal ${signal}` : `process exited with code ${code}`);
+            Object.assign(error, { stdout, stderr, progressEmitted: true });
+            reject(error);
+        });
+    });
+}
 async function prepareMediaAssets(request, options = {}) {
     assertPrepareRequest(request);
     const repoRoot = options.repoRoot ? path_1.default.resolve(options.repoRoot) : resolveDefaultRepoRoot();
@@ -88,18 +216,29 @@ async function prepareMediaAssets(request, options = {}) {
     }
     let stdout = '';
     try {
-        const result = await execFile('bash', [scriptPath, ...args], {
+        const execOptions = {
             cwd: repoRoot,
             env: {
                 ...process.env,
                 TIRTC_ENSURE_FFMPEG_SCRIPT: ensureFfmpegScriptPath,
             },
-            maxBuffer: 10 * 1024 * 1024,
-        });
+            maxBuffer: prepareExecMaxBuffer,
+        };
+        const useStreamingProgress = options.progress && !options.execFile;
+        const result = useStreamingProgress
+            ? await execPrepareWithProgress('bash', [scriptPath, ...args], {
+                ...execOptions,
+                progress: options.progress,
+            })
+            : await execFile('bash', [scriptPath, ...args], execOptions);
+        if (!useStreamingProgress) {
+            emitBufferedProgress(result.stderr, options.progress);
+        }
         stdout = String(result.stdout ?? '').trim();
     }
     catch (error) {
-        throw new Error(parseExecError(error));
+        const parsed = parseExecError(error, options.progress);
+        throw new PrepareMediaAssetsError(parsed.message, parsed.reasonCode);
     }
     let parsed;
     try {

package/dist/cli/src/role_driver.js

@@ -14,7 +14,6 @@ const embedded_paths_1 = require("./embedded_paths");
 const token_tool_1 = require("./token_tool");
 const defaultAudioStreamId = 10;
 const defaultVideoStreamId = 11;
-const defaultDurationMs = 10000;
 const defaultConnectTimeoutMs = 10000;
 const defaultFirstPacketTimeoutMs = 10000;
 const defaultFirstOutputTimeoutMs = 12000;
@@ -137,6 +136,12 @@ function parsePositiveInt(raw, fallback, name) {
     }
     return parsed;
 }
+function parseOptionalPositiveInt(raw, name) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    return parsePositiveInt(raw, 1, name);
+}
 function requireEnv(name) {
     const value = process.env[name]?.trim();
     if (!value) {
@@ -338,7 +343,7 @@ async function buildSendRequest(roots, artifactRoot, options) {
         },
         output: { consumer: 'frame_dump', video: { frame_limit: defaultFrameLimit } },
         run: {
-            duration_ms: parsePositiveInt(options.durationMs, defaultDurationMs, '--duration-ms'),
+            duration_ms: parseOptionalPositiveInt(options.durationMs, '--duration-ms'),
             connect_timeout_ms: parsePositiveInt(options.connectTimeoutMs, defaultConnectTimeoutMs, '--connect-timeout-ms'),
             first_packet_timeout_ms: parsePositiveInt(options.firstPacketTimeoutMs, defaultFirstPacketTimeoutMs, '--first-packet-timeout-ms'),
             first_output_timeout_ms: defaultFirstOutputTimeoutMs,
@@ -386,7 +391,7 @@ function buildReceiveRequest(roots, artifactRoot, options) {
             video: { frame_limit: parsePositiveInt(options.frameLimit, defaultFrameLimit, '--frame-limit') },
         },
         run: {
-            duration_ms: parsePositiveInt(options.durationMs, defaultDurationMs, '--duration-ms'),
+            duration_ms: parseOptionalPositiveInt(options.durationMs, '--duration-ms'),
             connect_timeout_ms: parsePositiveInt(options.connectTimeoutMs, defaultConnectTimeoutMs, '--connect-timeout-ms'),
             first_packet_timeout_ms: parsePositiveInt(options.firstPacketTimeoutMs, defaultFirstPacketTimeoutMs, '--first-packet-timeout-ms'),
             first_output_timeout_ms: parsePositiveInt(options.firstOutputTimeoutMs, defaultFirstOutputTimeoutMs, '--first-output-timeout-ms'),

package/package.json

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

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

@@ -96,6 +96,17 @@ typedef struct TirtcAudioOutputMetricsSnapshot {
   TirtcPendingDurationMetrics pending;
 } TirtcAudioOutputMetricsSnapshot;
 
+/**
+ * Diagnostic facts currently known for an audio output.
+ *
+ * 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.
+ */
+typedef struct TirtcAudioOutputDebugSnapshot {
+  TirtcMediaCodec codec;
+} TirtcAudioOutputDebugSnapshot;
+
 /**
  * Audio input observer.
  *
@@ -209,6 +220,16 @@ TirtcError tirtc_audio_output_stop_raw_dump(TirtcAudioOutput* output);
 TirtcError tirtc_metrics_audio_output_get_snapshot(TirtcAudioOutput* output,
                                                    TirtcAudioOutputMetricsSnapshot* out_snapshot);
 
+/**
+ * Copies the current or cached audio output diagnostic snapshot.
+ *
+ * The output owns the underlying media downlink. Callers provide only `out_snapshot` storage and do
+ * not receive ownership of any runtime object. The function returns `TIRTC_ERROR_INVALID_ARGUMENT`
+ * for null arguments and does not emit output callbacks or change output state.
+ */
+TirtcError tirtc_audio_output_get_debug_snapshot(TirtcAudioOutput* output,
+                                                 TirtcAudioOutputDebugSnapshot* out_snapshot);
+
 #ifdef __cplusplus
 }
 #endif

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

@@ -48,6 +48,23 @@ typedef struct TirtcVideoOutputMetricsSnapshot {
   TirtcPendingDurationMetrics pending;
 } TirtcVideoOutputMetricsSnapshot;
 
+/**
+ * Diagnostic facts currently known for a video output.
+ *
+ * The snapshot is a caller-owned value copy. `resolved_decoder_backend` is the runtime route that
+ * has actually locked, so AUTO fallback reports the concrete backend family instead of the request.
+ * Zero values mean no current fact or only cached zero-state is available. Additive changes require
+ * a new V2 struct/function instead of extending this layout.
+ */
+typedef struct TirtcVideoOutputDebugSnapshot {
+  TirtcMediaCodec codec;
+  TirtcVideoBitstreamFormat bitstream_format;
+  uint32_t width;
+  uint32_t height;
+  TirtcVideoDecoderPreference requested_decoder_preference;
+  TirtcVideoDecoderBackendKind resolved_decoder_backend;
+} TirtcVideoOutputDebugSnapshot;
+
 typedef struct TirtcVideoOutputOptions {
   TirtcVideoDecoderPreference decoder_preference;
 } TirtcVideoOutputOptions;
@@ -201,6 +218,17 @@ TirtcError tirtc_video_output_stop_raw_dump(TirtcVideoOutput* output);
 TirtcError tirtc_metrics_video_output_get_snapshot(TirtcVideoOutput* output,
                                                    TirtcVideoOutputMetricsSnapshot* out_snapshot);
 
+/**
+ * Copies the current or cached video output diagnostic snapshot.
+ *
+ * The output owns the underlying media downlink and the returned data is only a value copy. Use
+ * this for diagnostics and UI visibility, not to drive decoder selection. The function returns
+ * `TIRTC_ERROR_INVALID_ARGUMENT` for null arguments and does not emit output callbacks or change
+ * output state.
+ */
+TirtcError tirtc_video_output_get_debug_snapshot(TirtcVideoOutput* output,
+                                                 TirtcVideoOutputDebugSnapshot* out_snapshot);
+
 #ifdef __cplusplus
 }
 #endif

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

@@ -9,8 +9,6 @@ typedef enum TirtcError {
   TIRTC_ERROR_OK = 0,
   TIRTC_ERROR_INVALID_ARGUMENT = 6000,
   TIRTC_ERROR_NOT_INITIALIZED = 6001,
-  TIRTC_ERROR_INTERNAL = 6002,
-  TIRTC_ERROR_NOT_READY = 6003,
   TIRTC_ERROR_UNSUPPORTED_LOOP_POLICY = 6004,
   TIRTC_ERROR_SOURCE_HASH_MISMATCH = 6005,
   TIRTC_ERROR_ALREADY_STOPPED = 6006,
@@ -52,6 +50,47 @@ typedef enum TirtcError {
   TIRTC_ERROR_VIDEO_DECODER_RUNTIME_FAILED = 6040,
   TIRTC_ERROR_VIDEO_OUTPUT_TARGET_UNAVAILABLE = 6041,
   TIRTC_ERROR_VIDEO_OUTPUT_RENDER_FAILED = 6042,
+  TIRTC_ERROR_RESOURCE_EXHAUSTED = 6043,
+  TIRTC_ERROR_FILE_OPEN_FAILED = 6044,
+  TIRTC_ERROR_FILE_READ_FAILED = 6045,
+  TIRTC_ERROR_FILE_WRITE_FAILED = 6046,
+  TIRTC_ERROR_HTTP_REQUEST_FAILED = 6047,
+  TIRTC_ERROR_LOG_EXPORT_FAILED = 6048,
+  TIRTC_ERROR_LOG_UPLOAD_FAILED = 6049,
+  TIRTC_ERROR_S3_UPLOAD_FAILED = 6050,
+  TIRTC_ERROR_AUDIO_INPUT_OPEN_FAILED = 6051,
+  TIRTC_ERROR_AUDIO_INPUT_RUNTIME_FAILED = 6052,
+  TIRTC_ERROR_AUDIO_OUTPUT_OPEN_FAILED = 6053,
+  TIRTC_ERROR_AUDIO_OUTPUT_RUNTIME_FAILED = 6054,
+  TIRTC_ERROR_AUDIO_PROCESSING_INITIALIZATION_FAILED = 6055,
+  TIRTC_ERROR_AUDIO_PROCESSING_RUNTIME_FAILED = 6056,
+  TIRTC_ERROR_VIDEO_ENCODER_RUNTIME_FAILED = 6057,
+  TIRTC_ERROR_VIDEO_PROCESSING_RUNTIME_FAILED = 6058,
+  TIRTC_ERROR_VIDEO_INPUT_OPEN_FAILED = 6059,
+  TIRTC_ERROR_VIDEO_INPUT_RUNTIME_FAILED = 6060,
+  TIRTC_ERROR_VIDEO_OUTPUT_OPEN_FAILED = 6061,
+  TIRTC_ERROR_MEDIA_UPLINK_CREATE_FAILED = 6062,
+  TIRTC_ERROR_MEDIA_UPLINK_START_FAILED = 6063,
+  TIRTC_ERROR_MEDIA_DOWNLINK_DECODE_FAILED = 6064,
+  TIRTC_ERROR_MEDIA_RAW_DUMP_FAILED = 6065,
+  TIRTC_ERROR_FACADE_RUNTIME_FAILED = 6066,
+  TIRTC_ERROR_LOG_WRITE_FAILED = 6067,
+  TIRTC_ERROR_AUDIO_ENCODER_RUNTIME_FAILED = 6068,
+  TIRTC_ERROR_AUDIO_DECODER_RUNTIME_FAILED = 6069,
+  TIRTC_ERROR_HTTP_CLIENT_UNAVAILABLE = 6070,
+  TIRTC_ERROR_HTTP_TLS_UNSUPPORTED = 6071,
+  TIRTC_ERROR_UPLOAD_TOKEN_EXPIRED = 6072,
+  TIRTC_ERROR_STREAM_ID_IN_USE = 6073,
+  TIRTC_ERROR_VIDEO_PREVIEW_IN_USE = 6074,
+  TIRTC_ERROR_FACADE_PEER_ID_UNAVAILABLE = 6075,
+  TIRTC_ERROR_MEDIA_DOWNLINK_QUEUE_FULL = 6076,
+  TIRTC_ERROR_MEDIA_DOWNLINK_OUTPUT_PENDING = 6077,
+  TIRTC_ERROR_TRANSPORT_INVALID_HANDLE = 6078,
+  TIRTC_ERROR_VIDEO_ENCODER_INPUT_PENDING = 6079,
+  TIRTC_ERROR_VIDEO_ENCODER_OUTPUT_PENDING = 6080,
+  TIRTC_ERROR_VIDEO_DECODER_INPUT_PENDING = 6081,
+  TIRTC_ERROR_VIDEO_DECODER_OUTPUT_PENDING = 6082,
+  TIRTC_ERROR_MEDIA_UPLINK_INPUT_MODE_MISMATCH = 6083,
 } TirtcError;
 
 const char* tirtc_error_to_string(TirtcError error);

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

@@ -86,6 +86,33 @@ typedef struct TirtcMediaDownlinkVideoMetricsSnapshot {
   TirtcMediaDownlinkPendingMetricsSnapshot pending;
 } TirtcMediaDownlinkVideoMetricsSnapshot;
 
+/**
+ * Diagnostic facts currently known by an audio downlink.
+ *
+ * The snapshot is a value copy into caller-owned storage. `codec` is
+ * `TIRTC_MEDIA_CODEC_NONE` until the downlink accepts a valid encoded audio frame.
+ */
+typedef struct TirtcMediaDownlinkAudioDebugSnapshot {
+  TirtcMediaCodec codec;
+} TirtcMediaDownlinkAudioDebugSnapshot;
+
+/**
+ * Diagnostic facts currently known by a video downlink.
+ *
+ * The snapshot is a value copy into caller-owned storage. Zero values mean the downlink has not
+ * observed the corresponding fact since start/reset. `requested_decoder_preference` reflects the
+ * configured option; `resolved_decoder_backend` is only set after the runtime locks a concrete
+ * decode route.
+ */
+typedef struct TirtcMediaDownlinkVideoDebugSnapshot {
+  TirtcMediaCodec codec;
+  TirtcVideoBitstreamFormat bitstream_format;
+  uint32_t width;
+  uint32_t height;
+  TirtcVideoDecoderPreference requested_decoder_preference;
+  TirtcVideoDecoderBackendKind resolved_decoder_backend;
+} TirtcMediaDownlinkVideoDebugSnapshot;
+
 TirtcError tirtc_media_downlink_audio_create(TirtcMediaDownlinkAudio** out_downlink);
 void tirtc_media_downlink_audio_retain(TirtcMediaDownlinkAudio* downlink);
 void tirtc_media_downlink_audio_release(TirtcMediaDownlinkAudio* downlink);
@@ -147,6 +174,24 @@ TirtcError tirtc_media_downlink_video_get_metrics_snapshot(
     TirtcMediaDownlinkVideo* downlink, TirtcMediaDownlinkVideoMetricsSnapshot* out_snapshot);
 void tirtc_media_downlink_video_reset_metrics_session(TirtcMediaDownlinkVideo* downlink);
 
+/**
+ * Copies the current audio downlink diagnostic snapshot.
+ *
+ * This call does not start, stop, flush, or otherwise change the downlink. It returns
+ * `TIRTC_ERROR_INVALID_ARGUMENT` when `downlink` or `out_snapshot` is null.
+ */
+TirtcError tirtc_media_downlink_audio_get_debug_snapshot(
+    TirtcMediaDownlinkAudio* downlink, TirtcMediaDownlinkAudioDebugSnapshot* out_snapshot);
+
+/**
+ * Copies the current video downlink diagnostic snapshot.
+ *
+ * This call does not start, stop, flush, or otherwise change the downlink. It returns
+ * `TIRTC_ERROR_INVALID_ARGUMENT` when `downlink` or `out_snapshot` is null.
+ */
+TirtcError tirtc_media_downlink_video_get_debug_snapshot(
+    TirtcMediaDownlinkVideo* downlink, TirtcMediaDownlinkVideoDebugSnapshot* out_snapshot);
+
 #ifdef __cplusplus
 }
 #endif

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

@@ -26,6 +26,19 @@ typedef enum TirtcVideoDecoderPreference {
   TIRTC_VIDEO_DECODER_PREFERENCE_HARDWARE = 2,
 } TirtcVideoDecoderPreference;
 
+/**
+ * Backend family that is actually handling a video decoder route.
+ *
+ * `UNKNOWN` means the runtime has not locked a decoder route or the current snapshot cannot prove
+ * one. The enum intentionally reports only the supported backend family; platform-specific decoder
+ * names and native handles are not part of this public surface.
+ */
+typedef enum TirtcVideoDecoderBackendKind {
+  TIRTC_VIDEO_DECODER_BACKEND_KIND_UNKNOWN = 0,
+  TIRTC_VIDEO_DECODER_BACKEND_KIND_SOFTWARE = 1,
+  TIRTC_VIDEO_DECODER_BACKEND_KIND_HARDWARE = 2,
+} TirtcVideoDecoderBackendKind;
+
 typedef enum TirtcVideoEncoderBackendKind {
   TIRTC_VIDEO_ENCODER_BACKEND_KIND_SOFTWARE = 1,
   TIRTC_VIDEO_ENCODER_BACKEND_KIND_HARDWARE = 2,

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

@@ -1,9 +1,9 @@
 platform=linux-x64
 profile=full
-staged_at_utc=2026-04-30T08:01:24Z
+staged_at_utc=2026-04-30T09:51:52Z
 source_sdk=/Users/allenfeng/Development/Repositories/tirtc-nexus/tirtc-matrix/.build/sdk/linux-x64
 
-e962631f85675937fd973797720466fd75717f74335c8102c664814d59179113  include/tirtc/audio.h
+bfc096be1484ac2b1c2776ccabfa2a4c6a982e869abf875192ff06fad85e82ca  include/tirtc/audio.h
 6d972ccfe150a3b4f2d7f18fa92b3ade9210c1c8bb754d061ac6b7997b59e2cb  include/tirtc/audio_codec.h
 7bacbdb2d8bb10d6444036a8fef42f2a8e3ea34dfc38e165ee678d61f189db41  include/tirtc/audio_frame.h
 fb8ea35263167c33487bd3aa503c26ed2dfbf97877f7bda92c10065cd5c97c13  include/tirtc/audio_io.h
@@ -13,17 +13,17 @@ c2e1f31dcc75be461c577d18b1cebe32774f212d51cb4dd2a5b5a9bfe62b693e  include/tirtc/
 51cbc911fe9f9834046f0e0a1a7cdd814a8e194a615894a8b4d11f9e5f095610  include/tirtc/audio_io_windows.h
 21f60729117260a44af22c1af986ef17d22673b102b7b7a035f492d0665cce16  include/tirtc/audio_processing.h
 0ca7c3c630b1242f51a0fd8154097c0a332b4c816a5707090e4381719852998c  include/tirtc/audio_sample_rate.h
-94f378da8bc728a1b9a44fbe74a0367b06ad2401ae55fa5bb6bee63b447ce511  include/tirtc/av.h
-70d0e950f78309e12c927b37a6f7184fe3724edc5391176a697f7d7c7f49ab5a  include/tirtc/error.h
+58807ba56770f38f47aec995661cadf9d3c1d6ea7bfc940767f1ce67317c7546  include/tirtc/av.h
+0f3e2f454c35e8c2f79bdc93ed77f9f1622751e5a05defa8c9d4213ed8a797c5  include/tirtc/error.h
 ae805545a9515edc9b94262e72ad2c7b7d649288166f4daeb450d8a55e82ae0b  include/tirtc/foundation/build_info.h
 7cf8b372a3d48d4de4a65a04c7f102281a7b42cebb9ec247853d3c53afb63b6a  include/tirtc/http.h
 70bbf93b84d9d1a85f376d9986de570c1f658319e1e5ab6d621f7a4d41033f5c  include/tirtc/logging.h
 7e2f7f81afe37e22f5414d9db32438edd948ff775230c3a0a17ff9ac1a0b560e  include/tirtc/media_codec.h
-0d1c3a8d1537a839cb6050fe5b35079087f094673dd9eb5b4d9acdcc9a2dd5fc  include/tirtc/media_downlink.h
+ca63fe4fa0c787f20923e264e116fa6d7cb8194a227c03be4e9843d0ce5a9864  include/tirtc/media_downlink.h
 e64191a39004165cdcd11b2ca824af34d4bfe02f7ec3c3101fa9291f56488c30  include/tirtc/media_uplink.h
 489f6c9caa3e4094566b660ef0a002a39c66c1956ef0a1bdb6eacca3798c849a  include/tirtc/transport.h
 bb9c1bf46f2ab51a9f7adb211276c8563b09e7968031c0c6abeebc0eddd66acb  include/tirtc/trp.h
-118593dd6e57d1a982c4b861e7d26f066a4eb4b5f2e152dbf7b7205d87b467f2  include/tirtc/video_codec.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
@@ -33,13 +33,13 @@ cae0bbeb884e5466a56da15182c78cc22baab6c743f349a58d3595f623333585  include/tirtc/
 8cd6b66bea14890a665cc317f8572429b2c3e4463773f8b77c1e4dc30a4a8747  include/tirtc/video_processing.h
 ceb7cdd45efae57e5bd53d4177cb20c4a0cb9917fcdd23127b050d69c8b919ac  lib/libTiRTC.a
 b1f4135025cb8e8520a14268d831b9998920a4239f84bb6b409d0e4909fd5bee  lib/libcrypto.a
-80ac9dbdaeb9663399f41611d1bc92a8ee42895b8b38e7d55c25182d90892830  lib/libmatrix_runtime_audio.a
-8833f0f933d73a4c6b10ff3cbbe449e11eb22b2267cb4f2da2fc347782d08d83  lib/libmatrix_runtime_facade.a
-36903d3970287164fa51fe9c2014aa7f654e144a93886c8909904f732ff14d94  lib/libmatrix_runtime_foundation_http.a
-e9a29e7e32a3402bbfdd3fead86ba50a778023ba623de79bc4ab7440797a90a0  lib/libmatrix_runtime_foundation_logging.a
-85c9a5f7ee47279be62c719a3f0efb9b0b5b9724ed3679c38c49900c53105c36  lib/libmatrix_runtime_media.a
-4afd4c0059a4735cd206f4d26669acaa97a367d572c0cc30e51efba198d9817f  lib/libmatrix_runtime_transport.a
-6d57712181cff75b8169753d7217c1a1675c3df4e4a30eca3645c5016cb0b87e  lib/libmatrix_runtime_video.a
+8e3aff3a400fe0971c61511947c0e69d06754002d970e21eaab2339ae38b4a42  lib/libmatrix_runtime_audio.a
+09696896a45a4fab199f0767979471c947b252fc8741a0e803624cdac6953b59  lib/libmatrix_runtime_facade.a
+2c8cc881eeeae679129360df5813dec17d0e33935f196d79cf79671dbd0c8581  lib/libmatrix_runtime_foundation_http.a
+4623c3c72a263f0397e554435e4998551c274b5b40f98f331902a8c0c8a29e3e  lib/libmatrix_runtime_foundation_logging.a
+fe6b5575ce5e80f81e07a7799a05d0a8ee5a338915a28ada86d9009eee952e96  lib/libmatrix_runtime_media.a
+86d9b41f84c6bcc13f8d23a1f9b46d97fe6769573758722f9f6c8d4a130306be  lib/libmatrix_runtime_transport.a
+6ac178f5cd371e9a5be1989dd1e8a3767291f4c4d9d30dcf12ecdd75a2081afa  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

@@ -96,6 +96,17 @@ typedef struct TirtcAudioOutputMetricsSnapshot {
   TirtcPendingDurationMetrics pending;
 } TirtcAudioOutputMetricsSnapshot;
 
+/**
+ * Diagnostic facts currently known for an audio output.
+ *
+ * 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.
+ */
+typedef struct TirtcAudioOutputDebugSnapshot {
+  TirtcMediaCodec codec;
+} TirtcAudioOutputDebugSnapshot;
+
 /**
  * Audio input observer.
  *
@@ -209,6 +220,16 @@ TirtcError tirtc_audio_output_stop_raw_dump(TirtcAudioOutput* output);
 TirtcError tirtc_metrics_audio_output_get_snapshot(TirtcAudioOutput* output,
                                                    TirtcAudioOutputMetricsSnapshot* out_snapshot);
 
+/**
+ * Copies the current or cached audio output diagnostic snapshot.
+ *
+ * The output owns the underlying media downlink. Callers provide only `out_snapshot` storage and do
+ * not receive ownership of any runtime object. The function returns `TIRTC_ERROR_INVALID_ARGUMENT`
+ * for null arguments and does not emit output callbacks or change output state.
+ */
+TirtcError tirtc_audio_output_get_debug_snapshot(TirtcAudioOutput* output,
+                                                 TirtcAudioOutputDebugSnapshot* out_snapshot);
+
 #ifdef __cplusplus
 }
 #endif

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

@@ -48,6 +48,23 @@ typedef struct TirtcVideoOutputMetricsSnapshot {
   TirtcPendingDurationMetrics pending;
 } TirtcVideoOutputMetricsSnapshot;
 
+/**
+ * Diagnostic facts currently known for a video output.
+ *
+ * The snapshot is a caller-owned value copy. `resolved_decoder_backend` is the runtime route that
+ * has actually locked, so AUTO fallback reports the concrete backend family instead of the request.
+ * Zero values mean no current fact or only cached zero-state is available. Additive changes require
+ * a new V2 struct/function instead of extending this layout.
+ */
+typedef struct TirtcVideoOutputDebugSnapshot {
+  TirtcMediaCodec codec;
+  TirtcVideoBitstreamFormat bitstream_format;
+  uint32_t width;
+  uint32_t height;
+  TirtcVideoDecoderPreference requested_decoder_preference;
+  TirtcVideoDecoderBackendKind resolved_decoder_backend;
+} TirtcVideoOutputDebugSnapshot;
+
 typedef struct TirtcVideoOutputOptions {
   TirtcVideoDecoderPreference decoder_preference;
 } TirtcVideoOutputOptions;
@@ -201,6 +218,17 @@ TirtcError tirtc_video_output_stop_raw_dump(TirtcVideoOutput* output);
 TirtcError tirtc_metrics_video_output_get_snapshot(TirtcVideoOutput* output,
                                                    TirtcVideoOutputMetricsSnapshot* out_snapshot);
 
+/**
+ * Copies the current or cached video output diagnostic snapshot.
+ *
+ * The output owns the underlying media downlink and the returned data is only a value copy. Use
+ * this for diagnostics and UI visibility, not to drive decoder selection. The function returns
+ * `TIRTC_ERROR_INVALID_ARGUMENT` for null arguments and does not emit output callbacks or change
+ * output state.
+ */
+TirtcError tirtc_video_output_get_debug_snapshot(TirtcVideoOutput* output,
+                                                 TirtcVideoOutputDebugSnapshot* out_snapshot);
+
 #ifdef __cplusplus
 }
 #endif

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

@@ -9,8 +9,6 @@ typedef enum TirtcError {
   TIRTC_ERROR_OK = 0,
   TIRTC_ERROR_INVALID_ARGUMENT = 6000,
   TIRTC_ERROR_NOT_INITIALIZED = 6001,
-  TIRTC_ERROR_INTERNAL = 6002,
-  TIRTC_ERROR_NOT_READY = 6003,
   TIRTC_ERROR_UNSUPPORTED_LOOP_POLICY = 6004,
   TIRTC_ERROR_SOURCE_HASH_MISMATCH = 6005,
   TIRTC_ERROR_ALREADY_STOPPED = 6006,
@@ -52,6 +50,47 @@ typedef enum TirtcError {
   TIRTC_ERROR_VIDEO_DECODER_RUNTIME_FAILED = 6040,
   TIRTC_ERROR_VIDEO_OUTPUT_TARGET_UNAVAILABLE = 6041,
   TIRTC_ERROR_VIDEO_OUTPUT_RENDER_FAILED = 6042,
+  TIRTC_ERROR_RESOURCE_EXHAUSTED = 6043,
+  TIRTC_ERROR_FILE_OPEN_FAILED = 6044,
+  TIRTC_ERROR_FILE_READ_FAILED = 6045,
+  TIRTC_ERROR_FILE_WRITE_FAILED = 6046,
+  TIRTC_ERROR_HTTP_REQUEST_FAILED = 6047,
+  TIRTC_ERROR_LOG_EXPORT_FAILED = 6048,
+  TIRTC_ERROR_LOG_UPLOAD_FAILED = 6049,
+  TIRTC_ERROR_S3_UPLOAD_FAILED = 6050,
+  TIRTC_ERROR_AUDIO_INPUT_OPEN_FAILED = 6051,
+  TIRTC_ERROR_AUDIO_INPUT_RUNTIME_FAILED = 6052,
+  TIRTC_ERROR_AUDIO_OUTPUT_OPEN_FAILED = 6053,
+  TIRTC_ERROR_AUDIO_OUTPUT_RUNTIME_FAILED = 6054,
+  TIRTC_ERROR_AUDIO_PROCESSING_INITIALIZATION_FAILED = 6055,
+  TIRTC_ERROR_AUDIO_PROCESSING_RUNTIME_FAILED = 6056,
+  TIRTC_ERROR_VIDEO_ENCODER_RUNTIME_FAILED = 6057,
+  TIRTC_ERROR_VIDEO_PROCESSING_RUNTIME_FAILED = 6058,
+  TIRTC_ERROR_VIDEO_INPUT_OPEN_FAILED = 6059,
+  TIRTC_ERROR_VIDEO_INPUT_RUNTIME_FAILED = 6060,
+  TIRTC_ERROR_VIDEO_OUTPUT_OPEN_FAILED = 6061,
+  TIRTC_ERROR_MEDIA_UPLINK_CREATE_FAILED = 6062,
+  TIRTC_ERROR_MEDIA_UPLINK_START_FAILED = 6063,
+  TIRTC_ERROR_MEDIA_DOWNLINK_DECODE_FAILED = 6064,
+  TIRTC_ERROR_MEDIA_RAW_DUMP_FAILED = 6065,
+  TIRTC_ERROR_FACADE_RUNTIME_FAILED = 6066,
+  TIRTC_ERROR_LOG_WRITE_FAILED = 6067,
+  TIRTC_ERROR_AUDIO_ENCODER_RUNTIME_FAILED = 6068,
+  TIRTC_ERROR_AUDIO_DECODER_RUNTIME_FAILED = 6069,
+  TIRTC_ERROR_HTTP_CLIENT_UNAVAILABLE = 6070,
+  TIRTC_ERROR_HTTP_TLS_UNSUPPORTED = 6071,
+  TIRTC_ERROR_UPLOAD_TOKEN_EXPIRED = 6072,
+  TIRTC_ERROR_STREAM_ID_IN_USE = 6073,
+  TIRTC_ERROR_VIDEO_PREVIEW_IN_USE = 6074,
+  TIRTC_ERROR_FACADE_PEER_ID_UNAVAILABLE = 6075,
+  TIRTC_ERROR_MEDIA_DOWNLINK_QUEUE_FULL = 6076,
+  TIRTC_ERROR_MEDIA_DOWNLINK_OUTPUT_PENDING = 6077,
+  TIRTC_ERROR_TRANSPORT_INVALID_HANDLE = 6078,
+  TIRTC_ERROR_VIDEO_ENCODER_INPUT_PENDING = 6079,
+  TIRTC_ERROR_VIDEO_ENCODER_OUTPUT_PENDING = 6080,
+  TIRTC_ERROR_VIDEO_DECODER_INPUT_PENDING = 6081,
+  TIRTC_ERROR_VIDEO_DECODER_OUTPUT_PENDING = 6082,
+  TIRTC_ERROR_MEDIA_UPLINK_INPUT_MODE_MISMATCH = 6083,
 } TirtcError;
 
 const char* tirtc_error_to_string(TirtcError error);

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

@@ -86,6 +86,33 @@ typedef struct TirtcMediaDownlinkVideoMetricsSnapshot {
   TirtcMediaDownlinkPendingMetricsSnapshot pending;
 } TirtcMediaDownlinkVideoMetricsSnapshot;
 
+/**
+ * Diagnostic facts currently known by an audio downlink.
+ *
+ * The snapshot is a value copy into caller-owned storage. `codec` is
+ * `TIRTC_MEDIA_CODEC_NONE` until the downlink accepts a valid encoded audio frame.
+ */
+typedef struct TirtcMediaDownlinkAudioDebugSnapshot {
+  TirtcMediaCodec codec;
+} TirtcMediaDownlinkAudioDebugSnapshot;
+
+/**
+ * Diagnostic facts currently known by a video downlink.
+ *
+ * The snapshot is a value copy into caller-owned storage. Zero values mean the downlink has not
+ * observed the corresponding fact since start/reset. `requested_decoder_preference` reflects the
+ * configured option; `resolved_decoder_backend` is only set after the runtime locks a concrete
+ * decode route.
+ */
+typedef struct TirtcMediaDownlinkVideoDebugSnapshot {
+  TirtcMediaCodec codec;
+  TirtcVideoBitstreamFormat bitstream_format;
+  uint32_t width;
+  uint32_t height;
+  TirtcVideoDecoderPreference requested_decoder_preference;
+  TirtcVideoDecoderBackendKind resolved_decoder_backend;
+} TirtcMediaDownlinkVideoDebugSnapshot;
+
 TirtcError tirtc_media_downlink_audio_create(TirtcMediaDownlinkAudio** out_downlink);
 void tirtc_media_downlink_audio_retain(TirtcMediaDownlinkAudio* downlink);
 void tirtc_media_downlink_audio_release(TirtcMediaDownlinkAudio* downlink);
@@ -147,6 +174,24 @@ TirtcError tirtc_media_downlink_video_get_metrics_snapshot(
     TirtcMediaDownlinkVideo* downlink, TirtcMediaDownlinkVideoMetricsSnapshot* out_snapshot);
 void tirtc_media_downlink_video_reset_metrics_session(TirtcMediaDownlinkVideo* downlink);
 
+/**
+ * Copies the current audio downlink diagnostic snapshot.
+ *
+ * This call does not start, stop, flush, or otherwise change the downlink. It returns
+ * `TIRTC_ERROR_INVALID_ARGUMENT` when `downlink` or `out_snapshot` is null.
+ */
+TirtcError tirtc_media_downlink_audio_get_debug_snapshot(
+    TirtcMediaDownlinkAudio* downlink, TirtcMediaDownlinkAudioDebugSnapshot* out_snapshot);
+
+/**
+ * Copies the current video downlink diagnostic snapshot.
+ *
+ * This call does not start, stop, flush, or otherwise change the downlink. It returns
+ * `TIRTC_ERROR_INVALID_ARGUMENT` when `downlink` or `out_snapshot` is null.
+ */
+TirtcError tirtc_media_downlink_video_get_debug_snapshot(
+    TirtcMediaDownlinkVideo* downlink, TirtcMediaDownlinkVideoDebugSnapshot* out_snapshot);
+
 #ifdef __cplusplus
 }
 #endif

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

@@ -26,6 +26,19 @@ typedef enum TirtcVideoDecoderPreference {
   TIRTC_VIDEO_DECODER_PREFERENCE_HARDWARE = 2,
 } TirtcVideoDecoderPreference;
 
+/**
+ * Backend family that is actually handling a video decoder route.
+ *
+ * `UNKNOWN` means the runtime has not locked a decoder route or the current snapshot cannot prove
+ * one. The enum intentionally reports only the supported backend family; platform-specific decoder
+ * names and native handles are not part of this public surface.
+ */
+typedef enum TirtcVideoDecoderBackendKind {
+  TIRTC_VIDEO_DECODER_BACKEND_KIND_UNKNOWN = 0,
+  TIRTC_VIDEO_DECODER_BACKEND_KIND_SOFTWARE = 1,
+  TIRTC_VIDEO_DECODER_BACKEND_KIND_HARDWARE = 2,
+} TirtcVideoDecoderBackendKind;
+
 typedef enum TirtcVideoEncoderBackendKind {
   TIRTC_VIDEO_ENCODER_BACKEND_KIND_SOFTWARE = 1,
   TIRTC_VIDEO_ENCODER_BACKEND_KIND_HARDWARE = 2,

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

@@ -1,9 +1,9 @@
 platform=macos-arm64
 profile=full
-staged_at_utc=2026-04-30T07:59:34Z
+staged_at_utc=2026-04-30T09:50:11Z
 source_sdk=/Users/allenfeng/Development/Repositories/tirtc-nexus/tirtc-matrix/.build/sdk/macos-arm64
 
-e962631f85675937fd973797720466fd75717f74335c8102c664814d59179113  include/tirtc/audio.h
+bfc096be1484ac2b1c2776ccabfa2a4c6a982e869abf875192ff06fad85e82ca  include/tirtc/audio.h
 6d972ccfe150a3b4f2d7f18fa92b3ade9210c1c8bb754d061ac6b7997b59e2cb  include/tirtc/audio_codec.h
 7bacbdb2d8bb10d6444036a8fef42f2a8e3ea34dfc38e165ee678d61f189db41  include/tirtc/audio_frame.h
 fb8ea35263167c33487bd3aa503c26ed2dfbf97877f7bda92c10065cd5c97c13  include/tirtc/audio_io.h
@@ -13,17 +13,17 @@ c2e1f31dcc75be461c577d18b1cebe32774f212d51cb4dd2a5b5a9bfe62b693e  include/tirtc/
 51cbc911fe9f9834046f0e0a1a7cdd814a8e194a615894a8b4d11f9e5f095610  include/tirtc/audio_io_windows.h
 21f60729117260a44af22c1af986ef17d22673b102b7b7a035f492d0665cce16  include/tirtc/audio_processing.h
 0ca7c3c630b1242f51a0fd8154097c0a332b4c816a5707090e4381719852998c  include/tirtc/audio_sample_rate.h
-94f378da8bc728a1b9a44fbe74a0367b06ad2401ae55fa5bb6bee63b447ce511  include/tirtc/av.h
-70d0e950f78309e12c927b37a6f7184fe3724edc5391176a697f7d7c7f49ab5a  include/tirtc/error.h
+58807ba56770f38f47aec995661cadf9d3c1d6ea7bfc940767f1ce67317c7546  include/tirtc/av.h
+0f3e2f454c35e8c2f79bdc93ed77f9f1622751e5a05defa8c9d4213ed8a797c5  include/tirtc/error.h
 ae805545a9515edc9b94262e72ad2c7b7d649288166f4daeb450d8a55e82ae0b  include/tirtc/foundation/build_info.h
 7cf8b372a3d48d4de4a65a04c7f102281a7b42cebb9ec247853d3c53afb63b6a  include/tirtc/http.h
 70bbf93b84d9d1a85f376d9986de570c1f658319e1e5ab6d621f7a4d41033f5c  include/tirtc/logging.h
 7e2f7f81afe37e22f5414d9db32438edd948ff775230c3a0a17ff9ac1a0b560e  include/tirtc/media_codec.h
-0d1c3a8d1537a839cb6050fe5b35079087f094673dd9eb5b4d9acdcc9a2dd5fc  include/tirtc/media_downlink.h
+ca63fe4fa0c787f20923e264e116fa6d7cb8194a227c03be4e9843d0ce5a9864  include/tirtc/media_downlink.h
 e64191a39004165cdcd11b2ca824af34d4bfe02f7ec3c3101fa9291f56488c30  include/tirtc/media_uplink.h
 489f6c9caa3e4094566b660ef0a002a39c66c1956ef0a1bdb6eacca3798c849a  include/tirtc/transport.h
 bb9c1bf46f2ab51a9f7adb211276c8563b09e7968031c0c6abeebc0eddd66acb  include/tirtc/trp.h
-118593dd6e57d1a982c4b861e7d26f066a4eb4b5f2e152dbf7b7205d87b467f2  include/tirtc/video_codec.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
@@ -35,13 +35,13 @@ cae0bbeb884e5466a56da15182c78cc22baab6c743f349a58d3595f623333585  include/tirtc/
 8db86d6714264047e8fd4086ddd7315722d675749719e6175f89eb5a636b48a1  lib/libTiRTC.a
 b39daee6a3d39bf0ca20c45084601133c4198de8dca848dcff6dd9c70ae99016  lib/libcrypto.a
 c052857ef315e3d61db9c862cad10709a3a6b2487dc41799cbe4d74a805de875  lib/libcrypto.dylib
-bebab2284a97d096459f529ce0487a5771b57d1093f463e4edd5a1412280c302  lib/libmatrix_runtime_audio.a
-799afd26eee24dba73df2822891c1853862637009dd30a91a815026f67f914b8  lib/libmatrix_runtime_facade.a
-9796bcdc16c2f5e42717c232cd420c2a9afe847ab5b0c796f069ad51d1d5b6e3  lib/libmatrix_runtime_foundation_http.a
-fd152bf7f0570a3bc4bf8189259b3ea503399e33e7de9e08cd6471c9ab81b7f0  lib/libmatrix_runtime_foundation_logging.a
-a85656deb81ca93db6b96335381c22e4459e8b4e33c50e55f7df4f0afd9e0119  lib/libmatrix_runtime_media.a
-b7becad7c95e98b8bece1cd517e60d713e2cc24d229a4f2d8daa464ea161ed08  lib/libmatrix_runtime_transport.a
-6953ed12d48116841f09e9edb6dfb0cc511323ed71887eb6cab5fe1c204d10b8  lib/libmatrix_runtime_video.a
+d6f03b56a9de8db6b283acbdd9fc2805d23d672f4cb88749f55a627443b2519f  lib/libmatrix_runtime_audio.a
+7524498dba92087ba33853290db0cfaa0ec79b50ffdf22c8e35b0484c24af7cc  lib/libmatrix_runtime_facade.a
+05687add5f3f27adea62568b9d42be52659a494500cce0245d601da566aa45e3  lib/libmatrix_runtime_foundation_http.a
+89af61f8a48b2c7cfa9c80de8b9a708bca4ac2b1b4b2929d1d932a5c4d422501  lib/libmatrix_runtime_foundation_logging.a
+6a61357646112e1427db956ba87766838b51bdd7d8aec43ec07c2aba20570ee7  lib/libmatrix_runtime_media.a
+cc39fbeacd2c8cd6b508cd3300bf8fd5b6a93f6d2d19b160b65ed03deca777c4  lib/libmatrix_runtime_transport.a
+7ab317069e6bdeb3d24d215cd7bb6f298ea47cf1cff43ac36460aaab7effbd8d  lib/libmatrix_runtime_video.a
 c11c65d373a127028350c41fa58cd2d1223f2b5d70a84e13b115d90daaba25ca  lib/libssl.a
 ef1c1104bbdd2528ed7b958fb7252bd6249875f92300b0c9577d6c4bd6c0d88a  lib/libssl.dylib
 e14e846e43d64e240fa0e5745bf4e702b79d0f2442e7f768beb990610735c71b  lib/libtgrtc.dylib

package/vendor/runtime/script/prepare_runtime_media_dataset.sh

@@ -20,6 +20,10 @@ fail() {
   exit 1
 }
 
+progress() {
+  echo "[prepare_runtime_media_dataset] progress: $*" >&2
+}
+
 require_cmd() {
   command -v "$1" >/dev/null 2>&1 || fail "missing required command: $1"
 }
@@ -145,6 +149,22 @@ readonly k_audio_codec="g711a"
 readonly k_output_audio_format="pcm_s16"
 readonly k_output_video_format="rgba8888"
 
+progress "checking source media streams"
+AUDIO_STREAM_PRESENT="$(
+  AUDIO_STREAM_JSON="$("$FFPROBE_BIN" -v error -select_streams a:0 \
+    -show_entries stream=index -of json "$SOURCE_ABS")" \
+    node <<'NODE'
+const payload = process.env.AUDIO_STREAM_JSON;
+if (!payload) {
+  throw new Error('missing AUDIO_STREAM_JSON');
+}
+const parsed = JSON.parse(payload);
+const stream = Array.isArray(parsed.streams) ? parsed.streams[0] : null;
+process.stdout.write(stream ? '1' : '0');
+NODE
+)"
+[[ "$AUDIO_STREAM_PRESENT" == "1" ]] || fail "invalid_source_media: source mp4 is missing an audio stream: $SOURCE_ABS"
+
 VIDEO_STREAM_FIELDS="$(
   VIDEO_STREAM_JSON="$("$FFPROBE_BIN" -v error -select_streams v:0 \
     -show_entries stream=width,height,bit_rate -of json "$SOURCE_ABS")" \
@@ -215,6 +235,7 @@ fi
 MANIFEST_PATH="$ASSETS_DIR/manifest.json"
 
 if [[ -f "$MANIFEST_PATH" && "$OVERWRITE" -ne 1 ]]; then
+  progress "using cached prepared media assets"
   emit_result "$ASSETS_DIR" "$MANIFEST_PATH" true
   exit 0
 fi
@@ -259,6 +280,7 @@ else
   video_encode_args+=(-crf 18)
 fi
 
+progress "encoding h264 video track"
 "$FFMPEG_BIN" -hide_banner -loglevel error -y \
   -i "$SOURCE_ABS" \
   -an \
@@ -287,6 +309,7 @@ else
   video_h265_encode_args+=(-crf 23)
 fi
 
+progress "encoding h265 video track"
 "$FFMPEG_BIN" -hide_banner -loglevel error -y \
   -i "$SOURCE_ABS" \
   -an \
@@ -296,6 +319,7 @@ fi
 
 mjpeg_frame_dir="$ASSETS_DIR/video/mjpeg_frames"
 mkdir -p "$mjpeg_frame_dir"
+progress "extracting mjpeg video frames"
 "$FFMPEG_BIN" -hide_banner -loglevel error -y \
   -i "$SOURCE_ABS" \
   -vf "fps=1/${k_mjpeg_extract_interval_seconds},scale=${TARGET_VIDEO_WIDTH}:${TARGET_VIDEO_HEIGHT}:flags=lanczos" \
@@ -311,6 +335,7 @@ if ! find "$mjpeg_frame_dir" -type f -name 'frame_*.jpg' | grep -q .; then
     "$mjpeg_frame_dir/frame_000001.jpg"
 fi
 
+progress "encoding 8k g711a audio track"
 "$FFMPEG_BIN" -hide_banner -loglevel error -y \
   -i "$SOURCE_ABS" \
   -vn \
@@ -320,6 +345,7 @@ fi
   -f alaw \
   "$AUDIO_PATH"
 
+progress "encoding 16k g711a audio track"
  "$FFMPEG_BIN" -hide_banner -loglevel error -y \
   -i "$SOURCE_ABS" \
   -vn \
@@ -329,6 +355,7 @@ fi
   -f alaw \
   "$AUDIO_16K_PATH"
 
+progress "indexing h264 video packets"
 VIDEO_PACKET_INDEX_PATH="$VIDEO_H264_PACKET_INDEX_PATH" \
 VIDEO_PATH="$VIDEO_H264_PATH" \
 VIDEO_FPS="$k_video_fps" \
@@ -426,6 +453,7 @@ for (let index = 0; index < packetOffsets.length; index += 1) {
 fs.writeFileSync(outputPath, `${lines.join('\n')}\n`, 'utf8');
 NODE
 
+progress "indexing h265 video packets"
 VIDEO_PACKET_INDEX_PATH="$VIDEO_H265_PACKET_INDEX_PATH" \
 VIDEO_PATH="$VIDEO_H265_PATH" \
 VIDEO_FPS="$k_video_fps" \
@@ -523,6 +551,7 @@ for (let index = 0; index < packetOffsets.length; index += 1) {
 fs.writeFileSync(outputPath, `${lines.join('\n')}\n`, 'utf8');
 NODE
 
+progress "indexing mjpeg video packets"
 VIDEO_MJPEG_PATH="$VIDEO_MJPEG_PATH" \
 VIDEO_MJPEG_PACKET_INDEX_PATH="$VIDEO_MJPEG_PACKET_INDEX_PATH" \
 MJPEG_FRAME_DIR="$mjpeg_frame_dir" \
@@ -578,6 +607,7 @@ for (let index = 0; index < packetCount; index += 1) {
 fs.writeFileSync(indexPath, `${lines.join('\n')}\n`, 'utf8');
 NODE
 
+progress "indexing 8k g711a audio packets"
 AUDIO_BYTES="$(wc -c < "$AUDIO_PATH" | tr -d '[:space:]')"
 AUDIO_PACKET_BYTES=$((k_audio_sample_rate_hz * k_audio_packet_duration_ms / 1000))
 [[ "$AUDIO_PACKET_BYTES" -gt 0 ]] || fail "invalid audio packet bytes"
@@ -609,6 +639,7 @@ AUDIO_PACKET_COUNT=$((AUDIO_BYTES / AUDIO_PACKET_BYTES))
   done
 } > "$AUDIO_PACKET_INDEX_PATH"
 
+progress "indexing 16k g711a audio packets"
 AUDIO_16K_BYTES="$(wc -c < "$AUDIO_16K_PATH" | tr -d '[:space:]')"
 AUDIO_16K_PACKET_BYTES=$((k_audio_sample_rate_16k_hz * k_audio_packet_duration_ms / 1000))
 [[ "$AUDIO_16K_PACKET_BYTES" -gt 0 ]] || fail "invalid 16k audio packet bytes"
@@ -640,6 +671,7 @@ AUDIO_16K_PACKET_COUNT=$((AUDIO_16K_BYTES / AUDIO_16K_PACKET_BYTES))
   done
 } > "$AUDIO_16K_PACKET_INDEX_PATH"
 
+progress "writing prepared media manifest"
 cat > "$MANIFEST_PATH" <<JSON
 {
   "schema_version": ${k_schema_version},