fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/services/video/player.py

@@ -0,0 +1,456 @@
+"""Browser / Web Player UI Face for Fleetmesh Video Streaming (node.planes.services.video.player).
+
+Mounts interactive HTML5 player and directory routes onto `ProtocolHost`:
+- `GET /video/watch`: Live Broadcast Directory & Transit Status Dashboard.
+- `GET /video/watch/<stream_id>`: Self-contained HTML5 + `hls.js` + WebCrypto
+  player that:
+  1. Verifies 1024-byte chunked `RhioBaoTree` Merkle roots (`X-Bao-Tree-Root`
+     and `#EXT-X-FLEETMESH-BAO-ROOT`) in-browser via `crypto.subtle.digest`.
+  2. Automatically follows `307 Temporary Redirect` Transit Reflector handovers
+     and surfaces active reflector endpoints in the telemetry HUD.
+  3. Intercepts HTTP `402 Payment Required` dual-item Cashu quotes (operator
+     `NUT-03` bandwidth + creator `NUT-11` P2PK) and attaches `X-Cashu` tokens.
+  4. Supports one-click fallback to `?audio_only=1` when soft debt degradation
+     is active.
+"""
+from __future__ import annotations
+
+import html
+import json
+import urllib.parse
+from typing import Any, Optional
+
+from fleetmesh_core.wire.interfaces import ProtocolHostRouter
+from .ledger import TransitLedgerStore
+from .packager import VideoStreamPackager
+from .transit import TransitReflectorManager
+
+
+def render_directory_html(
+    packager: VideoStreamPackager,
+    reflector: Optional[TransitReflectorManager] = None,
+    ledger: Optional[TransitLedgerStore] = None,
+) -> str:
+    """Render the `GET /video/watch` live stream directory and transit dashboard."""
+    with packager._lock:
+        streams = list(packager._streams.values())
+
+    cards_html: list[str] = []
+    for st in streams:
+        gen = st['genesis']
+        sid = html.escape(gen.stream_id)
+        title = html.escape(gen.title)
+        broadcaster = html.escape(gen.broadcaster[:20] + '...')
+        seg_count = len(st['segments'])
+        endpoints = st['transit_endpoints']
+        handover = bool(
+            endpoints or (reflector is not None and reflector.is_handover_active(gen.stream_id))
+        )
+        mode_badge = (
+            '<span class="badge badge-transit">Transit Reflector Handover</span>'
+            if handover
+            else '<span class="badge badge-origin">Origin Direct</span>'
+        )
+        econ_badge = (
+            f'<span class="badge badge-paid">Commercial ({gen.price_msat_per_mb} msat/MB + {gen.account_fee_msat} msat P2PK)</span>'
+            if (gen.price_msat_per_mb > 0 or gen.account_fee_msat > 0)
+            else '<span class="badge badge-barter">Pro-Bono / Barter IOU</span>'
+        )
+        cards_html.append(
+            f"""
+            <div class="stream-card" data-stream-id="{sid}">
+              <div class="card-header">
+                <h3><a href="/video/watch/{sid}">{title}</a></h3>
+                <div class="badges">{mode_badge} {econ_badge}</div>
+              </div>
+              <div class="card-meta">
+                <span>Stream ID: <code>{sid}</code></span>
+                <span>Broadcaster: <code>{broadcaster}</code></span>
+                <span>Segments: <strong>{seg_count}</strong> (seq #{st['latest_seq']})</span>
+              </div>
+              <div class="card-actions">
+                <a class="btn" href="/video/watch/{sid}">Open Web Player</a>
+                <a class="btn btn-secondary" href="/video/live/{sid}/index.m3u8">HLS Manifest (.m3u8)</a>
+                <a class="btn btn-secondary" href="/video/live/{sid}/index.m3u8?audio_only=1">Audio-Only (.m3u8)</a>
+              </div>
+            </div>
+            """
+        )
+
+    empty_state = (
+        '<p class="empty">No active live streams on this node yet. '
+        'Use <code>meshnode stream start</code> or <code>POST /video/ingest/&lt;stream_id&gt;/chunk.m4s</code>.</p>'
+        if not cards_html
+        else '\n'.join(cards_html)
+    )
+
+    debts_rows: list[str] = []
+    if ledger is not None:
+        summary = ledger.summary()
+        for d in summary.get('debts', []):
+            debtor_short = html.escape(str(d.get('debtor', ''))[:20])
+            gross = int(d.get('gross_transit_bytes', 0))
+            bartered = int(d.get('bartered_bytes', 0))
+            unsettled = int(d.get('unsettled_bytes', 0))
+            degraded = bool(d.get('degraded_audio_only', False))
+            q_badge = 'Degraded (Audio-Only)' if degraded else 'Full Quality'
+            debts_rows.append(
+                f'<tr><td><code>{debtor_short}</code></td>'
+                f'<td>{gross} B</td><td>{bartered} B</td>'
+                f'<td>{unsettled} B</td><td>{q_badge}</td></tr>'
+            )
+
+    ledger_table = (
+        '<table class="ledger-table"><thead><tr>'
+        '<th>Debtor Peer</th><th>Gross Transit</th><th>Barter Credited</th>'
+        '<th>Unsettled Debt</th><th>Stream Quality</th></tr></thead><tbody>'
+        + (''.join(debts_rows) if debts_rows else '<tr><td colspan="5">No active transit debt records</td></tr>')
+        + '</tbody></table>'
+    )
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Fleetmesh Video Streaming &amp; Transit Reflector</title>
+  <style>
+    :root {{
+      --bg: #0b0f17;
+      --panel: #131b2e;
+      --border: #243252;
+      --text: #e2e8f0;
+      --muted: #94a3b8;
+      --accent: #38bdf8;
+      --green: #22c55e;
+      --amber: #f59e0b;
+    }}
+    body {{
+      margin: 0; padding: 2rem; background: var(--bg); color: var(--text);
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, monospace;
+    }}
+    header {{
+      border-bottom: 1px solid var(--border); padding-bottom: 1rem; margin-bottom: 1.5rem;
+    }}
+    .stream-card {{
+      background: var(--panel); border: 1px solid var(--border); border-radius: 8px;
+      padding: 1.25rem; margin-bottom: 1rem;
+    }}
+    .card-header {{ display: flex; justify-content: space-between; align-items: center; flex-wrap: wrap; gap: 0.5rem; }}
+    .card-header h3 {{ margin: 0; }}
+    .card-header a {{ color: var(--accent); text-decoration: none; }}
+    .card-meta {{ display: flex; gap: 1.5rem; color: var(--muted); margin: 0.75rem 0; font-size: 0.9rem; flex-wrap: wrap; }}
+    .badge {{ padding: 0.2rem 0.6rem; border-radius: 4px; font-size: 0.75rem; font-weight: 600; }}
+    .badge-origin {{ background: rgba(34, 197, 94, 0.15); color: var(--green); }}
+    .badge-transit {{ background: rgba(245, 158, 11, 0.15); color: var(--amber); }}
+    .badge-barter {{ background: rgba(56, 189, 248, 0.15); color: var(--accent); }}
+    .badge-paid {{ background: rgba(168, 85, 247, 0.2); color: #c084fc; }}
+    .btn {{
+      display: inline-block; padding: 0.45rem 0.9rem; background: var(--accent);
+      color: #0b0f17; border-radius: 5px; text-decoration: none; font-weight: 600;
+      font-size: 0.85rem; margin-right: 0.5rem;
+    }}
+    .btn-secondary {{ background: transparent; color: var(--text); border: 1px solid var(--border); }}
+    .ledger-table {{ width: 100%; border-collapse: collapse; margin-top: 1rem; background: var(--panel); }}
+    .ledger-table th, .ledger-table td {{ border: 1px solid var(--border); padding: 0.6rem 0.8rem; text-align: left; font-size: 0.85rem; }}
+  </style>
+</head>
+<body>
+  <header>
+    <h1>Fleetmesh Decentralized Video &amp; Transit Reflector</h1>
+    <p>Content-Addressed CMAF / LL-HLS &bull; 1024-Byte RhioBaoTree Merkle Verification &bull; Bilateral Transit Barter &amp; Cashu 402</p>
+  </header>
+  <section>
+    <h2>Active Broadcast Streams ({len(streams)})</h2>
+    {empty_state}
+  </section>
+  <section style="margin-top: 2rem;">
+    <h2>Bilateral Transit IOU &amp; Bartered Utility Ledger</h2>
+    {ledger_table}
+  </section>
+</body>
+</html>
+"""
+
+
+def render_player_html(
+    stream_id: str,
+    packager: VideoStreamPackager,
+    reflector: Optional[TransitReflectorManager] = None,
+) -> Optional[str]:
+    """Render the `GET /video/watch/<stream_id>` cryptographic web player page."""
+    with packager._lock:
+        st = packager._streams.get(stream_id)
+        if st is None:
+            return None
+        gen = st['genesis']
+        endpoints = list(st['transit_endpoints'])
+        seg_count = len(st['segments'])
+        latest_seq = st['latest_seq']
+
+    sid_esc = html.escape(gen.stream_id)
+    stream_id_js = json.dumps(gen.stream_id).replace('</', '<\\/')
+    title_esc = html.escape(gen.title)
+    broadcaster_esc = html.escape(gen.broadcaster)
+    handover_active = bool(
+        endpoints or (reflector is not None and reflector.is_handover_active(stream_id))
+    )
+    active_reflector = html.escape(endpoints[0]) if endpoints else 'None (Serving direct from Origin)'
+    is_paid = gen.price_msat_per_mb > 0 or gen.account_fee_msat > 0
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>{title_esc} — Fleetmesh Web Player</title>
+  <style>
+    :root {{
+      --bg: #0b0f17;
+      --panel: #131b2e;
+      --border: #243252;
+      --text: #e2e8f0;
+      --muted: #94a3b8;
+      --accent: #38bdf8;
+      --green: #22c55e;
+      --amber: #f59e0b;
+      --red: #ef4444;
+    }}
+    body {{
+      margin: 0; padding: 1.5rem; background: var(--bg); color: var(--text);
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, monospace;
+    }}
+    .layout {{ display: grid; grid-template-columns: 2fr 1fr; gap: 1.5rem; max-width: 1280px; margin: 0 auto; }}
+    @media (max-width: 900px) {{ .layout {{ grid-template-columns: 1fr; }} }}
+    .player-box, .hud-box {{
+      background: var(--panel); border: 1px solid var(--border); border-radius: 8px; padding: 1.25rem;
+    }}
+    video {{ width: 100%; background: #000; border-radius: 6px; aspect-ratio: 16 / 9; }}
+    .hud-row {{ display: flex; justify-content: space-between; padding: 0.45rem 0; border-bottom: 1px solid var(--border); font-size: 0.85rem; }}
+    .status-ok {{ color: var(--green); font-weight: 600; }}
+    .status-warn {{ color: var(--amber); font-weight: 600; }}
+    .cashu-drawer {{
+      margin-top: 1rem; padding: 0.9rem; border: 1px solid var(--border); border-radius: 6px; background: rgba(15, 23, 42, 0.7);
+    }}
+    input[type="text"] {{
+      width: 100%; box-sizing: border-box; padding: 0.5rem; margin-top: 0.4rem;
+      background: #0b0f17; border: 1px solid var(--border); color: var(--text); border-radius: 4px;
+    }}
+    button {{
+      margin-top: 0.5rem; padding: 0.45rem 0.9rem; background: var(--accent); color: #0b0f17;
+      border: none; border-radius: 4px; font-weight: 600; cursor: pointer;
+    }}
+  </style>
+</head>
+<body>
+  <div style="max-width: 1280px; margin: 0 auto 1rem auto;">
+    <a href="/video/watch" style="color: var(--accent); text-decoration: none;">&larr; All Live Streams</a>
+  </div>
+  <div class="layout">
+    <div class="player-box">
+      <h2 style="margin-top: 0;">{title_esc}</h2>
+      <video id="video-player" controls autoplay muted playsinline
+             data-manifest-url="/video/live/{sid_esc}/index.m3u8"></video>
+      <div style="margin-top: 0.75rem; display: flex; gap: 0.5rem; flex-wrap: wrap;">
+        <button id="btn-verify-next" type="button" onclick="FleetmeshPlayer.verifyLatestSegment()">Verify Latest Segment (Bao Merkle)</button>
+        <button id="btn-audio-only" type="button" onclick="FleetmeshPlayer.toggleAudioOnly()">Toggle Audio-Only Fallback</button>
+      </div>
+      <div class="cashu-drawer" id="cashu-drawer">
+        <strong>HTTP 402 Cashu Settlement Token (X-Cashu)</strong>
+        <div style="font-size: 0.8rem; color: var(--muted); margin-top: 0.25rem;">
+          Pricing: {gen.price_msat_per_mb} msat/MB (NUT-03 operator bandwidth) + {gen.account_fee_msat} msat (NUT-11 creator P2PK)
+        </div>
+        <input type="text" id="cashu-token-input" placeholder="cashuAey..." />
+        <div id="cashu-quote-status" style="font-size: 0.8rem; margin-top: 0.4rem; color: var(--amber);"></div>
+      </div>
+    </div>
+
+    <div class="hud-box">
+      <h3 style="margin-top: 0;">Cryptographic &amp; Transit Telemetry</h3>
+      <div class="hud-row"><span>Stream ID</span><code>{sid_esc}</code></div>
+      <div class="hud-row"><span>Broadcaster</span><code title="{broadcaster_esc}">{broadcaster_esc[:18]}...</code></div>
+      <div class="hud-row"><span>p2panda Manifest Seq</span><strong id="hud-seq">#{latest_seq} ({seg_count} segments)</strong></div>
+      <div class="hud-row">
+        <span>Delivery Path</span>
+        <span id="hud-delivery" class="{'status-warn' if handover_active else 'status-ok'}">
+          {'Transit Reflector (307 Handover)' if handover_active else 'Origin Direct'}
+        </span>
+      </div>
+      <div class="hud-row"><span>Active Reflector</span><code id="hud-reflector">{active_reflector}</code></div>
+      <div class="hud-row"><span>Bao Sub-Chunk Size</span><code>1024 B (RhioBaoTree)</code></div>
+      <div class="hud-row"><span>Verified Segments</span><span id="hud-verified-count" class="status-ok">0 verified</span></div>
+      <div class="hud-row"><span>Last X-Bao-Tree-Root</span><code id="hud-bao-root">pending...</code></div>
+      <div class="hud-row"><span>Settlement Mode</span><span>{'Commercial 402' if is_paid else 'Pro-Bono / Barter'}</span></div>
+    </div>
+  </div>
+
+  <script>
+  const FleetmeshPlayer = (() => {{
+    const streamId = {stream_id_js};
+    let audioOnly = false;
+    let verifiedCount = 0;
+
+    function toHex(buf) {{
+      return Array.from(new Uint8Array(buf)).map(b => b.toString(16).padStart(2, '0')).join('');
+    }}
+
+    function fromHex(hex) {{
+      const out = new Uint8Array(hex.length / 2);
+      for (let i = 0; i < out.length; i++) {{
+        out[i] = parseInt(hex.substr(i * 2, 2), 16);
+      }}
+      return out;
+    }}
+
+    // Exact in-browser RhioBaoTree 1024-byte Merkle root verifier matching node/protocols/rhio/store.py
+    async function computeBaoTreeRoot(arrayBuffer) {{
+      const bytes = new Uint8Array(arrayBuffer);
+      const CHUNK_SIZE = 1024;
+      const leaves = [];
+      if (bytes.length === 0) {{
+        const emptyLeaf = new Uint8Array(1);
+        emptyLeaf[0] = 0x00;
+        const h = await crypto.subtle.digest('SHA-256', emptyLeaf);
+        return toHex(h);
+      }}
+      for (let offset = 0; offset < bytes.length; offset += CHUNK_SIZE) {{
+        const slice = bytes.subarray(offset, Math.min(offset + CHUNK_SIZE, bytes.length));
+        const buf = new Uint8Array(1 + slice.length);
+        buf[0] = 0x00;
+        buf.set(slice, 1);
+        const leafHash = await crypto.subtle.digest('SHA-256', buf);
+        leaves.push(new Uint8Array(leafHash));
+      }}
+      let level = leaves;
+      while (level.length > 1) {{
+        const nextLevel = [];
+        for (let i = 0; i < level.length; i += 2) {{
+          const left = level[i];
+          const right = (i + 1 < level.length) ? level[i + 1] : left;
+          const combined = new Uint8Array(1 + 32 + 32);
+          combined[0] = 0x01;
+          combined.set(left, 1);
+          combined.set(right, 33);
+          const parentHash = await crypto.subtle.digest('SHA-256', combined);
+          nextLevel.push(new Uint8Array(parentHash));
+        }}
+        level = nextLevel;
+      }}
+      return toHex(level[0]);
+    }}
+
+    async function fetchSegmentWithVerification(segUri) {{
+      const headers = {{}};
+      const tokenInput = document.getElementById('cashu-token-input');
+      if (tokenInput && tokenInput.value.trim()) {{
+        headers['X-Cashu'] = tokenInput.value.trim();
+      }}
+      const resp = await fetch(segUri, {{ headers, redirect: 'follow' }});
+      if (resp.redirected) {{
+        document.getElementById('hud-delivery').textContent = 'Transit Reflector (307 Handover)';
+        document.getElementById('hud-reflector').textContent = resp.url;
+      }}
+      if (resp.status === 402) {{
+        const quote = await resp.json().catch(() => ({{}}));
+        document.getElementById('cashu-quote-status').textContent =
+          '402 Payment Required: ' + JSON.stringify(quote);
+        return false;
+      }}
+      if (!resp.ok) return false;
+      const expectedRoot = (resp.headers.get('X-Bao-Tree-Root') || '').toLowerCase();
+      const buf = await resp.arrayBuffer();
+      const computedRoot = await computeBaoTreeRoot(buf);
+      if (expectedRoot && computedRoot !== expectedRoot) {{
+        document.getElementById('hud-bao-root').textContent = 'MISMATCH!';
+        return false;
+      }}
+      verifiedCount += 1;
+      document.getElementById('hud-verified-count').textContent = verifiedCount + ' verified';
+      document.getElementById('hud-bao-root').textContent = computedRoot.slice(0, 20) + '...';
+      return true;
+    }}
+
+    async function verifyLatestSegment() {{
+      const m3u8Url = `/video/live/${{streamId}}/index.m3u8` + (audioOnly ? '?audio_only=1' : '');
+      const resp = await fetch(m3u8Url);
+      if (!resp.ok) return false;
+      const text = await resp.text();
+      const lines = text.split('\\n').map(l => l.trim()).filter(Boolean);
+      const segLines = lines.filter(l => !l.startsWith('#') && l.endsWith('.m4s'));
+      if (segLines.length === 0) return false;
+      const latestSeg = segLines[segLines.length - 1];
+      return await fetchSegmentWithVerification(`/video/live/${{streamId}}/${{latestSeg}}`);
+    }}
+
+    function toggleAudioOnly() {{
+      audioOnly = !audioOnly;
+      const video = document.getElementById('video-player');
+      const url = `/video/live/${{streamId}}/index.m3u8` + (audioOnly ? '?audio_only=1' : '');
+      video.src = url;
+    }}
+
+    if (typeof document !== 'undefined') {{
+      document.addEventListener('DOMContentLoaded', () => {{
+        const video = document.getElementById('video-player');
+        if (video && !video.getAttribute('src')) {{
+          video.src = `/video/live/${{streamId}}/index.m3u8`;
+        }}
+      }});
+    }}
+
+    return {{ computeBaoTreeRoot, fetchSegmentWithVerification, verifyLatestSegment, toggleAudioOnly }};
+  }})();
+  </script>
+</body>
+</html>
+"""
+
+
+def mount_player_routes(
+    host: ProtocolHostRouter,
+    packager: VideoStreamPackager,
+    reflector: Optional[TransitReflectorManager] = None,
+    ledger: Optional[TransitLedgerStore] = None,
+) -> None:
+    """Mount `GET /video/watch` and `GET /video/watch/<stream_id>` onto `ProtocolHostRouter`."""
+    from node.transport import ws
+
+    def _handle_watch(conn: Any, req: Any) -> bool:
+        uri = getattr(req, 'path', '')
+        parsed = urllib.parse.urlparse(uri)
+        route_path = parsed.path.rstrip('/')
+
+        if route_path == '/video/watch':
+            page = render_directory_html(packager, reflector=reflector, ledger=ledger)
+            ws.http_response(conn, '200 OK', page.encode('utf-8'), 'text/html; charset=utf-8')
+            return True
+
+        prefix = '/video/watch/'
+        if not parsed.path.startswith(prefix):
+            return False
+        stream_id = parsed.path[len(prefix):].strip('/').split('/')[0]
+        if not stream_id:
+            page = render_directory_html(packager, reflector=reflector, ledger=ledger)
+            ws.http_response(conn, '200 OK', page.encode('utf-8'), 'text/html; charset=utf-8')
+            return True
+
+        player_html = render_player_html(stream_id, packager, reflector=reflector)
+        if player_html is None:
+            ws.http_response(
+                conn,
+                '404 Not Found',
+                b'{"error":"stream_not_found"}',
+                'application/json',
+            )
+            return True
+        ws.http_response(conn, '200 OK', player_html.encode('utf-8'), 'text/html; charset=utf-8')
+        return True
+
+    host.mount_route('/video/watch', _handle_watch, methods=('GET',), owner='video')
+
+
+__all__ = [
+    'render_directory_html',
+    'render_player_html',
+    'mount_player_routes',
+]

node/planes/services/video/timed_segments.py

@@ -0,0 +1,124 @@
+"""Timed segments: a captured segment carries its capture time on the shared clock inside its own bytes.
+
+MeshTube's textile model (`meshtube/docs/textile-spools.md`) asks that every fiber spun live carry its
+moment on a shared clock (UTC, microseconds) within its bytes, so it stands on its own whatever strand or
+spool it is in, and its content address covers the time.
+
+- A fragmented ISO-BMFF (CMAF) segment gets a standard Producer Reference Time box (`prft`, ISO/IEC 14496-12)
+  just before its first `moof`: the UTC time (NTP format) of the media time that fragment starts at
+  (`tfdt`), for its first track (`tfhd`). The segment stays plain CMAF; players skip the box.
+- Anything else is framed as a MeshTube timed fiber: `"MTF1" | u32 header length | header | payload`, the
+  header canonical JSON `{"clock":"utc","t_us":...,"v":1}` (byte for byte MeshTube's `timedFiberBytes`).
+
+Only *captured* segments are stamped. Re-aired segments (VOD playlists, ad breaks) are existing fibers:
+when they air is the spool's business, and stamping them would store a copy per airing.
+"""
+from __future__ import annotations
+
+import json
+import struct
+from typing import Iterator, Optional, Tuple
+
+NTP_UNIX_OFFSET = 2_208_988_800
+MTF_MAGIC = b'MTF1'
+_CONTAINER_BOXES = {b'moof', b'traf'}
+
+
+def _boxes(data: bytes, start: int = 0, end: Optional[int] = None) -> Iterator[Tuple[bytes, int, int, int]]:
+    """`(type, box_start, payload_start, box_end)` of each box in `data[start:end]`; stops at a malformed box."""
+    end = len(data) if end is None else end
+    pos = start
+    while pos + 8 <= end:
+        size, kind = struct.unpack('>I4s', data[pos:pos + 8])
+        header = 8
+        if size == 1:
+            if pos + 16 > end:
+                return
+            size = struct.unpack('>Q', data[pos + 8:pos + 16])[0]
+            header = 16
+        elif size == 0:
+            size = end - pos
+        if size < header or pos + size > end:
+            return
+        yield kind, pos, pos + header, pos + size
+        pos += size
+
+
+def _is_fragmented_bmff(data: bytes) -> bool:
+    kinds = [k for k, *_ in _boxes(data)]
+    return bool(kinds) and b'moof' in kinds and all(k.isalnum() or k in (b'prft',) for k in kinds)
+
+
+def _first_fragment(data: bytes) -> Optional[Tuple[int, int, int]]:
+    """`(moof_start, track_id, base_media_decode_time)` of the segment's first fragment; a fragment that names
+    no track or decode time refers to track 1 at media time 0, so any `moof` can take a `prft`."""
+    for kind, start, body, end in _boxes(data):
+        if kind != b'moof':
+            continue
+        for tkind, _ts, tbody, tend in _boxes(data, body, end):
+            if tkind != b'traf':
+                continue
+            track_id, media_time = None, 0
+            for ckind, _cs, cbody, cend in _boxes(data, tbody, tend):
+                if ckind == b'tfhd' and cend - cbody >= 8:
+                    track_id = struct.unpack('>I', data[cbody + 4:cbody + 8])[0]
+                elif ckind == b'tfdt' and cend - cbody >= 8:
+                    version = data[cbody]
+                    media_time = struct.unpack('>Q', data[cbody + 4:cbody + 12])[0] if version == 1 and cend - cbody >= 12 \
+                        else struct.unpack('>I', data[cbody + 4:cbody + 8])[0]
+            if track_id is not None:
+                return start, track_id, media_time
+        return start, 1, 0
+    return None
+
+
+def _ntp(t_us: int) -> Tuple[int, int]:
+    secs, frac_us = divmod(int(t_us), 1_000_000)
+    return secs + NTP_UNIX_OFFSET, (frac_us << 32) // 1_000_000
+
+
+def prft_box(t_us: int, track_id: int, media_time: int) -> bytes:
+    """A version-1 `prft` box: flags 0 (the time the referenced sample entered the encoder: its capture)."""
+    ntp_secs, ntp_frac = _ntp(t_us)
+    return struct.pack('>I4sB3sIIIQ', 32, b'prft', 1, b'\x00\x00\x00', track_id, ntp_secs, ntp_frac, media_time)
+
+
+def timed_fiber_bytes(t_us: int, payload: bytes, *, mime: str = '') -> bytes:
+    header = {'clock': 'utc', 't_us': int(t_us), 'v': 1}
+    if mime:
+        header['mime'] = mime
+    raw = json.dumps(header, sort_keys=True, separators=(',', ':')).encode('utf-8')
+    return MTF_MAGIC + struct.pack('>I', len(raw)) + raw + bytes(payload)
+
+
+def stamp_capture_time(segment: bytes, captured_us: int, *, mime: str = 'video/mp4') -> bytes:
+    """The captured segment with its capture time inside: a `prft` box for CMAF, else timed-fiber framing.
+
+    A segment already carrying a capture time is returned unchanged."""
+    if read_capture_time(segment) is not None:
+        return segment
+    if _is_fragmented_bmff(segment):
+        frag = _first_fragment(segment)
+        if frag is not None:
+            moof_start, track_id, media_time = frag
+            return segment[:moof_start] + prft_box(captured_us, track_id, media_time) + segment[moof_start:]
+    return timed_fiber_bytes(captured_us, segment, mime=mime)
+
+
+def read_capture_time(fiber: bytes) -> Optional[int]:
+    """A fiber's capture time (UTC µs) from its `prft` box or timed-fiber header; `None` when it has none."""
+    if fiber[:4] == MTF_MAGIC and len(fiber) >= 8:
+        (length,) = struct.unpack('>I', fiber[4:8])
+        try:
+            header = json.loads(fiber[8:8 + length].decode('utf-8'))
+        except (UnicodeDecodeError, ValueError):
+            return None
+        t_us = header.get('t_us') if isinstance(header, dict) and header.get('clock') == 'utc' else None
+        return t_us if isinstance(t_us, int) else None
+    for kind, _start, body, end in _boxes(fiber):
+        if kind == b'prft' and end - body >= 20:
+            ntp_secs, ntp_frac = struct.unpack('>II', fiber[body + 8:body + 16])
+            return (ntp_secs - NTP_UNIX_OFFSET) * 1_000_000 + ((ntp_frac * 1_000_000 + (1 << 31)) >> 32)
+        if kind == b'moof':
+            return None
+    return None