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

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

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

{rosotacom_dev-2.5.dev48 → 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.dev48 → 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.dev48 → 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.dev48 → 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.dev48
+Version: 2.5.dev49
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause

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

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

{rosotacom_dev-2.5.dev48 → 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