Performance runtime and speech motion
Responsibilities
The performance runner executes timed nodes, publishes runtime events and manages loaded/running/paused state. Storage/editing through WebUI is separate from runner execution. Speech-motion support coordinates speech-triggered animation. Multiple runner namespaces can exist; the default is /hr/control/performances/.
The runner loads robot identity from /hr/profile and performance content from PERFORMANCES_DIR. It maintains a worker queue, locks, active nodes, current performance, timing and autopause state. Enabled timelines contribute to sequential runtime duration; disabled timelines are skipped.
ROS service surface
| Suffix under runner namespace | Role |
|---|---|
reload_properties |
Reload stored performance properties |
set_properties |
Update a performance's property values |
load |
Load performance by ID |
load_performance |
Load supplied JSON performance payload |
unload |
Unload runtime content |
run |
Run loaded content from specified time |
run_by_name |
Load/run named content |
run_full_performance |
Run full named performance through its dedicated handler |
resume, pause, stop |
Change playback lifecycle |
current |
Read current runtime representation |
is_performance_loaded |
Query loaded state |
The performance reference includes each registration, request/response .srv definition, event type and speech-motion registrations. The currently registered services are authoritative; old README lists can contain operations absent from the runner.
running_performance and events are published under the runner namespace. Events contain event name, time, performance ID, running/paused flags and active timeline information. WebUI converts these into its versioned runtime/tick model.
ros2 service list -t
ros2 interface show performances/srv/Current
ros2 interface show performances/srv/Run
ros2 topic info -v /hr/control/performances/events
These probes do not execute a performance. Use the installed service type from the running graph when calling directly.
Playback and storage consistency
Loading selects runtime content; saving edits changes files. An unsaved WebUI preview can run a payload different from the stored file. Compare runtime content revision and GET /api/performances/current with the editor draft and storage revision.
The WebUI command channel supports load/loadInline/loadAndRun/run/pause/resume/stop/unload/autopause/preview. It returns authoritative snapshots; ticks are transient. A client should not reconstruct timeline content solely from ticks. The WebUI protocol guide describes revision matching.
Autopause is configurable and can alter playback progression. The default runner can interrupt TTS; separate namespaces disable that behavior in the constructor. Stopping one runner does not guarantee unrelated behavior, audio or actuator publishers have stopped.
Authoring and recovery
Use explicit IDs from the performance tree. Save with baseRevision to detect concurrent edits. A 409 requires reloading and reconciling; forcing a save overwrites current content intentionally. Multi-timeline saves can remove omitted files, and delete removes directories recursively.
Before previewing, inspect all timed node types: speech, expressions, gestures, target changes and other commands can have real effects. If playback fails, inspect loaded state, selected robot content root, node timing, property substitutions, runtime services and task-specific logs. Restore known-good stored content and reload rather than assuming a browser refresh resets execution.
Evidence: head-ros-nodes/ros/performances/scripts/{runner.py,speech_motion_controller.py}, src/performances/{nodes.py,speech_motion.py,config_nodes.py}, service definitions and WebUI performance storage/adapter.
The ROS2 WebUI adapter does not implement a seek command action. The editor selects a local indicator and uses run or loadAndRun with startTime for execution from a position.