Rename RangedPlayback capability to PlaybackControl (#879)

ericmlujan · web-flow · commit 94d02861d09a · 2026-02-13T15:45:53.000-08:00
### Changelog
None

### Docs
None

### Description
Coming out of launch review, we got consensus that `PlaybackControl` is
a more descriptive name than `RangedPlayback`, given that the new
callbacks and core functionality relate to controlling playback from the
Foxglove UI. This PR implements that renaming in the SDK.

Tested building and running an example with the `PlaybackControl`
capability against a Foxglove app build that had the renaming
implemented.
diff --git a/c/include/foxglove-c/foxglove-c.h b/c/include/foxglove-c/foxglove-c.h
diff --git a/c/src/server.rs b/c/src/server.rs
@@ -43,7 +43,7 @@ pub const FOXGLOVE_SERVER_CAPABILITY_ASSETS: u8 = 1 << 5;
 /// Indicates that the server is sending data within a fixed time range. This requires the
 /// server to specify the `data_start_time` and `data_end_time` fields in
 /// `foxglove_server_options`.
-pub const FOXGLOVE_SERVER_CAPABILITY_RANGED_PLAYBACK: u8 = 1 << 6;
+pub const FOXGLOVE_SERVER_CAPABILITY_PLAYBACK_CONTROL: u8 = 1 << 6;
 
 bitflags! {
     #[derive(Clone, Copy, PartialEq, Eq)]
@@ -54,7 +54,7 @@ bitflags! {
         const Time = FOXGLOVE_SERVER_CAPABILITY_TIME;
         const Services = FOXGLOVE_SERVER_CAPABILITY_SERVICES;
         const Assets = FOXGLOVE_SERVER_CAPABILITY_ASSETS;
-        const RangedPlayback = FOXGLOVE_SERVER_CAPABILITY_RANGED_PLAYBACK;
+        const PlaybackControl = FOXGLOVE_SERVER_CAPABILITY_PLAYBACK_CONTROL;
     }
 }
 
@@ -77,8 +77,8 @@ impl FoxgloveServerCapabilityBitFlags {
             FoxgloveServerCapabilityBitFlags::Assets => {
                 Some(foxglove::websocket::Capability::Assets)
             }
-            FoxgloveServerCapabilityBitFlags::RangedPlayback => {
-                Some(foxglove::websocket::Capability::RangedPlayback)
+            FoxgloveServerCapabilityBitFlags::PlaybackControl => {
+                Some(foxglove::websocket::Capability::PlaybackControl)
             }
             _ => None,
         })
@@ -170,10 +170,10 @@ pub struct FoxgloveServerOptions<'a> {
         ) -> bool,
     >,
 
-    /// If the server is sending data from a fixed time range, and has the RangedPlayback capability,
+    /// If the server is sending data from a fixed time range, and has the PlaybackControl capability,
     /// the start time of the data range.
     pub playback_start_time: Option<&'a u64>,
-    /// If the server is sending data from a fixed time range, and has the RangedPlayback capability,
+    /// If the server is sending data from a fixed time range, and has the PlaybackControl capability,
     /// the end time of the data range.
     pub playback_end_time: Option<&'a u64>,
 
@@ -326,7 +326,7 @@ pub struct FoxgloveServerCallbacks {
 
     /// Callback invoked when a client sends a playback control request message.
     ///
-    /// Requires `FOXGLOVE_CAPABILITY_RANGED_PLAYBACK`.
+    /// Requires `FOXGLOVE_CAPABILITY_PLAYBACK_CONTROL`.
     ///
     /// `playback_control_request` is an input parameter and guaranteed to be non-NULL.
     /// `playback_state` is a non-NULL output pointer to a struct that has already been allocated.
@@ -531,7 +531,7 @@ pub extern "C" fn foxglove_server_broadcast_time(
 
 /// Publishes the current playback state to all clients.
 ///
-/// Requires the `FOXGLOVE_CAPABILITY_RANGED_PLAYBACK` capability.
+/// Requires the `FOXGLOVE_CAPABILITY_PLAYBACK_CONTROL` capability.
 ///
 /// # Safety
 /// - `playback_state` must be a valid pointer to a playback state that lives for the duration of the call.
diff --git a/cpp/foxglove/include/foxglove/playback_control_request.hpp b/cpp/foxglove/include/foxglove/playback_control_request.hpp
@@ -17,7 +17,7 @@ enum class PlaybackCommand : uint8_t {
 
 /// @brief A request to control playback from the Foxglove app
 ///
-/// Only relevant if the `RangedPlayback` capability is enabled.
+/// Only relevant if the `PlaybackControl` capability is enabled.
 struct PlaybackControlRequest {
 public:
   /// @brief The playback command.
diff --git a/cpp/foxglove/include/foxglove/playback_state.hpp b/cpp/foxglove/include/foxglove/playback_state.hpp
@@ -26,7 +26,7 @@ enum class PlaybackStatus : uint8_t {
 /// state of playback has changed; for example, reaching the end of data, or an external mechanism
 /// causes playback to pause.
 ///
-/// Only relevant if the `RangedPlayback` capability is enabled.
+/// Only relevant if the `PlaybackControl` capability is enabled.
 struct PlaybackState {
 public:
   /// @brief The status of server data playback
diff --git a/cpp/foxglove/include/foxglove/server.hpp b/cpp/foxglove/include/foxglove/server.hpp
@@ -74,7 +74,7 @@ enum class WebSocketServerCapabilities : uint8_t {
   /// @cond foxglove_internal
   /// Indicates that the server is sending data within a fixed time range. This requires the
   /// server to specify the `playback_time_range` field in its `WebSocketServerOptions`.
-  RangedPlayback = 1 << 6,
+  PlaybackControl = 1 << 6,
   /// @endcond
 };
 
@@ -200,7 +200,7 @@ struct WebSocketServerCallbacks {
   /// @cond foxglove_internal
   /// @brief Callback invoked when a playback control request is sent from the client.
   ///
-  /// Requires the capability WebSocketServerCapabilities::RangedPlayback
+  /// Requires the capability WebSocketServerCapabilities::PlaybackControl
   ///
   /// @param playback_control_request The playback control request.
   /// @return The playback state to send back to the client.
@@ -268,7 +268,7 @@ struct WebSocketServerOptions {
   /// @brief The time range for playback. This applies if the server is playing back a fixed time
   /// range of data.
   ///
-  /// @note Setting this option imples the RangedPlayback capability
+  /// @note Setting this option imples the PlaybackControl capability
   std::optional<std::pair<uint64_t, uint64_t>> playback_time_range = std::nullopt;
   /// @endcond
 };
@@ -306,7 +306,7 @@ class WebSocketServer final {
   /// @cond foxglove_internal
   /// @brief Publishes the current playback state to all clients.
   ///
-  /// Requires the capability WebSocketServerCapabilities::RangedPlayback.
+  /// Requires the capability WebSocketServerCapabilities::PlaybackControl.
   ///
   /// @param playback_state The playback state to publish.
   void broadcastPlaybackState(const PlaybackState& playback_state) const noexcept;
diff --git a/cpp/foxglove/tests/test_server.cpp b/cpp/foxglove/tests/test_server.cpp
@@ -1600,7 +1600,7 @@ TEST_CASE("Playback control request callback") {
 
   foxglove::WebSocketServerOptions ws_options;
   ws_options.context = context;
-  ws_options.capabilities = foxglove::WebSocketServerCapabilities::RangedPlayback;
+  ws_options.capabilities = foxglove::WebSocketServerCapabilities::PlaybackControl;
   ws_options.playback_time_range = std::make_pair(0, 1000);
   ws_options.callbacks.onPlaybackControlRequest =
     [&]([[maybe_unused]] const foxglove::PlaybackControlRequest& playback_control_request
@@ -1673,7 +1673,7 @@ TEST_CASE("Broadcast playback state") {
   auto context = foxglove::Context::create();
   foxglove::WebSocketServerOptions ws_options;
   ws_options.context = context;
-  ws_options.capabilities = foxglove::WebSocketServerCapabilities::RangedPlayback;
+  ws_options.capabilities = foxglove::WebSocketServerCapabilities::PlaybackControl;
   ws_options.playback_time_range = std::make_pair(0, 1000);
   auto server = startServer(std::move(ws_options));
 
@@ -1708,7 +1708,7 @@ TEST_CASE("Broadcast playback state") {
   REQUIRE(server.stop() == foxglove::FoxgloveError::Ok);
 }
 
-TEST_CASE("RangedPlayback capability") {
+TEST_CASE("PlaybackControl capability") {
   auto context = foxglove::Context::create();
 
   const uint64_t start_time = 100000000000ULL;
@@ -1728,12 +1728,12 @@ TEST_CASE("RangedPlayback capability") {
   REQUIRE(parsed.contains("op"));
   REQUIRE(parsed["op"] == "serverInfo");
 
-  // Ensure that the rangedPlayback capability is enabled, since opt.playback_time_range is
+  // Ensure that the playbackControl capability is enabled, since opt.playback_time_range is
   // specified
   REQUIRE(parsed.contains("capabilities"));
   const auto& capabilities = parsed["capabilities"];
   REQUIRE(std::count_if(capabilities.begin(), capabilities.end(), [](const auto& capability) {
-            return capability == "rangedPlayback";
+            return capability == "playbackControl";
           }) == 1);
 
   REQUIRE(parsed.contains("dataStartTime"));
diff --git a/python/foxglove-sdk/python/foxglove/__init__.py b/python/foxglove-sdk/python/foxglove/__init__.py
@@ -77,7 +77,7 @@ def start_server(
             Return `True` to log the channel, or `False` to skip it. By default, all channels
             will be logged.
         :param playback_time_range: Time range of data being played back, in absolute nanoseconds.
-            Implies `Capability.RangedPlayback` if set.
+            Implies `Capability.PlaybackControl` if set.
         """
         return _foxglove.start_server(
             name=name,
diff --git a/python/foxglove-sdk/python/foxglove/_foxglove_py/websocket.pyi b/python/foxglove-sdk/python/foxglove/_foxglove_py/websocket.pyi
@@ -27,7 +27,7 @@ class Capability(Enum):
     Time = ...
     """Inform clients about the latest server time."""
 
-    RangedPlayback = ...
+    PlaybackControl = ...
     """Indicates that the server is sending data within a fixed time range."""
 
 class Client:
diff --git a/python/foxglove-sdk/python/foxglove/websocket.py b/python/foxglove-sdk/python/foxglove/websocket.py
@@ -184,7 +184,7 @@ def on_playback_control_request(
         """
         Called by the server when it receives an updated player state from the client.
 
-        Requires :py:data:`Capability.RangedPlayback`.
+        Requires :py:data:`Capability.PlaybackControl`.
 
         :meta private:
         :param playback_control_request: The playback control request sent from the client
diff --git a/python/foxglove-sdk/src/websocket.rs b/python/foxglove-sdk/src/websocket.rs
@@ -763,7 +763,7 @@ pub enum PyCapability {
     Services,
     /// Indicates that the server is sending data within a fixed time range. This requires the
     /// server to specify the `data_start_time` and `data_end_time` fields in its `ServerInfo` message.
-    RangedPlayback,
+    PlaybackControl,
 }
 
 impl From<PyCapability> for foxglove::websocket::Capability {
@@ -774,7 +774,7 @@ impl From<PyCapability> for foxglove::websocket::Capability {
             PyCapability::Parameters => foxglove::websocket::Capability::Parameters,
             PyCapability::Time => foxglove::websocket::Capability::Time,
             PyCapability::Services => foxglove::websocket::Capability::Services,
-            PyCapability::RangedPlayback => foxglove::websocket::Capability::RangedPlayback,
+            PyCapability::PlaybackControl => foxglove::websocket::Capability::PlaybackControl,
         }
     }
 }
diff --git a/rust/foxglove/src/protocol/common/server/playback_state.rs b/rust/foxglove/src/protocol/common/server/playback_state.rs
@@ -38,7 +38,7 @@ impl TryFrom<u8> for PlaybackStatus {
 /// state of playback has changed; for example, reaching the end of data, or an external mechanism
 /// causes playback to pause.
 ///
-/// Only relevant if the `RangedPlayback` capability is enabled.
+/// Only relevant if the `PlaybackControl` capability is enabled.
 pub struct PlaybackState {
     /// The status of server data playback
     pub status: PlaybackStatus,
diff --git a/rust/foxglove/src/protocol/common/server/server_info.rs b/rust/foxglove/src/protocol/common/server/server_info.rs
@@ -133,7 +133,7 @@ pub enum Capability {
     /// Indicates that the server is sending data within a fixed time range. This requires the
     /// server to specify the `data_start_time` and `data_end_time` fields in its `ServerInfo` message.
     /// Playback control requests are only accepted when this capability is enabled.
-    RangedPlayback,
+    PlaybackControl,
 }
 
 #[cfg(test)]
@@ -151,7 +151,7 @@ mod tests {
             .with_capabilities([
                 Capability::ClientPublish,
                 Capability::Time,
-                Capability::RangedPlayback,
+                Capability::PlaybackControl,
             ])
             .with_supported_encodings(["json"])
             .with_metadata(maplit::hashmap! {
diff --git a/rust/foxglove/src/protocol/common/server/snapshots/foxglove__protocol__common__server__server_info__tests__encode_full.snap b/rust/foxglove/src/protocol/common/server/snapshots/foxglove__protocol__common__server__server_info__tests__encode_full.snap
@@ -8,7 +8,7 @@ expression: message_full()
   "capabilities": [
     "clientPublish",
     "time",
-    "rangedPlayback"
+    "playbackControl"
   ],
   "supportedEncodings": [
     "json"
diff --git a/rust/foxglove/src/websocket/capability.rs b/rust/foxglove/src/websocket/capability.rs
@@ -22,7 +22,7 @@ pub enum Capability {
     ConnectionGraph,
     /// Indicates that the server is sending data within a fixed time range. This requires the
     /// server to specify the `data_start_time` and `data_end_time` fields in its `ServerInfo` message.
-    RangedPlayback,
+    PlaybackControl,
 }
 
 impl Capability {
@@ -37,7 +37,7 @@ impl Capability {
             Self::Services => &[server_info::Capability::Services],
             Self::Assets => &[server_info::Capability::Assets],
             Self::ConnectionGraph => &[server_info::Capability::ConnectionGraph],
-            Self::RangedPlayback => &[server_info::Capability::RangedPlayback],
+            Self::PlaybackControl => &[server_info::Capability::PlaybackControl],
         }
     }
 }
diff --git a/rust/foxglove/src/websocket/connected_client.rs b/rust/foxglove/src/websocket/connected_client.rs
@@ -676,8 +676,8 @@ impl ConnectedClient {
     }
 
     fn on_playback_control_request(&self, server: Arc<Server>, msg: PlaybackControlRequest) {
-        if !server.has_capability(Capability::RangedPlayback) {
-            self.send_error("Server does not support ranged playback capability".to_string());
+        if !server.has_capability(Capability::PlaybackControl) {
+            self.send_error("Server does not support playback control capability".to_string());
             return;
         }
 
@@ -703,7 +703,7 @@ impl ConnectedClient {
             server.broadcast_playback_state(playback_state);
         } else {
             self.send_error(
-                "Server advertised ranged playback capability but didn't provide a listener"
+                "Server advertised playback control capability but didn't provide a listener"
                     .to_string(),
             );
         }
diff --git a/rust/foxglove/src/websocket/server.rs b/rust/foxglove/src/websocket/server.rs
@@ -167,7 +167,7 @@ pub(crate) struct Server {
     /// Keys prefixed with "fg-" are reserved for internal use.
     server_info: HashMap<String, String>,
     /// Time range of data being played back, in absolute nanoseconds.
-    /// Implies the [`RangedPlayback`](crate::websocket::Capability::RangedPlayback) capability if set.
+    /// Implies the [`PlaybackControl`](crate::websocket::Capability::PlaybackControl) capability if set.
     playback_time_range: Option<(u64, u64)>,
 }
 
@@ -202,11 +202,11 @@ impl Server {
         }
 
         if opts.playback_time_range.is_some() {
-            capabilities.insert(Capability::RangedPlayback);
-        } else if capabilities.contains(&Capability::RangedPlayback) {
-            // The RangedPlayback capability requires a time range to be set using
+            capabilities.insert(Capability::PlaybackControl);
+        } else if capabilities.contains(&Capability::PlaybackControl) {
+            // The PlaybackControl capability requires a time range to be set using
             // ServerOptions::playback_time_range
-            panic!("Server declared the RangedPlayback capability but did not provide a playback time range");
+            panic!("Server declared the PlaybackControl capability but did not provide a playback time range");
         }
 
         // If the server was declared with fetch asset handler, automatically add the "assets" capability
@@ -374,8 +374,8 @@ impl Server {
     /// Publish the current playback state to all clients.
     #[doc(hidden)]
     pub fn broadcast_playback_state(&self, playback_state: PlaybackState) {
-        if !self.has_capability(Capability::RangedPlayback) {
-            tracing::error!("Server does not support the RangedPlayback capability");
+        if !self.has_capability(Capability::PlaybackControl) {
+            tracing::error!("Server does not support the PlaybackControl capability");
             return;
         }
 
diff --git a/rust/foxglove/src/websocket/server_listener.rs b/rust/foxglove/src/websocket/server_listener.rs
@@ -70,7 +70,7 @@ pub trait ServerListener: Send + Sync {
 
     #[doc(hidden)]
     /// Callback invoked when a client sends a playback control request.
-    /// Requires [`Capability::RangedPlayback`][super::Capability::RangedPlayback].
+    /// Requires [`Capability::PlaybackControl`][super::Capability::PlaybackControl].
     fn on_playback_control_request(
         &self,
         _request: PlaybackControlRequest,
diff --git a/rust/foxglove/src/websocket/tests.rs b/rust/foxglove/src/websocket/tests.rs
diff --git a/rust/foxglove/src/websocket_server.rs b/rust/foxglove/src/websocket_server.rs

Original file line number	Diff line number	Diff line change
`@@ -763,7 +763,7 @@ pub enum PyCapability {`
`763`	`763`	`Services,`
`764`	`764`	`/// Indicates that the server is sending data within a fixed time range. This requires the`
`765`	`765`	/// server to specify the `data_start_time` and `data_end_time` fields in its `ServerInfo` message.
`766`		`- RangedPlayback,`
	`766`	`+ PlaybackControl,`
`767`	`767`	`}`
`768`	`768`
`769`	`769`	`impl From<PyCapability> for foxglove::websocket::Capability {`
`@@ -774,7 +774,7 @@ impl From<PyCapability> for foxglove::websocket::Capability {`
`774`	`774`	`PyCapability::Parameters => foxglove::websocket::Capability::Parameters,`
`775`	`775`	`PyCapability::Time => foxglove::websocket::Capability::Time,`
`776`	`776`	`PyCapability::Services => foxglove::websocket::Capability::Services,`
`777`		`- PyCapability::RangedPlayback => foxglove::websocket::Capability::RangedPlayback,`
	`777`	`+ PyCapability::PlaybackControl => foxglove::websocket::Capability::PlaybackControl,`
`778`	`778`	`}`
`779`	`779`	`}`
`780`	`780`	`}`