@norskvideo/ctl-dev-kit 0.2.106 → 0.2.108

package/create-demo/template/core/ctl/site.example.env

@@ -0,0 +1,30 @@
+# Where and how this demo runs under norsk-ctl. Copy to ctl/site.env (which
+# is gitignored) and fill it in; ctl/install.sh, push.sh and mode.sh read it.
+
+# The machine norsk-ctl runs on: user@host over ssh, or empty for this one.
+DEMO_HOST=
+
+# Where the working dir is staged on that machine. It must be a path the
+# norsk-ctl user can reach: a directory under someone's home usually is not.
+WORKDIR=/srv/__DEMO__
+
+# The user the norsk-ctl daemon runs as: the working dir is owned by it and
+# norsk-ctl is run as it (via sudo). Empty runs both as the ssh/local user.
+RUN_AS=norsk
+
+# The norsk-ctl command on that machine.
+NORSK_CTL=norsk-ctl
+
+# A path on that machine to the norsk-studio licence, used once to add the
+# studio-dev product template if norsk-ctl does not have it yet.
+LICENSE_FILE=
+
+# docker (norsk-ctl's default) or hybrid. hybrid puts media on the host
+# network: needed when a viewer receives WebRTC media (WHEP, WHIP) directly.
+NETWORK_MODE=docker
+
+# Ingest ports to publish on the host, space separated, HOST[:CONTAINER][/udp].
+# Everything else is allocated by norsk-ctl; pin a port only when a sender or
+# a firewall outside the box must agree on it. 5001/udp is the SRT input
+# (srt_in in the workflow); change both together.
+HOST_PORTS="5001/udp"

package/create-demo/template/core/ctl/studio.example.env

@@ -0,0 +1,12 @@
+# Site settings for the workflow. Copy to ctl/studio.env (which is gitignored).
+#
+# Each line is a Studio environment override, <COMPONENT_ID>_<FIELD>=value:
+# it replaces that field of that component in the workflow YAML at launch, for
+# any field the component declares overridable. This is where ports,
+# passphrases and destinations go, so the YAML carries no site's values and no
+# secrets. ctl/push.sh writes these into the overrides norsk-ctl launches with.
+#
+# A port changed here must be changed in HOST_PORTS (ctl/site.env) too.
+
+# SRT_IN_PORT=5001
+# SRT_IN_PASSPHRASE=

package/create-demo/template/core/gitignore

@@ -0,0 +1,18 @@
+# The site's settings: copied from the .example files, never committed.
+ctl/site.env
+ctl/studio.env
+ctl/.mode
+
+node_modules/
+
+# Build output, rebuilt by scripts/build.sh.
+dashboard/dist/
+components/lib/
+components/src/**/_gen/
+workdir/studio-save-files/*/dashboards/
+workdir/components/
+
+# What Studio writes into its working dir while it runs.
+workdir/logs/
+workdir/.norsk/
+workdir/moq-certs/

package/create-demo/template/core/scripts/build.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Build what this demo adds to Studio, into workdir/ where Studio finds it:
+#   dashboard/   -> workdir/studio-save-files/__DEMO__/dashboards/  served at /dashboard/__DEMO__/
+#   components/  -> workdir/components/@__DEMO__/library/          loaded as a Studio library
+# A demo without either has nothing to build.
+set -euo pipefail
+root="$(cd "$(dirname "$0")/.." && pwd)"
+
+install_to() {
+  local from="$1" dest="$2"
+  rm -rf "$dest"
+  mkdir -p "$dest"
+  cp -r "$from/." "$dest/"
+  echo "installed ${dest#"$root"/}"
+}
+
+if [[ -d "$root/dashboard" ]]; then
+  # vite 8 needs util.parseEnv, which bun 1.1 does not have.
+  if ! bun -e 'if (typeof require("node:util").parseEnv !== "function") process.exit(1)' 2>/dev/null; then
+    echo "error: bun $(bun --version) is too old to build the dashboard (vite 8 needs util.parseEnv): run bun upgrade" >&2
+    exit 1
+  fi
+  (cd "$root/dashboard" && bun install >/dev/null && bun run build)
+  install_to "$root/dashboard/dist" "$root/workdir/studio-save-files/__DEMO__/dashboards"
+fi
+
+if [[ -d "$root/components" ]]; then
+  (cd "$root/components" && bun install >/dev/null && bun run build)
+  install_to "$root/components/lib/library" "$root/workdir/components/@__DEMO__/library"
+fi

package/create-demo/template/core/scripts/test-feed.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# A labelled test picture with a tone, sent into the SRT input (srt_in), so the
+# demo has something to show without a camera. Runs ffmpeg in docker.
+#
+#   scripts/test-feed.sh up|down
+#
+# FEED_HOST is where the demo runs (default this machine); the port is
+# SRT_IN_PORT from ctl/studio.env, else the workflow's 5001.
+set -euo pipefail
+root="$(cd "$(dirname "$0")/.." && pwd)"
+
+# A setting from ctl/studio.env, or nothing: an unset one is not an error.
+studio_env() { grep -E "^$1=" "$root/ctl/studio.env" 2>/dev/null | cut -d= -f2- || true; }
+
+host="${FEED_HOST:-127.0.0.1}"
+port="$(studio_env SRT_IN_PORT)"
+port="${port:-5001}"
+passphrase="$(studio_env SRT_IN_PASSPHRASE)"
+image="${FFMPEG_IMAGE:-linuxserver/ffmpeg:8.0.1}"
+name="__DEMO__-test-feed"
+
+case "${1:-up}" in
+  up)
+    url="srt://${host}:${port}?mode=caller&latency=200000"
+    if [[ -n "$passphrase" ]]; then url="${url}&passphrase=${passphrase}"; fi
+    docker rm -f "$name" >/dev/null 2>&1 || true
+    docker run -d --restart unless-stopped --name "$name" --network host "$image" \
+      -hide_banner -loglevel warning -re \
+      -f lavfi -i "testsrc2=size=1280x720:rate=25" \
+      -f lavfi -i "sine=frequency=440:sample_rate=48000" \
+      -vf "drawtext=text='__DEMO__  %{localtime\:%T}':fontcolor=white:fontsize=64:x=40:y=40" \
+      -c:v libx264 -preset veryfast -tune zerolatency -g 50 -b:v 3M -pix_fmt yuv420p \
+      -c:a aac -b:a 128k -ac 2 \
+      -f mpegts "$url" >/dev/null
+    echo "test feed -> ${host}:${port}"
+    ;;
+  down)
+    docker rm -f "$name" >/dev/null 2>&1 && echo "test feed stopped" || true
+    ;;
+  *)
+    echo "usage: $0 up|down" >&2
+    exit 2
+    ;;
+esac

package/create-demo/template/dashboard/dashboard/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <link rel="icon" href="data:," />
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>__DEMO__</title>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/main.tsx"></script>
+</body>
+</html>

package/create-demo/template/dashboard/dashboard/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "__DEMO__-dashboard",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "typescript": "^5.7.2",
+    "vite": "^8.0.0"
+  }
+}

package/create-demo/template/dashboard/dashboard/src/App.tsx

@@ -0,0 +1,61 @@
+import type { EnvResponse, WorkflowComponentDescriptor } from "./api/types";
+import { ImagePreview } from "./components/ImagePreview";
+import { StatusPill } from "./components/StatusPill";
+import { labelFromAlerts, toneFromAlerts, useAlerts } from "./hooks/useAlerts";
+import { useDiscovery } from "./hooks/useDiscovery";
+import { useEnv } from "./hooks/useEnv";
+import { useLiveComponent } from "./hooks/useLiveComponent";
+import { WORKFLOW } from "./lib/workflow";
+
+// The starter page: the program preview, and every running component with its
+// health and live state. Replace it with what the operator actually needs; the
+// hooks are the parts to keep.
+export function App() {
+  const { env, error } = useEnv();
+  const { components, loading } = useDiscovery(env);
+
+  if (error) return <main className="page">Cannot reach Studio: {error}</main>;
+  return (
+    <main className="page">
+      <header>
+        <h1>__DEMO__</h1>
+      </header>
+      <ImagePreview componentId={WORKFLOW.preview.id} env={env} />
+      <section>
+        <h2>Components</h2>
+        {loading ? (
+          <p>Waiting for the workflow to start</p>
+        ) : (
+          <ul className="components">
+            {components.map((c) => (
+              <ComponentRow key={c.componentId} component={c} env={env} />
+            ))}
+          </ul>
+        )}
+      </section>
+    </main>
+  );
+}
+
+function ComponentRow({ component, env }: { component: WorkflowComponentDescriptor; env: EnvResponse | null }) {
+  const { alerts, loaded } = useAlerts(component.componentId, env);
+  return (
+    <li>
+      <span className="component-name">{component.displayName ?? component.componentId}</span>
+      <span className="component-type">{component.componentType}</span>
+      <StatusPill tone={toneFromAlerts(alerts, loaded)} label={labelFromAlerts(alerts, loaded, { live: "OK" })} />
+      {component.capabilities.hasState && <LiveState componentId={component.componentId} env={env} />}
+    </li>
+  );
+}
+
+function LiveState({ componentId, env }: { componentId: string; env: EnvResponse | null }) {
+  const { state } = useLiveComponent<unknown>({ componentId, env });
+  if (state === null) return null;
+  return (
+    <details className="component-state">
+      <summary>State</summary>
+      <pre>{JSON.stringify(state, null, 2)}</pre>
+    </details>
+  );
+}

package/create-demo/template/dashboard/dashboard/src/api/types.ts

@@ -0,0 +1,38 @@
+// What the dashboard reads from Studio. The discovery response is the
+// workflow's `<apiBasePath>/components` endpoint, which returns each running
+// component's type and capabilities only: its config and state arrive over the
+// component's websocket (see useLiveComponent).
+
+export interface EnvResponse {
+  studioUrlPrefix: string;
+  apiBasePath: string;
+  wsBasePath: string;
+  note?: string;
+}
+
+export interface ComponentCapabilities {
+  hasHttp: boolean;
+  hasWebSocket: boolean;
+  hasViews: boolean;
+  hasState: boolean;
+}
+
+export interface WorkflowComponentDescriptor {
+  componentId: string;
+  componentType: string;
+  displayName?: string;
+  capabilities: ComponentCapabilities;
+}
+
+export interface ComponentsResponse {
+  components: WorkflowComponentDescriptor[];
+  totalComponents: number;
+}
+
+// `output.preview`'s state. `url` depends on the preview mode: a JPEG URL in
+// image mode, a WHEP endpoint in webrtc mode, a WebTransport base URL in moq.
+export interface PreviewState {
+  url?: string;
+  previewMode?: string;
+  [k: string]: unknown;
+}

package/create-demo/template/dashboard/dashboard/src/components/ImagePreview.tsx

@@ -0,0 +1,23 @@
+import { useCallback, useState } from "react";
+import type { EnvResponse, PreviewState } from "../api/types";
+import { useLiveComponent } from "../hooks/useLiveComponent";
+
+// The program as a still from an `output.preview` in image mode. Its state
+// carries the first JPEG's URL, and each newer one arrives as a `url-published`
+// event, about once a second. No player and no media ports, so it works in
+// norsk-ctl's docker network mode. For live video, see the CLAUDE.md
+// "Dashboard" notes.
+export function ImagePreview({ componentId, env }: { componentId: string; env: EnvResponse | null }) {
+  const [published, setPublished] = useState<string | null>(null);
+  const onEvent = useCallback((evt: unknown) => {
+    const e = evt as { type?: string; url?: unknown };
+    if (e.type === "url-published" && typeof e.url === "string") setPublished(e.url);
+  }, []);
+  const { state, connected } = useLiveComponent<PreviewState>({ componentId, env, onEvent });
+
+  const url = published ?? (typeof state?.url === "string" && state.url.length > 0 ? state.url : null);
+  if (!url) {
+    return <div className="preview preview-empty">{connected ? "Waiting for a picture" : "Connecting"}</div>;
+  }
+  return <img className="preview" src={url} alt="Program preview" />;
+}

package/create-demo/template/dashboard/dashboard/src/components/StatusPill.tsx

@@ -0,0 +1,65 @@
+// A status pill. Six tones aligned with what Studio's per-component /alerts
+// endpoint reports.
+// A component's tone is derived from its live alerts list:
+//
+//   live    — no alerts (Studio considers this component healthy)
+//   ready   — warning-level alerts only (e.g. "no active connections")
+//   waiting — expected upstream not yet reached (config-derived)
+//   idle    — configured but off / disabled (config-derived)
+//   error   — any error-level alert (e.g. "receiving no data")
+//   unknown — Studio's state doesn't expose the signal we'd need
+//
+// Card headers may add a matching border-left accent via `toneAccentColor`.
+
+export type StatusTone = "live" | "ready" | "waiting" | "idle" | "error" | "unknown";
+
+interface StatusPillProps {
+  tone: StatusTone;
+  label: string;
+}
+
+const PALETTE: Record<StatusTone, { background: string; color: string; border: string }> = {
+  live: {
+    background: "rgba(34, 197, 94, 0.20)",
+    color: "rgb(134, 239, 172)",
+    border: "1px solid rgba(34, 197, 94, 0.55)",
+  },
+  ready: {
+    background: "rgba(59, 130, 246, 0.20)",
+    color: "rgb(147, 197, 253)",
+    border: "1px solid rgba(59, 130, 246, 0.55)",
+  },
+  waiting: {
+    background: "rgba(234, 179, 8, 0.20)",
+    color: "rgb(253, 224, 71)",
+    border: "1px solid rgba(234, 179, 8, 0.55)",
+  },
+  idle: {
+    background: "rgba(107, 114, 128, 0.20)",
+    color: "rgb(209, 213, 219)",
+    border: "1px solid rgba(107, 114, 128, 0.55)",
+  },
+  error: {
+    background: "rgba(239, 68, 68, 0.20)",
+    color: "rgb(252, 165, 165)",
+    border: "1px solid rgba(239, 68, 68, 0.55)",
+  },
+  unknown: {
+    background: "rgba(107, 114, 128, 0.08)",
+    color: "rgb(156, 163, 175)",
+    border: "1px dashed rgba(107, 114, 128, 0.55)",
+  },
+};
+
+export function StatusPill({ tone, label }: StatusPillProps) {
+  return (
+    <span className="status-pill" style={PALETTE[tone]} data-tone={tone}>
+      {label}
+    </span>
+  );
+}
+
+// For card border-left accents matching a section's aggregate status.
+export function toneAccentColor(tone: StatusTone): string {
+  return PALETTE[tone].border.replace("1px solid ", "").replace("1px dashed ", "");
+}

package/create-demo/template/dashboard/dashboard/src/hooks/useAlerts.ts

@@ -0,0 +1,98 @@
+import { useEffect, useState } from "react";
+import type { EnvResponse } from "../api/types";
+import type { StatusTone } from "../components/StatusPill";
+
+// Studio's per-component alert. Emitted by `setAlert(id, {level, message})`
+// in the runtime; polled from `<apiBasePath>/<componentId>/alerts`. Cleared
+// entries drop out of the endpoint response, so an empty array means the
+// component is currently healthy (from Studio's own POV).
+export interface Alert {
+  level: "error" | "warning" | "info";
+  message: string;
+  startMs?: number;
+}
+
+const POLL_INTERVAL_MS = 3_000;
+
+// Polls Studio's alerts endpoint for a single component. Returns the current
+// alert array plus a `loaded` flag distinguishing "no alerts, healthy" from
+// "haven't fetched yet". Reset on componentId / env change.
+export function useAlerts(componentId: string | null, env: EnvResponse | null): { alerts: Alert[]; loaded: boolean } {
+  const [alerts, setAlerts] = useState<Alert[]>([]);
+  const [loaded, setLoaded] = useState(false);
+
+  useEffect(() => {
+    if (!componentId || !env) return;
+    setLoaded(false);
+    setAlerts([]);
+    let cancelled = false;
+    const url = `${env.apiBasePath}/${componentId}/alerts`;
+    const poll = async () => {
+      try {
+        const res = await fetch(url, { credentials: "include" });
+        if (!res.ok) return;
+        const json = (await res.json()) as Alert[];
+        if (cancelled) return;
+        setAlerts(Array.isArray(json) ? json : []);
+        setLoaded(true);
+      } catch {
+        // Silent — proxy hiccups, transient errors. Stale alerts stay
+        // visible until the next poll succeeds.
+      }
+    };
+    void poll();
+    const timer = setInterval(poll, POLL_INTERVAL_MS);
+    return () => {
+      cancelled = true;
+      clearInterval(timer);
+    };
+  }, [componentId, env]);
+
+  return { alerts, loaded };
+}
+
+// Derive a StatusPill tone from an alert list. Errors dominate warnings;
+// warnings dominate the healthy case. When the endpoint hasn't answered
+// yet, callers should fall back to the "unknown" tone via the second arg.
+export function toneFromAlerts(alerts: Alert[], loaded: boolean, fallbackTone: StatusTone = "unknown"): StatusTone {
+  if (!loaded) return fallbackTone;
+  if (alerts.some((a) => a.level === "error")) return "error";
+  if (alerts.some((a) => a.level === "warning")) return "ready";
+  return "live";
+}
+
+// Rewrite Studio's internal alert messages into copy that doesn't require
+// knowing what a "component" is. Studio phrases everything in terms of the
+// producing/consuming component; we recast for the operator reading the
+// dashboard. Optional `context` lets callers narrow to a role-specific
+// noun ("source", "camera", etc.).
+export function humanizeAlert(
+  message: string,
+  context?: { subject?: string; kind?: "input" | "output" | "session" },
+): string {
+  const subject = context?.subject ?? "This source";
+  if (/receiving no data/i.test(message)) {
+    return context?.kind === "input" ? "No data arriving from upstream" : `${subject}: nothing arriving yet`;
+  }
+  if (/sending no data/i.test(message)) {
+    return context?.kind === "output" ? "Not producing output yet" : `${subject}: not producing output yet`;
+  }
+  if (/no active connections/i.test(message)) return "No active connection";
+  return message.replace(/^This component /i, "");
+}
+
+// Short label for the pill based on alert state. `livedLabel` and
+// `errorLabel` let callers customise per row-type (e.g. "3 streams" vs
+// "Publishing").
+export function labelFromAlerts(
+  alerts: Alert[],
+  loaded: boolean,
+  labels: { live: string; warning?: string; error?: string; unknown?: string },
+): string {
+  if (!loaded) return labels.unknown ?? "Connecting";
+  const errorCount = alerts.filter((a) => a.level === "error").length;
+  if (errorCount > 0) return labels.error ?? `${errorCount} error${errorCount === 1 ? "" : "s"}`;
+  const warningCount = alerts.filter((a) => a.level === "warning").length;
+  if (warningCount > 0) return labels.warning ?? "Warning";
+  return labels.live;
+}

package/create-demo/template/dashboard/dashboard/src/hooks/useDiscovery.ts

@@ -0,0 +1,88 @@
+import { useEffect, useRef, useState } from "react";
+import type { ComponentsResponse, EnvResponse, WorkflowComponentDescriptor } from "../api/types";
+
+interface UseDiscoveryResult {
+  components: WorkflowComponentDescriptor[];
+  error: string | null;
+  loading: boolean;
+  attempts: number;
+  nextRetryMs: number | null;
+}
+
+// Bounded-exponential-backoff poller of `<apiBasePath>/components`. Studio
+// returns 503 with `{error: "Workflow is not running yet"}` until the
+// workflow boots; we keep polling until the response is 200 with a non-empty
+// `components` array. Once we have it, we exit the loop and the component
+// stays mounted regardless of later disconnects — the per-component WS hooks own
+// their own reconnect.
+const INITIAL_DELAY_MS = 500;
+const MAX_DELAY_MS = 5000;
+
+export function useDiscovery(env: EnvResponse | null): UseDiscoveryResult {
+  const [components, setComponents] = useState<WorkflowComponentDescriptor[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [attempts, setAttempts] = useState(0);
+  const [nextRetryMs, setNextRetryMs] = useState<number | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (!env) return;
+    let cancelled = false;
+    let delay = INITIAL_DELAY_MS;
+    let attempt = 0;
+
+    const tick = async () => {
+      attempt += 1;
+      if (cancelled) return;
+      setAttempts(attempt);
+      try {
+        const res = await fetch(`${env.apiBasePath}/components`);
+        if (res.status === 503) {
+          // Workflow not yet running — bounded retry.
+          scheduleRetry();
+          return;
+        }
+        if (!res.ok) {
+          throw new Error(`HTTP ${res.status}`);
+        }
+        const body = (await res.json()) as ComponentsResponse;
+        if (!body.components || body.components.length === 0) {
+          // Empty surface — keep polling.
+          scheduleRetry();
+          return;
+        }
+        if (cancelled) return;
+        setComponents(body.components);
+        setError(null);
+        setLoading(false);
+        setNextRetryMs(null);
+      } catch (err) {
+        if (cancelled) return;
+        setError(err instanceof Error ? err.message : String(err));
+        scheduleRetry();
+      }
+    };
+
+    const scheduleRetry = () => {
+      if (cancelled) return;
+      setNextRetryMs(delay);
+      timerRef.current = setTimeout(() => {
+        delay = Math.min(delay * 2, MAX_DELAY_MS);
+        void tick();
+      }, delay);
+    };
+
+    void tick();
+
+    return () => {
+      cancelled = true;
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+    };
+  }, [env]);
+
+  return { components, error, loading, attempts, nextRetryMs };
+}

package/create-demo/template/dashboard/dashboard/src/hooks/useEnv.ts

@@ -0,0 +1,53 @@
+import { useEffect, useState } from "react";
+import type { EnvResponse } from "../api/types";
+
+interface UseEnvResult {
+  env: EnvResponse | null;
+  error: string | null;
+  loading: boolean;
+}
+
+// Resolves the dashboard's bound `env` endpoint. Studio serves
+// `/dashboard/<workflowName>/env` and returns `{studioUrlPrefix, apiBasePath, wsBasePath}`.
+// We fetch via a relative URL so the bundle works under arbitrary
+// `studioUrlPrefix` deployments.
+export function useEnv(): UseEnvResult {
+  const [env, setEnv] = useState<EnvResponse | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    (async () => {
+      try {
+        const res = await fetch("./env");
+        if (!res.ok) {
+          throw new Error(`env returned HTTP ${res.status}`);
+        }
+        const body = (await res.json()) as Partial<EnvResponse>;
+        if (!body.wsBasePath || !body.apiBasePath) {
+          throw new Error("env response missing wsBasePath/apiBasePath");
+        }
+        if (cancelled) return;
+        setEnv({
+          studioUrlPrefix: body.studioUrlPrefix ?? "",
+          apiBasePath: body.apiBasePath,
+          wsBasePath: body.wsBasePath,
+          note: body.note,
+        });
+        setLoading(false);
+      } catch (err) {
+        if (cancelled) return;
+        setError(err instanceof Error ? err.message : String(err));
+        setLoading(false);
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return { env, error, loading };
+}