rosotacom-dev 2.5.dev47__tar.gz → 2.5.dev49__tar.gz

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev47
+Version: 2.5.dev49
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev49}/docs/forensics-report.md

@@ -93,6 +93,13 @@ delivered below it; `unknown` without sender-side records. `min_offered_hz` /
 rate — they never enter the delivered view, where the cross-peer join would
 upgrade receiver-inferred lost rows to delivered.
 
+The sending peer's status overview emits those rows itself for every wrapped
+stream (stage `com_out`, status `sent`, sequence gaps in its own observation as
+`unobserved` — see RFC 0003): record on both machines and place both peers'
+`logs/<peer>/status/` under one instance directory before running the report,
+and the `unknown` verdicts disappear. Recordings made before the sender-side
+rows existed stay `unknown` for their outbound streams.
+
 Events across streams and kinds are grouped into **incidents** when their
 windows touch (merge gap defaults to one bin): one degradation moment, several
 lenses on it.

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev49}/docs/rfcs/0003-metric-backbone.md

@@ -56,6 +56,17 @@ Every metric on the wishlist is a projection of one recorded object per message:
   inter_arrival / jitter         — receiver-local regularity
 ```
 
+The **sending peer** records its own view of the same message at `com_out`
+(`direction: outbound`): `t_wrap` plus `t_com_out` (both its own clock, so
+`sections.wrap_to_com_out_ms` is the relay hop, and there is no θ). Its status
+values are deliberately different — `sent` for an observed message,
+`unobserved` for a gap in its own observation (the local best-effort observer
+missed it; the link cannot lose a message before the link) — so the offline
+join, which ranks only `lost < reordered < delivered`, can enrich a receiver
+row with sender timestamps but a sender row can never overwrite a receiver's
+`lost` verdict. This is what lets the forensics report classify a rate collapse
+as `source` vs `link`: offered (sender `t_wrap` bins) against delivered.
+
 **Why `epoch` is part of the key.** `universal_ota_wrapper` counts per topic
 from zero, so a peer that restarts inside an instance replays sequence numbers
 the receiver has already seen. The receiver detects the restart from the

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev49}/session-configuration.md

@@ -568,13 +568,39 @@ number being reported.
 - `bit_rate` (int)
 - `encoder_av_options` (string)
 
-#### Receiver-side playout pacing (manual node)
+#### Receiver-side playout pacing
 
 A receiver that hands every packet to the decoder the moment it arrives turns
 network delay jitter into display stutter. `com_py playout_pacer` re-times a
 received packet stream to `stamp + budget` (budget adaptive above the fastest
 observed path, clock-offset-proof; late packets pass through immediately, order
-always preserved — the decoder chain sees every packet):
+always preserved — the decoder chain sees every packet). On the 2026-08-17 CCNG
+field trace this removes ~95 % of delay-caused >200 ms display gaps at ~100 ms
+median added age (adaptive mode).
+
+Declaratively, add a `playout` block to the transport:
+
+```yaml
+        transport:
+          type: "ffmpeg"
+          gop_size: 3
+          remote_republish: compressed
+          playout:            # receiver-side; requires remote_republish
+            adaptive: true    # default true; false uses target_ms as a fixed budget
+            target_ms: 350    # fixed budget when adaptive: false
+            min_ms: 100       # adaptive clamp above the observed delay floor
+            max_ms: 800
+```
+
+The receiving peer then runs the pacer in its own `PACE` window against the
+arrived encoded stream, and the reverse republish decodes `<encoded>/paced`
+instead of the raw arrival — the delivered topic name is unchanged, which is
+why `playout` requires `remote_republish`: without a republish the pacer's
+`/paced` suffix would rename what the receiving application subscribes to.
+The sender's own preview decode (`local_republish`) is never paced — it reads
+the local copy of what was just encoded, so there is no jitter to absorb.
+
+The node also runs standalone against any packet stream:
 
 ```bash
 ros2 run com_py playout_pacer --ros-args \
@@ -583,11 +609,7 @@ ros2 run com_py playout_pacer --ros-args \
 ```
 
 It republishes on `<topic>/paced` plus `.../paced/budget_ms` and
-`.../paced/queue_depth` debug topics; point the reverse republish (or any
-decoder) at the paced name. On the 2026-08-17 CCNG field trace this removes
-~95 % of delay-caused >200 ms display gaps at ~100 ms median added age
-(adaptive mode). Declarative wiring as a `transport.playout` block is tracked
-in issue #284.
+`.../paced/queue_depth` debug topics.
 
 `type: foxglove` supports (CompressedVideo):
 - `gop_size` (int)

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev49}/src/rosotacom/resources/ws/ros2src/com_py/com_py/status_overview.py

@@ -253,6 +253,22 @@ class StageObserver(Node):
                     ),
                     None,
                 )
+                com_out = next(
+                    (
+                        context
+                        for context in contexts
+                        if context.get("stage") == "com_out"
+                        and context.get("direction") == "outbound"
+                    ),
+                    None,
+                )
+                keyframe: Optional[bool] = None
+                if com_in is not None or com_out is not None:
+                    try:
+                        if msg.msg_type == FFMPEG_PACKET_TYPE:
+                            keyframe = parse_keyframe_flag(bytes(msg.serialized_msg))
+                    except Exception:
+                        keyframe = None
                 if com_in is not None:
                     seq = int(msg.seq)
                     t_wrap_s = _stamp_seconds(msg.header.stamp)
@@ -262,12 +278,6 @@ class StageObserver(Node):
                         clock_offset_s = estimate["offset_s"]
                         rtt_s = estimate["rtt_s"]
                         delay_s = now_ros_s + clock_offset_s - t_wrap_s
-                    keyframe: Optional[bool] = None
-                    try:
-                        if msg.msg_type == FFMPEG_PACKET_TYPE:
-                            keyframe = parse_keyframe_flag(bytes(msg.serialized_msg))
-                    except Exception:
-                        keyframe = None
                     transit = {
                         "peer": com_in.get("peer"),
                         "source": com_in.get("source"),
@@ -279,6 +289,26 @@ class StageObserver(Node):
                         "t_com_in": now_ros_s,
                         "keyframe": keyframe,
                     }
+                elif com_out is not None:
+                    # The sending peer's own view of the same message: what the
+                    # source handed to the link, before any OTA hop. The wrapper
+                    # stamped `t_wrap` on THIS machine, so no peer offset applies
+                    # (same rule as the generic local-stage branch below) and the
+                    # delay is the wrap->com_out relay hop, not an OTA number.
+                    seq = int(msg.seq)
+                    t_wrap_s = _stamp_seconds(msg.header.stamp)
+                    delay_s = now_ros_s - t_wrap_s
+                    transit = {
+                        "peer": com_out.get("peer"),
+                        "source": com_out.get("source"),
+                        "target": com_out.get("target"),
+                        "topic": com_out.get("base"),
+                        "direction": com_out.get("direction"),
+                        "stage": com_out.get("stage"),
+                        "t_wrap": t_wrap_s,
+                        "t_com_out": now_ros_s,
+                        "keyframe": keyframe,
+                    }
             else:
                 header = getattr(msg, "header", None)
                 stamp = getattr(header, "stamp", None) if header is not None else None

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev49}/src/rosotacom/resources/ws/ros2src/com_py/com_py/status_overview_core.py

@@ -451,6 +451,15 @@ class StageObservation:
                 self.sequence_events.append((now, expected_delta, missing, reordered, missing))
 
             if transit is not None and seq is not None:
+                # A sender-side com_out row observes its own machine's wrapper:
+                # a sequence gap there means the local observer missed the
+                # message, not that the link lost it, and an observed message
+                # was *sent*, not delivered. The distinct status values also
+                # keep the offline join honest: `join_transit_records` ranks
+                # only lost < reordered < delivered, so a sender row can never
+                # overwrite the receiving side's `lost` verdict for the same
+                # (source, topic, epoch, seq).
+                outbound = transit.get("direction") == "outbound"
                 common = {
                     "kind": "transit",
                     "peer": transit.get("peer"),
@@ -465,16 +474,21 @@ class StageObservation:
                     "epoch": self.epoch,
                 }
                 if missing_start is not None:
+                    gap_time_field = "t_com_out" if outbound else "t_com_in"
                     for missing_seq in range(missing_start, int(seq)):
                         self.transit_records.append(
                             {
                                 **common,
                                 "seq": missing_seq,
-                                "status": "lost",
+                                "status": "unobserved" if outbound else "lost",
                                 "t_wrap": None,
-                                "t_com_in": None,
+                                gap_time_field: None,
                                 "clock_offset_ms": None,
-                                "sections": {"ota_hop_ms": None},
+                                "sections": (
+                                    {"wrap_to_com_out_ms": None}
+                                    if outbound
+                                    else {"ota_hop_ms": None}
+                                ),
                                 "size_bytes": None,
                                 "inter_arrival_ms": None,
                                 "jitter_ms": None,
@@ -493,27 +507,42 @@ class StageObservation:
                 if inter_arrival_s is not None:
                     self.last_inter_arrival_s = inter_arrival_s
                 self.last_transit_recv_wall = wall
+                if outbound:
+                    # Same clock on both ends of this hop, so there is no
+                    # corrected/uncorrected pair and no OTA section: the only
+                    # honest number is the wrap->com_out relay hop.
+                    status = "sent"
+                    time_fields = {"t_com_out": transit.get("t_com_out")}
+                    sections: Dict[str, Any] = {
+                        "wrap_to_com_out_ms": (
+                            round(delay_s * 1000.0, 3) if delay_s is not None else None
+                        ),
+                    }
+                else:
+                    status = sequence_status
+                    time_fields = {"t_com_in": transit.get("t_com_in")}
+                    sections = {
+                        "ota_hop_ms": (
+                            round(delay_s * 1000.0, 3) if delay_s is not None else None
+                        ),
+                        "ota_hop_uncorrected_ms": (
+                            round(raw_delay_s * 1000.0, 3)
+                            if raw_delay_s is not None
+                            else None
+                        ),
+                    }
                 row = {
                     **common,
                     "seq": int(seq),
-                    "status": sequence_status,
+                    "status": status,
                     "t_wrap": transit.get("t_wrap"),
-                    "t_com_in": transit.get("t_com_in"),
+                    **time_fields,
                     "clock_offset_ms": (
                         round(clock_offset_s * 1000.0, 3)
                         if clock_offset_s is not None
                         else None
                     ),
-                    "sections": {
-                        "ota_hop_ms": (
-                            round(delay_s * 1000.0, 3) if delay_s is not None else None
-                        ),
-                        "ota_hop_uncorrected_ms": (
-                            round(raw_delay_s * 1000.0, 3)
-                            if raw_delay_s is not None
-                            else None
-                        ),
-                    },
+                    "sections": sections,
                     "size_bytes": size,
                     "inter_arrival_ms": (
                         round(inter_arrival_s * 1000.0, 3)

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev49}/src/rosotacom/resources/ws/session/content/base/session_plugin_base.yaml

@@ -232,15 +232,49 @@ parameters:
   irt_1_topic: # e.g. /sensors/camera/front_wide/image_color
   irt_1_transport: # e.g. raw
   irt_1_out_transport: compressed # e.g. raw, compressed – determines the output remap format
+  irt_1_paced: # "true" -> decode reads ${irt_1_topic}/paced (playout pacer, PACE window)
   irt_2_topic: # e.g. /sensors/front_camera/image_raw/compressed
   irt_2_transport: # e.g. raw
   irt_2_out_transport: compressed # e.g. raw, compressed – determines the output remap format
+  irt_2_paced: # "true" -> decode reads ${irt_2_topic}/paced
   irt_3_topic: # e.g. /sensor/front_camera/image_color/compressed
   irt_3_transport: # e.g. raw
   irt_3_out_transport: compressed # e.g. raw, compressed – determines the output remap format
+  irt_3_paced: # "true" -> decode reads ${irt_3_topic}/paced
   irt_4_topic: # e.g. /sensor/front_camera/image_color/compressed
   irt_4_transport: # e.g. raw
   irt_4_out_transport: compressed # e.g. raw, compressed – determines the output remap format
+  irt_4_paced: # "true" -> decode reads ${irt_4_topic}/paced
+
+  # Receiver-side playout pacing (transport.playout in the session definition):
+  # re-times the arrived encoded stream on '<topic>/paced' so the decode sees a
+  # steady cadence instead of the network's delay jitter. Never reorders, never
+  # drops; late packets pass through immediately.
+  pace: false
+  pace_1_topic: # the arrived encoded stream, e.g. /camera/image/ffmpeg
+  pace_1_msg_type: # e.g. ffmpeg_image_transport_msgs/msg/FFMPEGPacket
+  pace_1_adaptive: # "true" | "false"
+  pace_1_target_ms: # fixed budget when adaptive is "false"
+  pace_1_min_ms: # adaptive clamp above the observed delay floor
+  pace_1_max_ms:
+  pace_2_topic:
+  pace_2_msg_type:
+  pace_2_adaptive:
+  pace_2_target_ms:
+  pace_2_min_ms:
+  pace_2_max_ms:
+  pace_3_topic:
+  pace_3_msg_type:
+  pace_3_adaptive:
+  pace_3_target_ms:
+  pace_3_min_ms:
+  pace_3_max_ms:
+  pace_4_topic:
+  pace_4_msg_type:
+  pace_4_adaptive:
+  pace_4_target_ms:
+  pace_4_min_ms:
+  pace_4_max_ms:
 
 common:
   before_commands:
@@ -623,6 +657,30 @@ windows:
         - args+=(--remap "${in_remap}:=${it_4_topic}" --remap "out/${it_4_transport}:=${it_4_topic}/${outgoing_suffix}")
         - echo ${args[@]}
         - ${args[@]}
+  - name: PACE
+    if: pace
+    layout: even-vertical
+    splits:
+      - commands:
+        - if [ '${pace_1_topic}' = "None" ]; then exit; fi
+        - args=(ros2 run com_py playout_pacer --ros-args -p topic:=${pace_1_topic} -p msg_type:=${pace_1_msg_type} -p adaptive:=${pace_1_adaptive} -p target_ms:=${pace_1_target_ms} -p min_ms:=${pace_1_min_ms} -p max_ms:=${pace_1_max_ms} -p qos_config_file:='${qos_config_file}')
+        - echo ${args[@]}
+        - ${args[@]}
+      - commands:
+        - if [ '${pace_2_topic}' = "None" ]; then exit; fi
+        - args=(ros2 run com_py playout_pacer --ros-args -p topic:=${pace_2_topic} -p msg_type:=${pace_2_msg_type} -p adaptive:=${pace_2_adaptive} -p target_ms:=${pace_2_target_ms} -p min_ms:=${pace_2_min_ms} -p max_ms:=${pace_2_max_ms} -p qos_config_file:='${qos_config_file}')
+        - echo ${args[@]}
+        - ${args[@]}
+      - commands:
+        - if [ '${pace_3_topic}' = "None" ]; then exit; fi
+        - args=(ros2 run com_py playout_pacer --ros-args -p topic:=${pace_3_topic} -p msg_type:=${pace_3_msg_type} -p adaptive:=${pace_3_adaptive} -p target_ms:=${pace_3_target_ms} -p min_ms:=${pace_3_min_ms} -p max_ms:=${pace_3_max_ms} -p qos_config_file:='${qos_config_file}')
+        - echo ${args[@]}
+        - ${args[@]}
+      - commands:
+        - if [ '${pace_4_topic}' = "None" ]; then exit; fi
+        - args=(ros2 run com_py playout_pacer --ros-args -p topic:=${pace_4_topic} -p msg_type:=${pace_4_msg_type} -p adaptive:=${pace_4_adaptive} -p target_ms:=${pace_4_target_ms} -p min_ms:=${pace_4_min_ms} -p max_ms:=${pace_4_max_ms} -p qos_config_file:='${qos_config_file}')
+        - echo ${args[@]}
+        - ${args[@]}
   - name: IRT
     if: irt
     layout: even-vertical
@@ -630,28 +688,32 @@ windows:
       - commands:
         - if [ '${irt_1_topic}' = "None" ]; then exit; fi
         - if [[ "${irt_1_out_transport}" == "raw" ]]; then out_remap="out"; else out_remap="out/${irt_1_out_transport}"; fi
+        - if [[ "${irt_1_paced}" != "None" ]]; then irt_in_topic="${irt_1_topic}/paced"; else irt_in_topic="${irt_1_topic}"; fi
         - args=(ros2 run image_transport republish --ros-args -r __node:=irt_republish1 -p in_transport:=${irt_1_transport} -p out_transport:=${irt_1_out_transport}
-            --remap in/${irt_1_transport}:=${irt_1_topic} --remap ${out_remap}:=${irt_1_topic}/${irt_1_out_transport})
+            --remap in/${irt_1_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_1_topic}/${irt_1_out_transport})
         - echo ${args[@]}
         - ${args[@]}
       - commands:
         - if [ '${irt_2_topic}' = "None" ]; then exit; fi
         - if [[ "${irt_2_out_transport}" == "raw" ]]; then out_remap="out"; else out_remap="out/${irt_2_out_transport}"; fi
+        - if [[ "${irt_2_paced}" != "None" ]]; then irt_in_topic="${irt_2_topic}/paced"; else irt_in_topic="${irt_2_topic}"; fi
         - args=(ros2 run image_transport republish --ros-args -r __node:=irt_republish2 -p in_transport:=${irt_2_transport} -p out_transport:=${irt_2_out_transport}
-            --remap in/${irt_2_transport}:=${irt_2_topic} --remap ${out_remap}:=${irt_2_topic}/${irt_2_out_transport})
+            --remap in/${irt_2_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_2_topic}/${irt_2_out_transport})
         - echo ${args[@]}
         - ${args[@]}
       - commands:
         - if [ '${irt_3_topic}' = "None" ]; then exit; fi
         - if [[ "${irt_3_out_transport}" == "raw" ]]; then out_remap="out"; else out_remap="out/${irt_3_out_transport}"; fi
+        - if [[ "${irt_3_paced}" != "None" ]]; then irt_in_topic="${irt_3_topic}/paced"; else irt_in_topic="${irt_3_topic}"; fi
         - args=(ros2 run image_transport republish --ros-args -r __node:=irt_republish3 -p in_transport:=${irt_3_transport} -p out_transport:=${irt_3_out_transport}
-            --remap in/${irt_3_transport}:=${irt_3_topic} --remap ${out_remap}:=${irt_3_topic}/${irt_3_out_transport})
+            --remap in/${irt_3_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_3_topic}/${irt_3_out_transport})
         - echo ${args[@]}
         - ${args[@]}
       - commands:
         - if [ '${irt_4_topic}' = "None" ]; then exit; fi
         - if [[ "${irt_4_out_transport}" == "raw" ]]; then out_remap="out"; else out_remap="out/${irt_4_out_transport}"; fi
+        - if [[ "${irt_4_paced}" != "None" ]]; then irt_in_topic="${irt_4_topic}/paced"; else irt_in_topic="${irt_4_topic}"; fi
         - args=(ros2 run image_transport republish --ros-args -r __node:=irt_republish4 -p in_transport:=${irt_4_transport} -p out_transport:=${irt_4_out_transport}
-            --remap in/${irt_4_transport}:=${irt_4_topic} --remap ${out_remap}:=${irt_4_topic}/${irt_4_out_transport})
+            --remap in/${irt_4_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_4_topic}/${irt_4_out_transport})
         - echo ${args[@]}
         - ${args[@]}

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev49}/src/rosotacom/resources/ws/session/creation/generate_session_files.py

@@ -92,6 +92,13 @@ class TransportSpec:
     #: image_transport itself, or one that only forwards or records packets,
     #: does not want a second copy of every frame.
     remote_republish: Optional[str] = None
+    #: Receiver-side playout pacing (issue #284): re-time the arrived packet
+    #: stream to smooth network delay jitter before the reverse republish
+    #: decodes it. Keys: adaptive / target_ms / min_ms / max_ms (validated in
+    #: the parser; defaults live in the playout_pacer node). Requires
+    #: `remote_republish`, because the pacer publishes on `<encoded>/paced`
+    #: and only the republish remap keeps the delivered topic name unchanged.
+    playout: Optional[Dict[str, Any]] = None
 
 
 @dataclass
@@ -1692,12 +1699,45 @@ def _compute_pipeline(
                 )
             return str(value)
 
-        params = {k: v for k, v in t.items() if k not in ("type", *republish_keys)}
+        remote_republish = _republish("remote_republish")
+
+        playout: Optional[Dict[str, Any]] = None
+        playout_cfg = t.get("playout")
+        if playout_cfg is not None:
+            if not isinstance(playout_cfg, dict):
+                raise ValueError(f"transport.playout must be a mapping for topic '{entry.base}'")
+            allowed = {"adaptive", "target_ms", "min_ms", "max_ms"}
+            unknown = sorted(set(playout_cfg) - allowed)
+            if unknown:
+                raise ValueError(
+                    f"transport.playout for topic '{entry.base}' has unknown keys {unknown}; "
+                    f"allowed: {sorted(allowed)}"
+                )
+            if remote_republish is None:
+                raise ValueError(
+                    f"transport.playout for topic '{entry.base}' requires remote_republish: "
+                    "the pacer publishes on '<encoded>/paced', and only the reverse republish's "
+                    "input remap keeps the delivered topic name unchanged. Without a republish "
+                    "the receiver would have to subscribe a renamed topic."
+                )
+            for key in ("target_ms", "min_ms", "max_ms"):
+                if key in playout_cfg and (not isinstance(playout_cfg[key], (int, float)) or playout_cfg[key] <= 0):
+                    raise ValueError(f"transport.playout.{key} must be a positive number for topic '{entry.base}'")
+            min_ms = float(playout_cfg.get("min_ms", 100.0))
+            max_ms = float(playout_cfg.get("max_ms", 800.0))
+            if max_ms < min_ms:
+                raise ValueError(f"transport.playout.max_ms must be >= min_ms for topic '{entry.base}'")
+            if "adaptive" in playout_cfg and not isinstance(playout_cfg["adaptive"], bool):
+                raise ValueError(f"transport.playout.adaptive must be a boolean for topic '{entry.base}'")
+            playout = dict(playout_cfg)
+
+        params = {k: v for k, v in t.items() if k not in ("type", "playout", *republish_keys)}
         transport = TransportSpec(
             type=ttype,
             params=params,
             local_republish=_republish("local_republish"),
-            remote_republish=_republish("remote_republish"),
+            remote_republish=remote_republish,
+            playout=playout,
         )
 
     topic = entry.base
@@ -3201,21 +3241,46 @@ def func(
         # it encoded and (b) the decode of what arrived. Both run on *this* peer;
         # what differs is which copy they decode and which transport the session
         # asked each of them to publish in.
-        irt_all: List[Tuple[str, str, str]] = []
+        # The sender's own preview decode is never paced: it reads the local
+        # copy of what it just encoded, so there is no network jitter to
+        # absorb. Playout pacing exists on the receiving side only.
+        irt_all: List[Tuple[str, str, str, Optional[Dict[str, Any]]]] = []
         for t, tspec in irt_items_local:
             assert tspec is not None
-            irt_all.append((t, tspec.type, str(tspec.local_republish)))
-        irt_all.extend((topic, tspec.type, str(tspec.remote_republish)) for topic, tspec in irt_items_remote)
+            irt_all.append((t, tspec.type, str(tspec.local_republish), None))
+        irt_all.extend(
+            (topic, tspec.type, str(tspec.remote_republish), tspec.playout) for topic, tspec in irt_items_remote
+        )
         _assert_max("irt", irt_all, 4)
         if irt_all:
             items2 = [("irt", True)]
-            for i, (topic, _ttype, _out_transport) in enumerate(irt_all, 1):
+            for i, (topic, _ttype, _out_transport, _playout) in enumerate(irt_all, 1):
                 items2.append((f"irt_{i}_topic", topic))
-            for i, (_topic, ttype, out_transport) in enumerate(irt_all, 1):
+            for i, (_topic, ttype, out_transport, playout) in enumerate(irt_all, 1):
                 items2.append((f"irt_{i}_transport", ttype))
                 items2.append((f"irt_{i}_out_transport", out_transport))
+                if playout is not None:
+                    # Points the decode's input remap at '<topic>/paced'; the
+                    # pacer itself runs in the PACE window below.
+                    items2.append((f"irt_{i}_paced", "true"))
             blocks.append(PluginBlock("irt", items2))
 
+        paced_entries = [
+            (i, topic, ttype, playout)
+            for i, (topic, ttype, _out_transport, playout) in enumerate(irt_all, 1)
+            if playout is not None
+        ]
+        if paced_entries:
+            items_pace: List[Tuple[str, Any]] = [("pace", True)]
+            for i, topic, ttype, playout in paced_entries:
+                items_pace.append((f"pace_{i}_topic", topic))
+                items_pace.append((f"pace_{i}_msg_type", TRANSPORT_OUTPUT_TYPES[ttype]))
+                items_pace.append((f"pace_{i}_adaptive", "true" if playout.get("adaptive", True) else "false"))
+                items_pace.append((f"pace_{i}_target_ms", float(playout.get("target_ms", 350.0))))
+                items_pace.append((f"pace_{i}_min_ms", float(playout.get("min_ms", 100.0))))
+                items_pace.append((f"pace_{i}_max_ms", float(playout.get("max_ms", 800.0))))
+            blocks.append(PluginBlock("pace", items_pace))
+
         if nor_items:
             items2 = [("nor", True)]
             nor_prefix = f"/{peer_name[remote]}" if bool(inbound_cfg.get("keep_source_prefix", False)) else ""

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev49}/src/rosotacom_dev.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev47
+Version: 2.5.dev49
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev49}/src/rosotacom_dev.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
   "tag": "2.4",
-  "distance": 47,
-  "node": "g73fa1de72a3f04bd36058dcc88da7d62b6668edb",
+  "distance": 49,
+  "node": "g992b77df07a37e0060e78e24fda488156bdce238",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-18"

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev49}/tests/unit/test_session_pipeline.py

@@ -233,3 +233,76 @@ def test_generated_peer_files_wire_the_wrapped_camera(tmp_path: Path) -> None:
     # ... and what the application finally reads is the decoded image.
     assert stages["native_in"]["topic"] == "/camera/image/ffmpeg/raw"
     assert stages["native_in"]["type"] == "sensor_msgs/msg/Image"
+
+
+# ---------------------------------------------------------------------------
+# receiver-side playout pacing (transport.playout, issue #284)
+# ---------------------------------------------------------------------------
+
+
+def test_playout_requires_a_receiver_republish() -> None:
+    """Without a reverse republish the pacer would rename the delivered topic."""
+    with pytest.raises(ValueError, match="requires remote_republish"):
+        _pipeline({"transport": {"type": "ffmpeg", "playout": {"min_ms": 100}}})
+
+
+def test_playout_rejects_unknown_keys_and_bad_numbers() -> None:
+    with pytest.raises(ValueError, match="unknown keys"):
+        _pipeline(_ffmpeg(playout={"budget_ms": 350}))
+    with pytest.raises(ValueError, match="positive number"):
+        _pipeline(_ffmpeg(playout={"target_ms": -1}))
+    with pytest.raises(ValueError, match="max_ms must be >= min_ms"):
+        _pipeline(_ffmpeg(playout={"min_ms": 500, "max_ms": 100}))
+
+
+def test_playout_never_leaks_into_encoder_params() -> None:
+    _entry, pipe = _pipeline(_ffmpeg(gop_size=3, playout={"min_ms": 100, "max_ms": 800}))
+    tspec = pipe["transport"]
+    assert tspec.playout == {"min_ms": 100, "max_ms": 800}
+    assert "playout" not in tspec.params
+    assert tspec.params["gop_size"] == 3
+
+
+def test_playout_does_not_rename_the_delivered_topic() -> None:
+    """The pacer sits between unwrapper and decode; what the application reads keeps its name."""
+    _entry, plain = _pipeline(_ffmpeg())
+    _entry, paced = _pipeline(_ffmpeg(playout={}))
+    assert generator._delivered_topic(paced, paced["final"]) == generator._delivered_topic(plain, plain["final"])
+
+
+def test_generated_peer_files_wire_the_pacer(tmp_path: Path) -> None:
+    processing = {
+        "transport": {
+            "type": "ffmpeg",
+            "gop_size": 3,
+            "remote_republish": "compressed",
+            "playout": {"adaptive": True, "min_ms": 120, "max_ms": 600},
+        },
+        "use_ota_wrapper": True,
+    }
+    generator.func(
+        session_config_obj=_camera_cfg(processing),
+        output_dir=str(tmp_path),
+        force=True,
+        peer_addresses={"a": "127.0.0.1", "b": "127.0.0.2"},
+    )
+
+    receiver = (tmp_path / "a" / "plugin.yaml").read_text(encoding="utf-8")
+    # The pacer runs on the receiving peer against the arrived encoded stream...
+    assert "pace_1_topic: /camera/image/ffmpeg" in receiver
+    assert "pace_1_msg_type: ffmpeg_image_transport_msgs/msg/FFMPEGPacket" in receiver
+    assert (
+        "pace_1_adaptive: 'true'" in receiver
+        or 'pace_1_adaptive: "true"' in receiver
+        or "pace_1_adaptive: true" in receiver
+    )
+    assert "pace_1_min_ms: 120.0" in receiver
+    assert "pace_1_max_ms: 600.0" in receiver
+    # ...and the decode reads the paced copy.
+    assert "irt_1_paced" in receiver
+
+    # The sender has no pacer: its preview (if any) reads its own encode, and
+    # this session declares no local_republish at all.
+    sender = (tmp_path / "b" / "plugin.yaml").read_text(encoding="utf-8")
+    assert "pace" not in sender or "pace_1_topic" not in sender
+    assert "irt_1_paced" not in sender