tirtc-device-builder 0.5.0 → 0.7.0

package/skills/tirtc-esp32-builder/scripts/install_video_gate.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Install the portable TiRTC video semantic gate into an ESP-IDF project."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+
+MARKER = "# tirtc-video-semantic-gate-v1"
+BLOCK = f"""
+
+{MARKER}
+add_custom_target(tirtc_video_semantic_gate ALL
+    COMMAND "${{PYTHON}}"
+            "${{CMAKE_CURRENT_LIST_DIR}}/tools/verify_video_contract.py"
+            "${{CMAKE_CURRENT_LIST_DIR}}/board-video-contract.json"
+            --project "${{CMAKE_CURRENT_LIST_DIR}}"
+            --evidence-out "${{CMAKE_BINARY_DIR}}/video-contract-evidence.json"
+    COMMENT "Validating camera lock, CPU isolation, complete JPEG framing, backpressure and memory"
+    VERBATIM
+)
+add_dependencies(${{CMAKE_PROJECT_NAME}}.elf tirtc_video_semantic_gate)
+"""
+
+
+def install(project: Path) -> None:
+    project = project.expanduser().resolve()
+    cmake = project / "CMakeLists.txt"
+    contract = project / "board-video-contract.json"
+    if not cmake.is_file():
+        raise ValueError(f"ESP-IDF project CMakeLists.txt not found: {cmake}")
+    if not contract.is_file():
+        raise ValueError(
+            f"video contract not found: {contract}; create and verify it before installing the gate"
+        )
+    tools = project / "tools"
+    tools.mkdir(parents=True, exist_ok=True)
+    destination = tools / "verify_video_contract.py"
+    source = Path(__file__).resolve().with_name("video_contract.py")
+    if destination.exists() and destination.read_bytes() != source.read_bytes():
+        raise ValueError(f"refusing to overwrite a different gate: {destination}")
+    if not destination.exists():
+        shutil.copyfile(source, destination)
+    text = cmake.read_text(encoding="utf-8")
+    if MARKER not in text:
+        cmake.write_text(text.rstrip() + BLOCK + "\n", encoding="utf-8")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("project", type=Path)
+    args = parser.parse_args()
+    try:
+        install(args.project)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    print(f"installed TiRTC video semantic gate: {args.project.resolve()}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/tirtc-esp32-builder/scripts/project_portability.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Check that a generated TiRTC ESP32 source package can move to another machine."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+ABSOLUTE_PATH = re.compile(r"(?:^|[\s\"'])(?:/home/|/root/|[A-Za-z]:[\\/])")
+BUILD_INPUT_NAMES = {"CMakeLists.txt", "idf_component.yml", "idf_component.yaml"}
+BUILD_INPUT_SUFFIXES = {".c", ".h", ".cmake", ".py", ".sh"}
+SKIP_PARTS = {"build", "managed_components", ".git"}
+
+
+def source_files(project: Path):
+    for path in project.rglob("*"):
+        relative = path.relative_to(project)
+        if not path.is_file() or SKIP_PARTS.intersection(relative.parts):
+            continue
+        if path.name in BUILD_INPUT_NAMES or path.suffix.lower() in BUILD_INPUT_SUFFIXES:
+            yield path
+
+
+def check_project(project_path: Path, export: bool = False) -> dict[str, Any]:
+    project = project_path.expanduser().resolve()
+    errors: list[str] = []
+    if not (project / "CMakeLists.txt").is_file():
+        return {"ok": False, "errors": ["CMakeLists.txt is missing"]}
+    if not (project / "dependencies.lock").is_file():
+        errors.append("dependencies.lock is missing")
+    sdk_required = (
+        project / "third_party" / "tirtc" / "include" / "tirtc" / "tiRTC.h",
+        project / "third_party" / "tirtc" / "lib" / "libTiRTC.a",
+        project / "third_party" / "tirtc" / "manifest" / "build-contract.env",
+    )
+    missing_sdk = [str(path.relative_to(project)) for path in sdk_required if not path.is_file()]
+    if missing_sdk:
+        errors.append("bundled TiRTC SDK is incomplete: " + ", ".join(missing_sdk))
+    if export and (project / "build").exists():
+        errors.append("export source contains a machine-bound build/ directory")
+
+    for path in source_files(project):
+        relative = path.relative_to(project)
+        text = path.read_text(encoding="utf-8", errors="replace")
+        if ABSOLUTE_PATH.search(text):
+            errors.append(f"build input contains a machine-specific absolute path: {relative}")
+        if path.name == "CMakeLists.txt" or path.suffix.lower() == ".cmake":
+            for number, line in enumerate(text.splitlines(), 1):
+                stripped = line.strip()
+                if stripped.startswith("COMMAND ") and ".sh" in stripped:
+                    command = stripped[len("COMMAND ") :].lstrip('"')
+                    if not command.startswith("bash ") and not command.startswith("${BASH"):
+                        errors.append(
+                            f"shell gate relies on executable permission: {relative}:{number}"
+                        )
+    return {"ok": not errors, "errors": errors}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("project", type=Path)
+    parser.add_argument(
+        "--export",
+        action="store_true",
+        help="also reject a carried build/CMakeCache.txt",
+    )
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+    result = check_project(args.project, export=args.export)
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    elif result["ok"]:
+        print("PASS: project source is relocatable")
+    else:
+        for error in result["errors"]:
+            print(f"FAIL: {error}", file=sys.stderr)
+    return 0 if result["ok"] else 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/tirtc-esp32-builder/scripts/runtime_contract.py

@@ -0,0 +1,314 @@
+#!/usr/bin/env python3
+"""Verify the generated project's ThingConnect/TiRTC runtime protocol contract."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+CALLBACKS = (
+    "on_event",
+    "on_conn_accepted",
+    "on_conn_error",
+    "on_disconnected",
+    "on_ai_connect",
+    "on_audio",
+    "on_video",
+    "on_command",
+    "on_request_key_frame",
+    "on_subscribe_audio",
+    "on_subscribe_video",
+    "on_unsubscribe_audio",
+    "on_unsubscribe_video",
+)
+FORBIDDEN_CALLBACK_CALLS = (
+    "TiRtcDisconnect(",
+    "TiRtcStop(",
+    "TiRtcUninit(",
+)
+VIDEO_PROFILES = {
+    "mjpeg": ("TIRTC_VIDEO_JPEG", "complete_jpeg"),
+    "h264": ("TIRTC_VIDEO_H264", "annex_b_access_unit"),
+    "h265": ("TIRTC_VIDEO_H265", "annex_b_access_unit"),
+}
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def project_file(project: Path, value: Any, label: str) -> Path:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{label} must be a non-empty project-relative path")
+    relative = Path(value)
+    if relative.is_absolute():
+        raise ValueError(f"{label} must be project-relative, got {value!r}")
+    resolved = (project / relative).resolve()
+    if project != resolved and project not in resolved.parents:
+        raise ValueError(f"{label} escapes project root: {value!r}")
+    return resolved
+
+
+def function_body(text: str, name: str) -> str | None:
+    pattern = re.compile(rf"\b{re.escape(name)}\s*\([^;]*?\)\s*\{{", re.DOTALL)
+    match = pattern.search(text)
+    if match is None:
+        return None
+    brace = text.find("{", match.start())
+    depth = 0
+    for index in range(brace, len(text)):
+        if text[index] == "{":
+            depth += 1
+        elif text[index] == "}":
+            depth -= 1
+            if depth == 0:
+                return text[brace : index + 1]
+    return None
+
+
+def require_tokens(
+    text: str, label: str, tokens: tuple[str, ...], errors: list[str]
+) -> None:
+    compact = re.sub(r"\s+", "", text)
+    for token in tokens:
+        if re.sub(r"\s+", "", token) not in compact:
+            errors.append(f"{label} is missing protocol token: {token}")
+
+
+def check_platform_contract(platform: Any, errors: list[str]) -> None:
+    if not isinstance(platform, dict) or platform.get("schema_version") != 1:
+        errors.append("platform media contract schema_version must be 1")
+        return
+    expected_audio = {
+        ("h5", "audio_up"): (10, "alaw", 8000, 1),
+        ("h5", "audio_down"): (14, "alaw", 8000, 1),
+        ("ai", "audio_up"): (1, "alaw", 8000, 1),
+        ("ai", "audio_down"): (1, "alaw", 8000, 1),
+    }
+    for (section, direction), expected in expected_audio.items():
+        parent = platform.get(section)
+        actual = parent.get(direction) if isinstance(parent, dict) else None
+        if not isinstance(actual, dict):
+            errors.append(f"platform contract is missing {section}.{direction}")
+            continue
+        values = (
+            actual.get("stream_id"),
+            actual.get("codec"),
+            actual.get("sample_rate_hz"),
+            actual.get("channels"),
+        )
+        if values != expected or actual.get("media") != "TIRTC_AUDIO_ALAW" or actual.get(
+            "flags"
+        ) != "TIRTC_AUDIOSAMPLE_8K16B1C":
+            errors.append(
+                f"platform {section}.{direction} must be stream/codec/rate/channels "
+                f"{expected} with TiRTC A-law 8k flags"
+            )
+    h5 = platform.get("h5")
+    video = h5.get("video_up") if isinstance(h5, dict) else None
+    profiles = video.get("supported_profiles") if isinstance(video, dict) else None
+    if not isinstance(video, dict) or video.get("stream_id") != 11 or not isinstance(
+        profiles, list
+    ):
+        errors.append("platform contract must define H5 video stream 11 profiles")
+    else:
+        actual_profiles = {
+            item.get("codec"): (item.get("media"), item.get("send_boundary"))
+            for item in profiles
+            if isinstance(item, dict) and isinstance(item.get("codec"), str)
+        }
+        if actual_profiles != VIDEO_PROFILES:
+            errors.append(
+                "platform H5 video profiles must declare MJPEG, H.264 and H.265 "
+                "with their exact TiRTC media and send boundaries"
+            )
+    ai = platform.get("ai")
+    response = ai.get("start_session_response") if isinstance(ai, dict) else None
+    required = response.get("required_fields") if isinstance(response, dict) else None
+    if (
+        not isinstance(required, list)
+        or not {
+            "id",
+            "result.session_id",
+            "result.input_audio",
+            "result.output_audio",
+        }.issubset(set(required))
+        or response.get("response_formats_authoritative") is not True
+    ):
+        errors.append(
+            "platform AI contract must make session_id and response audio formats authoritative"
+        )
+
+
+def verify_contract(contract_path: Path, project_path: Path) -> dict[str, Any]:
+    project = project_path.expanduser().resolve()
+    contract_file = contract_path.expanduser().resolve()
+    errors: list[str] = []
+    inputs: dict[str, str] = {}
+    if not project.is_dir():
+        return {"ok": False, "errors": [f"project directory does not exist: {project}"]}
+    if not contract_file.is_file():
+        return {"ok": False, "errors": [f"runtime contract does not exist: {contract_file}"]}
+    if project != contract_file and project not in contract_file.parents:
+        return {"ok": False, "errors": ["runtime contract must be inside the project"]}
+    try:
+        contract = json.loads(contract_file.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return {"ok": False, "errors": [f"invalid runtime contract: {exc}"]}
+    if not isinstance(contract, dict) or contract.get("schema_version") != 1:
+        return {"ok": False, "errors": ["runtime contract schema_version must be 1"]}
+    inputs[str(contract_file.relative_to(project))] = sha256_file(contract_file)
+
+    files = contract.get("files")
+    if not isinstance(files, dict):
+        return {"ok": False, "errors": ["runtime contract files must be an object"]}
+    contents: dict[str, str] = {}
+    for name in ("platform_client", "app_main", "starter_tirtc", "starter_runtime"):
+        try:
+            path = project_file(project, files.get(name), f"files.{name}")
+        except ValueError as exc:
+            errors.append(str(exc))
+            continue
+        if not path.is_file():
+            errors.append(f"files.{name} does not exist: {path}")
+            continue
+        contents[name] = path.read_text(encoding="utf-8", errors="replace")
+        inputs[str(path.relative_to(project))] = sha256_file(path)
+
+    try:
+        platform_path = project_file(
+            project, contract.get("platform_contract"), "platform_contract"
+        )
+    except ValueError as exc:
+        errors.append(str(exc))
+        platform_path = None
+    if platform_path is not None:
+        if not platform_path.is_file():
+            errors.append(f"platform media contract does not exist: {platform_path}")
+        else:
+            inputs[str(platform_path.relative_to(project))] = sha256_file(platform_path)
+            try:
+                check_platform_contract(
+                    json.loads(platform_path.read_text(encoding="utf-8")), errors
+                )
+            except json.JSONDecodeError as exc:
+                errors.append(f"invalid platform media contract: {exc}")
+
+    platform_source = contents.get("platform_client", "")
+    app_main = contents.get("app_main", "")
+    tirtc = contents.get("starter_tirtc", "")
+    runtime = contents.get("starter_runtime", "")
+    require_tokens(
+        platform_source,
+        "platform_client",
+        ('"tirtc-srv"', "platform_client_tirtc_endpoint", "s_services.tirtc"),
+        errors,
+    )
+    require_tokens(
+        app_main,
+        "app_main",
+        ("platform_client_tirtc_endpoint()", ".service_endpoint = tirtc_endpoint"),
+        errors,
+    )
+    require_tokens(
+        tirtc,
+        "starter_tirtc",
+        (
+            "TIRTC_OPT_SERVICE_ENDPOINT",
+            "config->service_endpoint",
+            ".stream_id = mode == STARTER_TIRTC_H5 ? H5_AUDIO_STREAM : AI_AUDIO_STREAM",
+            ".media = TIRTC_AUDIO_ALAW",
+            ".flags = TIRTC_AUDIOSAMPLE_8K16B1C",
+            "frame->media != TIRTC_AUDIO_ALAW",
+            "frame->flags != TIRTC_AUDIOSAMPLE_8K16B1C",
+            "TIRTC_VIDEO_JPEG",
+            "TIRTC_VIDEO_H264",
+            "TIRTC_VIDEO_H265",
+            "defer_disconnect(connection)",
+        ),
+        errors,
+    )
+    for callback in CALLBACKS:
+        body = function_body(tirtc, callback)
+        if body is None:
+            errors.append(f"starter_tirtc callback {callback} is missing")
+            continue
+        for forbidden in FORBIDDEN_CALLBACK_CALLS:
+            if forbidden in body:
+                errors.append(
+                    f"starter_tirtc callback {callback} calls forbidden lifecycle API {forbidden[:-1]}"
+                )
+    worker = function_body(tirtc, "deferred_disconnect_task")
+    if worker is None or "TiRtcDisconnect(" not in worker:
+        errors.append("deferred disconnect worker must own TiRtcDisconnect")
+
+    require_tokens(
+        runtime,
+        "starter_runtime",
+        (
+            '"input_audio"',
+            '"output_audio"',
+            '"codec", "alaw"',
+            '"sample_rate", 8000',
+            '"channels", 1',
+            '"session_id"',
+            "ai_audio_format_is_alaw_8k_mono(input_audio)",
+            "ai_audio_format_is_alaw_8k_mono(output_audio)",
+            "has_result && !accepted",
+            'strcmp(method->valuestring, "end_session")',
+        ),
+        errors,
+    )
+    ai_handler = function_body(runtime, "handle_ai_command")
+    if ai_handler is None or "starter_media_start(STARTER_TIRTC_AI" not in re.sub(
+        r"\s+", "", ai_handler
+    ):
+        errors.append("AI media must start only from the validated command handler")
+
+    return {
+        "ok": not errors,
+        "summary": "endpoint + callbacks + H5/AI stream and negotiation contract",
+        "inputs": inputs,
+        "errors": errors,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Verify TiRTC endpoint, callbacks, stream metadata, and AI negotiation."
+    )
+    parser.add_argument("contract", type=Path)
+    parser.add_argument("--project", type=Path, required=True)
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--evidence-out", type=Path)
+    args = parser.parse_args()
+    result = verify_contract(args.contract, args.project)
+    if args.evidence_out is not None:
+        output = args.evidence_out.expanduser().resolve()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(
+            json.dumps(result, ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    elif result["ok"]:
+        print(f"PASS: TiRTC runtime contract: {result['summary']}")
+    else:
+        for error in result["errors"]:
+            print(f"FAIL: {error}", file=sys.stderr)
+    return 0 if result["ok"] else 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())